Metadata-Version: 2.4
Name: pydobotlab
Version: 0.1.0.1
Summary: Pure-Python control library for the Dobot Magician robot arm. A lightweight, cross-platform replacement for DobotStudio / DobotLab. Tel Aviv University CIM Lab
Author-email: Tal Eylon <taleylon1@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://taleylon.github.io/pydobotlab/
Project-URL: Documentation, https://taleylon.github.io/pydobotlab/
Project-URL: Repository, https://github.com/taleylon/pydobotlab
Project-URL: Issues, https://github.com/taleylon/pydobotlab/issues
Keywords: dobot,magician,robotics,serial,education
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyserial>=3.5
Provides-Extra: gui
Requires-Dist: PySide6>=6.5; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.6; extra == "docs"
Dynamic: license-file

# pydobotlab

Python control for the **Dobot Magician**, with full coverage of the 28 Python
API entries in the [official DobotLab Magician manual](https://cdn.release.dobot.cc/dobotlab-doc/dobotlab/coding-manual-en/20260205/Dobot%20Magician/Dobot%20Magician.html).
Use the documented function names and arguments for motion, I/O, sensors,
end-effectors, the slideway, and the conveyor.

All ten `ptp` modes are supported. Extended control adds `move_to` with waiting,
timeouts, and alarm handling, command batching, and live pose streaming. Run Python scripts
and the optional desktop control panel separately or in parallel. A simulator
supports working without hardware.

Communicates over serial using `pyserial` and the
[Dobot Communication Protocol V1.1.5](https://download.dobot.cc/product-manual/dobot-magician/pdf/en/Dobot-Communication-Protocol-V1.1.5.pdf);
no vendor DLL or DobotStudio installation is required.

**[Documentation & homepage](https://taleylon.github.io/pydobotlab/)** ·
[API reference](https://taleylon.github.io/pydobotlab/api/overview/) ·
[GitHub](https://github.com/taleylon/pydobotlab) ·
[Report an issue](https://github.com/taleylon/pydobotlab/issues)

## Installation

Requires **Python 3.10 or newer**. Install in a virtual environment:

```bash
python -m pip install pydobotlab
```

For the optional PySide6 desktop panel:

```bash
python -m pip install "pydobotlab[gui]"
pydobotlab-panel
```

The base library requires only `pyserial`; Qt is installed only with the
`gui` extra. See the [installation guide](https://taleylon.github.io/pydobotlab/getting-started/install/)
for virtual environments, Windows drivers, and Linux serial-port permissions.
The project has been used on Ubuntu and Windows; macOS hardware has not been verified.

## Quick start

With the arm connected and its workspace clear:

```python
from pydobotlab import Magician, PTPMode

with Magician() as robot:  # auto-discover; or specify "/dev/ttyUSB0" / "COM3"
    robot.clear_alarm()
    robot.set_home()
    command_index = robot.ptp(mode=PTPMode.MOVJ_XYZ, x=220, y=0, z=50, r=0)
    robot.wait_for(command_index)
    pose = robot.get_pose()
    print(pose)
```

`print(pose)` displays `x`, `y`, `z`, `r`, and all four joint angles:

```text
Pose(x=220.00, y=0.00, z=50.00, r=0.00, joints=[0.00, 30.00, 45.00, 0.00])
```

The values above illustrate the format; actual joint angles depend on the robot's
pose. Access individual values with `pose.x`, `pose.y`, `pose.z`, `pose.r`, or
`pose.joints`. Positions are in millimetres and angles are in degrees.

`Dobot` is also available as an alias for `Magician`. The documented DobotLab
method names and parameters are preserved for existing scripts.

Queued commands such as `ptp` return a queue index; use `wait_for` to wait for
completion. `move_to` combines motion and waiting in one call:

```python
with Magician() as robot:
    robot.move_to(220, 0, 50, r=0, mode=PTPMode.MOVL_XYZ, timeout=30)
```

See [DobotLab compatibility](https://taleylon.github.io/pydobotlab/api/dobotlab/)
for the complete function list and return-value conventions.

## Try it without hardware

```bash
pydobotlab-panel --simulator
```

Or use the simulator from Python:

```python
from pydobotlab import Magician
from pydobotlab.simulator import install_simulator, stop_all

install_simulator(arms=1)
try:
    with Magician("/dev/sim0", via_broker=False) as robot:
        robot.move_to(220, 0, 50)
        print(robot.get_pose())
finally:
    stop_all()
```

The simulator supports offline examples and tests. It approximates motion
and firmware behavior; it does not validate a real robot's trajectory.

## Features and examples

- Cartesian and joint motion, jogging, homing, speed settings, and continuous paths.
- Suction cup, gripper, laser, digital I/O, sensors, and conveyor commands.
- Structured alarms, motion-failure exceptions, and live pose streaming.
- Firmware queue control and `with robot.batch()` for accumulating commands.
- Multiple robot connections and a local broker for sharing a port between the GUI and scripts.

Start with [pick and place](https://github.com/taleylon/pydobotlab/blob/main/examples/pick_and_place.py),
[smiley drawing](https://github.com/taleylon/pydobotlab/blob/main/examples/draw_smiley.py),
or [two arms with live panels](https://github.com/taleylon/pydobotlab/blob/main/examples/two_dobots_with_panels.py).
The [user guide](https://taleylon.github.io/pydobotlab/) covers the API,
control panel, broker, and wire protocol.

## License

MIT. Maintained by Tal Eylon, <taleylon1@gmail.com>.
