The Device Contract

# glados/devices.py
from abc import ABC, abstractmethod


class DeviceDriver(ABC):
    def __init__(self, name: str, pin: int) -> None:
        self.name = name
        self.pin = pin
        self._initialized = False

    @abstractmethod
    def initialize(self) -> bool:
        """Claim the hardware. Set self._initialized, return whether it worked."""

    @abstractmethod
    def read(self) -> dict:
        """Return this device's current state. May raise."""

    @abstractmethod
    def write(self, value) -> bool:
        """Apply value to the device. A read-only device returns False."""


class SimulatedServo(DeviceDriver):
    def __init__(self, pin: int) -> None:
        super().__init__("arm_servo", pin)
        self._angle = 0

    def initialize(self) -> bool:
        self._initialized = True
        print(f"[sim] arm_servo ready on pin {self.pin}")
        return True

    def read(self) -> dict:
        return {"angle": self._angle}

    def write(self, angle: int) -> bool:
        self._angle = max(0, min(180, int(angle)))
        print(f"[sim] arm_servo -> {self._angle} deg")
        return True


if __name__ == "__main__":
    servo = SimulatedServo(pin=18)
    servo.initialize()
    servo.write(90)
    servo.write(250)
    print(servo.read())

$ uv run python -m glados.devices
[sim] arm_servo ready on pin 18
[sim] arm_servo -> 90 deg
[sim] arm_servo -> 180 deg
{'angle': 180}

Three obligations, because there are three things you do to a device: bring it up, ask it something, tell it something. Two details carry forward from the simulated body of chapter 27. The clamp max(0, min(180, int(angle))) sits inside write, where no caller can go around it, so the 250 lands at 180 instead of grinding a real servo against its mechanical stop. And _initialized starts False in the base constructor, which is the one piece of state the base needs to own if it is going to make any promise at all about reads. Right now it owns it and nothing consults it.

class DeviceDriver(ABC):
    # ... __init__ and the three abstract methods as above ...

    def safe_read(self) -> dict:
        if not self._initialized:
            return {"device": self.name, "error": "not initialized"}
        try:
            reading = self.read()
        except Exception as exc:
            return {"device": self.name, "error": f"{type(exc).__name__}: {exc}"}
        return {"device": self.name, **reading}


if __name__ == "__main__":
    servo = SimulatedServo(pin=18)
    print("before:", servo.safe_read())
    servo.initialize()
    servo.write(90)
    print("after: ", servo.safe_read())

$ uv run python -m glados.devices
before: {'device': 'arm_servo', 'error': 'not initialized'}
[sim] arm_servo ready on pin 18
[sim] arm_servo -> 90 deg
after:  {'device': 'arm_servo', 'angle': 90}

safe_read is the first method in this class with a body, and it is the whole point of the class. Read it as three steps in a fixed order: refuse if the device never came up, attempt the device-specific read, stamp the answer with the name of the device that produced it. Only the middle step varies between devices, and the middle step is precisely the one written as self.read(). The stamp matters more than it looks. A caller polling four devices gets four dicts back, and without "device" in each one it has to remember which answer came from where.

import random


class SimulatedDistance(DeviceDriver):
    def __init__(self, trig_pin: int, echo_pin: int) -> None:
        super().__init__("range_finder", trig_pin)
        self.echo_pin = echo_pin

    def initialize(self) -> bool:
        self._initialized = True
        print(f"[sim] range_finder ready on pins {self.pin}/{self.echo_pin}")
        return True

    def read(self) -> dict:
        if random.random() < 0.2:
            raise RuntimeError("echo timeout after 38 ms")
        return {"distance_cm": round(random.uniform(5.0, 100.0), 1)}

    def write(self, value) -> bool:
        return False


if __name__ == "__main__":
    sensor = SimulatedDistance(trig_pin=23, echo_pin=24)
    sensor.initialize()
    for _ in range(5):
        print(sensor.safe_read())

$ uv run python -m glados.devices   # simulated jitter: your five lines will differ
[sim] range_finder ready on pins 23/24
{'device': 'range_finder', 'distance_cm': 41.7}
{'device': 'range_finder', 'distance_cm': 62.3}
{'device': 'range_finder', 'error': 'RuntimeError: echo timeout after 38 ms'}
{'device': 'range_finder', 'distance_cm': 18.9}
{'device': 'range_finder', 'error': 'RuntimeError: echo timeout after 38 ms'}

An ultrasonic module really does fail this way: it fires a pulse and waits for the reflection, and a soft surface, a steep angle or an empty room means the reflection never comes back, so the driver gives up after a timeout. The one-in-five failure rate here is a rehearsal dial, higher than any sane module, set so a five-line run shows you both outcomes. Notice what the loop did with the bad reads: it kept going. Two timeouts became two dictionaries, the other three lines still carry distances, and no caller anywhere wrote a try. The error string starts with RuntimeError because str(exc) alone is sometimes the empty string, and {'error': ''} in a log at two in the morning tells you nothing at all.

# glados/devices.py — the driver for the metal, plus the runner
class PiServo(DeviceDriver):
    def __init__(self, pin: int, name: str = "head_servo") -> None:
        super().__init__(name, pin)
        self._pwm = None
        self._angle = 0

    def initialize(self) -> bool:
        try:
            import RPi.GPIO as GPIO
        except ImportError as exc:
            print(f"[pi ] {self.name} unavailable: {exc}")
            return False
        GPIO.setmode(GPIO.BCM)
        GPIO.setup(self.pin, GPIO.OUT)
        self._pwm = GPIO.PWM(self.pin, 50)
        self._pwm.start(0)
        self._initialized = True
        print(f"[pi ] {self.name} ready on pin {self.pin}")
        return True

    def read(self) -> dict:
        return {"angle": self._angle}

    def write(self, angle: int) -> bool:
        self._angle = max(0, min(180, int(angle)))
        self._pwm.ChangeDutyCycle(5.0 + (self._angle / 180.0) * 5.0)
        return True


def main() -> None:
    devices: list[DeviceDriver] = [
        SimulatedServo(pin=18),
        SimulatedDistance(trig_pin=23, echo_pin=24),
        PiServo(pin=12),
    ]
    for device in devices:
        device.initialize()
    for device in devices:
        print(device.safe_read())


if __name__ == "__main__":
    main()

$ uv run python -m glados.devices   # on the desktop, no GPIO anywhere
[sim] arm_servo ready on pin 18
[sim] range_finder ready on pins 23/24
[pi ] head_servo unavailable: No module named 'RPi'
{'device': 'arm_servo', 'angle': 0}
{'device': 'range_finder', 'distance_cm': 33.2}
{'device': 'head_servo', 'error': 'not initialized'}

The pulse widths from chapter 27 turn into duty cycle here, at the only place in the project that knows what a duty cycle is. At 50 Hz each cycle is 20 milliseconds, so a 1 ms pulse is 5 percent and a 2 ms pulse is 10 percent, and the arithmetic in write spreads 0 to 180 degrees across that band. The import lives inside initialize, so this module still loads on a laptop, and the third line of output is what that buys: the Pi driver announced honestly that it could not come up, returned False, left _initialized alone, and the run continued. When you do run this on the board, the last line reads {'device': 'head_servo', 'angle': 0} instead, and nothing else about the program changes.