esphome-samsung-vfd/CLAUDE.md

CLAUDE.md

ESPHome external component for a Samsung 2×20 serial VFD (5 V TTL, 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_().
• 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. Only ESC @, 0C and 0B are known to work.

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.