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, esp32 (OTA to 10.1.1.198) and esp32_usb (COM11). 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.
• After any change, build both targets: pio run -e nano -e 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 Nano and the ESP32 share one UART. On the ESP32, Serial is the display link, so don't print debug output on the ESP32's Serial: the Nano would read it as commands. The Nano ignores unknown command bytes, but text that starts with s/S/F/D/P/B/R/T will be run as a command.
• 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: bootloader, then begin() flips every dot on and off. Any data the ESP sends during that time is lost. The Nano keeps no state over a power cycle except the flip time in EEPROM.
• Hardware is not available here. Builds can be checked, but runtime behaviour can't.

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

• 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 sends one frame per second, ending with D.
• 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 doesn't send an acknowledgement. Whether the Nano's TX is wired to the ESP's RX is unknown, so don't make the ESP wait for replies.
• To test the parser without hardware, compile main.cpp with g++ (Strawberry Perl provides it at C:\Strawberry\c\bin) and mock headers for Arduino.h, EEPROM.h and BROSE9323.h.

Git

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