Power Distribution

# labs/power_budget.py
from dataclasses import dataclass


@dataclass(frozen=True)
class Load:
    """One thing that draws current, in the three states it can be in."""
    name: str
    rail: str
    idle_ma: float     # powered, doing nothing
    active_ma: float   # doing its ordinary job, measured with a meter in series
    peak_ma: float     # the worst it can do: stalled, full white, loudest note


LOADS = [
    Load("pi 4b",        "logic",  600,  950, 1200),
    Load("mic array",    "logic",  100,  120,  150),
    Load("amplifier",    "logic",    3,  420, 1400),
    Load("adc + sense",  "logic",    1,    1,    2),
    Load("led ring",     "motion",  24,  430, 1440),
    Load("eye pan",      "motion",  10,  250,  700),
    Load("eye tilt",     "motion",  10,  250,  700),
    Load("arm shoulder", "motion",  10,  900, 2500),
    Load("arm elbow",    "motion",  10,  900, 2500),
    Load("arm wrist",    "motion",  10,  900, 2500),
    Load("arm gripper",  "motion",  10,  400, 1200),
]

SUPPLY_MA = {"logic": 5000.0, "motion": 8000.0}   # what each converter is rated for
DERATE = 0.80                                     # how much of a rating you spend

# A scenario names the column each load is read from. "*" is the default.
SCENARIOS = {
    "idle":       {"*": "idle_ma"},
    "speaking":   {"*": "idle_ma", "pi 4b": "active_ma", "mic array": "active_ma",
                   "amplifier": "active_ma", "led ring": "active_ma",
                   "eye pan": "active_ma", "eye tilt": "active_ma"},
    "arm reach":  {"*": "idle_ma", "led ring": "active_ma",
                   "arm shoulder": "active_ma", "arm elbow": "active_ma"},
    "everything": {"*": "peak_ma"},
}


def draw_ma(load: Load, scenario: dict[str, str]) -> float:
    """What this load takes in this scenario."""
    return getattr(load, scenario.get(load.name, scenario["*"]))


def rail_draw_ma(rail: str, scenario: dict[str, str]) -> float:
    """Every load on one rail, added up for one scenario."""
    return sum(draw_ma(load, scenario) for load in LOADS if load.rail == rail)


def within_budget(rail: str, draw_ma: float) -> bool:
    """True when the draw fits under the derated rating of that rail's converter."""
    return draw_ma <= SUPPLY_MA[rail] * DERATE


if __name__ == "__main__":
    rails = sorted(SUPPLY_MA)
    print(f"{'scenario':<12}" + "".join(f"{rail + ' rail':>19}" for rail in rails))
    for name, scenario in SCENARIOS.items():
        row = f"{name:<12}"
        for rail in rails:
            total = rail_draw_ma(rail, scenario)
            verdict = "ok" if within_budget(rail, total) else "OVER"
            row += f"{total / 1000:>11.2f} A {verdict:<5}"
        print(row.rstrip())
    print()
    for rail in rails:
        print(f"{rail:<7} converter {SUPPLY_MA[rail] / 1000:.1f} A rated,"
              f" {SUPPLY_MA[rail] * DERATE / 1000:.1f} A budget at {DERATE:.0%} derating")

$ uv run python -m labs.power_budget
scenario             logic rail        motion rail
idle               0.70 A ok          0.08 A ok
speaking           1.49 A ok          0.97 A ok
arm reach          0.70 A ok          2.27 A ok
everything         2.75 A ok         11.54 A OVER

logic   converter 5.0 A rated, 4.0 A budget at 80% derating
motion  converter 8.0 A rated, 6.4 A budget at 80% derating

The last row is the one people misread. 11.54 A is every servo stalled at the same instant with the ring at full white and the speaker at full volume, and nothing in her software ever intentionally asks for that. A stalled mechanism can still create it. The motion converter cannot sustain that row; calibrated joint limits and sequencing reduce ordinary demand but cannot interrupt a short circuit or a jam. The three rows that are commands all sit inside the budget with room over, which is the answer you want before any wire gets cut. The 80 percent derating is there because a converter's rating is a maximum, not a comfortable operating point: run one at its number and it gets hot, and hot converters droop.

# labs/wire_drop.py
from labs.power_budget import SCENARIOS, rail_draw_ma

# Copper resistance of one conductor, milliohms per metre, at room temperature.
MILLIOHMS_PER_M = {24: 84.2, 22: 52.9, 20: 33.3, 18: 20.9, 16: 13.2}

