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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
uc2_rest-0.2.0.40.tar.gz
(77.4 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file uc2_rest-0.2.0.40.tar.gz.
File metadata
- Download URL: uc2_rest-0.2.0.40.tar.gz
- Upload date:
- Size: 77.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9c83443b5d74fefe12dd3dd9c5b243e6f0526436d8ba14edc91275065d8e1160
|
|
| MD5 |
c27768d794a7cb7c36200c965a7d8ade
|
|
| BLAKE2b-256 |
e87f4f8f32c501b4c60dbf5de8b492c18756ce623fdbf3b27b4f09094b688fc1
|
File details
Details for the file uc2_rest-0.2.0.40-py3-none-any.whl.
File metadata
- Download URL: uc2_rest-0.2.0.40-py3-none-any.whl
- Upload date:
- Size: 91.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
aed117c93ee8b4e007f33335cf853e506d70f69324fea7c26736c06de98eb0fc
|
|
| MD5 |
553b19b3d1d60fe367c699838e679501
|
|
| BLAKE2b-256 |
fcd9ea096cc426decfad6b3e1e23354dc223b8d2048d444cf99d2cda81d2fd0b
|
