Auxiliary Display
Spec hygiene (canonical-spec.md rule 1). This document does not restate canonical values (panel size, pixel count, color, current draw). Those live in the Canonical Hardware Specification. Any value inline is a bug — fix it.
Bench note (GWP-619, 2026-07-02). The physical SSD1322 module on the bench arrived strapped for an 80xx/8080-style parallel bus, while the canonical docs still specify Pico-driven SPI. We achieved first light and UART-driven layouts by matching the scratch Pico firmware to the as-shipped board instead of moving the SMD mode jumper. See
2026-07-02-oled-8080-bench-bringup.md(deleted 2026-07-29; recover from git history). This note does not supersedeCLAUDE.md; if 8080 becomes product direction, update the parent canonical spec and ADR-0015 in the same reconciliation PR.
The CIPHER-LINE is a small auxiliary OLED mounted above the key plate. It is the exclusive home for the Cipher voice and absorbs utility surfaces that don’t belong on the primary 80×25 grid:
- battery glyph, mission/gameplay timer, mode chip, TERM hint
- Cipher scrollback (current fragment + previous echo)
- contextual surface (seed capture, gameplay sub-timer, mission phase meta, linked-deck status)
CIPHER glyphs render here — never on the primary-display.md (one sanctioned exception: the Null cartridge, per canonical-spec.md Spec Hygiene Rule 6 + ADR-0015 §3a).
For module class, pixel dimensions, and color, see Canonical Hardware Specification — Display auxiliary row.
Module
Section titled “Module”3.12” OLED, SSD1322 controller, 256×64 pixels, yellow pixel element (warm-phosphor family, close to the AMBER #E6A020 default of the main display per ADR-0036; hardware-fixed yellow, not retinted when the main display swaps to WHITE / GREEN), 16-pin breakout with strap-selectable interface mode. Sourced from Waveshare direct (sourcing-guide.md line 2b). The yellow-pixel variant is less commonly stocked than the white-pixel variant — verify yellow is in cart before checkout. White is acceptable as a bench-stand-in for mechanical fit + bus validation only; it does not ship in any build Josh signs off on.
Layout
Section titled “Layout”Press Start 2P 8×8 native, rendered 1:1 on the 256×64 panel = 32 character cells wide × 8 rows tall, partitioned into 4 logical rows of ~32 chars each (each logical row = 16 panel-pixel rows = 2 × 8 source px tall):
| Logical row | Purpose | Owner |
|---|---|---|
| Row 1 | Status strip — battery glyph, mission/gameplay timer, mode chip (DEV / PROD / LINK), TERM-hint chip. | nOSh runtime |
| Row 2 | CIPHER scrollback — current fragment (the live utterance). | nOSh runtime generator + cartridge vocabulary |
| Row 3 | CIPHER scrollback — previous echo (the prior utterance, fading). | nOSh runtime generator + cartridge vocabulary |
| Row 4 | Contextual surface — seed capture (when seed-display mode active) / gameplay sub-timer / mission phase meta / linked-deck status. | nOSh runtime, mode-switched by cart / phase |
Cartridges do not address CIPHER-LINE rows by coordinate. They call the FFI primitives in ADR-0015 §4 (cipher-emit, cipher-push-event, cipher-extend-grammar, cipher-set-mode-weights, aux-timer-start, aux-timer-stop, aux-show-seed, aux-status-render) and the runtime places text in the right row.
Interface
Section titled “Interface”Per ADR-0017 (2026-04-24), the SSD1322 panel bus is driven by the Pi Pico 2 coprocessor — not by the Pi Zero 2 W’s SPI0. The current canonical direction is Pico-driven SPI; the GWP-619 bench note records an as-shipped 8080 harness pending reconciliation. The Pi sends high-level OLED commands (OLED_SET_ROW, OLED_SCROLL_ROW, OLED_FILL, OLED_CLEAR) over UART0; the Pico owns the physical display bus and executes the ticker scroll on its own timer. Animation cadence is rock-steady regardless of Pi rendering load.
The pre-ADR-0017 Pi-side pin assignment (GPIO10/11/8/25/24) is superseded and retained only as design-history context inside ADR-0015. The Pi’s SPI0 is freed for a future peripheral.
Canonical SPI path, pending F2 pin finalization:
| Signal | Pico 2 GPIO | Notes |
|---|---|---|
| MOSI | TBD at F2 firmware bring-up | One of Pico’s SPI MOSI-capable pins. |
| SCLK | TBD at F2 firmware bring-up | One of Pico’s SPI SCLK-capable pins. |
| CS | TBD at F2 firmware bring-up | Any GPIO. |
| DC (data/command) | TBD at F2 firmware bring-up | Any GPIO. |
| RST (reset) | TBD at F2 firmware bring-up | Any GPIO. |
| VCC | 3.3 V | From Pico’s 3V3 (OUT) pin. |
| GND | GND | — |
The SSD1322 module is powered from the Pico’s 3.3 V output rather than the Pi’s 3.3 V GPIO rail — keeping all OLED-related signals and power on a single ground domain.
The driver runs SSD1322 in 8 bpp grayscale mode with a single-level palette (monochrome yellow). Later firmware revisions may exploit the SSD1322’s 16-level grayscale for typewriter fade transitions on Cipher utterances.
For the 2026-07-02 as-built 8080 harness, do not follow the SPI table above; use the bench note linked at the top of this page until the canonical direction is reconciled.
CIPHER-LINE grammar
Section titled “CIPHER-LINE grammar”The Cipher voice on this surface is generated by a runtime-owned grammar that cartridges contribute vocabulary and fragment productions to (via cipher-extend-grammar). For the engine spec, see software/runtime/cipher-voice.md. For the grammar surface, see software/api-reference/grammars/cipher-line-grammar.md.
The authoring boundary is physical: text-* primitives target the main grid, cipher-* and aux-* primitives target CIPHER-LINE. There is no API for a cartridge to render a Cipher passage on the main grid (except the Null exception above).
Module draw and runtime impact are canonical values — see canonical-spec.md (Display auxiliary + Battery rows) and power.md. Bring-up at Stage 1b validates real draw against the estimate.
Mechanical
Section titled “Mechanical”CIPHER-LINE mounts behind a bezel cutout in the base panel of the Pelican 1170 inset, centered above the key plate on the operator’s sight line. Cutout dimensions are TBD during mechanical bring-up (ADR-0015 Known Unknown #2) — measure against the panel CAD with a physical module in hand. The Pelican shell is not modified — the cutout is in the printed inset panel only. See enclosure.md.
Bring-up
Section titled “Bring-up”Stage 1b in build-specification.md §4. Run Stage 1c first (coprocessor bring-up — see coprocessor.md), then complete Stage 1b with the OLED wired to the Pico’s display-bus pins.
- Identify the module’s mode strap population before wiring. If the board is reworked to SPI, wire it to the Pico SPI header per the GPIO selection finalised at F2 firmware bring-up. If using the 2026-07-02 as-shipped 8080 module, follow the bench note until ADR-0015 and the parent canonical spec are reconciled.
- Run the SSD1322 init sequence from the driver shipped in the Pico firmware. Confirms the panel wakes, accepts oscillator / GPIO / segment-remap config, and responds to a framebuffer write.
- Render the four-row test layout. Verify Press Start 2P 8×8 glyphs read at normal sight distance.
- Measure 3.3 V rail current with CIPHER-LINE idle and during a full-field update. If real draw exceeds the canonical peak by a material margin, flag the
canonical-spec.mdBattery row. - With the panel physically in hand, measure bezel cutout dimensions against the printed inset panel CAD; update CAD as needed.
Sourcing
Section titled “Sourcing”BOM line 2b in sourcing-guide.md. Primary supplier: Waveshare direct (yellow variant is reliably stocked there; Adafruit stock is intermittent; Amazon and AliExpress listings frequently default to white even when the title reads “yellow”). Order 2 units (one per deck in a linked-play pair). Dupont jumper kit on BOM line 4b for the v0.1 bench harness.
See also
Section titled “See also”coprocessor.md— Pi Pico 2 owns the SSD1322 display bus.primary-display.md— main 80×25 grid (separate surface).software/runtime/cipher-voice.md— CIPHER-LINE engine spec.software/api-reference/grammars/cipher-line-grammar.md— grammar surface.build-specification.md§4 Stage 1b — bring-up checklist.