[Discussion] Proposal for improving stability: Boot sequence and WiFi handling

[Jane84894]

Hi @jnthas,

First of all, thank you for this amazing project! I've been studying the code and really like the architecture.

While running the firmware on my ESP32 + HUB75 setup, I noticed a few potential stability issues that might cause boot loops or blocking behavior in certain environments. I have analyzed the source code and would like to share my findings and some potential solutions I am currently exploring.

1. Boot Loop / Brownout Risk

Observation: In setup(), the display is initialized and turned on (potentially drawing high current) before wifi.begin() is called.
Hypothesis: The combined current spike from the display and WiFi RF calibration might trigger the Brownout Detector on some boards.
Proposed Idea: Initialize the display with setBrightness8(0) (black screen) first, and only ramp up the brightness after the WiFi connection sequence is complete.

2. WiFi Connection Blocking

Observation: The current connection logic seems to block the execution loop if the configured WiFi network is unavailable. This makes it difficult to reconfigure the device if it's moved to a new location.
Proposed Idea: Implementing a timeout mechanism or integrating a library like WiFiManager. This would allow the device to fall back to AP mode or an "Offline Mode" if the connection fails, keeping the UI responsive.

3. NTP Synchronization

Observation: The boot process appears to stall if the WiFi is connected but the NTP server is unreachable.
Proposed Idea: Making the NTP synchronization non-blocking or adding a timeout to prevent the device from hanging on a blank screen during startup.

---

Next Steps:
I am currently trying to implement these changes locally to verify if they solve the issues.

I wanted to ask if you are open to these kinds of modifications? If you think this approach makes sense, I can continue working on it and hopefully submit a Pull Request once I have a stable solution.

Thanks again!

[Jane84894]

One more thing: Proposal for Chinese Localization (i18n)

While diving into the code, I also noticed that the project has great potential to be popular in the Chinese maker community (since ESP32 and HUB75 panels are very accessible here).

I am considering working on a Localization (i18n) feature and would love to hear your thoughts on the best approach:

1. Web UI Translation:
   The current SettingsWebPage.h uses hardcoded HTML strings. I can help refactor this to support multiple languages (English/Chinese) or simply provide a translated version. This would make the configuration much friendlier for non-English speakers.

2. Font Support (Optional):
   Displaying Chinese characters on the LED matrix might require a larger font library (GB2312/UTF-8 support), which consumes more flash. We could potentially implement a lightweight solution that only includes necessary characters (e.g., for Weekdays or Menu items) or allow loading fonts from the filesystem (SPIFFS/LittleFS).

If you are interested in opening up the project to a wider audience, I would be more than happy to contribute the Chinese translation and help test the font implementation.

Looking forward to your feedback on both the stability fixes and this feature request! 🚀

[jnthas]

Hello @Jane84894, I loved your ideas and I'm totally open for improvements in this project.

Regarding your ideas:

1. Boot Loop / Brownout Risk
   I haven't thought about this possibility, it seems easy to modify the code and

2. WiFi Connection Blocking
   Clockwise already has implemented WifiManager. If Wifi fails, it will shows a message. Here

3. NTP Synchronization
   This is a known problem and it happen very often to be honest. My only concern is how to let the user aware that the time is wrong because of the NTP server.

4. Chinese I18n
   Please, let's implement it. I also think it bring more people to the project.

Let me know if it is possible to do some video in Chinese demoing how to configure the Clockwise.

[Jane84894]

Thanks for the positive feedback! @jnthas

I'd like to share some more specific details about the issues I encountered, which might help clarify things:

1. Re: Boot Loop / Brownout

To clarify the severity: This actually blocks the initial setup.
In my case, when I flash the firmware or boot with the HUB75 panel connected, the device enters an infinite restart loop immediately. I have to physically disconnect the display cables to let it boot successfully and configure WiFi.
It seems the power draw during initialization is too high for the ESP32 to handle alongside the WiFi startup. I just wanted to highlight this phenomenon as it affects the "out-of-the-box" experience.

2. Re: NTP Synchronization

Regarding the connection failures, I dug a bit deeper and found two main root causes:

1. Default Server: The default is hardcoded to time.google.com, which is blocked or unreliable in many regions (like China).
2. Single Server Limitation: The current code only passes one server to the config, ignoring the ESP32's ability to support multiple fallbacks.

• My Plan: I will modify the code to support multiple NTP servers (e.g., adding pool.ntp.org as fallback). This should significantly improve the success rate globally and solve the issue at the root level.

3. Re: WiFi Blocking

