Ultimate Timer

Documentation

Document	Description
codingRules.md	Coding conventions and rules for this project
menuStructure.md	Menu layout, navigation, and event handling specification
colorSettings.md	Display color theme and UI color rules
DisplayDriverClass.md	Technical and API documentation for the reusable display driver class
InputClass.md	Technical and API documentation for the reusable encoder + auxiliary button input class
WifiSettings.md	Technical and API documentation for the reusable WiFi settings struct
WiFiManagerExt.md	Technical and API documentation for the reusable WiFi manager class
webUI.md	Web UI architecture, behavior, menus, and API endpoints
24hTimer.md	24 hour timer, behavior, menus, and API endpoints

Disclaimer

This software and/or hardware is developed incrementally. That means I have no clear idea how it works (though it mostly does).

If you have questions about this software, it will probably take you just as long to figure things out as it would take me. So I’d prefer that you investigate it yourself.

Having said that Don’t Even Think About Using It.

Seriously. Don’t.

Building this design may injure or kill you during construction, burn your house down while in use, and then—just to be thorough—explode afterward.

This is not a joke. This project involves lethal voltages and temperatures. If you are not a qualified electronics engineer, close this repository, step away from the soldering iron, and make yourself a cup of tea.

If you decide to ignore all of the above and build it anyway, you do so entirely at your own risk. You are fully responsible for taking proper safety precautions. I take zero responsibility for anything that happens—electrically, mechanically, chemically, spiritually, or otherwise.

Also, full disclosure: I am not a qualified electrical engineer. I provide no guarantees, no warranties, and absolutely no assurance that this design is correct, safe, or suitable for any purpose whatsoever.

What it is

ESP32 cyclic and 24h timer for a 2.4 inch SPI TFT + EC11 rotary encoder module with the Piggy Back Board attached.

Confirm to codingRules

Read codingRules.md

Comply to Menu, and Event rules

read menuStructure.md

Comply to Color Settings Display

read colorSettings.md

Implemented structure

• Local TFT menu
• Main menu splits timer editing into Cyclic Timer Settings and 24h Timer Settings
• Rotary encoder editing
• Save Profile confirmation via [No] [Yes] buttons for the active profile
• New Profile name entry with character-by-character editing
• JSON profiles in LittleFS
• JSON cyclic profiles in LittleFS (stored as <name>.json)
• JSON 24h profiles in LittleFS (stored as <name>24h.json)
• Trigger and reset inputs
• Output control with selectable polarity
• Web UI Timer Settings split into two submenu items:
  • Cyclic Timer Settings for cyclic timer editing
  • 24h Timer Settings for full 24h timer configuration (including quarter-hour editing)
• Web UI action buttons (Start/Stop/Reset) hidden for 24h timer profiles
• Web UI automatically stops timer when a menu tile opens and automatically starts it again when all menu tiles are closed
• Web UI shows a save warning when Auto Save Profile is No and settings are saved
• Output control with selectable polarity
• Web UI with matching timer settings
• Web UI live-apply only for Timer Settings (apply immediately, save only on explicit save)
• Web UI System settings are changed only via explicit Save (no live-apply)
• Web UI Cancel buttons always close the current sub-screen without saving
• Web UI Save Profile uses the active profile (no editable profile-name field in Save Profile tile)
• Web UI Save Profile button remains enabled while timer is running
• Web UI System tile has a Theme selector only (no extra read-only Theme display field)
• Web UI status refresh always updates Timer Screen, but does not overwrite fields in an open edit tile
• Web UI header shows (not saved) after active profile name when Timer Settings are changed but not saved to profile
• System settings stored separately from profile timer fields
• Profile dropdown refresh keeps current selection
• repeatCount = 0 support for infinite cycles
• TFT status updates while running with partial line redraw (no full-screen flicker)
• Build-time configuration through build_flags in platformio.ini
• Optional color test mode through TEST_COLOR_PATERN
• Reusable InputClass for EC11 encoder + auxiliary button (PIN_KEY0) with configurable pins, press thresholds, and full in-class event/state logic
• Reusable DisplayDriver class for the current ST7789 hardware, with generic init, theme, tile, header, button, and screen helpers; legacy free-function wrappers remain for existing firmware call sites

Local TFT controls

• Timer screen shows:
  • cyclic timer: State, On time, Off time, Output, and Cycles
  • 24h timer: State, Next Change Between, Last State Change (ON/OFF), Next State Change (OFF/ON), Output (no Cycles tile)
