Auxiliary Display
Spec hygiene (CLAUDE.md rule 1). This document does not restate canonical values (panel size, pixel count, color, current draw). Those live in CLAUDE.md’s Canonical Hardware Specification. Any value inline is a bug — fix it.
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 CLAUDE.md Spec Hygiene Rule 6 + ADR-0015 §3a).
For module class, pixel dimensions, and color, see CLAUDE.md 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 SPI breakout. 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 + SPI 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 SPI bus is driven by the Pi Pico 2 coprocessor — not by the Pi Zero 2 W’s SPI0. The Pi sends high-level OLED commands (OLED_SET_ROW, OLED_SCROLL_ROW, OLED_FILL, OLED_CLEAR) over UART0; the Pico runs the SPI 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.
| 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.
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 CLAUDE.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 SPI pins.
- Wire the SSD1322 module to the Pico SPI header per the GPIO selection finalised at F2 firmware bring-up. Use short jumper leads with Dupont header connectors for v0.1; a JST-PH harness is a polish pass.
- 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
CLAUDE.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 SPI 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.