# Wiring — Pi Zero 2 W ↔ Commodore IEC bus

PoC listener (printer) interface. Full rationale: PLAN.md §3 and
`_research/commodore-iec-serial-bus-2026-06-18.md` §1.

> ⚠️ The Pi GPIO is **3.3 V and NOT 5 V tolerant**. The IEC bus idles at 5 V.
> A level shifter is **mandatory** — never wire a bus line straight to a Pi pin.

## Topology

A single **4-channel bidirectional MOSFET level shifter** (BSS138 + pull-ups,
the "logic level converter" board) carries all four lines:

- low side → Pi 3.3 V rail
- high side → IEC bus 5 V rail
- **DATA** is the one bidirectional, open-drain-emulated line.
- **ATN / CLK / RESET** are input-only (Pi always reads them).
- 100 nF bypass cap across the shifter VCC pins.
- **Common ground** between Pi GND and IEC pin 2.
- SRQ (IEC pin 1) left unconnected.

The shifter is **non-inverting**: bus low (asserted) ⇒ Pi reads LOW.

## Pin map

| IEC signal | IEC DIN pin | Pi GPIO (BCM) | Header pin | Direction |
|------------|-------------|---------------|------------|-----------|
| ATN        | 3           | GPIO 4        | 7          | input (via shifter) |
| CLK        | 4           | GPIO 3        | 5          | input (via shifter) |
| DATA       | 5           | GPIO 2        | 3          | **bidirectional** (via shifter) |
| RESET      | 6           | GPIO 17       | 11         | input (via shifter) |
| GND        | 2           | GND           | 6 (or any) | — |
| SRQ        | 1           | —             | —          | not connected |

> ℹ️ **DATA (GPIO2) and CLK (GPIO3) are the Pi's ARM I²C pins** and carry the
> SoC's fixed ~1.8 kΩ pull-ups (benign — DATA is open-drain). Keep
> `dtparam=i2c_arm` **off** in `/boot/firmware/config.txt` (the default) so I²C
> does not claim these pins. This layout matches a confirmed-working reference
> listener.

## DATA open-drain emulation

GPIO 2 is never a push-pull driver of the bus. The module flips its direction:

- **assert** (pull bus low): GPIO 2 = output **LOW** → shifter pulls bus to 0 V.
- **release / read**: GPIO 2 = **input (Hi-Z)** → bus pull-ups float it to 5 V,
  and GPIO 2 reads the level the *talker* (C64) is driving — this is how bits
  are sampled during receive.

Logical mapping (handled in `kernel/iec_lines.h`): asserted ⇔ Pi reads LOW.

## Bring-up checklist (before connecting the C64)

1. Load the module: `sudo insmod kernel/iec_listener.ko`.
2. Run the wiring selftest (drives DATA low, releases, reads back; reads sense
   lines) via the `IEC_IOC_SELFTEST` ioctl — expect:
   - DATA reads low while driven, high after release (Hi-Z floats up);
   - ATN / CLK / RESET all released (high) with the C64 powered off.
3. Meter/LED-check each line for the expected idle-high.
4. Verify common ground continuity Pi↔IEC pin 2.
5. Only then connect the C64 and try `OPEN 1,4 : CLOSE 1`.