Hardware Integration

# labs/hardware_map.py
from collections import defaultdict

SERVOS = {
    "eye_pan":    {"bcm_pin": 12},
    "eye_tilt":   {"bcm_pin": 13},
    "bench_test": {"bcm_pin": 17},
}


def servo_claims(servos: dict) -> dict[int, list[str]]:
    """{bcm_pin: [owner, ...]} for the servos wired straight to the header."""
    claims: dict[int, list[str]] = defaultdict(list)
    for name, servo in servos.items():
        claims[servo["bcm_pin"]].append(f"servo:{name}")
    return dict(claims)


if __name__ == "__main__":
    for pin, owners in sorted(servo_claims(SERVOS).items()):
        print(f"GPIO {pin:>2}: {', '.join(owners)}")

$ uv run python -m labs.hardware_map
GPIO 12: servo:eye_pan
GPIO 13: servo:eye_tilt
GPIO 17: servo:bench_test

One decision in that function carries the whole chapter, and it looks like an accident: the value is a list, not a string. A dictionary from pin to owner would be the obvious model and it destroys the evidence, because the second assignment to a key overwrites the first and the collision you were hunting disappears at the moment it happens. A list keeps both claimants. defaultdict(list) is what makes the append legal on a key that has never been seen; a plain dict raises KeyError on the very first pin, since there is no list waiting there to append to.

# labs/hardware_map.py — the amplifier's three wires join the map
I2S = {"amp_max98357a": {"bcm_bclk": 18, "bcm_lrclk": 19, "bcm_din": 21}}


def claim_map(servos: dict, i2s: dict) -> dict[int, list[str]]:
    claims: dict[int, list[str]] = defaultdict(list)
    for name, servo in servos.items():
        claims[servo["bcm_pin"]].append(f"servo:{name}")
    for name, device in i2s.items():
        for key, pin in device.items():
            claims[pin].append(f"i2s:{name}:{key[4:]}")   # bcm_lrclk -> lrclk
    return dict(claims)


if __name__ == "__main__":
    stale = dict(SERVOS, eye_pan={"bcm_pin": 18})   # the number the bench rig used
    for pin, owners in sorted(claim_map(stale, I2S).items()):
        verdict = "CONFLICT" if len(owners) > 1 else "ok"
        print(f"GPIO {pin:>2} {verdict:>8}: {', '.join(owners)}")

$ uv run python -m labs.hardware_map
GPIO 13       ok: servo:eye_tilt
GPIO 17       ok: servo:bench_test
GPIO 18 CONFLICT: servo:eye_pan, i2s:amp_max98357a:bclk
GPIO 19       ok: i2s:amp_max98357a:lrclk
GPIO 21       ok: i2s:amp_max98357a:din

GPIO 18 is the bench rig's servo pin, carried forward out of habit, and in the body it belongs to the amplifier's bit clock. Notice what the detection cost: one comparison, len(owners) > 1. No set arithmetic, no comparing every claim against every other claim. Stage 1 chose a structure where the question the program has to answer is already the length of something, and every later check in this file inherits that.

{
  "board": "raspberry-pi-4b",
  "revision": "0.9.0",
  "servos": {
    "eye_pan":    {"bcm_pin": 12, "note": "hardware PWM channel 0"},
    "eye_tilt":   {"bcm_pin": 13, "note": "hardware PWM channel 1"},
    "bench_test": {"bcm_pin": 17, "note": "the sweep rig, still wired"}
  },
  "i2s": {
    "amp_max98357a": {"bcm_bclk": 18, "bcm_lrclk": 19, "bcm_din": 21}
  },
  "buses": {
    "spi0": {"pins": [9, 10, 11], "exclusive": true,
             "devices": ["led:eye_ring"]},
    "spi4": {"pins": [4, 5, 6, 7], "exclusive": false,
             "devices": ["adc:battery"]},
    "i2c1": {"pins": [2, 3], "exclusive": false,
             "devices": ["pca9685_arm@0x40", "pca9685_aux@0x40"]}
  },
  "arm": {"driver": "pca9685_arm",
          "channels": {"shoulder": 0, "elbow": 1, "wrist": 2, "gripper": 3}},
  "audio": {"mic_name_substr": "ReSpeaker", "output_name_substr": "hifiberry"}
}

