docs: plasma bitmap mode (ESC P) + correct panel geometry to 128x32

The display is fully dot-addressable: document the ESC P graphics write
(row format, MSB-left, changed-row streaming as Red Planet does it, and the
~0.77s full-frame budget at 9600 baud) per vRIO PlasmaProtocol.cs, recovered
from the Tesla 4.10 sources + firmware dump. Fixes the guide''s 112x32 guess
(the legacy auto-center pivot x=56 sits left of the true 128px center) and
notes the firmware cursor ranges (x 0-127, y 0-31).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Cyd
2026-07-31 20:34:25 -05:00
co-authored by Claude Fable 5
parent 94d32a1f06
commit 66c3cbdb57
+48 -14
View File
@@ -80,32 +80,66 @@ lamp per 25 ms** (~40/s). Practical consequences:
## The plasma display model
The plasma/VFD is a **112 × 32 pixel** text display on its own serial port
(so text updates never contend with the input link). Two glyph sizes exist:
The plasma is a **128 × 32 dot-matrix panel** on its own serial port at 9600
8N1 (so display updates never contend with the input link). It is fully
dot-addressable: it has a text mode (cursor + fonts + attributes) **and a raw
bitmap mode** (`ESC P` graphics write — see
[Bitmap graphics](#bitmap-graphics-esc-p)). The command set is documented in
vRIO's `VPlasma.Core/Protocol/PlasmaProtocol.cs`, recovered from the Tesla
4.10 sources and the display firmware dump.
Text mode has two glyph sizes:
| Font | Cell | Fits per line | Auto-selected when |
|---|---|---|---|
| large (font 5) | 10×14 px | ~11 chars | text ≤ 9 chars |
| small (font 2) | 5×7 px | ~22 chars | text 1020 chars (longer is truncated to 20) |
| large (font 5) | 10×14 px | ~12 chars | text ≤ 9 chars |
| small (font 2) | 5×7 px | ~25 chars | text 1020 chars (longer is truncated to 20) |
What the endpoint exposes (v1):
- **`plasma text <text>`** — auto-fit: short text renders large, longer text
small, centered on the display (the `PlasmaPosText` behavior the original
games used). This is the right default for callsigns, scores, and status
words.
- **`plasma text <x> <y> <text>`** — explicit cursor position in **pixels**
(top-left origin). You choose the position; the font still auto-fits by
length. Use this to keep two fields on screen at once (e.g. callsign top
line, score bottom line: `plasma text 2 2 "VIPER 1-1"` +
`plasma text 2 18 "SCORE 4200"`).
games used; its pivot is x=56, faithfully a touch left of the true 128-px
center). This is the right default for callsigns, scores, and status words.
- **`plasma text <x> <y> <text>`** — explicit cursor position in **pixels**,
top-left origin; the firmware accepts x 0127, y 031. You choose the
position; the font still auto-fits by length. Use this to keep two fields on
screen at once (e.g. callsign top line, score bottom line:
`plasma text 2 2 "VIPER 1-1"` + `plasma text 2 18 "SCORE 4200"`).
- **`plasma clear`** — blank the display.
Text is **Latin-1** (one byte per char) — don't send UTF-8.
Not exposed through the endpoint yet (the underlying `PlasmaCommands` port has
them, so they're a small extension when needed): explicit font/attribute
selection and box draw/fill.
Not exposed through the endpoint yet (small extensions when needed): explicit
font/attribute selection, box draw/fill, and the bitmap mode below.
### Bitmap graphics (`ESC P`)
The display accepts **raw bitmap rows** — this is how the native Red Planet
game draws everything (it renders into a local 1-bpp buffer and streams the
*changed* rows). The wire command:
```
ESC P s y x w h data…
```
`s` = screen (single-screen hardware, ignored), `y` = top row (031),
`x` = left **byte column** (015), `w` = bytes per row, `h` = rows, followed
by `w×h` data bytes, **MSB = leftmost pixel**. The native game always sends
whole rows: `x=0, w=16, h=1` — 16 bytes covering one full 128-px row.
Budget the bandwidth: a full-frame repaint is 32 rows × (7-byte header +
16 data bytes) ≈ 740 bytes ≈ **0.77 s** at 9600 baud. That's why the native
game diffs and streams only changed rows — an animation that touches a few
rows per tick is smooth; full-frame repaints are ~1 fps. Text mode is far
cheaper for text; reserve bitmaps for logos, custom gauges, and icons.
Status: the hardware and the vPlasma emulator fully support `ESC P`, but
RIOJoy's `PlasmaCommands` port and the feedback endpoint don't expose it yet.
The natural extension is a line command (e.g.
`plasma row <y> <32-hex-digit row>` or a base64 block form) — if an
integration needs it, that plus a `PlasmaCommands.GraphicsWrite` builder is a
small, self-contained addition.
### Update semantics