esphome-samsung-vfd/CLAUDE.md

CLAUDE.md

ESPHome external component for a Samsung 20L203 2×20 serial VFD (RS-232 input, write-only, factory default 9600 8N1). An ESPHome server consumes it from git (https://mangavalk.com/mangavalk/esphome-samsung-vfd, a self-hosted server, so type: git with a URL, not github://). The layout must stay components/samsung_vfd/ at the repo root.

Layout

• components/samsung_vfd/__init__.py: the config schema (size, brightness, code table, international charset, user characters), codegen and every samsung_vfd.* action registration.
• components/samsung_vfd/samsung_vfd.h: the protocol constants, enums, the class and the templated action classes.
• components/samsung_vfd/samsung_vfd.cpp: the shadow buffer, word wrap, UTF-8 → display byte encoding, settings re-apply and the raw commands.
• components/samsung_vfd/charmaps.h: generated by python tools/gen_charmaps.py; don't edit it by hand.
• docs/20L203DA12-datasheet.pdf: the command set (section 5.4), jumpers, wiring and the CG-ROM tables (section 6). Check it before changing the protocol.
• case/vfd-case.scad: parametric OpenSCAD desk case (body, bezel, base) for the display and a WEMOS D1 R1. After any change, run all the check_* parts (each must be empty or zero-volume) and re-export case/stl/*.stl. On Windows, call openscad.com for console output.
• examples/samsung-vfd.yaml: the full reference device config. It pulls the component from git; for local work, switch to the commented type: local, path: ../components source.

Design rules

• lines_ is the screen as it should be, each line padded to exactly cols_. Every change goes through flush_(). It rebuilds the payload, returns early if the payload equals last_payload_, and otherwise sends 0B (home) plus the payload. Don't clear before redrawing: that causes flicker.
• Anything that changes the screen out of band (clear, init, raw writes, CAN, user-character changes, the self-test) must call invalidate_() so the next flush retransmits.
• Settings (brightness, blink/on, annunciators, code table, charset, user characters, mode) are stored in members and re-sent by apply_settings_() after ESC @ (reinit()) and after the self-test. A new setting must be added there too.
• Text sent to the display is one byte per character; always pass it through encode(), which uses the current code table, then strips accents, then falls back to ?.
• The display boots in overwrite mode: the cursor wraps from the end of line 1 to line 2 and from the end of line 2 back home, and nothing scrolls. The buffered text API depends on this; the scroll modes are only for raw writes.
• The RXD input is RS-232. The reference build uses a MAX3232 (no inversion in config); a directly wired ESP8266 pin needs inverted: true on the UART TX pin. Baud rate and parity come from the board's jumpers, so they are not validated by the component.
• User characters: up to 4, codes 0x20–0x7E. Each is 5 column bytes, bit 6 = top row. pattern_to_columns() must turn the datasheet's $ example into 12 2A 7F 2A 24.

Checking changes

Hardware isn't available to Claude, so validate with ESPHome itself:

pip install esphome
cd examples
# switch external_components to the local source first
esphome config samsung-vfd.yaml     # schema check
esphome compile samsung-vfd.yaml    # full C++ build

On Windows, run the compile from PowerShell or cmd, not Git Bash: the ESP-IDF installer refuses MSYS shells. secrets.yaml is gitignored. Copy examples/secrets.yaml.example to examples/secrets.yaml to compile.

Follow ESPHome C++ style: this-> on members, a trailing _ on protected members, and the esphome::samsung_vfd namespace.