Lumio V2 Codebase Documentation

To View the Hardware docs and BOM click HERE

System Overview

Lumio V2 is a two-processor robot: a Raspberry Pi 5 runs the high-level software (web UI, WiFi, motor control, ADC), and an RP2040 acts as a GPIO co-processor, expanding the available I/O with runtime-configurable pins, PWM, and ADC channels over a UART JSON protocol.

Think of it like a city with two governments: the Pi is the mayor (policy, communication, web services) and the RP2040 is the public works department (raw GPIO muscle, sensor polling, hardware-level pin management). They communicate via a simple JSON postal system over UART.

Architecture

The system has four hardware subsystems managed by separate software layers. This separation — like your RS-485 master/slave pattern from the workshop server project — means each layer can be tested or replaced independently.

The web layer (web.py) is a thin adapter: it translates WebSocket events from the browser into method calls on RobotController, MCP3008, and RP2040 objects — similar to how your MQTT/Redis gateway translated upstream messages into RS-485 bus commands.

Module Map

Pi — main.py · Entry Point

Boots the platform in a strict sequence. All hardware objects are instantiated here and passed into the web server factory function — this is dependency injection, preventing any module from needing global singletons.

Boot Sequence

Key Behaviour

If rp.ping() fails at boot, the system logs a warning and continues — the RP2040 is treated as optional hardware. Same for WiFi: missing network does not prevent the web server from starting.

Environment Variables

Pi — config.py · Pin Definitions

The single source of truth for all hardware constants. Changing a wire? Edit only this file. Every other module imports from here — making config like the one schematic everyone reads from, rather than hardcoded magic numbers scattered across files.

Pin Groups

Motion Constants

Pi — robot.py · Motor + Sensor Control

Controls the L298N H-bridge and both HC-SR04 ultrasonic sensors. The class is thread-safe: all movement methods acquire self._lock, so the web server can't issue two simultaneous movement commands and cause GPIO conflicts.

Public API

Distance Measurement

Uses the standard HC-SR04 timing method: 10 µs TRIG pulse, then measure ECHO pulse width. Distance = pulse_time × 17150 cm/s (speed of sound / 2, rounded). Timeout of 100 ms per phase prevents lockup on missing sensors.

# Current (fixed) code
while GPIO.input(echo_pin) == 0:
    if time.monotonic() > deadline: return 999.0
t_start = time.monotonic()   # set after loop exits — correct

while GPIO.input(echo_pin) == 1:
    if time.monotonic() > deadline: return 999.0
t_end = time.monotonic()     # set after loop exits — correct

Simulation Mode

If RPi.GPIO is not installed (dev machine, CI), the module falls back to _FakeGPIO — a minimal stub that silently no-ops all GPIO calls. This lets you run and test the web server without physical hardware.

Pi — adc.py · MCP3008 ADC Driver

A pure bit-bang SPI driver — no kernel SPI device, no spidev used here. Think of it like I2C bit-banging you've seen in firmware, but for SPI: manually toggling CS, CLK, MOSI, and reading MISO pin-by-pin.

The MCP3008 protocol: send 5 bits (start + SGL/DIFF + D2..D0 channel select), then clock in 11 bits back (1 null + 10 data). The driver masks the result to 10 bits with & 0x3FF.

Public API

Pi — coprocessor.py · RP2040 UART Interface

A non-blocking serial interface. A background daemon thread reads continuously from /dev/ttyAMA0 and splits on newlines — identical in concept to the background reader thread in your RS-485 MQTT gateway. Synchronous commands use a threading.Event as a one-shot signal: send, wait for event with timeout, return the last-received reply.

Threading Model

Public API

def gpio_set_mode(self, pin: int, mode: str, label: str = "") -> bool:
    reply = self.send({"cmd": "gpio_set_mode", "pin": pin, "mode": mode, "label": label})
    return bool(reply and reply.get("ok"))

def adc_read(self, pin: int) -> float | None:
    reply = self.send({"cmd": "adc_read", "pin": pin})  # "pin", not "ch"
    if reply and reply.get("ok"):
        return reply.get("value")
    return None

Pi — web.py · Flask / SocketIO Server

A thin integration layer. The Flask app is created at module level (not inside the factory) which means the global app and socketio objects exist before create_app() is called — this is a standard Flask pattern, but means you can't run two server instances in one process.

HTTP Endpoints

WebSocket Events

# Current (fixed)
from flask import Flask, render_template, jsonify, request