FEED_LENGTH_M = 0.35   # converter to the servo bracket, one way
RAIL_VOLTS = 5.0
SERVO_MIN_V = 4.60     # below this the servos in this build start misbehaving


def loop_milliohms(awg: int, one_way_m: float) -> float:
    """Current goes out and comes back, so both conductors count."""
    return MILLIOHMS_PER_M[awg] * one_way_m * 2


def drop_volts(awg: int, one_way_m: float, amps: float) -> float:
    """Ohm's law on the feed: the volts the wire keeps for itself."""
    return loop_milliohms(awg, one_way_m) / 1000 * amps


if __name__ == "__main__":
    reach = rail_draw_ma("motion", SCENARIOS["arm reach"]) / 1000
    worst = rail_draw_ma("motion", SCENARIOS["everything"]) / 1000
    print(f"motion rail feed: {FEED_LENGTH_M} m each way, {RAIL_VOLTS:.2f} V at the converter")
    print(f"{'awg':>4}{'loop':>11}{'arm reach':>23}{'everything':>23}")
    for awg in sorted(MILLIOHMS_PER_M):
        d_reach = drop_volts(awg, FEED_LENGTH_M, reach)
        d_worst = drop_volts(awg, FEED_LENGTH_M, worst)
        end_reach = RAIL_VOLTS - d_reach
        end_worst = RAIL_VOLTS - d_worst
        print(f"{awg:>4}{loop_milliohms(awg, FEED_LENGTH_M):>8.1f} mR"
              f"{d_reach * 1000:>10.0f} mV -> {end_reach:.2f} V"
              f"{d_worst * 1000:>10.0f} mV -> {end_worst:.2f} V"
              f"{'' if end_worst >= SERVO_MIN_V else '  under 4.60 V'}")

$ uv run python -m labs.wire_drop
motion rail feed: 0.35 m each way, 5.00 V at the converter
 awg       loop              arm reach             everything
  16     9.2 mR        21 mV -> 4.98 V       107 mV -> 4.89 V
  18    14.6 mR        33 mV -> 4.97 V       169 mV -> 4.83 V
  20    23.3 mR        53 mV -> 4.95 V       269 mV -> 4.73 V
  22    37.0 mR        84 mV -> 4.92 V       427 mV -> 4.57 V  under 4.60 V
  24    58.9 mR       134 mV -> 4.87 V       680 mV -> 4.32 V  under 4.60 V

22 AWG is what comes attached to a servo extension lead, and for one eye servo it is fine. The same wire feeding seven things is not. Current leaves on one conductor and returns on the other, so the loop is twice the length of the run, and the fault column in 22 AWG puts the servo end below its floor while the converter is still doing everything right. Move the feed to 18 AWG and the cable costs 33 mV during a reach instead of 84. The other half of the fix is geometry: shorten the run. Both are free now and expensive once the cable is inside a printed shell with the arm over it.

# labs/power_sense.py
from dataclasses import dataclass

VREF = 3.3        # the MCP3008's reference, tied to the Pi's 3.3 V pin
ADC_MAX = 1023    # a 10-bit converter counts 0 to 1023, not 0 to 1024
MAX_SOURCE_OHMS = 10_000   # what the chip's sampling capacitor can charge from


@dataclass(frozen=True)
class Sense:
    """One divider feeding one ADC channel."""
    name: str
    channel: int
    r_top: float       # from the thing being measured to the junction
    r_bottom: float    # from the junction to ground
    rail_max_v: float  # the highest this point should ever legitimately reach

    @property
    def ratio(self) -> float:
        return self.r_bottom / (self.r_top + self.r_bottom)

    @property
    def full_scale_v(self) -> float:
        """The input voltage that would put the junction exactly at VREF."""
        return VREF / self.ratio

    @property
    def source_ohms(self) -> float:
        """What the ADC sees looking back into the junction: the two in parallel."""
        return self.r_top * self.r_bottom / (self.r_top + self.r_bottom)

    def problems(self) -> list[str]:
        out = []
        if self.rail_max_v > self.full_scale_v:
            out.append(f"{self.name}: {self.rail_max_v:.2f} V is past the "
                       f"{self.full_scale_v:.2f} V full scale of this divider")
        if self.source_ohms > MAX_SOURCE_OHMS:
            out.append(f"{self.name}: {self.source_ohms:.0f} ohm source is above the "
                       f"{MAX_SOURCE_OHMS} ohm the chip can sample cleanly")
        return out


