mangavalkandClaude Opus 5.5
ba83275d88
The reference build now uses a D1 R1. The example config targets esp8266/d1 and sends on GPIO2 (header pin D9, UART1 TX), which leaves UART0 free for the USB logger. The README wiring and signal-level notes are updated to match. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
76 lines
3.7 KiB
Markdown
76 lines
3.7 KiB
Markdown
# 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.
|