# labs/hardware_map.py — continued
import json
import sys
from pathlib import Path

CONFIG_PATH = Path("configs/hardware.json")
CARD = Path("glados/data/pin_map.txt")


def load_config(path: Path = CONFIG_PATH) -> dict:
    """Read the map. On a machine that has never run this, write the draft and stop."""
    if not path.exists():
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps(DRAFT_CONFIG, indent=2) + "\n")
        print(f"no {path}; wrote the draft. Edit it to match your wiring, then re-run.")
        sys.exit(0)
    return json.loads(path.read_text())

$ uv run python -m labs.hardware_map
no configs/hardware.json; wrote the draft. Edit it to match your wiring, then re-run.

The arm and the audio blocks are in this file even though neither claims a header pin. Her four arm joints are channels 0 to 3 on a PCA9685, a chip that turns two I2C wires into sixteen independent pulse outputs, so the number a joint carries is a channel and not a GPIO. A second identical board rides the same two wires beside it. Sixteen channels is one board's ceiling, and the time to fit the second one is while the head is open, not after. The microphone and the amplifier are resolved by the name substrings chapter 67 argued for, because a USB index is not an identity. All of them belong here anyway: this is the file you open to ask what a subsystem is attached to, and an answer of "nothing on the header" is an answer.

The two SPI entries are not a duplicate. spi0 is the controller the light ring took in chapter 66 and spi4 is the second one chapter 70 turned on for the battery converter, and the four pins under spi4 are the ones dtoverlay=spi4-1cs hands that controller: GPIO 4 for chip select, 5 and 6 for the two data directions, 7 for the clock. Written down here they are four claims like any other. Left only in a boot config and a pair of constants in the sampler, they are four pins the map would have called free.

# labs/hardware_map.py — continued
def extract_claims(config: dict) -> dict[int, list[str]]:
    """{bcm_pin: [owner, ...]} across every subsystem the config declares."""
    claims: dict[int, list[str]] = defaultdict(list)
    for name, servo in config.get("servos", {}).items():
        claims[servo["bcm_pin"]].append(f"servo:{name}")
    for name, device in config.get("i2s", {}).items():
        for key, pin in device.items():
            if key.startswith("bcm_"):
                claims[pin].append(f"i2s:{name}:{key[4:]}")
    for name, bus in config.get("buses", {}).items():
        for pin in bus["pins"]:
            claims[pin].append(f"bus:{name}")     # one claim per bus, whatever hangs off it
    return dict(claims)


def pin_conflicts(claims: dict[int, list[str]]) -> list[str]:
    return [f"GPIO {pin} claimed by {len(owners)}: {', '.join(owners)}"
            for pin, owners in sorted(claims.items()) if len(owners) > 1]


def bus_problems(config: dict) -> list[str]:
    """Two faults a pin count cannot see: an oversubscribed bus and a repeated address."""
    problems: list[str] = []
    for name, bus in config.get("buses", {}).items():
        devices = bus.get("devices", [])
        if bus.get("exclusive") and len(devices) > 1:
            problems.append(f"bus {name} takes one device, {len(devices)} declared: "
                            f"{', '.join(devices)}")
        at: dict[str, list[str]] = defaultdict(list)
        for device in devices:
            if "@" in device:
                node, address = device.split("@")
                at[address].append(node)
        for address, nodes in sorted(at.items()):
            if len(nodes) > 1:
                problems.append(f"bus {name} address {address} claimed by {', '.join(nodes)}")
    return problems


if __name__ == "__main__":
    config = load_config()
    problems = pin_conflicts(extract_claims(config)) + bus_problems(config)
    print(f"FAIL — {len(problems)} problem(s):" if problems else "PASS — every claim checks out")
    for problem in problems:
        print(f"  [x] {problem}")

