Flipdot-display/CLAUDE.md

# Flipdot display: notes for Claude

A PlatformIO project with two firmware targets for an 84×19 Brose flipdot clock.
See README.md for the overview.

## Layout and build

- `platformio.ini` has the environments `nano`, `nano_ota`, `esp32` (OTA to 10.1.1.198),
  `esp32_usb` (COM11), and the PC test environments `test_nano` and `test_esp32`. The
  sources are split with `build_src_filter` (`src/nano/`, `src/esp32/`).
- `lib/BROSE9323/` is the shared driver. Its behaviour depends on build flags set in
  `platformio.ini`, not in the header:
  - `ESPSERIAL` (ESP32): draw calls become serial commands.
  - `FLIPDOT_PLCC_ADAPTER` (Nano, optional): alternative pinout.
- PlatformIO CLI is not on PATH. Run `~/.platformio/penv/Scripts/pio.exe run` (Git Bash)
  or `$env:USERPROFILE\.platformio\penv\Scripts\pio.exe run` (PowerShell).
- If an ESP32 build fails with `No module named 'intelhex'`, run
  `~/.platformio/penv/Scripts/python.exe -m pip install intelhex`.
- `nano_ota` flashes the Nano over WiFi: `tools/nano_net_upload.py` (STK500v1 over TCP)
  talks to `NanoFlashBridge` on the ESP32 (port 2323). The uploader first sends
  `FLASH <baud>\n`. The ESP power cycles the Nano (plus an optional reset pulse on
  `NANO_RESET_PIN`), answers `OK\n`, then passes the bytes through at that baud rate.
  `--baud=auto` tries 57600 (old ATmegaBOOT, which also starts after a power cycle), then
  115200 (Optiboot, which only starts after a reset-pin reset, so it needs `NANO_RESET_PIN`).
  avrdude 6.3's `net:` port is broken on Windows (`ser_drain()` fails), which is why the
  uploader is a Python script.
  The uploader only uses the Python standard library. Test it against a simulated
  bootloader before changing it.
- After any change, build both targets (`pio run`) and run the tests
  (`pio test -e test_nano -e test_esp32`).

## Constraints

- **Nano RAM is tight** (ATmega328P, 2 KB). The frame buffers are allocated with
  `calloc`. Avoid `String`, large stack buffers and new globals in Nano code. Put constant
  data in `PROGMEM`.
- The ESP32 talks to the Nano on `Serial2` (owned by `NanoLink`, GPIO 17 TX / GPIO 16 RX).
  `Serial` (UART0/USB) is free for debug output. Never write debug text to `Serial2`: the
  Nano runs lines that start with s/S/F/D/P/B/R/T as commands.
- Open hardware TODOs are listed in the README `TODO` section. Update it when one is done.
- `src/esp32/secrets.h` holds the real credentials and is gitignored. Never commit it.
  Add new secrets to `secrets.example.h` as placeholders.
- The relay (ESP32 GPIO 13, `LOW` = on) powers both the panels and the Nano. Each time it
  switches on, the Nano cold-boots and then sends `READY`. `NanoLink::on()` waits for
  that message, at most `NANO_BOOT_TIMEOUT`. The timeout also covers the case where the
  Nano's TX isn't wired to the ESP's RX.
- `NanoLink::off()` ends `Serial2` and sets its TX pin to input. Otherwise the idle-high TX
  line powers the Nano through its RX pin. Never send display commands while
  `NanoLink::isOn()` is false (`DisplayController` takes care of this).
- The Nano keeps no state over a power cycle except the flip time in EEPROM. The driver
  forces a full redraw on the first `display()` after boot (`_force_next`).
- Hardware is not available here. Builds can be checked, but runtime behaviour can't.

## Nano serial parser (`src/nano/main.cpp`)

- Files: `main.cpp` (setup/loop, refresh), `config.h` (all constants and debug
  defines), `command_parser.*` (protocol, one method per command), `settings.*` (EEPROM).
- Line based and non-blocking: bytes are collected into a 64-character buffer and a
  command runs when `\n` arrives. Bitmap (`B`) pixel data is the exception. It is drawn
  while it arrives, so it can be longer than the buffer. Keep `loop()` free of busy-waits.
- A full redraw (`display(true)`) blocks for about 0.5 s, which overflows the 64-byte
  serial receive buffer. Only run it when no data is expected: right after a `D`, or after
  2 s with no serial data. The ESP only sends a frame (ending with `D`) when the screen
  changes, mostly once a minute.
- Flip time is stored in EEPROM as a magic word at address 0 and a `uint16_t` at
  address 2. Values outside 50–2000 µs are rejected.
- The Nano only replies `READY` (at boot) and `ERR: ...`. There is no per-frame
  acknowledgement. Whether the Nano's TX is wired to the ESP's RX is unconfirmed, so every
  wait for a reply needs a timeout.
- Unit tests: `pio test -e test_nano` runs `test/test_nano/` on the PC with the fakes in
  `test/mocks/` (Arduino, EEPROM, and a `BROSE9323` that records calls). It needs gcc on
  PATH (Strawberry Perl provides it at `C:\Strawberry\c\bin`). Add a test for every
  protocol change. The mocks only implement what the Nano code uses, so extend them when
  new Arduino or driver functions are called.
- The board environments have `test_ignore = *`, so test firmware is never uploaded. Plain
  `pio test` runs nothing; always pass `-e test_nano -e test_esp32`.

## ESP32 structure (`src/esp32/`)

- Folders: `logic/` (pure C++, no Arduino includes, tested in `test/test_esp32`),
  `display/` (frames and bitmaps), `nano_link/` (relay, serial, flash bridge), `net/`
  (WiFi/OTA, Home Assistant). Includes are relative to `src/esp32` (`-I src/esp32`), e.g.
  `#include "logic/schedule.h"`.
- `DisplayController` holds the display logic and only uses the `DisplayPower` and
  `Frames` interfaces. Put new behaviour there, behind those interfaces, so it stays
  testable. `logic/` must not include Arduino headers, or `test_esp32` stops building.
- All settings are in `config.h`. Keep it free of Arduino types for the same reason.
- Frames are only sent when the screen changes. The schedule uses 08:00 as the start of
  the day on purpose (that is what the old code did, and the README documents it).
- Home Assistant switches are not optimistic: callbacks must call `sender->setState()`.
  The unique ids `FlipDotDisplayClock` / `FlipDotDisplayPower` and `HA_DEVICE_ID` must stay
  the same, or Home Assistant creates new entities.

## Keeping ESP32 OTA alive (most important requirement)

- The user never wants to need USB for the ESP32 again. Any change must keep OTA working,
  also when the new code crashes or hangs.
- `system/firmware_guard.cpp` overrides the Arduino core's weak `verifyRollbackLater()`
  (C linkage) to return true. A new OTA image stays `PENDING_VERIFY` until it has run
  `FIRMWARE_VALID_TIME` with WiFi. Any restart before that makes the bootloader roll back.
  Check with `nm` that the strong symbol is linked after toolchain or core updates.
- The task watchdog (`WATCHDOG_TIMEOUT_S`) covers `loop()`. ArduinoOTA's `onStart` stops
  it, because an upload blocks `loop()`. Never block `loop()` for 30 s or longer.
- The crash counter lives in `RTC_NOINIT_ATTR` memory. Decisions are in
  `logic/boot_policy.*` (tested). Safe mode runs only WiFi + OTA.
- Keep `otaLoop()` and `firmwareGuardLoop()` at the top of `loop()`, before anything that
  can return early or block.

## Git

- Remote: https://mangavalk.com/mangavalk/Flipdot-display.git, branch `main`.