Metadata-Version: 2.4
Name: megawrapper
Version: 1.0.0
Summary: Arduino-style motor and servo control using Firmata — a combined MegaWrapper library
Author: Vihaan Parlikar
License: MIT
Keywords: arduino,motor,servo,control,firmata,megawrapper
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyfirmata2
Provides-Extra: pyserial
Requires-Dist: pyserial; extra == "pyserial"
Provides-Extra: sensor
Requires-Dist: adafruit-circuitpython-vl53l0x; extra == "sensor"
Dynamic: license-file

# MegaWrapper

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

```python
from megawrapper import Board

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

## Installation

```bash
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](../../wiki).

## Examples

Ready-to-run scripts are in [`examples/`](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

```python
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

```python
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

```python
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

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

### Backend Modes

```python
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

```bash
python -m pytest tests/ -v
```

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

## License

MIT
