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 ESP32 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.