@app.route("/")
def index():
    return render_template("control.html")

@app.route("/gpio")
def gpio_page():
    return render_template("gpio.html")

# Current (fixed)
for cfg in configs:
    pin   = cfg.get("pin")
    mode  = cfg.get("mode", "input")   # input|output|adc|pwm|unused
    label = cfg.get("label", "")
    ok    = _rp.gpio_set_mode(pin, mode, label)
    results.append({"pin": pin, "ok": ok})

Pi — wifi_provision.py · WiFi Setup

Handles the classic IoT "first-boot" problem: the device doesn't know your WiFi password yet. The approach is an AP hotspot + captive portal — like how home routers let you set them up via a connected laptop.

Boot Decision Tree

Defaults

RP2040 — main.py · Firmware Entry Point

MicroPython entry point. Creates a UART on GP1(TX)/GP2(RX) at 115200 baud, instantiates PinManager and Protocol, then runs a tight loop: read UART → process complete JSON lines → poll inputs for edge events every 20 ms.

# Main loop structure
while True:
    chunk = uart.read(256)
    if chunk:
        buf += chunk
        while b"\n" in buf:
            line, buf = buf.split(b"\n", 1)
            proto.handle(line)          # dispatch command

    if ticks_diff(now, last_poll) >= POLL_MS:
        pm.poll_events(proto.push_event)  # check input edges
    sleep_ms(1)

The 1 ms sleep keeps the loop from burning CPU while still being responsive. POLL_MS=20 ms means input edge events are detected with up to 20 ms latency — fine for sensors, too slow for high-speed encoders.

RP2040 — protocol.py · Command Dispatcher

A pure dispatcher: it owns the UART send path and maps command strings to PinManager method calls. No state of its own beyond references to UART and PinManager. Think of it like a router in your MQTT/RS-485 bridge — it reads a message, figures out which handler owns it, and forwards it.

Command Handling Flow

RP2040 — pin_manager.py · GPIO State Machine

Each pin is a PinState object that holds its current mode, the live MicroPython machine object (Pin, ADC, or PWM), and last-known value for edge detection. The release() method calls PWM.deinit() before reconfiguring — like properly closing a file before reopening it in a different mode.

Pin Availability

PinState API

Note: inputs are initialised with Pin.PULL_DOWN. If your sensor requires pull-up, you'll need to pass Pin.PULL_UP in configure() or use an external resistor.

RP2040 ↔ Pi — Full Protocol Reference

All messages are newline-terminated JSON (\n). The Pi is always master: it sends commands, the RP2040 replies synchronously. The RP2040 can additionally push unsolicited event frames when an input pin changes state.

Commands (Pi → RP2040)

// Health check
{"cmd": "ping"}

// Configure a pin's mode and optional label
{"cmd": "gpio_set_mode", "pin": 5, "mode": "input",  "label": "IR sensor"}
{"cmd": "gpio_set_mode", "pin": 6, "mode": "output", "label": "LED"}
{"cmd": "gpio_set_mode", "pin": 26, "mode": "adc"}
{"cmd": "gpio_set_mode", "pin": 7, "mode": "pwm"}
{"cmd": "gpio_set_mode", "pin": 8, "mode": "unused"}

// Digital I/O
{"cmd": "gpio_read",  "pin": 5}
{"cmd": "gpio_write", "pin": 6, "value": 1}

// ADC (pin must be GP26–GP29 in adc mode) — key is "pin", not "ch"!
{"cmd": "adc_read", "pin": 26}

// PWM (duty: 0–65535 u16 resolution)
{"cmd": "pwm_set", "pin": 7, "freq": 50, "duty": 4915}

// Introspection
{"cmd": "list_pins"}   // all assignable pins
{"cmd": "get_all"}     // only non-unused pins

Replies (RP2040 → Pi)

{"ok": true}
{"ok": true,  "value": 1}          // gpio_read
{"ok": true,  "value": 1.6523}     // adc_read (voltage, 3.3V ref)
{"ok": true,  "pins": [{"pin": 5, "mode": "input", "label": "IR", "value": 0}, ...]}
{"ok": false, "error": "pin 26 not in adc mode"}

Async Events (RP2040 → Pi, unsolicited)

{"event": "change", "pin": 5, "value": 1}   // rising edge
{"event": "change", "pin": 5, "value": 0}   // falling edge

✓ Resolved Issues — Changelog

Four bugs were identified and fixed across three files. The warning about BCM 35 remains open — it requires physical board verification before first power-on.