v1.5.0 — Action API, Physical Button & WiFi Improvements
⚡ New: Unified `/action` API:
- New `/action` endpoint replaces individual `/set_*` endpoints (legacy endpoints still supported)
- Device control via HTTP GET or POST: messages, brightness, navigation, timers, toggles, and more
- Toggle behavior: sending a parameter without a value toggles it and jumps to the relevant mode
- Explicit value behavior: sending `=0` or `=1` sets without disrupting the display
- All boolean settings now controllable via API: `twelvehour`, `dayofweek`, `showdate`, `colon_blink`, `humidity`, `weatherdesc`, `units`, `countdown`, `flip`, `clock_only_dimming`
- Navigation actions: `next_mode`, `prev_mode`, `go_to_mode` (by number or name)
- Brightness actions: `brightness`, `brightness_up`, `brightness_down`, `display_off`
- Rotation control: `enable_rotation` — freeze or resume automatic mode rotation
- System actions: `save`, `restart`, `clear_message`, `language`
- Timer actions: `timer`, `timer_stop`, `timer_cancel`, `timer_pause`, `timer_resume`, `timer_start`, `timer_restart`
- Message aliases: `scrolltimes`, `scrolls`, `scroll_times` all accepted
- `clear_message` correctly restores the persistent Web UI message
🔘 New: Physical Button Template
- Optional physical button support — disabled by default, uncomment to enable
- Short press: advance to next mode (customizable)
- Long press (800ms): toggle display on/off (customizable)
- Uses internal pull-up — no external resistor needed
- Any action from the `/action` API can be assigned to either press
- Full documentation and wiring guide added to README
📶 Improved: WiFi Reconnection
- New exponential backoff reconnection system
- Reconnect attempts: 5s → 10s → 20s → 40s → 80s → 160s → 300s (caps at 5 min)
- Prevents hammering the router with rapid reconnection attempts
- `WiFi.setAutoReconnect(false)` — manual backoff now handles all reconnection
- ESP8266 uses `WiFi.begin(ssid, password)` for reconnection (ESP32 uses `WiFi.reconnect()`)
- Logs connection loss, reconnection attempts, and successful reconnection
- mDNS restarts automatically after reconnection
- Weather fetch deferred briefly after reconnection to let network stabilize
🌐 ESPTimeCast Companion Extension
- New browser extension available on the Chrome Web Store
- Automatically detects and displays media titles from YouTube, Spotify, Prime Video, Twitch, Vimeo, Dailymotion, and SoundCloud
- Control brightness, modes, and rotation directly from the popup
- Cast to multiple ESPTimeCast devices simultaneously
- Requires **v1.5.0 or later** (uses the new `/action` endpoint)
🎨 Font Changes
- `mfactoryfont.h` is now bundled directly with the firmware following the license change
- No separate font download required — the custom font is included out of the box
- Basic Font has been removed — all builds now use the full `mfactoryfont.h`
- All icons, weather symbols, and custom glyphs available on all installations
📜 License Change
- ESPTimeCast is no longer licensed under GPL-3.0
- New license: Source-available for personal, non-commercial use only
- Personal use includes home, hobby, and small non-commercial settings
- Forking permitted with license retained
- Commercial licensing available — contact mario.felipe.tf@gmail.com
- Previous versions (v1.4.2 and earlier) remain under GPL-3.0
### 📖 Documentation
- Full API reference added to README covering all `/action` parameters
- Physical button wiring guide and customization examples
- WiFi reconnection behavior documented
- Timer documentation added (moved from HA section to standalone section)
- Chrome Extension section added to README
- Legacy endpoint note added for `/set_custom_message` and `/set_brightness`
This update focuses on polishing the setup experience and improving consistency across interfaces.
• Cleaner AP Mode with only essential options
• Consistent error handling aligned with the web installer
• Improved onboarding messaging for new users
• General UI and text refinements
• Fixed scroll bug in short messages when the "flip display" option was enabled
This release (v1.4.2) marks the final version of ESPTimeCast distributed under the GPL 3.0 license. Starting from v1.5.0, ESPTimeCast will transition to a Source-Available, Personal Use Only license.
What this means:
- v1.4.2 and earlier remain fully open-source (GPL-3.0)
- Future versions will have different usage terms
- Existing users can continue using and modifying GPL versions as before
This change helps support the long-term development of the project while keeping it accessible for personal use.
🙏 Thank you to everyone who supported and keep supporting ESPTimeCast and helped the project grow!
Future releases will introduce new features including a new API and extended integrations.
Whats new:
- Fix: Serve Web UI directly from PROGMEM instead of LittleFS, freeing ~114KB of filesystem space for config files and preventing storage-related save errors
- Fix: Hostname handling now correctly defaults to "esptimecast" on fresh install, preventing empty hostname errors on first save.
- Improvement: Hostname redirect after save now correctly stays on IP address when accessed via IP, instead of always redirecting to .local
- Improvement: OTA update success screen now hides the form and footer for a cleaner post-update experience
- Removed: ensureHtmlFileExists() function no longer needed — Web UI is always in sync with firmware
New Feature: Timer Mode
• ESPTimeCast now supports a built-in timer that can be started directly from a custom message command.
• Example command: [TIMER 5M], this starts a 5-minute countdown timer on the display.
• When a timer is active, the device enters Timer Mode: The normal display loop (clock, weather, messages, etc.) will not interrupt the timer.
• Timer remains visible until it finishes or is manually controlled.
• Only messages sent with allowInterrupt=0 will pass through during an active timer.
Timer Commands:
[TIMER XHXMXSX] → Start a timer with defined duration (24hrs max)
[TIMER STOP] or [TIMER CANCEL]→ Stop the timer
[TIMER PAUSE] → pause the timer
[TIMER RESUME] [TIMER START] → Resume paused timer
[TIMER RESTART] → Restart current timer
Timers can be triggered from: the Web UI, API (/set_custom_message)
Other Improvements:
• Fixed incorrect Turkish day translations
• Added support for the ¥ (Yen) symbol
• Improved Custom Message input field for easier timer and icons input
Whats new:
Dynamic Hostname Configuration: You can now change the device's network hostname directly from the Web UI. No more digging through the code to identify your ESPTimeCast on the network!
Symbol Support: The character set for custom messages has been massively expanded. You can now use technical and decorative symbols for richer data display: ! . : ? ; , ' " - _ + % / [ ] # & $ | ° @ ^ ~ * = < > { } \
Protected Messages: Added the allowInterrupt parameter to the custom message API. This gives you more control over whether a new message should immediately take over the display or wait for the current one to finish.
Clock-Only Mode Stability: Fixed a logic bug that occurred when the device was set to "Clock-Only" mode. The display should now remain stable and responsive without unexpected transitions.
Whats new:
Dynamic Hostname Configuration: You can now change the device's network hostname directly from the Web UI. No more digging through the code to identify your ESPTimeCast on the network!
Symbol Support: The character set for custom messages has been massively expanded. You can now use technical and decorative symbols for richer data display: ! . : ? ; , ' " - _ + % / [ ] # & $ | ° @ ^ ~ * = < > { } \
Protected Messages: Added the allowInterrupt parameter to the custom message API. This gives you more control over whether a new message should immediately take over the display or wait for the current one to finish.
Clock-Only Mode Stability: Fixed a logic bug that occurred when the device was set to "Clock-Only" mode. The display should now remain stable and responsive without unexpected transitions.
Improved Advanced Settings Visibility:
All categories within the Advanced Settings menu are now expanded by default, making it easier to locate and adjust parameters without additional clicks.
Hardware Pinout Optimization:
Migrated ESP32-C3 to neutral GPIOs (CLK_PIN 4, CS_PIN 10, DATA_PIN 6) to prevent boot-up hangs caused by strapping pins and conflicts with the onboard LED.
AP Mode Auto-Recovery:
Added a 3-minute safety timer to Access Point mode. If WiFi credentials are already stored, the device assumes a temporary interruption (e.g., power outage) and automatically reboots to retry connecting with the saved credentials.
Weather Icons in Description:
Integrated OpenWeather icons directly into the weather description display. Added Mist/Fog icon support and updated mfactoryfont.h to include the new glyph.
WiFi & Handshake Stability:
Refined connection and retry logic to improve resilience against router drops and ensure a faster, more reliable initial setup.
Binary Footprint Optimization:
Removed redundant CSS and consolidated style declarations to reduce firmware size and improve Web UI loading speed on ESP devices.
This is a special milestone: version 1.3.1 is the first-ever update designed to be installed wirelessly using the OTA (Over-The-Air) feature we introduced in the previous version!
What’s New:
First OTA Milestone: You can now skip the USB cable! If you are running v1.3.0, this is the first update you can install directly through your browser.
Improved Custom Message Transition: Long custom messages that fill the screen now "step aside" just before the clock arrives. This prevents text from overlapping and makes the handover look professional.
Stronger Wi-Fi Handling: We’ve made the connection logic much more robust. Your device is now better at staying connected and recovering from network blips.
Intuitive Web UI: We fixed the "Enter" key behavior. Typing a Custom Message and hitting Enter now sends it instantly, while hitting Enter in the settings area saves your configuration.
Rock-Solid Sync: Transitions are now more reliable than ever. No matter how you trigger a custom message (Web UI or Home Assistant), the clock is guaranteed to scroll back into place perfectly.
Updated mfactoryfont.h: We have updated the font file to support new spacing and character logic. If you are flashing manually via USB, please make sure to download the latest version of the font from the repository to ensure your display looks its best!
This release introduces secure HTTPS OTA updates for ESP8266 and ESP32.
You must install this version once via USB.
After that, all future updates can be performed wirelessly from the web interface, even from your phone.
One last wired update, then freedom ;)
Note: OTA = Over-the-air updates
v1.2.2 Patch Release Highlights
1. Home Assistant Brightness Fix
• Fixed an issue where brightness values 0–15 were not saving correctly via Home Assistant.
• Now all valid brightness values persist, improving automation reliability.
2. Font Separation & Licensing Update
• mfactoryfont.h moved to the Web Installer repo.
• Font is now personal, non-commercial use only, with embedded license in the .h file.
• Firmware repo now uses a clean BasicFont fallback, ensuring compilable builds without the custom font.
Temperature Display: Resolved rendering issues with the temperature units when changing units thru the Web UI.
Memory Management: Refactored days_lookup.h and months_lookup.h to remove hardcoded delimiters, significantly reducing the Flash memory footprint.
1. New Parameter: bignumbers
You can now force the clock to use the Big Number Font for custom messages.
Via Home Assistant: Send bignumbers=1 as a POST parameter.
Via Web UI (Smart Shortcut): Wrap your number in brackets, and the UI will automatically set the flag for you.
Example: Typing [25] DEGREES sends "25 DEGREES" in the Big Numbers Font.
2. Symbol Tokens
The clock now supports "Shortcodes" that are replaced with special hardware icons/glyphs:
[C]: Displays the C (Celsius) icon.
[F]: Displays the F (Fahrenheit) icon.
[DEG]: Displays the degree symbol (˚).
°: You can also type or paste the actual degree symbol directly into the UI!
3 Month and Day look up: If you previously edited your font header file (.h) to remove these lines, v1.2.0 will overwrite those changes with the default "lined" font.
Action Required: You will need to manually re-edit the font file to remove the top-row pixels if you prefer the "clean" look.
Fixes & Improvements:
• Instant Interrupts: Added forceMessageRestart checks to all display modes (Clock, Weather, Nightscout, Countdown). Notifications now show up instantly without waiting for animations or delays to finish.
• ESP8266 Stability: Implemented SSL buffer size limits (setBufferSizes) for Nightscout/Weather fetches to prevent "Out of Memory" crashes on 8266 hardware.
• Race Condition Fix: Resolved the "Spam-to-Clock" bug where sending multiple rapid HA messages would accidentally trigger the "Message Finished" logic and return to the clock prematurely.
• Memory Management: Replaced all blocking delay() calls with non-blocking timer loops, ensuring the device remains "awake" and responsive during long display durations.
• UI Persistence: Improved the restoration logic for persistent messages; HA temporary messages now properly restore the previous background message to the buffer without forcing it to scroll immediately.
• New Status API: Introduced a robust /status endpoint providing a full JSON snapshot of the device state. This includes real-time display modes, masked security tokens, and live sensor data.
• Universal Messaging Hub: The customMessage logic has been completely refactored. The device now supports prioritized temporary messages via HTTP POST—perfect for Spotify "Now Playing," YouTube alerts, or Home Assistant notifications.
• Intelligent State Machine: Improved display logic ensures the clock correctly returns to background tasks (Weather/Nightscout) only after temporary messages have finished their programmed scroll count.
• Nightscout Integration Enhancements: Enhanced data tracking for CGM users, including "Time Since Last Reading" and trend-arrow support directly within the API for external dashboarding.
• Safari-Optimized Web UI: Refined the Advanced Settings interface with CSS fixes to ensure a consistent, pixel-perfect experience across Safari and iOS devices.
• Security Hardening (Status API): Implemented "Surgical Masking" for the new /status endpoint. Sensitive information like OpenWeather API keys and Nightscout tokens are now hidden in status reports to allow for safe sharing of device data with third-party dashboards and integrations. (Note: Full keys remain visible in /config.json and the Web UI for administrative management).
⸻
Notes:
• Integration Ready: This version is fully compatible with Home Assistant and external scripts. See the updated README for examples on how to push music titles to your display.
• Feature Update: This is a major version jump; users are encouraged to verify their Nightscout and Weather settings after flashing.
• ESP32 auto pin handling: Improved board detection and automatic MAX7219 pin configuration for ESP32 variants.
• Reliable Web UI update mechanism: Replaced size-only validation of /index.html with content comparison to ensure HTML updates correctly, even when file size remains unchanged.
• AP-mode SSID/Password bug: Saving in AP mode now preserves the correct SSID and password, preventing the device from getting stuck in AP mode.
• AP-mode loop refactor: Display animation and web server handling optimized for better responsiveness and stability.
• Web UI updates: factory_reset and upload endpoints updated to match the new design. Small UI improvements.
⸻
Notes:
• Users experiencing AP-mode issues should reselect their WiFi and re-enter their password once to restore STA mode.
• Patch release only; no new features added.
Fixed / Updated:
• AP-mode SSID/Password bug: Saving in AP mode now preserves the correct SSID and password, preventing the device from getting stuck in AP mode.
• AP-mode loop refactor: Display animation and web server handling optimized for better responsiveness and stability.
• Web UI updates: factory_reset and upload endpoints updated to match the new design.
Notes:
• Users experiencing AP-mode issues should reselect their WiFi and re-enter their password once to restore STA mode.
• Patch release only; no new features added.
Time Zone Update
•Added updated rule for: Atlantic/Canary → WET0WEST,M3.5.0/1,M10.5.0
•Ensures correct DST handling for Canary Islands region.
ESP32-S2 Adjustment
ESP32-S2 builds have been temporarily moved to HTTP-only mode.
This change improves stability due to SSL/TLS issues observed on certain boards (yes… looking at you, Wemos S2 Mini 👀).
Brand New Web UI
•Complete UI refinement for improved structure and clarity.
•Advanced settings reorganized into modular categories.
•Cleaner hierarchy and better consistency with the web installer.
•Improved micro-interactions and visual polish.
This resolves random reboots and memory exhaustion when refreshing the UI
while a weather update is in progress on ESP8266.
- ESP8266 now uses HTTP for OpenWeatherMap to avoid TLS-related OOM crashes
- ESP32 continues to use HTTPS without regression
- Verified stability during forced mid-fetch refreshes from the web UI
- Centralized device identity (hostname, AP SSID, AP password).
- Added cross-platform setupHostname() for ESP8266 / ESP32.
- Apply hostname before WiFi connection in STA and AP modes.
- Enabled WiFi.persistent(false) to reduce flash writes.
- mDNS now uses configured hostname consistently.
- Added /ip and /hostname endpoints.
- Web UI footer now displays live IP and host (or AP mode).
- Clear behavior in AP mode (shows AP IP and AP-Mode).
- Implemented safe config migration for new JSON key
- Auto-update HTML UI when version changes
- Improve USB CDC serial stability on native USB boards
- Avoid blocking serial dumps on native USB boards
- Added “Clock-Only Mode When Dimmed” feature
- Cross-board stability validation (ESP8266 / ESP32 / S2)
This update changes the root web handler to serve the configuration page strictly from LittleFS. On the first boot, the large HTML content is safely copied from the embedded PROGMEM string to a file using a streaming write loop, which prevents heap fragmentation and subsequent memory allocation failures. This guarantees stable and reliable loading of the configuration page across all devices.
The ESPTimeCast project now includes the web interface (HTML/CSS/JS) and configuration files directly in the sketch.
Key improvements:
- No separate `/data` folder or LittleFS upload is needed.
- After flashing the sketch, the device will automatically create and manage the configuration on first boot.
- The setup process is simplified: users only need to upload the main sketch for full functionality.
- Backwards-compatible with existing boards: previous configuration files will still be loaded if present.
This change makes installation faster, reduces potential errors with LittleFS uploads, and simplifies maintenance for new users.