Regarding the WiFiManager: You are right, it is implemented. However, the current timeout is set to 300 seconds (5 minutes). If the router is down or I just want to use the clock offline, I have to wait for a full 5 minutes. I plan to optimize this flow to make it quicker to enter "Offline Mode".

---

I will work on these improvements and the Chinese Localization (I18n) and keep you posted!

[Jane84894]

Just to add a bit more context on why the Chinese Localization would be so impactful:

The pixel clock ecosystem (ESP32 + HUB75) is actually thriving in the Chinese maker community. There are countless mature video tutorials, open-source PCB designs, and high-quality 3D-printed enclosures available here.

To give you a concrete example, there is a very popular open-source hardware project on OSHWHub (a major open-source hardware platform in China) called the "Mario Clock":
🔗 Link: SuperCaii's Mario Clock on OSHWHub

The interesting part is: This project (and many others like it) actually uses a modified/forked version of Clockwise!

This proves that Clockwise is already the preferred firmware for these hardware builds. However, because of the language barrier, users often rely on these forked versions. If we add official Localization support, I believe we can unify the community and bring these users back to the official repository! 🚀

[Jane84894]

Upon further analyzing that modified firmware (the "Mario Clock" link above), I found two specific improvements they implemented that we should definitely adopt.

These features effectively solve the instability issues I mentioned earlier:

1. AP-Mode Provisioning (Solves the Boot Loop)

They use an Access Point (AP) mode for the initial setup instead of relying solely on Serial.

• Key Finding: This approach actually fixes the infinite restart loop. Instead of crashing or getting stuck when WiFi is unavailable, the device gracefully falls back to creating a Hotspot. This makes the system much more stable and consumer-friendly.

2. IP Address Display

They also added a feature to display the IP address on the screen immediately after connection. This solves the headache of finding the device's address on the local network.

---

Note: I haven't implemented these features in my code yet, but seeing how well they work in the community fork, I strongly suggest we port these logic flows into the official Clockwise firmware.

If you agree with this direction, I can try to work on porting them!

[jnthas]

Hello @Jane84894. Yeah, I know there are some variants of Clockwise around, some of them being sold on AliExpress. I didn't know about this one you sent. We can follow the priority order defined earlier.

1. Re: Boot Loop / Brownout
2. Re: NTP Synchronization
3. Re: WiFi Blocking

---

You mentioned about the 5min timeout, this is expected considering that there is no "Offline mode" so far. Clockwise first try to connect in the wifi, if it's not available, it starts the alternative setup method and will wait for 5 minutes to be set via Access Point. If it does not happen, it start the process over again.

Another thing to be aware: once Clockwise is up and running, if the internet connection goes down for any reason, it will not cause Clockwise to restart. It will continue working for some time, which means that internet fluctuations will not impact Clockwise.

---

I liked the idea of having a fallback in the NTP server. The Google server is hardcoded but as a default value. The NTP Server is actually a parameter in the config screen, you probably saw this parameter there.

---

About the IP in the startup screen, I agree that it'd be easy. The clockwise.local address doesn't work as it should.

Long time ago I did some tests displaying a qrcode which worked very well, you can see and read it here:

Let me know what do you think, maybe implement this as a link to the AP.

[Jane84894]

Hi @jnthas,

Thanks for the detailed response! The QR code concept looks really cool—definitely a great feature for a future release!

Here is how I plan to align with your feedback:

1. Offline Mode (The Key to Timeout)

You are right about the 5-minute timeout being a fallback.

• The Reality: Since most DIY builds lack an RTC battery, I understand that booting without WiFi means the time will reset to 00:00.
• My Goal: However, showing 00:00 is still vastly better than a boot loop.
  • If the device enters "Offline Mode" (AP Mode active), the user sees the screen is working and can connect to the Web UI to fix the WiFi config.
  • Currently, if it loops or crashes (due to brownout/blocking), the user is locked out and cannot access the Web UI at all.

2. NTP Robustness

I noticed the config parameter.

• My Implementation: I will enhance the backend logic to support multiple servers (Main + Fallbacks). This ensures that even if the default (Google) is blocked, it automatically fails over to pool.ntp.org, making the "out-of-box" experience much smoother.

3. IP Display vs QR Code

• My Implementation: For **PR **, I will stick to a simple Scrolling/Static IP Address text. It is lightweight and solves the immediate "what is my IP" problem effectively.
• Future: We can definitely explore adding the QR Code in a later update!

---

Plan:
I plan to work on implementing and testing these changes over the upcoming weekend. Once I have verified everything on my hardware, I will submit the Pull Request. 🛠️