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.