# Cross-Chapter Handout: Tang Nano Board Roster

> **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 N` going 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:027` vs `3:029`). **current canonical disambiguation**, but enumeration order can drift across reboots / unplug-replug
- `ftdi_eeprom` reprogram (deepest fix; permanent until re-flashed). **planned post-toolchain-fix** as canonical lab-rig hygiene step

## Naming policy

1. **First board in service** is `A`. Subsequent boards are `B`, `C`, ... in order of first-plugin.
2. **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).
3. **Each commit / Signal turn / doc reference** uses the letter. Never "right one" / "new one" / "the one Jon plugged in."
4. **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.
5. **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 archaeology
- `bitstream-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.*