docs: Bring-up context + rev3/rev4 keypad correction (plan for PiFinder.bringup)

[brickbots]

Groundwork for a python -m PiFinder.bringup bench entry point for validating freshly assembled rev4 boards. Docs and plan only — no code.

What's here

• docs/ax/bringup/CONTEXT.md (new) — glossary for the Bring-up context, plus its CONTEXT-MAP.md entry and relationships.
• docs/ax/ui/CONTEXT.md — the keypad-layout block still showed the 4-column rev3 pad; the matrix has been 5 columns since Rev-4 hardware enablement: battery telemetry, sound/earcons, power button, SSD1333 display #498.
• bringup-implementation-plan.md — the full implementation plan.

The vocabulary that does the work

A check is one of three kinds, and the kind decides whether it can gate the exit status:

kind	meaning	gates verdict
probed	the program reads the answer itself (IMU chip id, charger part number)	yes
exercised	builder acts, program verifies (each switch closing)	yes
witnessed	program can only emit; the builder is the sensor (screen, backlight, buzzer)	no

A program cannot know whether sound came out of a buzzer, so witnessed checks are reported as emitted and the verdict stays silent about them.

Two more: pre-flight (a provisioning check on the card — kernel overlays, bus enablement — so a misprovisioned image is never diagnosed as a bad board) and population map (which matrix positions carry a switch on a given revision).

The keypad correction

The matrix grew from 4 to 5 columns in #498. rev4 moved the directional cluster off the bottom row into col 4 and gave it a centre SQUARE:

       col0  col1  col2  col3    col4
row0    7     8     9    (na)    UP     ┐
row1    4     5     6    PLUS    LEFT   │ col4 = the cluster
row2    1     2     3    MINUS   DOWN   │ added for rev4, with
row3   (na)   0    (na)  SQUARE  RIGHT  │ a centre SQUARE
row4    LEFT  UP    DOWN  RIGHT  SQUARE ┘
        └─ rev3 directional row ─┘

rev3 = 17 switches, rev4 = 18, with two SQUARE positions. Both clusters emit the same logical keys, so UI code stays revision-agnostic — but a logical key therefore does not identify a physical switch, which is why bring-up speaks in matrix positions rather than keys.

Two findings worth a look

1. pifinder_setup.sh:64 may leave the buzzer unrouted. It provisions only dtoverlay=pwm,pin=13,func=4 — a single-channel overlay routing ch1 → GPIO13 (keypad backlight). The buzzer is ch0 → GPIO12, and nothing in the repo provisions pwm-2chan. The Pi's PWM block always exposes two channels, so HardwarePWM(pwm_channel=0) exports fine and drives no pin: silent, with no error. Needs checking against a reference rev4 card's /boot/config.txt.
2. rev4's population map needs confirming on hardware. The plan assumes 18 switches, but Rev-4 hardware enablement: battery telemetry, sound/earcons, power button, SSD1333 display #498's message says the fix "enables repeat on both directional clusters", which could mean rev4 populates the bottom row too (22). It's one constant either way.

Sequencing

• This PR — docs only.
• Next — extract the matrix tables to an import-safe PiFinder/keypad.py (keyboard_pi.py can't be imported off-Pi), a pure data move landed on its own so a keypad regression stays bisectable.
• Then — PiFinder/bringup.py + tests.

🤖 Generated with Claude Code