megawrapper 0.2.1

Arduino-style motor and servo control using Firmata — a combined MegaWrapper library

MegaWrapper

A combined DC-motor + servo control library for Arduino via Firmata.

from megawrapper import Board

board = Board("/dev/ttyUSB0")
motor = board.attach_motor(2, 4, 11)
motor.forward(100)
board.close()

Installation

pip install -e /path/to/MegaWrapper

Requires Python 3.8+. Primary dependency: pyfirmata2. Optional: pyserial (for the alternative Firmata backend), adafruit-circuitpython-vl53l0x (for the ToF sensor).

Documentation

Full API reference, wiring diagrams, and usage guides are on the project wiki.

Examples

Ready-to-run scripts are in examples/:

File	What it shows
single_motor.py	Basic motor forward/stop
dual_motor.py	Two motors with names
tank_drive.py	Differential steering pattern
keyboard_control.py	Interactive CLI motor control
endless_sweep.py	Servo sweep via sweep()
move_smooth.py	Servo motion with move_smooth()
pyserial_control.py	Using the pyserial Firmata backend
vl53l0x_sensor.py	Single VL53L0X distance sensor readout
vl53l0x_multi_sensor.py	Multiple VL53L0X sensors via auto_address

Run any example with python examples/<file>.py.

API Overview

Board

Board(port, stby=None)      # Connect to Arduino (stby = optional STBY pin)
Board.get_active_board()    # Get the most recently created Board
Board.has_active_board()    # True if any Board is active
board.attach_motor(d1, d2, pwm, name=None)
board.stop_all()
board.wake() / board.sleep()   # Requires stby pin
board.close()                  # Stop motors + release board

Motor

motor.forward(speed)    # 0–100
motor.backward(speed)   # 0–100
motor.stop()            # Coast stop
motor.brake()           # Active brake
motor.set_speed(n)      # Change speed without changing direction
motor.speed             # Current speed (0–100)
motor.direction         # "forward" | "backward" | "stopped" | "braked"

Servo

servo = Servo()
servo.attach(pin)               # Must create a Board first
servo.write(angle)              # 0–180 (clamped)
servo.read()                    # Returns last commanded angle
servo.move_smooth(target, delay_ms=15)
servo.sweep(start=0, end=180, step=1, delay_ms=15)
servo.detach()

VL53L0X Time-of-Flight Sensor

from megawrapper.sensor import VL53L0X

# Single sensor (default I²C address 0x29)
sensor = VL53L0X()
distance = sensor.distance               # cm

# Multiple sensors with auto-address
sensors = VL53L0X.auto_address([17, 27, 22])  # GPIO pins for XSHUT
for s in sensors:
    print(s.distance)

• VL53L0X(i2c=None, address=0x29) — initialise at given I²C address
• sensor.distance — returns distance in centimetres (range mm / 10)
• VL53L0X.auto_address(xshut_pins, i2c=None) — sequences XSHUT pins to assign unique addresses 0x30, 0x31, … (up to 16 sensors)
• Independent of Board/Firmata — runs on the host's I²C bus (Raspberry Pi GPIO). Requires the [sensor] extra: pip install 'megawrapper[sensor]'

Utilities

delay(ms)      # Blocking sleep in milliseconds
millis()       # Monotonic millisecond counter

Backend Modes

set_mode("pyserial")            # Use built-in pyserial Firmata client
set_mode("pyfirmata2")          # Default — use pyfirmata2 library
get_mode()                      # Current mode

Exceptions

MegaWrapperError, InvalidSpeedError, BoardConnectionError, StandbyNotConfiguredError

Testing

python -m pytest tests/ -v

All tests mock the Arduino — no hardware required. 92 tests, ~1.5 s.

License

MIT