• Output line includes a live countdown timer (MMM:SS) to the next ON/OFF switch while running/paused.
• For cyclic timers, when Warp Speed is enabled, elapsed runtime advances at 60x speed (1 real second = 60 countdown seconds) for phases using s or Min, while the countdown format remains MMM:SS.
• If either cyclic phase unit is Min, warp acceleration remains active across both phases.
• For cyclic timers, the Cycles tile always keeps the cycle counter visible; when Warp Speed is enabled it also shows Warp mode near the right side of the same tile.
• For 24h timers, the Next Change Between tile shows hh:mm - hh:mm for the next possible switch span.
• When Warp Speed is enabled, the TFT header keeps showing the warped clock (HH:MM) even if WiFi is disconnected.
• Open the local menu with a long press on the rotary encoder.
• Select menu options with a short press on the rotary encoder.
• Menu navigation is clamped (no wrap-around).
• In Manual trigger mode, timer action row includes Start, Stop, Reset.
• In External trigger mode, the action row is replaced by External Trigger text (no local start/stop/reset actions).
• For 24h timer profiles, local Start, Stop, and Reset actions are hidden.
• Menu list items are rendered left-aligned with a two-character prefix area: selected item is shown as > Item <, unselected items use leading spaces so text starts at the same position.

Main menu options

• Cyclic Timer Settings
• 24h Timer Settings
• Save Profile
• Load Profile
• New Profile
• Delete Profile
• System Settings
• Exit (return to status screen)

Press duration build flags

The press durations are configurable in platformio.ini via build_flags:

• ENCODER_SHORT_PRESS_MS
• ENCODER_MEDIUM_PRESS_MS
• ENCODER_LONG_PRESS_MS
• BUTTON_SHORT_PRESS_MS
• BUTTON_MEDIUM_PRESS_MS
• BUTTON_LONG_PRESS_MS

Current configured values in this repository:

• ENCODER_SHORT_PRESS_MS=50
• ENCODER_MEDIUM_PRESS_MS=1000
• ENCODER_LONG_PRESS_MS=2000
• BUTTON_SHORT_PRESS_MS=50
• BUTTON_MEDIUM_PRESS_MS=1000
• BUTTON_LONG_PRESS_MS=2000

Notes

- Cyclic profile files are stored as `/<profileName>.json` (no suffix)
- 24h profile files are stored as `/<profileName>-24h.json` (automatic "-24h" suffix)

• Profile files store: timerType, onTimeValue, offTimeValue, onTimeUnit, offTimeUnit, repeatCount, triggerMode, triggerEdge, and the 24h quarter-hour states
• System-level settings such as output polarity, lock input during run, auto-save profile, theme color, and encoder direction are stored separately in Preferences/NVS
  • Display rotation is a system setting in System Settings and is persisted in Preferences/NVS (values: 1 or 3)
  • Built-in profiles default (cyclic) and default-24h (24h) are always available in the Load Profile list
  • Built-in profiles default and default-24h cannot be deleted and are hidden from the Delete Profile list
  • If the active profile is deleted, firmware automatically loads the corresponding default profile based on timer type
• The fallback access point is open (no password)
• If no WiFi credentials are found (or STA connection fails), use the local WiFi Setup menu: scan nearby APs, select SSID with the rotary encoder, then enter the WiFi password via rotary text input and save/apply.
• At startup, Serial Monitor prints WiFi connected. IP address: <ip> once when STA connects, or No WiFi Connection if no STA link is established within the startup connection window.
• The local UI currently includes timer and profile management
• Local TFT WiFi credential editing is available through the rotary menu
• If LittleFS marker file /firstBoot exists at startup, firmware skips WiFi startup for that boot, erases stored STA credentials, shows firstBoot / WiFi init skipped, and removes the marker file

TFT display behavior

• All TFT text is rendered with the built-in monospaced font.
• Header uses the same calibrated blue background as selected action buttons.
• Header right side shows No WiFi when disconnected, or HH:MM when WiFi and NTP time are available.
• Header time is refreshed across all screens with a lightweight header-only redraw (at least once per 10 seconds while NTP time is valid).
• Selected action button is blue; not-selected action buttons are light gray.
• Button text is rendered in the calibrated high-contrast mapping used by this panel.
• Status screen redraws only changed lines for smooth runtime updates.
• In button-mode field input, buttons are centered and drawn directly on the black background near the bottom (no tile behind the button group).

TEST_COLOR_PATERN mode

• Add -D TEST_COLOR_PATERN to build_flags in platformio.ini to enable test mode.
• In this mode, firmware only initializes the display and shows a color palette test screen.
• Timer/menu/WiFi runtime logic is skipped in this mode.

TFT wiring/configuration hints

• This project currently targets an ST7789-based 2.4 inch SPI display module.
• Required signals include power, CS, DC, RST, BL, plus SPI SCK and MOSI.
• Rotation is configurable in local System Settings via Display Rotation (1 or 3).