Interfaces

Core interfaces

Abstract interfaces for openbricks components.

MicroPython doesn’t ship full typing.Protocol support, so these are plain base classes. Drivers should subclass the appropriate interface and fill in every method. The higher-level modules (robotics, config) only depend on these interfaces, never on concrete drivers — that’s what makes the system plug-and-play.

If you add a new category of component (e.g. a distance sensor), add its interface here.

class openbricks.interfaces.Motor

Bases: object

A bidirectional motor.

Implementations range from an open-loop H-bridge driver (L298N) to a closed-loop geared motor with quadrature encoder (JGB37-520).

Units

• power is -100..100 (percent duty cycle, sign = direction).

• speed is degrees per second at the output shaft (closed-loop only).

• angle is degrees at the output shaft (closed-loop only).

run(power)

Run at the given power (-100..100). Non-blocking.

brake()

Stop with active braking (both terminals shorted).

coast()

Stop by cutting drive power (motor free-wheels).

hold()

Stop and actively hold the current shaft angle via closed-loop control. Only motors with position-mode hardware (e.g. ST-3215) or a software position loop implement this; open-loop drivers raise NotImplementedError — pick brake or coast instead.

angle()

Return the current shaft angle in degrees.

reset_angle(angle=0)

Set the current angle to angle degrees.

run_speed(deg_per_s)

Hold a target speed (closed loop).

run_angle(deg_per_s, target_angle, wait=True)

Rotate by target_angle degrees at deg_per_s. Blocks if wait; otherwise returns immediately and the caller polls done() to advance the move and detect completion.

done()

Return True if no non-blocking move is in flight or the active run_angle(wait=False) move has reached its target. Drivers that don’t support non-blocking moves always return True (a wait=True call is finished before returning to the caller, by definition).

class openbricks.interfaces.Servo

Bases: object

A position-controlled servo (angle-addressable).

move_to(angle_deg, speed=None, wait=True)

Move to absolute angle in degrees.

angle()

Read back the current angle.

class openbricks.interfaces.IMU

Bases: object

A 3-axis inertial measurement unit.

The expected unit convention is:

• heading/yaw/pitch/roll in degrees

• angular_velocity in degrees / second

• acceleration in m / s^2

heading()

Return heading (yaw) in degrees, wrapped to [-180, 180).

angular_velocity()

Return (wx, wy, wz) in deg/s.

acceleration()

Return (ax, ay, az) in m/s^2.

class openbricks.interfaces.ColorSensor

Bases: object

An RGB-ish color sensor.

rgb()

Return (r, g, b) each in 0..255.

ambient()

Return ambient / clear-channel intensity in 0..100.

Distance sensors

Distance-sensor interface, kept separate from interfaces.py.

Why split: openbricks/__init__.py eagerly imports the four core interfaces (Motor / Servo / IMU / ColorSensor) so that every import openbricks pays them. The observer’s variance test runs close to the MicroPython heap ceiling, so adding even a small class to interfaces.py tips it over. Distance-sensor users explicitly import this module.

class openbricks.distance.DistanceSensor

Bases: object

A forward-facing range sensor (HC-SR04 / VL53L0X).

distance_mm()

Distance ahead in millimetres; -1 if no echo / out of range.