SENSES = {
    "pack":   Sense("pack",   0, 10_000, 3_900, rail_max_v=8.40),
    "motion": Sense("motion", 1, 10_000, 10_000, rail_max_v=5.30),
}

# Measured on one 2S pack, resting, with the machine idle. Descending.
LIPO_2S = [
    (8.40, 100), (8.20, 90), (8.00, 78), (7.80, 64), (7.60, 49),
    (7.40, 33), (7.20, 18), (7.00, 6), (6.60, 0),
]


def adc_to_volts(raw: int, sense: Sense) -> float:
    """Raw count -> junction volts -> the volts on the other side of the divider."""
    junction_v = raw / ADC_MAX * VREF
    return junction_v / sense.ratio


def capacity_percent(volts: float, table: list[tuple[float, int]] = LIPO_2S) -> int:
    """State of charge, interpolated between the two rows this voltage falls between."""
    if volts >= table[0][0]:
        return table[0][1]
    if volts <= table[-1][0]:
        return table[-1][1]
    for (v_hi, c_hi), (v_lo, c_lo) in zip(table, table[1:]):
        if v_lo <= volts <= v_hi:
            fraction = (volts - v_lo) / (v_hi - v_lo)
            return round(c_lo + fraction * (c_hi - c_lo))
    return table[-1][1]


if __name__ == "__main__":
    for sense in SENSES.values():
        print(f"{sense.name:<7} ch{sense.channel}  {sense.r_top:.0f}/{sense.r_bottom:.0f} ohm"
              f"  ratio {sense.ratio:.4f}  full scale {sense.full_scale_v:5.2f} V"
              f"  source {sense.source_ohms:.0f} ohm")
        for problem in sense.problems():
            print(f"  PROBLEM  {problem}")
    print()
    for raw in (689, 671, 640, 597):
        volts = adc_to_volts(raw, SENSES["pack"])
        print(f"pack   raw {raw}  ->  {volts:5.2f} V  ->  {capacity_percent(volts):3d}%")
    for raw in (778, 755):
        print(f"motion raw {raw}  ->  {adc_to_volts(raw, SENSES['motion']):5.2f} V")

$ uv run python -m labs.power_sense
pack    ch0  10000/3900 ohm  ratio 0.2806  full scale 11.76 V  source 2806 ohm
motion  ch1  10000/10000 ohm  ratio 0.5000  full scale  6.60 V  source 5000 ohm

pack   raw 689  ->   7.92 V  ->   72%
pack   raw 671  ->   7.71 V  ->   57%
pack   raw 640  ->   7.36 V  ->   30%
pack   raw 597  ->   6.86 V  ->    4%
motion raw 778  ->   5.02 V
motion raw 755  ->   4.87 V

Three properties earn their place. ratio is the arithmetic the divider performs. full_scale_v answers a question the ratio hides: what input would put the junction exactly at the reference, and therefore how much headroom sits above the highest legal reading. The pack divider tops out at 11.76 V against a pack that should never exceed 8.40, which is deliberate slack for a charger left connected or a wrong pack plugged in. source_ohms is the property nobody expects to matter, and it is the whole of the next few paragraphs.

The capacity table is measured, not derived. A lithium cell's discharge curve is flat through the middle and steep at both ends, so nine anchor points with a straight line between neighbours fits it where no single formula does. 7.71 V lands between the 7.80 row and the 7.60 row and comes back 57 percent, not the 64 a nearest-row lookup would report. The two clamps matter as much as the interpolation: outside the table the loop has no pair to sit between, and an over-voltage reading would fall out as zero.

# labs/power_monitor.py
import json
import time
from datetime import datetime, timezone
from pathlib import Path

import spidev

from labs.power_sense import SENSES, Sense, adc_to_volts, capacity_percent
from labs.wire_drop import SERVO_MIN_V

SPI_BUS, SPI_DEVICE = 4, 0        # /dev/spidev4.0, the ADC's own bus
SPI_HZ = 1_350_000                # the MCP3008's ceiling at a 3.3 V reference
SAMPLE_HZ = 50                    # how often each channel is looked at
REPORT_S = 10.0                   # how much history each printed line covers
LOG_PATH = Path("glados/data/power_log.jsonl")


def read_channel(spi: spidev.SpiDev, channel: int) -> int:
    """One single-ended conversion. Returns 0-1023."""
    if not 0 <= channel <= 7:
        raise ValueError(f"MCP3008 has channels 0-7, got {channel}")
    reply = spi.xfer2([0x01, (0x08 | channel) << 4, 0x00])
    return ((reply[1] & 0x03) << 8) | reply[2]


