Scope. Canonical naming convention for the physical Tang Nano boards in the project's hardware-debug rotation. Resolves the "which board was that again?" problem when more than one board is plugged in simultaneously to the dev-rig.
Discipline. Every Tang Nano reference in code / commits / docs uses
Board A/Board B/Board Ngoing forward. No more "the one on the right" / "the new one" / "the original." Atoms-side, physical labels (sharpie, tape) match this roster.
Current roster (live state. Update with each board addition / swap)
| Slot | Position on redbook | First plugged in | USB enumeration | FTDI EEPROM serial | Physical label | Live state |
|---|---|---|---|---|---|---|
| Board A | RIGHT | (in service pre-2026-05-01) | Bus 3 / Device 027 (port 3-3) | SIPEED_USB_Debugger_2025030317 |
✅ Sharpie on PCB (Jon ~08:32 ET firing #68) | Currently flashed: tn20k_blink_v7.fs = canon-004 binary-cascade ripple (D117 close artifact firing #68); SD card inserted in TF slot |
| Board B | LEFT | 2026-05-01 ~07:30 ET | UNKNOWN as of firing #70. See correction note below | SIPEED_USB_Debugger_2025030317 (collides) |
✅ Sharpie on PCB (Jon ~08:32 ET firing #68) | Was: Sipeed factory flow_led scrolling-LED demo; current state pending Jon physical check |
Correction note. Firing #70 (2026-05-01 ~09:08 ET)
The roster row for Board B previously read "Bus 3 / Device 029". That was wrong. Per Jon Signal ~09:05 ET clarification, Bus 3 / Device 029 (port 3-1) on redbook is actually a Sipeed USB-JTAG-UART dongle attached to the Ultra96, NOT Board B. The LiteX shell traffic that initially appeared on /dev/ttyUSB3 during R-UART-1 first-validate run was Ultra96's UART output via that dongle (Ultra96 has been running LiteX-VexRiscv for days).
Where Board B's USB enumeration currently sits is unknown. Pending Jon physical check. Working hypothesis: Jon may have unplugged Board B from redbook (possibly when grabbing the SD card to insert into Board A), and it's currently powered down. Roster will be updated when Jon confirms.
FTDI EEPROM serial collision (Sipeed-shipped, identical across boards). Host-side disambiguation by --ftdi-serial is NOT available out of the box. Resolve via:
- USB enumeration order (
--busdev-num 3:027vs3:029). current canonical disambiguation, but enumeration order can drift across reboots / unplug-replug ftdi_eepromreprogram (deepest fix; permanent until re-flashed). planned post-toolchain-fix as canonical lab-rig hygiene step
Naming policy
- First board in service is
A. Subsequent boards areB,C, ... in order of first-plugin. - Order is permanent, even if boards physically swap positions or get swapped USB cables, the canonical name follows the original FT2232H chip (use FTDI EEPROM serial reprogram + label-tape to lock).
- Each commit / Signal turn / doc reference uses the letter. Never "right one" / "new one" / "the one Jon plugged in."
- Physical label (sharpie or color-coded tape) on each board's PCB silkscreen + matching label on the corresponding USB cable end. Mismatches between PCB label and cable label = stand-down until re-labeled.
- When a board is permanently retired or RMA'd, do NOT recycle its letter. Increment to next available. Roster table preserves the retirement record (with
[retired]marker).
Three-tier disambiguation roadmap
Per D132 (firing #67):
| Tier | Method | Cost | Permanence | When |
|---|---|---|---|---|
| 1 | Sharpie / label tape on PCB + USB cable | Free | Will fade / peel | Now (recommended). Unblocks all immediate work |
| 2 | Programmed-ID flash bitstream (e.g. unique LED pattern at boot) | Free; software-only | Survives power cycle | Once toolchain is fixed. Also doubles as lab-archaeology demo |
| 3 | ftdi_eeprom reprogram of FT2232H EEPROM serial (BOARD-A / BOARD-B / ...) |
~15 min/board, requires sudo | Permanent until re-flashed | Canonical professional lab-rig hygiene, once confirmed, all bitstreams ship with --ftdi-serial BOARD-X rather than --busdev-num |
Pedagogical anchor
This roster is itself a teachable artifact:
- CSA-101 / VCA-HW-101 Toolchain Diary entry candidate, "How to keep multiple FPGA boards distinguishable on a single dev-rig" addresses a real-world pattern students will encounter in any non-trivial lab environment.
- Architecture Comparison Sidebar candidate, "USB device disambiguation across vendor practices" (Sipeed identical-serial-shipping vs. Digilent globally-unique-serial vs. Xilinx EEPROM-programmed serials).
- Discovery-learning anchor, Sipeed shipping all boards with the same FTDI serial is an instructive "real-world ambiguity" pattern; students discover the gap, learn the workarounds, internalize the canonical fix.
Other FPGAs on the same dev-rig (NOT Tang Nanos but enumerate alongside)
Roster scope here is Tang Nano boards specifically, but for orchestrator awareness:
| Slot | USB enumeration on redbook | TTY | Live state |
|---|---|---|---|
| Ultra96 (Xilinx Zynq UltraScale+) | Bus 3 / Device 026 (port 3-2; native PYNQ-USB CDC bridge) + Bus 3 / Device 029 (port 3-1; Sipeed USB-JTAG-UART dongle attached) | /dev/ttyACM0 (native CDC) + /dev/ttyUSB2 (dongle JTAG) + /dev/ttyUSB3 (dongle UART) |
Running PYNQ Linux 3.0.1 + LiteX-VexRiscv firmware; LiteX shell prompt reachable on /dev/ttyUSB3 |
Pedagogical anchor: this dev-rig has THREE distinct FPGA targets (Tang Nano 20K Board A + Board B + Ultra96) all enumerating at once. Disambiguation discipline is central, and each FPGA has its OWN UART autonomous-validation primitive per D139 doctrine. R-UART-1 generalizes to "any FPGA with USB-CDC = autonomous-validation target via expected-prompt observation."
Cross-references
handouts/cross-chapter-tang-nano-20k-board-reference.md. Physical board / silicon spec (post-D119/D120 corrected baseline)handouts/cross-chapter-sd-card-format-procedure.md, SD card prep (Step 9 umount discipline)peripheral-ip-pack/synth/tn20k-blink/D117-TRIAGE-MATRIX.md. Debug archaeologybitstream-archive/README.md. Canon-NNN reference roster + R-UART-N progression
Naming convention ratified 2026-05-01. Atoms-side labels TBD. Recommended Tier 1 (sharpie) NOW.