$ uv run python -m labs.hardware_map
FAIL — 1 problem(s):
  [x] bus i2c1 address 0x40 claimed by pca9685_arm, pca9685_aux

A bus contributes exactly one claim per pin no matter how many devices hang off it, and that single line is what keeps the pin count honest. Two devices sharing SDA and SCL is not a fault, it is the entire point of a bus, and a validator that counted claimants instead of owners would report GPIO 2 and 3 as conflicts on a build that is correct. Chapter 55 hit the same wall with power rails and solved it with a guard in the first pass; a bus is that lesson applied to signal pins.

The fault it does report is not a pin collision at all, and no pin map could have seen it. Both PCA9685 boards left the factory strapped to I2C address 0x40, because that is the address every one of them ships with. Two chips answering to the same address on the same two wires both drive the data line during a reply, so what the Pi reads back is neither board's answer. The cure is on the board, not in the file: each one carries six solder pads labelled A0 to A5, and bridging A0 on the second board adds one to its address. Bridge it, check with i2cdetect -y 1 that 0x40 and 0x41 now both answer, and write down what you did.

// configs/hardware.json — the corrected bus map, with the aux board's A0 pad bridged
{
  "revision": "1.0.0",
  "buses": {
    "spi0": {"pins": [9, 10, 11], "exclusive": true,
             "devices": ["led:eye_ring"]},
    "spi4": {"pins": [4, 5, 6, 7], "exclusive": false,
             "devices": ["adc:battery"]},
    "i2c1": {"pins": [2, 3], "exclusive": false,
             "devices": ["pca9685_arm@0x40", "pca9685_aux@0x41"]}
  }
}

$ uv run python -m labs.hardware_map
PASS — every claim checks out

The exclusive flag has been quiet through all of that, so prove it does something. Hang a second device off the light ring's bus and ask again:

# labs/bus_probe.py
from labs.hardware_map import bus_problems, load_config

if __name__ == "__main__":
    probe = load_config()
    probe["buses"]["spi0"]["devices"].append("adc:battery")
    for problem in bus_problems(probe):
        print(f"  [x] {problem}")

$ uv run python -m labs.bus_probe
  [x] bus spi0 takes one device, 2 declared: led:eye_ring, adc:battery

The ring does not speak SPI: it borrows the data line and pushes a raw bit stream down it at 2.4 megahertz, with no chip select input to ignore anything addressed elsewhere. So a second device on that bus arrives at the ring as pixel colours. That is what "exclusive": true declares, and it is the reason the battery converter reads through a controller of its own instead: spi0 claims three pins and can never hold a second device, spi4 claims four and could. One flag in the config carries a difference that is otherwise buried in a datasheet.

# labs/hardware_map.py — continued
BCM_TO_PHYSICAL = {
    2: 3,   3: 5,   4: 7,   5: 29,  6: 31,  7: 26,  8: 24,  9: 21,
    10: 19, 11: 23, 12: 32, 13: 33, 14: 8,  15: 10, 16: 36,
    17: 11, 18: 12, 19: 35, 20: 38, 21: 40, 22: 15, 23: 16,
    24: 18, 25: 22, 26: 37, 27: 13,
}


def report(config: dict, claims: dict[int, list[str]]) -> str:
    head = f"{'BCM':>4}  {'PHYS':>4}  OWNER"
    lines = [f"GLaDOS body rev {config['revision']} on {config['board']}", "", head, "-" * 44]
    for pin in sorted(claims):
        for owner in claims[pin]:
            lines.append(f"{pin:>4}  {BCM_TO_PHYSICAL.get(pin, '?'):>4}  {owner}")
    free = sorted(set(BCM_TO_PHYSICAL) - set(claims))
    lines += ["", f"{len(claims)} pins claimed, {len(free)} free: {free}"]
    return "\n".join(lines)


def pin_of(claims: dict[int, list[str]], owner: str) -> int:
    """The BCM pin a named owner holds. Raises if that owner claims no header pin."""
    for pin, owners in sorted(claims.items()):
        if owner in owners:
            return pin
    raise KeyError(f"{owner!r} claims no GPIO pin in this map")