def summarise(raws: list[int], sense: Sense) -> tuple[float, float]:
    """The least-loaded and most-loaded volts in a window of samples."""
    return adc_to_volts(max(raws), sense), adc_to_volts(min(raws), sense)


def append_log(entry: dict) -> None:
    """One JSON object, one line, appended. A half-written line loses one sample."""
    LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
    with LOG_PATH.open("a") as f:
        f.write(json.dumps(entry) + "\n")


def main() -> None:
    spi = spidev.SpiDev()
    spi.open(SPI_BUS, SPI_DEVICE)
    spi.max_speed_hz = SPI_HZ
    window: dict[str, list[int]] = {name: [] for name in SENSES}
    deadline = time.monotonic() + REPORT_S
    try:
        while True:
            for name, sense in SENSES.items():
                window[name].append(read_channel(spi, sense.channel))
            time.sleep(1 / SAMPLE_HZ)
            if time.monotonic() < deadline:
                continue
            pack_rest, pack_sag = summarise(window["pack"], SENSES["pack"])
            rail_rest, rail_sag = summarise(window["motion"], SENSES["motion"])
            entry = {
                "t": datetime.now(timezone.utc).isoformat(timespec="seconds"),
                "pack_rest_v": round(pack_rest, 2), "pack_sag_v": round(pack_sag, 2),
                "rail_rest_v": round(rail_rest, 2), "rail_sag_v": round(rail_sag, 2),
                "capacity_pct": capacity_percent(pack_rest),
            }
            append_log(entry)
            warning = "  MOTION RAIL BELOW SPEC" if rail_sag < SERVO_MIN_V else ""
            print(f"{entry['t'][11:19]}  pack {pack_rest:.2f} V (sag {pack_sag:.2f})"
                  f"  motion {rail_rest:.2f} V (sag {rail_sag:.2f})"
                  f"  {entry['capacity_pct']:3d}%{warning}")
            window = {name: [] for name in SENSES}
            deadline = time.monotonic() + REPORT_S
    except KeyboardInterrupt:
        pass
    finally:
        spi.close()


if __name__ == "__main__":
    main()

$ uv run python -m labs.power_monitor   # measured on the bench, yours will vary
19:04:11  pack 7.92 V (sag 7.92)  motion 5.02 V (sag 5.02)   72%
19:04:21  pack 7.92 V (sag 7.83)  motion 5.02 V (sag 4.94)   72%
19:04:31  pack 7.92 V (sag 7.71)  motion 5.02 V (sag 4.87)   72%
19:04:41  pack 7.90 V (sag 7.44)  motion 5.01 V (sag 4.58)   71%  MOTION RAIL BELOW SPEC
19:04:51  pack 7.91 V (sag 7.90)  motion 5.02 V (sag 5.02)   72%

The highest sample in a window is the closest thing to a resting reading, so capacity comes from that; the lowest is the deepest sag, so the warning comes from that. Read the third and fourth lines together: the pack barely moved while the motion rail lost almost half a volt and crossed the floor the servos need. The rail is where a brownout actually lives. Capacity also ticks back up on the last line, from 71 to 72, because an unloaded pack recovers a few tens of millivolts. That is chemistry, and a good argument against showing anyone a percentage that jitters.

Fifty samples a second per channel is twenty milliseconds between looks. A servo move lasts a few hundred milliseconds and the window catches it comfortably. The inrush at the very start lasts a couple of milliseconds and this loop will usually miss it entirely. This loop records trends and sampled minima. Capacitors can reduce short droops, but proving their effect needs a scope or faster acquisition with a suitable trigger and bandwidth; the logger cannot certify the intervals it never observed.

The log is JSON Lines: one object, one line, opened for append. This chapter exists because the machine sometimes loses power without warning, so the format has to survive that. Rewriting a whole JSON array every ten seconds leaves an instant where the old file is gone and the new one unfinished; losing power there costs the entire history. Appending costs, at worst, a truncated final line.

$ tail -2 glados/data/power_log.jsonl
{"t": "2026-08-14T19:04:41+00:00", "pack_rest_v": 7.9, "pack_sag_v": 7.44, "rail_rest_v": 5.01, "rail_sag_v": 4.58, "capacity_pct": 71}
{"t": "2026-08-14T19:04:51+00:00", "pack_rest_v": 7.91, "pack_sag_v": 7.9, "rail_rest_v": 5.02, "rail_sag_v": 5.02, "capacity_pct": 72}