Tspico v3

TS-Pico v3 KiCad project

Status 2026-10-19: prototype 3 (v3.0-proto3, changes below). Proto1 (v3.0-proto1) was built and brought up; proto2 added its fixes (below). Both proto2 and proto3 were routed by scripts/flow.py with no hand edits, DRC clean at every severity. ERC: one warning, U4's unused input tied to GND.

To order: the JLCPCB upload files (Gerber zip, BOM, placement), ordering notes, schematic PDF and renders are on the v3.0-proto3.1 release: proto3 with the board labels, and L1 assembled by JLCPCB again. U22, J3 and J5 are fitted by hand. v3.0-proto3 is the same copper without the labels, with L1 fitted by hand. Proto2: v3.0-proto2.1 (L1 by hand) and v3.0-proto2 (L1 assembled by JLCPCB), same Gerbers. To regenerate them from this folder, run python3 scripts/gen_fab.py (output in fab/jlcpcb/).

Proto3 changes

Proto2 changes (from proto1 bring-up and issue #21)

Firmware for proto2: set SD_PWR_EN (expander port 0 bit 6) after the detect switch reads a card and before any SPI; return the SD pins to inputs before clearing it.

Sheets are generated by scripts/gen_<sheet>.py on top of scripts/schlib.py, netlist-style (labels on every pin, no wires). Regenerating a sheet overwrites hand edits, so once a sheet is being edited in KiCad, retire its generator. Spec: ../docs/v3-architecture.md.

Files

Edge connector geometry

Measured from the v2.2 fab Gerbers (../old/tsPico2_2Fab/Gerber/tsPico.GTL, .GBL, .Outline):

Pad names are A1..A32 on F.Cu and B1..B32 on B.Cu (no A6/B6), following the TS2068 Technical Manual table 2.4.1-1. Position 1 is at the left when the board is viewed from the top with the connector at the bottom.

Side A is the top (component) side, confirmed: side A (GND, EAR, D7, ..., SOUND) is on the top and side B (+15V, +5V, address bus, video) on the bottom. Proto1 proved it in a 2068 on 2026-10-07 (firmware/bringup/README.md). In shadow mode it logged every address the Z80 read through the side-B fingers, the boot log matching the ROM exactly. It then served the HOME ROM onto side A, with /MREQ and /RD timing each read, /BE on A29 and the data on D0-D7, and the 2068 booted to the card's "TS-Pico v3 ROM" banner. With the sides swapped, the address fingers would sit on data and control lines and none of that could work. This also matches how the v2.2 layout routes +5V (bottom trace from the fourth finger).

Fab notes for the fingers: hard gold over the fingers if the fab offers it (ENIG otherwise), 30 degree bevel on the tongue edge, no copper within 0.3 mm of the slot.

Stock library parts already identified

RP2350B symbol (MCU_RaspberryPi), Package_DFN_QFN:QFN-80-1EP_10x10mm_P0.4mm_EP3.4x3.4mm, TSPico:microSD_TF-01A (to be drawn from the HRO TF-01A drawing), Connector_Dsub:DSUB-9_*, Connector_USB:USB_C_Receptacle_HRO_TYPE-C-31-M-12, SOIC/TSSOP logic packages, Button_Switch_SMD:SW_SPST_PTS645Sx43SMTR92, Connector_Audio:Jack_3.5mm_CUI_SJ-352x-SMT_Horizontal, Crystal:Crystal_SMD_3225-4Pin_3.2x2.5mm.

All parts used so far have stock symbols and footprints (the APS6404L PSRAM is in Memory_RAM, the ESP32-C3-WROOM-02 in RF_Module).

Regenerating the BOM

cd hardware
KC=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli
$KC sch export bom --output bom/tspico-v3-jlcpcb-bom.csv --fields "Value,Reference,Footprint,LCSC" --labels "Comment,Designator,Footprint,LCSC Part #" --group-by "Value,Footprint" --exclude-dnp tspico-v3.kicad_sch

Part choices are priced against JLCPCB's catalog with python3 scripts/jlc_price.py --boards 10; the reasoning for each substitution is in docs/bom-cost-optimization.md (2026-09-17: parts + fees per board went from $32.95 to $14.93 on a 10-board run, to $14.48 after the DMA option was dropped; fitted logic packages from 16 to 7). The board was laid out again for these parts on 2026-09-17 (see the routing section).

Fab outputs

python3 scripts/gen_fab.py writes fab/jlcpcb/: tspico-v3-gerbers.zip (4-layer Gerbers + Excellon drill), tspico-v3-bom.csv and tspico-v3-cpl.csv (JLCPCB assembly format), and refreshes the two BOMs in bom/. fab/NOTES.md lists what to check on upload (L1 has no LCSC number yet; rotations of QFN/SOT/connector parts need checking in JLC's placement preview; J3 and J5 are through-hole).

Schematic and PCB PDFs, renders

Regenerate after a board or schematic change (from hardware/):

KC=/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli
$KC sch export pdf -o docs/tspico-v3-schematic.pdf tspico-v3.kicad_sch
$KC pcb export pdf --mode-multipage --ibt --scale 0 --cdnp -l F.Cu,In1.Cu,In2.Cu,B.Cu,F.Silkscreen,B.Silkscreen,F.Fab,B.Fab --cl Edge.Cuts -o docs/tspico-v3-pcb.pdf tspico-v3.kicad_pcb
$KC pcb render --side top --quality high -w 2384 -h 1376 --zoom 1.1 -o renders/tspico-v3-top.png tspico-v3.kicad_pcb
$KC pcb render --side bottom --quality high -w 2384 -h 1376 --zoom 1.1 -o renders/tspico-v3-bottom.png tspico-v3.kicad_pcb
$KC pcb render --side top --quality high -w 2384 -h 1568 --rotate '-45,0,45' --perspective -o renders/tspico-v3-iso.png tspico-v3.kicad_pcb

Parts without a 3D model in the KiCad library (the four buttons, USB-C, micro SD socket, audio jack) show as bare pads in the renders; U22 is DNP.

Layout notes

• Body 130 x 56 mm (the register row of the first layout is gone). Left edge, top to bottom: ESP32-C3 antenna, USB-C, micro SD. The TF-01A socket's shell is flush with the board edge (its shield pads sit 3 mm back, so nothing needs edge clearance). Right edge: 3.5 mm jack in the corner, DE-9 below it.
• Top edge: buttons in a 2x2 block on 0.5 in centres (top row TS Reset, NMI; below them RUN, BOOTSEL; proto1/2 had all four in a row), then the OLED header. The module on J3 covers everything right of the buttons, so nothing there may be taller than its standoff. The LED (D4, R5) sits left of the ESP32, between the mounting hole and the USB-C socket. A bottom-layer keepout (no tracks or vias) sits under the RP2350B.
• Row above the fingers: data U3, high address byte U2 directly over fingers A15-A8, control U4 (U3 is turned 180 degrees from the others: its A side is the Z80 side so DIR can be /RD itself). Row above that: low address byte U1 over U2, fed from fingers A0-A3 on the left and A7-A4 on the right along the bottom layer, then strobe OR gates U6 and open-drain drivers U7. Both address buffers put plain bytes on MD0-MD7, so the firmware sees ordinary addresses. I2C expander U15 and the joystick conditioning network sit beside the DE-9; audio and the two LDOs above them.
• RP2350B core regulator copied from "Hardware design with RP2350" figure 4: input cap C22 and output cap C20 (0402) straddle the VREG_LX pin, LX runs 3.7 mm under both to L1, VIN and PGND go straight into C22, feedback senses at C20, the AVDD filter R28/C39 sits above. L1 is the polarised Abracon part: pad 2 (dot) is the DVDD end, away from the top edge of the board.
• Crystal 6.5 mm from its pins with R20 between chip and crystal; XOUT_R runs under the crystal to pad 3. XIN and XOUT drop one pad lane after leaving the chip so DVDD pin 32 has room for its via.
• Before ordering: check the D-sub footprint against the CONNFLY DS1037 drawing, check lib/tspico.pretty/microSD_TF-01A and L_Abracon_AOTA-B201610 against the parts' drawings (both were generated from LCSC's land patterns). (TF-01A card detect: low = card in, confirmed on proto1.)

Routing flow and state

cd hardware
PY=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3
$PY scripts/gen_layout.py     # placement, keepouts, planes (discards all routing)
$PY scripts/preroute.py       # locked hand routes: regulator, crystal, DVDD spine, inner supply links, bottom-row fan
$PY scripts/autoroute.py --passes 100     # jar from $FREEROUTING_JAR (or --jar); about 25 minutes
$PY scripts/finish.py         # widen necked tracks, join orphan supply islands, retry open nets, drop unused vias and stubs
$PY scripts/silk.py           # place reference designators clear of pads, silk and the edge; trim outlines at the edge
$PY scripts/labels.py v3      # board name on top; name, URL, licence and OSHW logo on the bottom

Or all five in one command, which is the way to run it:

$PY scripts/flow.py                       # jar from $FREEROUTING_JAR (or --jar); 10 to 15 minutes per attempt, up to 3 attempts

Freerouting does not give the same result twice from the same input. Before U1's address pins had their pre-routed via fan (below), about one run in three left one of them (A3, A5) sealed in behind its neighbours' vias; with the fan, three runs out of three closed on the first attempt. The safety net stays: if a signal net is left open, finish.py tries lifting the neighbours' copper around the pin, routing the open net and putting the neighbours back, but refuses a result that needs more than three vias per net (the only way out of such a pocket has been a 9-via, 70 mm detour). If the board still is not clean finish.py exits non-zero and flow.py routes again from the placement, keeping the failed board as fab/route/attempt-N.kicad_pcb.

Rules: 0.15 mm signal tracks (the router may neck down to 0.11 mm in a squeeze; board minimum 0.1 mm, JLCPCB's is 0.09), 0.4 mm on the 5 V rails and +3V3_WIFI, 0.127 mm clearance, every via 0.6/0.3 mm (JLCPCB's no-surcharge size; the ESP32 footprint's 0.2 mm thermal vias are opened to 0.3 mm by gen_layout.py). The pre-stitch step skips the RP2350B's pins: a via 0.9 mm out of a 0.4 mm pitch pin blocks both neighbours' escape lanes. Its exposed pad gets five ground vias.

What preroute.py fixes in place before the autorouter runs, because the router handles a fully used 0.4 mm pitch QFN badly (whichever pins it leaves for last end up sealed behind its own vias):

• the regulator and crystal, as above;
• the DVDD spine: 0.25 mm track under the package from the regulator's pin 65 to DVDD pins 51, 10 and 32 (10, 15 and 22 mm from the output capacitor; only the first 3 mm at the pins is 0.15 mm), and pin 51's 100 nF 2 mm from its pin;
• the 3.3 V supply pins linked in groups under the package, each group with one via: 50 to corner pin 41, 68/69 to 76 to pin 5, 24 to 29;
• the bottom pad row (pins 1-20, all used) as a deterministic fan: straight out to a staggered depth, a 45 degree turn, and a via on a common line at 0.75 mm spacing, which is the tightest legal pattern for 0.6 mm vias at 0.4 mm pitch.
• U1's Z80-side pins (A0-A7): each runs straight in under U1's body to its own via, in two staggered rows 1.26 and 2.06 mm from the pads. U1's bottom pad row faces U2's top row across a 0.8 mm gap, so these pins can only leave under U1, and their fingers are on the bottom layer, so each needs a via anyway. Neighbouring vias are 1.03 mm apart, and a track on either layer still passes between two vias of the near row.

State on 2026-09-17 (DMA option dropped, address buffers delivering plain bytes, audio and joystick passives respaced for silkscreen, U1 address fan pre-routed): fully routed, DRC clean at every severity (no errors, no warnings, no unconnected items), no tracks on either plane layer. 2073 track segments, 378 vias, all 0.6/0.3 mm, no track under 0.13 mm. Produced by flow.py on its first attempt with no hand edits. (Run DRC on the board where it sits: a copy outside the project folder is checked against KiCad's default rules and reports hundreds of false clearance errors.)

Silkscreen: silk.py sets designators to 0.8 mm text and tries positions around each part until one clears pads, other silk, other parts and the board edge; rows of equal parts all get the label on the same side (above a flat part, to the right of an upright one), and a hidden designator gets a second chance by moving a neighbour's. The layout leaves room for this: passive rows are 3.2 mm apart in the audio block, 2.7 mm in the SD pull-ups, and the joystick RC columns are 2.6 mm apart. 139 of 140 designators are on silk; only C39 (the VREG_AVDD capacitor, boxed in by the design guide's regulator layout) is hidden, and it is on F.Fab with all the others. Outlines of edge connectors that overhang the board are trimmed where they cross the edge.

Board labels: labels.py (also run by flow.py) puts "TS-Pico v3" on the top silkscreen above the left end of the fingers. On the bottom it puts the name, the repository URL (the CERN-OHL-S Source Location), the licence and the OSHW logo. It only touches its own group of silkscreen items, so it can be rerun on a routed board, and it refuses to save if a label would land on a pad, a courtyard or other silk. labels.py v2.6 does the same for ../hardware-v2.6/.

Rerunning autoroute.py continues from the current routing (it exports existing tracks); --fresh starts over. Do not rerun gen_layout.py: it rebuilds the board from placement and discards routing.