Blueforcer · ltloopy · Jul 7, 2026 · Jul 7, 2026 · Jul 7, 2026 · Jul 9, 2026
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -15,6 +15,7 @@
 - Features
   - [Apps](apps.md)
      - [Native Apps](apps.md#native-apps)
+     - [Timer](apps.md#timer)
      - [Custom Apps](apps.md#custom-apps)
   - [Effects](effects.md)
   - [Icons](icons.md)
@@ -33,4 +34,5 @@
      - [Drawing](api.md#drawing-instructions)
      - [Colored textfragmentss](api.md#display-text-in-colored-fragments)
      - [App switching](api.md#switch-to-specific-app)
+     - [Timer Control](api.md#timer-control)
      - [Settings](api.md#change-settings)
diff --git a/docs/api.md b/docs/api.md
diff --git a/docs/apps.md b/docs/apps.md
@@ -110,6 +110,79 @@ Due to differences in battery batches and the degradation of the cheap battery o
    - **`max_battery`**: Enter the `bat_raw` value when the battery is fully charged.  
 
 
+---
+## Timer
+
+The Timer app counts down a configurable duration with on-device and remote control. It is auto-hidden from the app rotation while idle by default, so it only takes a slot in the rotation when actively counting down, paused, or finished.
+
+#### Display
+
+- 8×8 icon on the left (the built-in colour `icon_timer` hourglass, the same glyph shown in the on-device menu; override by placing an 8×8 `/ICONS/timer.jpg` in the file manager).
+- Time text in the middle: `MM:SS` for durations under one hour, `H:MM` between 1h and 10h, `HH:MM` for 10h+.
+- A 1-pixel depleting progress bar across the bottom row (x=9..31) reflects `remaining / duration`.
+- In the `Hold` and `Re-alert` finished modes the time text blinks at ~1 Hz to signal that user action is required.
+
+#### States
+
+| State | Visible behaviour |
+| --- | --- |
+| `idle` | App shows the configured duration with no progress bar |
+| `running` | Time counts down; progress bar drains from the left (right edge anchored at column 31) |
+| `paused` | Time and bar frozen at the current value |
+| `finished` | Timer app pulls itself to the foreground, wakes the display if it was asleep, and blinks `0:00` at 500 ms with no progress bar. Depending on finished mode it auto-clears, holds, or re-alerts |
+
+#### Physical controls
+
+While the Timer app is the current app:
+- **SELECT short** — start (idle), pause (running), resume (paused), restart (finished).
+- **SELECT long** — reset to idle at the configured duration. Clears the finished screen if shown.
+
+While **any** app is current AND the timer is in the `finished` state, SELECT short and long both work as above (so you can react to the end alert without navigating back to the Timer app).
+
+#### Buzzer modes
+
+| Mode | Behaviour |
+| --- | --- |
+| `Off` | Silent in all phases |
+| `End` | Single end tone at `00:00` |
+| `Countdown` | Tick tone fires once a second for the final `timer_countdown_seconds` (dev.json, default 3), then the end tone at `00:00` |
+
+The end tone is loaded from `/MELODIES/timer_end.txt` if present, otherwise a built-in RTTTL fallback is used. The countdown tick tone uses `/MELODIES/timer_tick.txt` with the same fallback pattern.
+
+#### Finished modes
+
+| Mode | Behaviour |
+| --- | --- |
+| `Auto-clear` | Finished screen disappears after `timer_finished_hold` seconds (dev.json, default 10), then state returns to `idle` |
+| `Hold` | Finished screen stays with a blinking `00:00` until cleared (SELECT button, or a Start/Reset command — from HA, the Start/Reset buttons) |
+| `Re-alert` | Like `Hold`, but additionally re-plays the buzzer end tone every `timer_realert_interval` seconds (dev.json, default 15) |
+
+#### Setting the duration on the device
+
+While the Timer app is the current app and the timer is `idle`, **long-press SELECT** to open the **TIMER menu** (see [onscreen menu](onscreen.md)). Duration is its first item: select the `DURATION` leaf to get the `HH:MM:SS` wheel with a 1-pixel underline beneath the field you are currently editing.
+
+| Gesture | Effect |
+| --- | --- |
+| SELECT short | Cycles the active field: HH → MM → SS → HH |
+| LEFT short | Decreases the active field by 1 (wraps within the field) |
+| RIGHT short | Increases the active field by 1 (wraps within the field) |
+| LEFT / RIGHT hold | After ~500 ms triggers auto-repeat at ~4 ticks per second until released |
+| SELECT long | Saves the duration and returns to the menu list |
+
+The menu has **no idle timeout** — it never auto-exits while you are editing. The dialed value is silently clamped to `[1, timer_max_duration]` on save. Each field has independent bounds (HH 0–99, MM 0–59, SS 0–59) — incrementing seconds past 59 does **not** carry over into minutes. Use SELECT short to switch to the minutes field instead. While the timer is running or paused the `DURATION` leaf is read-only.
+
+You can also set the duration via Home Assistant or the [native API](https://blueforcer.github.io/awtrix3/#/api?id=timer-control).
+
+#### Customisation
+
+- Sounds: drop `timer_tick.txt` and `timer_end.txt` (RTTTL strings) into `/MELODIES/` via the web file manager.
+- Icon: drop an 8×8 `timer.jpg` into `/ICONS/`.
+- Behaviour knobs: see the [Timer-related dev.json keys](https://blueforcer.github.io/awtrix3/#/dev).
+
+#### Remote control
+
+The timer is fully controllable from Home Assistant (when `HA_DISCOVERY` is enabled — it exposes eight entities under the device card) and from the native MQTT/HTTP API. See [Timer Control](https://blueforcer.github.io/awtrix3/#/api?id=timer-control) for the API surface.
+
 ---
 # Custom Apps
 

diff --git a/docs/dev.md b/docs/dev.md
@@ -40,6 +40,24 @@ The JSON object has the following properties:
 | `new_year` | boolean | Displays fireworks and plays a jingle at newyear. | false |
 | `swap_buttons` | boolean | Swaps the left and right hardware button. | false |
 | `ldr_on_ground` | boolean | Sets the LDR configuration to LDR-on-ground. | false |
+| `show_timer` | boolean | Master enable for the [Timer app](https://blueforcer.github.io/awtrix3/#/apps?id=timer). When `false`: app removed from rotation, the 10 Timer HA entities not published, `POST /api/timer` and the `{prefix}/timer` MQTT topic ignored, any running timer reset. On the `true → false` transition the firmware publishes empty retained discovery payloads so HA prunes the stale entities. Also exposed via `/api/settings` (`TIMER` key) and the on-device **APPS** menu. | `true` |
+| `timer_max_duration` | integer | Upper bound on accepted `duration` values (range 1–604800). Out-of-range duration commands are rejected, not clamped. Also caps the HH/MM/SS wheels in the Timer-app config mode. Promoted to `{prefix}/timer` / `/api/timer`. | `86400` |
+| `timer_remaining_publish_interval` | integer | Seconds between `timer_rem` republishes while Running (range 1–60). Drives the HA `{id}_timer_rem` sensor cadence. | `1` |
+| `timer_finished_hold` | integer | Seconds the `00:00` Finished screen stays visible in Auto-clear finished mode (range 1–300). | `10` |
+| `timer_realert_interval` | integer | Seconds between buzzer re-fires in Re-alert finished mode (range 5–300). | `15` |
+| `timer_countdown_seconds` | integer | Tick window (seconds before zero) in Countdown buzzer mode (range 0–30). | `3` |
+| `timer_icon_idle` | string | Bare icon name (resolved against `/ICONS/<name>.{jpg,gif}`) for the Timer app's **Idle** state. Also used as fallback for any other state with an empty slot. Empty/absent = no override of the NVS-stored value. Capped at 32 chars. **Overrides NVS on every boot.** | `""` |
+| `timer_icon_running` | string | Same, for the Running state. Empty falls back to `timer_icon_idle`. | `""` |
+| `timer_icon_paused` | string | Same, for the Paused state. Empty falls back to `timer_icon_idle`. | `""` |
+| `timer_icon_finished` | string | Same, for the Finished (blinking `0:00`) state. Empty falls back to `timer_icon_idle`. | `""` |
+| `timer_melody_tick` | string | Bare melody name (resolved against `/MELODIES/<name>.txt`) for countdown beeps. Empty resets to default `"timer_tick"`. | `"timer_tick"` |
+| `timer_melody_end` | string | Bare melody name for the end melody. Empty resets to default `"timer_end"`. | `"timer_end"` |
+| `timer_bar_enabled` | boolean | Show/hide the Running/Paused progress bar. | `true` |
+| `timer_icon_enabled` | boolean | Show/hide the timer icon; when hidden the time text and bar reflow to the full panel. | `true` |
+| `timer_bar_color` | integer | Hex color (0..0xFFFFFF) for the progress bar (foreground). `0` follows `TEXTCOLOR_888`. | `0` |
+| `timer_bar_bg_color` | integer | Hex color (0..0xFFFFFF) for the progress-bar **background track** drawn behind the bar. `0` = black = no track (literal, not a sentinel). | `0` |
+| `timer_sync_follow` | boolean | When `true`, this clock obeys inbound timer-sync packets it is targeted by (multi-device sync follow consent gate). Local identity — never propagated. | `true` |
+| `timer_sync_targets` | string | Whom this clock commands on a local timer action: `""` (sync off), `all`, or a comma list of peer device IDs (e.g. `awtrix_ab12,awtrix_cd34`). Local identity — never propagated. | `""` |
 
 
 #### Example:

diff --git a/docs/onscreen.md b/docs/onscreen.md
@@ -4,6 +4,8 @@ AWTRIX 3 provides a **onscreen menu** directly on your clock.
 Press and hold the middle button for 2 seconds to access the menu.   
 Navigate through the items with the left and right buttons and choose the submenu with a push on the middle button.  
 Hold down the middle button for 2s to exit the current menu and to save your setting.  
+
+Any menu label too wide for the 32px panel **scrolls**: it holds briefly at the left so you can read the beginning, then scrolls left and loops continuously while the item stays selected (the same scroll speed as notifications and apps). Labels that fit stay centered and still. The scroll restarts from the left whenever you move to another item or re-open the menu.
 
 !>  You can easily turn your AWTRIX matrix on or off by simply double-pressing the middle button if youre not in Menu.
 
@@ -18,6 +20,7 @@ Hold down the middle button for 2s to exit the current menu and to save your set
 | `DATE` | Allows selection of date format. |
 | `WEEKDAY` | Allows selection of start of week. |
 | `TEMP` | Allows selection of temperature system (°C or °F).  |
+| `TIMER` | Configure the [Timer app](apps.md#timer) via a drill-in list: left/right walks the items (wrapping), a short press opens the highlighted item's editor, a long press steps back up. Also reachable by long-pressing the middle button from an idle Timer app (a long press out of the list then returns you there). Items: `DURATION` (HH:MM:SS wheel — short press cycles the field, left/right adjusts with hold-to-repeat, long press saves; read-only while the timer runs), `BUZZER` (Off/End/Countdown), `COUNTDOWN` (beep window, 0–30 s), `FINISH` (`CLEAR`/`HOLD`/`RE-ALERT`), `CLEAR DELAY` (1–300 s), `RE-ALERT INTERVAL` (5–300 s), `ICON` and `PROGRESS BAR` (show/hide toggles), `MAIN` (back to the main menu). Mode changes apply immediately as you scroll; everything persists when you leave the list. |
 | `APPS` | Allows to enable or disable internal apps  |
 | `SOUND` | Allows to enable or disable sound output   |
 | `UPDATE` | Check and download new firmware if available. |