def main() -> None:
    config = load_config()
    claims = extract_claims(config)
    print(report(config, claims))
    problems = pin_conflicts(claims) + bus_problems(config)
    if problems:
        print(f"\nFAIL — {len(problems)} problem(s):")
        for problem in problems:
            print(f"  [x] {problem}")
        sys.exit(1)
    CARD.write_text(report(config, claims) + "\n")
    print("\nPASS — no pin claimed twice, no bus oversubscribed.")
    print(f"Wrote {CARD}")


if __name__ == "__main__":
    main()

$ uv run python -m labs.hardware_map
GLaDOS body rev 1.0.0 on raspberry-pi-4b

 BCM  PHYS  OWNER
--------------------------------------------
   2     3  bus:i2c1
   3     5  bus:i2c1
   4     7  bus:spi4
   5    29  bus:spi4
   6    31  bus:spi4
   7    26  bus:spi4
   9    21  bus:spi0
  10    19  bus:spi0
  11    23  bus:spi0
  12    32  servo:eye_pan
  13    33  servo:eye_tilt
  17    11  servo:bench_test
  18    12  i2s:amp_max98357a:bclk
  19    35  i2s:amp_max98357a:lrclk
  21    40  i2s:amp_max98357a:din

15 pins claimed, 11 free: [8, 14, 15, 16, 20, 22, 23, 24, 25, 26, 27]

PASS — no pin claimed twice, no bus oversubscribed.
Wrote glados/data/pin_map.txt

GPIO 7 and 8 are the two chip selects SPI0 would otherwise hold, and dtoverlay=spi0-0cs in the boot config hands both back: nothing on that bus gets selected, so nothing needs a select line. Only 8 shows as free, because 7 was picked up again immediately as the second controller's clock, which is the sort of second-hand fact a map is for. Eleven free pins is not a lot of headroom for a machine that is nearly finished, and seeing the number is the point. A free list computed by set difference answers "where does the next device go" in the same breath as "is anything broken", off the same map.

# labs/hardware_bind.py
from glados.devices import PiServo             # the DeviceDriver subclass from chapter 53
from labs.hardware_map import BCM_TO_PHYSICAL, extract_claims, load_config, pin_of

if __name__ == "__main__":
    claims = extract_claims(load_config())
    for owner in ("servo:eye_pan", "servo:eye_tilt"):
        pin = pin_of(claims, owner)
        print(f"{owner:<16} -> GPIO {pin} (physical {BCM_TO_PHYSICAL[pin]})")

    eye_pan = PiServo(pin=pin_of(claims, "servo:eye_pan"), name="eye_pan")
    eye_pan.initialize()
    print(eye_pan.safe_read())

    try:
        pin_of(claims, "arm:shoulder")
    except KeyError as exc:
        print(f"KeyError: {exc}")

$ uv run python -m labs.hardware_bind   # measured on the bench — yours will vary
servo:eye_pan    -> GPIO 12 (physical 32)
servo:eye_tilt   -> GPIO 13 (physical 33)
[pi ] eye_pan ready on pin 12
{'device': 'eye_pan', 'angle': 0}
KeyError: "'arm:shoulder' claims no GPIO pin in this map"

Chapter 53's DeviceDriver already takes its pin as a constructor argument, so binding a driver to the map is one call and no rewrite. Two lines of that output earn a second look. initialize() has to run before the read, because safe_read tests the flag that initialize sets and answers {'device': 'eye_pan', 'error': 'not initialized'} on a driver that never claimed its pin. The angle that comes back is 0 rather than a centred 90: the driver reports the last angle it was told to hold, and nothing has told it one yet. A servo knows what it was commanded, never where the horn actually sits.

The last line is the other one. Asking for the shoulder's pin raises, and that is correct: the shoulder is channel 0 on the PCA9685 and has no header pin to hold. A lookup that returned a plausible number there would be worse than useless, because the caller would go on to drive it.