UC2‑Python Client
Python interface to the UC2 REST micro‑controller firmware — control motors, lasers, LED matrices, galvos and more over USB‑Serial or Wi‑Fi from any Python environment.
Highlights
- Plug‑and‑play connection via USB (
/dev/ttyUSB*,COM*) or TCP (host,port). - Rich device model: every hardware block is a Python object with high‑level helpers (e.g.
motor.move_x,led.setPattern,laser.set_laser). - Asynchronous & blocking modes for precise timing or maximum throughput.
- Callback hooks to react to hardware feedback in real time.
- Runs everywhere: desktop Python, headless Raspberry Pi, or in‑browser with PyScript.
- LGPL‑3.0‑or‑later license – use it in academic and commercial projects.
Installation
pip install uc2rest # latest release
# or for the bleeding‑edge version
pip install git+https://github.com/openUC2/UC2-REST.git#subdirectory=PYTHON
Dependencies (requests, numpy, pyserial) are resolved automatically.
Quick start
import uc2rest
# USB example
esp = uc2rest.UC2Client(serialport="/dev/ttyUSB0") # Linux / Mac OS
# esp = uc2rest.UC2Client(serialport="COM3") # Windows
# Wi‑Fi example
# esp = uc2rest.UC2Client(host="192.168.4.1", port=31950)
# LED matrix: switch all pixels on at half intensity
esp.led.setAll(True, intensity=128)
# Move X axis by 1 mm (1000 steps @ 1 kHz)
esp.motor.move_x(steps=1000, speed=1000, is_blocking=True)
# Turn green laser to full power
esp.laser.set_laser(channel="G", value=255)
Supported modules (automatically attached to UC2Client) citeturn1file12
| Object | Purpose | Example method(s) |
|---|---|---|
motor |
X/Y/Z/θ stages | move_x / move_xy, setup_motor |
led |
8×8 RGB LED matrix | setPattern, send_LEDMatrix_rings |
laser |
3‑channel RGB or IR lasers | set_laser, set_servo |
galvo |
Analogue DAC & 2‑axis scanner | set_dac, set_scanner_pattern |
gripper |
Micro‑gripper (servo) | open, close |
home |
End‑stop homing routines | home_x, home_z |
rotator |
Filter wheel or Dove prism | move, set_speed |
objective |
Piezo objective positioner | move_z, calibrate |
temperature |
NTC digital temperature sensor | get_temperature |
analog |
Arbitrary analogue outputs | set_voltage |
digitalout |
GPIO (TTL) outputs | set_pin, pulse |
wifi |
ESP32 network helpers | scan, connect |
message |
Generic key‑value messaging/trigger | register_callback, trigger_message |
Design philosophy
UC2 REST splits interaction into three JSON endpoints per device:
/*_act → perform an action (e.g. move)
/*_set → configure a device (e.g. speed)
/*_get → query state (e.g. position)
The Python client wraps those endpoints so you rarely deal with raw JSON.
Running in a browser (PyScript)
<py-config>
packages = ["uc2rest"]
</py-config>
<py-script>
from uc2rest import UC2Client
esp = UC2Client(SerialManager=pyserial_manager) # see docs
esp.led.setAll(True)
</py-script>
Documentation & examples
- Jupyter notebook tutorial:
PYTHON/UC2_REST_Tutorial_v0.ipynb - Example scripts:
examples/directory (motor scan, laser modulation, timelapse) - Firmware sources and hardware guides: https://github.com/openUC2
Troubleshooting
| Symptom | Fix |
|---|---|
serial.serialutil.SerialException |
Check port name and permissions (sudo adduser $USER dialout) |
| No JSON response / timeout | Increase timeout argument; verify baud rate matches firmware |
Contributing
- Fork the repo and create a feature branch.
- Follow the
pre‑commitchecks (black,isort,flake8). - Create pull requests against
develop.
Please open issues for bugs or feature requests.
License
MIT — see LICENSE for details.
Made with 💚 by the OpenUC2 community.
1 maintainer
Metadata
1 maintainer
Release files for UC2-REST 0.2.0.41
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| uc2_rest-0.2.0.41.tar.gz | 90.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| uc2_rest-0.2.0.41-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 190.9 kB
Release files / uc2_rest-0.2.0.41.tar.gz
| Download URL | uc2_rest-0.2.0.41.tar.gz |
|---|---|
| Size | 90.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
038d41f2afc4953889953f2c6b07910a0afc9ab0fe5747ac6d46bdfa730f86c9
|
|
BLAKE2b-256 checksum How to use checksums |
c0c738ff7f7331d306523a28626445ff7fb6af899179394e760aea77120ac6a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / uc2_rest-0.2.0.41-py3-none-any.whl
| Download URL | uc2_rest-0.2.0.41-py3-none-any.whl |
|---|---|
| Size | 100.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
22a0762ebc9a83619feb8d44d44e6867943ff2f9ffc5bcf5bd689eb20fcdbff7
|
|
BLAKE2b-256 checksum How to use checksums |
ee2faba6217e65c50c8dc931ebe3e33be862ad3acc53d465ec4c0211de2f4042
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
