pydobotlab 0.1.0__tar.gz

pydobotlab-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Use Python 3.10 or newer and a virtual environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev,gui]"
+python -m pytest --timeout=30
+ruff check .
+ruff format --check .
+```
+
+Tests use simulated devices; they do not move connected hardware. The GUI
+can be exercised without a display with `QT_QPA_PLATFORM=offscreen`.
+
+## Python style
+
+- Use descriptive verbs for functions and descriptive nouns for variables.
+  Keep established coordinate names (`x`, `y`, `z`, `r`) and the documented
+  DobotLab method signatures so existing scripts remain compatible.
+- Prefer direct code to trivial forwarding helpers. Use public methods for
+  supported operations and GUI callbacks; reserve leading underscores for
+  state and implementation details that require internal synchronization.
+- Use `pathlib.Path` for filesystem paths, explicit UTF-8 for text files,
+  built-in generic types, and `Type | None` for optional values.
+- Keep imports at module scope unless an optional dependency or circular
+  dependency requires delaying them. Do not use dynamic `__import__` calls.
+- Run Ruff and the hardware-free tests before submitting changes. Add
+  regression tests when fixing behavior, especially transport and queue bugs.
+
+## Package boundaries
+
+`protocol.py` encodes frames, `transport.py` owns serial/TCP connections,
+`device.py` exposes the robot API, and `discovery.py` finds devices. The
+optional `panel` package contains the Qt GUI. Keep Qt imports out of the
+base library. `simulator.py` supplies a software serial backend for testing.
+
+The release process is described in [docs/publishing.md](docs/publishing.md).
+
+## Documentation
+
+Install `python -m pip install -e ".[docs]"`, then use `mkdocs serve` to
+preview or `mkdocs build --strict` to check links and build the site.
+Navigation is configured in `mkdocs.yml`; retain `docs/SUMMARY.md` as the
+Markdown table of contents.

pydobotlab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tal Eylon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydobotlab-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE README.md CONTRIBUTING.md
+recursive-include pydobotlab *.py *.qss
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include docs *.md
+recursive-include scripts *.py
+prune .github
+prune .venv
+prune build
+prune dist
+global-exclude __pycache__ *.py[cod]
+include mkdocs.yml
+prune site
+global-exclude PyPI-Recovery-Codes-*.txt

pydobotlab-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: pydobotlab
+Version: 0.1.0
+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** robot arm, with an optional desktop
+control panel and a simulator for working without hardware. Communicates
+over serial using `pyserial`; 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()
+    robot.move_to(220, 0, 50, mode=PTPMode.MOVJ_XYZ)
+    pose = robot.get_pose()
+    print(pose.x, pose.y, pose.z, pose.joints)
+```
+
+`Dobot` is also available as an alias for `Magician`. The documented DobotLab
+method names and parameters are preserved for existing scripts and teaching material.
+
+## 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.
+
+## Development
+
+From a local checkout, including before the first PyPI release:
+
+```bash
+python -m pip install -e ".[dev,gui,docs]"
+python -m pytest --timeout=30
+ruff check .
+ruff format --check .
+mkdocs serve
+```
+
+See [contributor guidance](https://github.com/taleylon/pydobotlab/blob/main/CONTRIBUTING.md)
+and the [publishing guide](https://taleylon.github.io/pydobotlab/publishing/).
+
+## License
+
+MIT. Maintained by Tal Eylon, <taleylon1@gmail.com>.

pydobotlab-0.1.0/README.md

@@ -0,0 +1,105 @@
+# pydobotlab
+
+Python control for the **Dobot Magician** robot arm, with an optional desktop
+control panel and a simulator for working without hardware. Communicates
+over serial using `pyserial`; 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()
+    robot.move_to(220, 0, 50, mode=PTPMode.MOVJ_XYZ)
+    pose = robot.get_pose()
+    print(pose.x, pose.y, pose.z, pose.joints)
+```
+
+`Dobot` is also available as an alias for `Magician`. The documented DobotLab
+method names and parameters are preserved for existing scripts and teaching material.
+
+## 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.
+
+## Development
+
+From a local checkout, including before the first PyPI release:
+
+```bash
+python -m pip install -e ".[dev,gui,docs]"
+python -m pytest --timeout=30
+ruff check .
+ruff format --check .
+mkdocs serve
+```
+
+See [contributor guidance](https://github.com/taleylon/pydobotlab/blob/main/CONTRIBUTING.md)
+and the [publishing guide](https://taleylon.github.io/pydobotlab/publishing/).
+
+## License
+
+MIT. Maintained by Tal Eylon, <taleylon1@gmail.com>.

pydobotlab-0.1.0/docs/README.md

@@ -0,0 +1,54 @@
+# pydobotlab — User Guide
+
+`pydobotlab` is a pure-Python control library and GUI for the **Dobot Magician** robot arm. It replaces the official DobotStudio / DobotLab desktop app with something students can drive from a Python script *and* a control panel at the same time.
+
+Browse the guide using the sidebar, search for an API method, or use the [table of contents](SUMMARY.md). The Markdown source lives in the [GitHub repository](https://github.com/taleylon/pydobotlab/tree/main/docs). If you're new, start with [Getting Started](getting-started/install.md). If you already know the SDK and just want to look up a command, jump to the [API Reference](api/overview.md).
+
+```bash
+python -m pip install pydobotlab
+# Optional desktop control panel:
+python -m pip install "pydobotlab[gui]"
+```
+
+[Get started](getting-started/install.md){ .md-button .md-button--primary }
+[View on PyPI](https://pypi.org/project/pydobotlab/){ .md-button }
+
+## What's in this guide
+
+The guide is split into four parts:
+
+1. **[Getting Started](getting-started/install.md)** — installing the package, connecting to an arm, running your first program, and the simulator.
+2. **[API Reference](api/overview.md)** — every public function on `Magician`, grouped by what it does (motion, alarms, queue, end-effectors, I/O, ...). Each entry says what it does, what it returns, and which Dobot protocol command it sends.
+3. **[Control Panel & Broker](panel/overview.md)** — the PySide6 GUI, the multi-arm hub, and the TCP broker that lets the panel and a script share one arm.
+4. **[Protocol Reference](protocol/frame-format.md)** — the wire-level Dobot protocol: frame format, control byte, the full `CommandID` table, and how each ID maps back to a `Magician` method.
+
+## How the layers fit together
+
+```
+   ┌───────────────────────────────┐    ┌────────────────────────────┐
+   │  your script  (Magician API)  │    │   ControlPanel (PySide6)   │
+   └───────────────┬───────────────┘    └──────────────┬─────────────┘
+                   │                                   │
+                   └──────────────┬────────────────────┘
+                                  ▼
+                       ┌─────────────────────┐
+                       │     DobotBroker     │   TCP 127.0.0.1:8765
+                       │  (per-port refcnt)  │   (auto-spawned by panel)
+                       └──────────┬──────────┘
+                                  ▼
+                       ┌─────────────────────┐
+                       │    SerialTransport  │   115200 8N1
+                       └──────────┬──────────┘
+                                  ▼
+                       ┌─────────────────────┐
+                       │  Dobot V1.1.5 wire  │   AA AA  len  id  ctrl  …  cks
+                       └─────────────────────┘
+```
+
+The script-side and panel-side both speak through the same `Magician` class. When the panel is open the broker mediates so both can drive one arm; when there's no panel, `Magician` opens the serial port directly.
+
+## Quick links
+
+- Source code on disk: `pydobotlab/` (library), `pydobotlab/panel/` (GUI), `examples/`.
+- Protocol PDF reference: [Dobot Communication Protocol V1.1.5](https://www.alcom.no/wp-content/uploads/2019/11/Dobot-Communication-Protocol-V1.1.5-1.pdf) — the canonical source for command IDs and parameter layouts. Every page in the [Protocol Reference](protocol/frame-format.md) section cites it.
+- Magician feature page: [Dobot Magician — features](https://www.dobot-robots.com/products/education/magician.html).

pydobotlab-0.1.0/docs/SUMMARY.md

@@ -0,0 +1,45 @@
+# Summary
+
+* [Introduction](README.md)
+
+## Getting Started
+
+* [Installation](getting-started/install.md)
+* [Connecting to an arm](getting-started/connect.md)
+* [Hello, Magician](getting-started/first-script.md)
+* [Running without hardware (simulator)](getting-started/simulator.md)
+* [Linux setup (Ubuntu / Debian)](getting-started/linux.md)
+
+## API Reference
+
+* [Overview](api/overview.md)
+* [Connection lifecycle](api/connection.md)
+* [Pose & motion](api/motion.md)
+* [JOG (live, non-trajectory motion)](api/jog.md)
+* [Speed & motion parameters](api/speed.md)
+* [Alarms](api/alarms.md)
+* [Queue control](api/queue.md)
+* [End-effectors](api/end-effectors.md)
+* [Digital I/O & sensors](api/io.md)
+* [Conveyor & extras](api/extras.md)
+* [Real-time pose stream](api/pose-stream.md)
+* [Discovery (finding arms)](api/discovery.md)
+* [Errors & exceptions](api/errors.md)
+
+## Control Panel & Broker
+
+* [Overview](panel/overview.md)
+* [Running the panel](panel/running.md)
+* [The DobotBroker (multi-client)](panel/broker.md)
+
+## Protocol Reference
+
+* [Frame format](protocol/frame-format.md)
+* [Control byte (rw / isQueued)](protocol/ctrl-byte.md)
+* [Command ID table](protocol/command-ids.md)
+* [Method ↔ command mapping](protocol/method-to-cmd.md)
+* [Alarm bitmask](protocol/alarms.md)
+
+## Project
+
+* [Publishing and maintaining the project](publishing.md)

pydobotlab-0.1.0/docs/api/alarms.md

@@ -0,0 +1,125 @@
+# Alarms
+
+The arm reports faults as a 16-byte (128-bit) bitmask. Each bit is a named alarm code (`0x00..0x7F`); `byte_index = code // 8`, `bit_index = code % 8`. pydobotlab decodes that mask into a friendly [`AlarmSet`](#alarmset) with names *and* per-alarm troubleshoot lines.
+
+When motion alarms fire, pydobotlab surfaces them as [`DobotKinematicError`](errors.md#dobotkinematicerror-extends-dobotalarmerror) from the waiters in [`move_to`](motion.md#move-to) / [`set_home`](motion.md#set_home-waittrue-timeout600-raise_on_alarmtrue-int) / [`wait_for`](queue.md#wait_forindex-timeoutnone-poll002-raise_on_alarmtrue-none) / [`wait_idle`](queue.md#wait_idle-timeoutnone-poll002-raise_on_alarmtrue-none), so you don't sit on a `wait_for` forever for a command the firmware has refused.
+
+---
+
+## `get_alarms() -> AlarmSet`
+
+**Purpose.** Read and decode the firmware's 16-byte alarm bitmask.
+
+**Inputs.** None.
+
+**Returns.** [`AlarmSet`](#alarmset).
+
+**Protocol.** [`GET_ALARMS_STATE`](../protocol/command-ids.md) (20), read + immediate. Response: 16 raw bytes (the mask).
+
+**Example.**
+
+```python
+alarms = bot.get_alarms()
+if alarms:
+    for line in alarms.format():
+        print(" •", line)
+```
+
+---
+
+## `clear_alarm(*, verify=False, settle=0.15) -> None` {#clear-alarm}
+
+**Purpose.** Clear all active alarms.
+
+**Inputs.**
+
+| Arg | Type | Default | Meaning |
+|-----|------|---------|---------|
+| `verify` | `bool` | `False` | After clearing, sleep `settle` seconds and re-poll. If any *motion-related* alarm bit is still set, the firmware honoured the clear but the **physical condition** that triggered it (e.g. a joint mashed against a limit) is still active — raise [`DobotAlarmError`](errors.md#dobotalarmerror) so the student knows to fix the physical state, not just the bitmask. |
+| `settle` | `float` | `0.15` | Verification settle delay in seconds. Only relevant when `verify=True`. |
+
+**Returns.** `None`.
+
+**Raises.** [`DobotAlarmError`](errors.md#dobotalarmerror) when `verify=True` and an alarm reasserts itself.
+
+**Protocol.** [`CLEAR_ALL_ALARMS_STATE`](../protocol/command-ids.md) (20), **write** + immediate. Param: empty. Response: ack.
+
+> **Note** — the protocol uses the same command ID (`20`) for read (get) and write (clear); the [`rw` bit](../protocol/ctrl-byte.md) of the control byte is what distinguishes them.
+
+**Example — verify-on-clear.**
+
+```python
+from pydobotlab.errors import DobotAlarmError
+
+try:
+    bot.clear_alarm(verify=True)
+except DobotAlarmError as e:
+    print("alarm reasserted — fix the physical condition first:")
+    for name in e.alarms:
+        print("  •", name)
+```
+
+`clear_alarms()` (plural) is kept as a deprecated alias.
+
+---
+
+## `ensure_no_alarms() -> None`
+
+**Purpose.** Guard call — raise [`DobotAlarmError`](errors.md#dobotalarmerror) if any alarm is currently active.
+
+**Returns.** `None`.
+
+**Protocol.** Sends `GET_ALARMS_STATE` (20) and inspects the result.
+
+---
+
+## `AlarmSet`
+
+`from pydobotlab import AlarmSet`. The decoded result of `get_alarms()`.
+
+| Attribute / Method            | Returns | What |
+|-------------------------------|---------|------|
+| `raw`                         | `bytes` | The original 16-byte mask, untouched. |
+| `alarms`                      | `tuple[Alarm \| int, ...]` | Active alarm codes, named when known. |
+| `bool(alarmset)`              | `bool`  | `True` iff any bit is set. |
+| `iter(alarmset)`              | iter    | Iterates the active alarm codes. |
+| `name in alarmset`            | `bool`  | Membership test. |
+| `.names()`                    | `list[str]` | Friendly names, including categorised labels for unmapped codes (e.g. `JOINT_LIMIT_POS_0x44`). |
+| `.format()`                   | `list[str]` | One `"{TAG}: {explanation + how to fix}"` line per active alarm — what the panel banner and `DobotKinematicError.message` use. |
+| `.describe()`                 | `list[str]` | Backwards-compat alias for `.format()`. |
+
+---
+
+## `Alarm` codes
+
+`from pydobotlab import Alarm`. The named bit positions in the mask. Categorised by byte:
+
+| Byte | Range | Members |
+|------|-------|---------|
+| 0    | `0x00..0x07` | `PUBLIC_RESET`, `PUBLIC_UNDEFINED_INSTRUCTION`, `PUBLIC_FILE_SYSTEM`, `PUBLIC_MCU_COMM`, `PUBLIC_ANGLE_SENSOR_READ` |
+| 2    | `0x10..0x17` | `PLAN_INVERSE_RESOLVE`, `PLAN_INVERSE_LIMIT`, `PLAN_DATA_REPEAT`, `PLAN_CURRENT_JOINT_OUT_OF_RANGE`, `PLAN_MOTION_TARGET_OUT_OF_WORKSPACE`, `PLAN_IN_SINGULARITY_ZONE` |
+| 4    | `0x20..0x27` | `KINEMATIC_SINGULARITY`, `KINEMATIC_TARGET_OUT_OF_WORKSPACE`, `KINEMATIC_INVERSE_LIMIT` |
+| 6    | `0x30..0x33` | `OVERSPEED_J1..J4` |
+| 8    | `0x40..0x43` | `LIMIT_POS_J1..J4` (positive joint limit) |
+| 10   | `0x50..0x53` | `LIMIT_NEG_J1..J4` (negative joint limit) |
+| 12   | `0x60..0x63` | `LOST_STEP_J1..J4` |
+| 14   | `0x70`       | `OTHER_LIMIT_TRIGGERED_J1_J2` (auto-leveling switch) |
+
+Each named alarm has a one-line troubleshoot tip surfaced via `AlarmSet.format()`. For example, `LIMIT_POS_J3` reads:
+
+> `joint 3 (forearm) hit positive limit — jog Z down (or J3 negative), or call set_home()`
+
+Unmapped bits are surfaced as `JOINT_LIMIT_POS_0x44` / `OVERSPEED_0x35` / `UNKNOWN_0x90` etc. so they're never silently dropped.
+
+---
+
+## Recovery patterns
+
+| Situation | What to do |
+|-----------|-----------|
+| Workspace / IK alarm (`PLAN_INVERSE_RESOLVE`, `PLAN_MOTION_TARGET_OUT_OF_WORKSPACE`, `KINEMATIC_*`) | The physical state is fine; the *target* was the problem. Call [`bot.clear_alarm()`](#clear-alarm), then retry with a reachable target. |
+| Joint limit hit during JOG (`LIMIT_POS_J*` / `LIMIT_NEG_J*`) | The joint is *physically* against the stop. Jog away from the limit first, then `clear_alarm()`. Or just call [`bot.set_home()`](motion.md#set_home-waittrue-timeout600-raise_on_alarmtrue-int) — homing re-zeroes joints and clears the alarm in one step. |
+| Lost step (`LOST_STEP_J*`) | Re-home to recalibrate. |
+| Public / system fault (`PUBLIC_*`) | Power-cycle the arm (sometimes a re-home is enough for `PUBLIC_RESET`). |
+
+The control panel's "Clear Alarm" button now calls [`clear_alarm()`](#clear-alarm) and re-polls 200 ms later; if the alarm comes back, it pops up an "Alarm persists" warning with the exact troubleshoot lines.

pydobotlab-0.1.0/docs/api/connection.md

@@ -0,0 +1,91 @@
+# Connection lifecycle
+
+Methods that open and close the serial / broker channel to the arm. The `Magician` constructor doesn't talk to hardware; that happens in `connect()`.
+
+## `Magician(port=None, baudrate=115200, timeout=1.0, *, auto_start_queue=True, only_known_adapters=False, via_broker="auto", broker_host="127.0.0.1", broker_port=8765)`
+
+**Purpose.** Construct a Magician driver. No I/O happens here.
+
+See [Connecting to an arm](../getting-started/connect.md) for the full table of constructor options.
+
+---
+
+## `connect() -> None`
+
+**Purpose.** Resolve the port, open the line, and prepare the firmware queue.
+
+**Inputs.** None.
+
+**Returns.** `None`.
+
+**Raises.**
+* [`DobotConnectionError`](errors.md#dobotconnectionerror) — port not found or open failed.
+* [`DobotPortInUseError`](errors.md#dobotportinuseerror-extends-dobotconnectionerror) — a second Magician in this process already owns this port, or the OS refused exclusive access.
+
+**Protocol.** No single command — at the wire level this is the OS-side `serial.Serial.open()` (or a TCP `ATTACH` to the broker), followed by:
+* [`SET_QUEUED_CMD_CLEAR`](../protocol/command-ids.md) (245)
+* [`SET_QUEUED_CMD_START_EXEC`](../protocol/command-ids.md) (240)
+
+The two queue commands are skipped if you constructed with `auto_start_queue=False`.
+
+**Example.**
+
+```python
+bot = Magician(port="/dev/ttyUSB0")
+bot.connect()
+# … work …
+bot.disconnect()
+```
+
+---
+
+## `disconnect() -> None`
+
+**Purpose.** Stop any running pose stream, stop the firmware queue, and close the transport.
+
+**Inputs.** None.
+
+**Returns.** `None`.
+
+**Raises.** Doesn't raise — the close path swallows transport errors so you can call it from `finally:` blocks safely.
+
+**Protocol.** Sends [`SET_QUEUED_CMD_STOP_EXEC`](../protocol/command-ids.md) (241) on the way out, then closes the OS handle (or sends a TCP close to the broker).
+
+---
+
+## `__enter__() / __exit__()` — context-manager support
+
+**Purpose.** Use `Magician` with `with`, which calls `connect()` on entry and `disconnect()` on exit even if an exception is raised inside the block.
+
+**Example.**
+
+```python
+with Magician() as bot:
+    bot.move_to(200, 0, 50, 0)
+# Disconnected here — even if the move raised.
+```
+
+---
+
+## `port` *(read-only property)*
+
+**Purpose.** The OS-resolved port name once `connect()` has run. `None` before connection.
+
+**Returns.** `str | None`.
+
+---
+
+## `is_open` *(read-only property)*
+
+**Purpose.** `True` while the underlying transport is open.
+
+**Returns.** `bool`.
+
+---
+
+## Process-level helpers
+
+These live in `pydobotlab.discovery` and are documented on the [Discovery](discovery.md) page, but you'll see them often when wrangling multi-arm setups:
+
+* `is_port_in_use(port)` — `True` if some `Magician` in *this process* currently owns the port.
+* `find_free_port(only_known_adapters=False)` — return the first port that answers like a Dobot and isn't already claimed.