megawrapper 1.0.0

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	VL53L0X distance sensor readout

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()

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, ~0.5 s.

License

MIT