esphome-samsung-vfd/CLAUDE.md

CLAUDE.md

ESPHome external component for a Samsung 20L203 2×20 serial VFD (RS-232 input, 9600 8N1, write-only). It is consumed from git by an ESPHome server through external_components: source: github://..., so the layout must stay components/samsung_vfd/ at the repo root.

Layout

• components/samsung_vfd/__init__.py: config schema, codegen and the action registrations (print, printf, clear, home).
• components/samsung_vfd/samsung_vfd.h: the class, the control-byte constants and the templated action classes.
• components/samsung_vfd/samsung_vfd.cpp: the shadow buffer, word wrap, UTF-8 → single-byte sanitising and flush_().
• docs/20L203DA12-datasheet.pdf: the command set (section 5.4), jumpers, wiring and the character tables. Check it before adding protocol features.
• examples/samsung-vfd.yaml: the full reference device config. It pulls the component from GitHub; 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 display out of band (clear, init) must reset last_payload_ so the next flush retransmits.
• Text sent to the display is one byte per character; always pass it through sanitize_().
• Keep the protocol constants in samsung_vfd.h. 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. A full-screen redraw is therefore 0B plus rows × cols characters.
• The RXD input is RS-232. The reference build uses a MAX3232 (no inversion in config); a directly wired ESP32 pin needs inverted: true on the UART TX pin.

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

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.