Metadata-Version: 2.5
Name: plesty-arduino-firmata
Version: 0.1.0
Summary: Plesty device for any board running StandardFirmata (Arduino Uno, Mega, …): digital, PWM, servo and analog pins over USB serial.
Author-email: Yunshuang Yuan <yunshuang.yuan@fkp.uni-hannover.de>
Maintainer-email: Plesty Development Team <plesty.dev@example.com>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
License-File: LICENSES/LGPL-3.0-or-later.txt
Requires-Python: >=3.12
Requires-Dist: plesty-lib>=0.5.2
Requires-Dist: pyserial>=3.5
Provides-Extra: gui
Requires-Dist: plesty-lib[gui]>=0.5.2; extra == 'gui'
Description-Content-Type: text/markdown

# Plesty Arduino Firmata

A [PLESTY](https://plesty.net) device module for any board running the stock
**StandardFirmata** sketch — Arduino Uno, Mega and the like. It drives the
board's pins over USB serial: digital outputs and inputs, PWM, hobby servos and
analog inputs.

The module knows pins, not instruments. An instrument wired to the board —
a polarization controller, a motor driver — gets its own module that builds on
this one and gives the pins their meaning (for example
[`plesty-pcd-m02`](https://gitlab.com/plesty/hub/devices/luna/plesty-pcd-m02)).

## Prepare the board

Upload StandardFirmata once, from the Arduino IDE: **File → Examples →
Firmata → StandardFirmata**. No other sketch is needed; this module speaks the
public [Firmata protocol](https://github.com/firmata/protocol) at 57600 baud.

## Installation

```bash
git clone https://gitlab.com/plesty/hub/devices/arduino/plesty-arduino-firmata.git
cd plesty-arduino-firmata
uv sync
```

On Linux, add your user to the `dialout` group for serial access
(`sudo usermod -aG dialout $USER`, then log in again).

## Usage

```python
from plesty.arduino_firmata import Device

with Device(port="auto") as board:  # or "COM5", "/dev/ttyACM0", a USB serial number
    print(board.identity())  # StandardFirmata.ino 2.5 (Firmata) on COM5

    board.set_pin_modes([22, 23], "output")
    board.write_digital_pins(pins=[22, 23], levels=[True, False])

    board.set_pin_mode(pin=5, mode="input_pullup")
    print(board.read_digital(pin=5))  # {'level': True}
    print(board.read_analog(channel=0))  # {'counts': 512}
```

`port="auto"` picks the one genuine Arduino attached and refuses when there
are none or several. A clone with a CH340 USB chip is not recognised — name
its port or serial number instead.

Opening a session resets the board: every pin starts in the sketch's default
and must be given a mode before it is written or read. Firmata cannot report
an output pin back, so `read_digital` on an output answers the level this
session last wrote.

`port="mock"` runs everything against a simulated Arduino Mega, no board
needed.

## Run as TCP server

Copy `.env.example` to `.env` and set `DEVICE_ADDRESS`, then:

```bash
uv run python -m plesty.arduino_firmata --tcp-port 5555
```

## Open the control panel

```bash
uv sync --extra gui
uv run python -m plesty.arduino_firmata --gui
```

`--gui` drives the board from this process instead of serving it — one
session is all the serial port allows, so the process does one or the other.
