so101-workshop 0.1.0__tar.gz

so101_workshop-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: so101-workshop
+Version: 0.1.0
+Summary: SO-101 workshop: local arm control and a browser UI
+Author-email: iltlo <pypi@ianlo.net>
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: numpy<2.3,>=2
+Requires-Dist: scipy>=1.14
+Requires-Dist: PyYAML>=6
+Requires-Dist: opencv-python-headless<4.14,>=4.11
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.32
+Requires-Dist: pyserial<4,>=3.5
+Requires-Dist: feetech-servo-sdk>=1.0.0
+Requires-Dist: paho-mqtt>=2.1
+Requires-Dist: pupil-apriltags>=1.0.4
+Requires-Dist: websockets>=13
+Requires-Dist: rerun-sdk<0.34,>=0.33
+Provides-Extra: vision
+Requires-Dist: pyrealsense2; extra == "vision"
+Provides-Extra: twin
+Requires-Dist: pynput<1.9,>=1.7.8; extra == "twin"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+
+# SO-101 workshop
+
+Local control for an SO-101 follower: a browser UI for connection, calibration, teleop, and picking, plus a small Python API. Distances are metres. Joint angles are degrees.
+
+## Run
+
+Install [uv](https://docs.astral.sh/uv/), then start one local process. It prints `http://127.0.0.1:8020` and listens only on this machine. An installed run keeps its config and downloaded URDF meshes in `~/.so101-workshop/`. Override that directory with `--config-dir` or `SO101_WORKSHOP_HOME`.
+
+macOS and Linux:
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uvx so101-workshop@latest run
+```
+
+Windows PowerShell. Use native Windows so the reCamera USB gadget at `192.168.42.1` is visible:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+uvx so101-workshop@latest run
+```
+
+From a checkout of this repository:
+
+```sh
+uvx --from . so101-workshop run
+```
+
+`--mock` runs the page without an arm. `--no-viewer` skips the Rerun panel.
+
+The page is split into **Hardware** (arm, camera, USB port, motor calibration), **Hand-eye** and **Intrinsics**, and **Tasks** (teleop, click and go, click and pick, detect and pick). Motor calibration stays disabled until you press **Start motor calibration**. The E-stop turns torque off.
+
+- Linux: add your user to the `dialout` group. The arm is usually `/dev/ttyACM0`.
+- Windows: serial ports are `COM*`.
+- macOS: the arm is `/dev/cu.usbmodem*`.
+
+Requires Python 3.12 or 3.13. On macOS, AprilTags provides a wheel for Apple silicon only.
+
+## Safety
+
+Clear the table before any live motion. Joint speed defaults to 90 deg/s, which is the maximum. Change it with `arm.set_speed(...)`. Torque off lets the arm fall: support it, and keep a power cutoff within reach. Ctrl-C and the keyboard are not emergency stops. There is no collision checker.
+
+## First use
+
+Plug in the USB adapter. Motors can stay off. Under **Arm connection**, find the port, then calibrate the motors once before any live move. Torque turns off, so support the arm. Pose every joint at the middle of its travel and confirm. Then move every joint except wrist roll through its whole travel, including the gripper, and confirm again. Wrist roll keeps a full turn. That writes `motors.json`. Later connects load it and update a servo whose midpoint or range differs. 0° is the calibrated midpoint.
+
+Connect the arm and the camera. The default camera is the reCamera at `ws://192.168.42.1:8090/ws/boxes`.
+
+## Calibration
+
+**Intrinsics.** The webcam and the reCamera do not report fx, fy, or distortion. The board has 8 × 11 inner corners (9 × 12 squares). Hold it in view, move it between captures (tilt it, and use different parts of the image), and take at least ten views. **Capture chessboard** is green only while the board is in view.
+
+**Hand-eye.** The camera stays fixed. The tag is tag36h11, id 0, 40 mm, mounted on the gripper. That mount is the `tag:` section of `robot.yaml`. With the arm and camera connected, torque on, and the tag in view, **Run auto calibration** moves through the poses, keeps the samples that see the tag, and saves `hand_eye.yaml`. **Stop** and the E-stop abort the tour. Clear the table first, because the arm moves by itself. Redo this if you move the camera. The hand-eye view shows the tag's XYZ in millimetres and RPY in degrees while the tag is detected.
+
+## Tasks
+
+**Teleop** uses the keyboard or the on-screen keypad. WASD or the arrows move x and y. Q/E move z and keep the current orientation. Z/C change base roll, F/V change base pitch, R rests, H homes, and space toggles the gripper. Keys follow the Teleop tab. **Key teleop** in the top bar keeps them on across tabs.
+
+**Click and go** treats a click as a ray onto the base plane z = 0, then moves the gripper there, 20 mm above the plane.
+
+**Click and pick** starts from rest with the gripper open, picks at the click, closes, returns to rest, and opens.
+
+**Detect and pick** uses the on-device YOLO boxes. Click inside a box and the arm picks that box's centre. Overlapping boxes: the smallest one wins. A click outside every box does not move the arm.
+
+Depth picking is not included.
+
+## Config
+
+Files live in the station directory (`config/` in a checkout, `~/.so101-workshop/config/` when installed).
+
+| File | What you edit |
+| --- | --- |
+| `robot.yaml` | port, arm id, joint limits, joint offsets, tag family/id/size and mount |
+| `camera*.yaml` | backend, device, url, resolution, fps, intrinsics |
+| `workshop.yaml` | feature flags, active camera profile, detection websocket and MQTT |
+| `hand_eye.yaml` | camera pose in the base frame, written by calibration |
+| `motors.json` | servo midpoint and range, written by motor calibration |
+
+Switch camera under **Hardware → Camera connection**. Intrinsics belong to that profile, so calibrate the camera you will use. For a webcam, `device` is the camera index: `/dev/videoN` on Linux, DirectShow on Windows, and AVFoundation on macOS.
+
+| Profile | Backend | Notes |
+| --- | --- | --- |
+| `camera_recamera.yaml` | `recamera` | Default. `ws://192.168.42.1:8090/ws/boxes`, 1280×720 |
+| `camera_logi.yaml` | `webcamera` | USB webcam, index 0 |
+| `camera_usbcam.yaml` | `webcamera` | Second USB webcam. Set `device` if that index is not this machine's camera |
+
+RealSense needs the vision extra: `uvx --with pyrealsense2 so101-workshop run`.
+
+`joint_limits_deg` and `joint_offsets_deg` in `robot.yaml` are this arm's limits and small zero corrections. Edit the offsets only if you re-measure them.
+
+## Scripts
+
+From a checkout, the same work is available as scripts. `--mock` draws the arm in Rerun and does not open the serial port. `--live` uses the arm. Clear the table first.
+
+```sh
+uv sync --locked --all-extras
+uv run python scripts/fetch_so101_assets.py
+```
+
+The asset script downloads the SO-101 URDF and its meshes once.
+
+```sh
+uv run python scripts/check_port.py
+uv run python scripts/calibrate_motors.py
+uv run python scripts/twin.py --mock
+uv run python scripts/twin.py --live
+uv run python scripts/get_pose.py --live
+uv run python scripts/arm_move.py --live
+uv run python scripts/gripper.py --live
+uv run python scripts/joint_jog.py --mock
+uv run python scripts/keyboard_control.py --live
+uv run python scripts/camera_view.py
+uv run python calibration/apriltag.py
+uv run python calibration/intrinsics.py
+uv run python calibration/hand_eye.py
+uv run python calibration/auto_hand_eye.py --live
+uv run python application/click_and_go.py --live
+uv run python application/click_and_pick.py --live
+uv run python application/detect_and_pick.py --live
+uv run python application/pick_and_place.py --live
+```
+
+`check_port.py` asks you to unplug the adapter and writes `port` in `config/robot.yaml`. `twin.py --live` only reads joint feedback; `--relax` lets `T` turn torque off while you pose the arm. `arm_move.py` homes (every arm joint to 0°) and visits three points; change `POINTS` in that file for different ones. Gripper percent is 0 closed and 100 fully open. `joint_jog.py` steps one joint by at most 2°: type `shoulder_pan 1`, then `q`.
+
+Keyboard teleop adds P to print the pose, +/- to change the step, and Esc as E-stop. Translation keys keep the current orientation.
+
+`camera_view.py` shows the live picture in Rerun. Q quits. `calibration/intrinsics.py` searches every frame for the chessboard, so that view updates more slowly. **Space** captures the current view, **Enter** solves and writes `config/camera.yaml`, **Q** quits.
+
+`calibration/apriltag.py` is the camera only. Ctrl-C stops. `calibration/hand_eye.py` records settled poses: **Enter** samples, **C** solves and writes `config/hand_eye.yaml` after four or more samples, **T** turns torque off (support the arm first), **Q** quits without saving. `calibration/auto_hand_eye.py` drives the poses in `calibration/poses.md`.
+
+`click_and_go.py --mock` still needs the camera, so the image and the ray are real. Only the arm is simulated. The click is on the printed browser page. Edit `PICK` and `PLACE` in `application/pick_and_place.py` before a live run. They are metres in the base frame.
+
+## Using the arm from Python
+
+```python
+from so101_control import SO101
+
+with SO101.connect(mock=True) as arm:
+    arm.home()
+    arm.rest()
+    arm.set_speed(60)
+    arm.move_to(0.20, 0.00, 0.10)
+    print(arm.get_pose())
+    arm.grip()
+    arm.release()
+```
+
+`SO101.connect(mock=False)` opens the follower on the port in `robot.yaml`.

so101_workshop-0.1.0/README.md

@@ -0,0 +1,148 @@
+# SO-101 workshop
+
+Local control for an SO-101 follower: a browser UI for connection, calibration, teleop, and picking, plus a small Python API. Distances are metres. Joint angles are degrees.
+
+## Run
+
+Install [uv](https://docs.astral.sh/uv/), then start one local process. It prints `http://127.0.0.1:8020` and listens only on this machine. An installed run keeps its config and downloaded URDF meshes in `~/.so101-workshop/`. Override that directory with `--config-dir` or `SO101_WORKSHOP_HOME`.
+
+macOS and Linux:
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uvx so101-workshop@latest run
+```
+
+Windows PowerShell. Use native Windows so the reCamera USB gadget at `192.168.42.1` is visible:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+uvx so101-workshop@latest run
+```
+
+From a checkout of this repository:
+
+```sh
+uvx --from . so101-workshop run
+```
+
+`--mock` runs the page without an arm. `--no-viewer` skips the Rerun panel.
+
+The page is split into **Hardware** (arm, camera, USB port, motor calibration), **Hand-eye** and **Intrinsics**, and **Tasks** (teleop, click and go, click and pick, detect and pick). Motor calibration stays disabled until you press **Start motor calibration**. The E-stop turns torque off.
+
+- Linux: add your user to the `dialout` group. The arm is usually `/dev/ttyACM0`.
+- Windows: serial ports are `COM*`.
+- macOS: the arm is `/dev/cu.usbmodem*`.
+
+Requires Python 3.12 or 3.13. On macOS, AprilTags provides a wheel for Apple silicon only.
+
+## Safety
+
+Clear the table before any live motion. Joint speed defaults to 90 deg/s, which is the maximum. Change it with `arm.set_speed(...)`. Torque off lets the arm fall: support it, and keep a power cutoff within reach. Ctrl-C and the keyboard are not emergency stops. There is no collision checker.
+
+## First use
+
+Plug in the USB adapter. Motors can stay off. Under **Arm connection**, find the port, then calibrate the motors once before any live move. Torque turns off, so support the arm. Pose every joint at the middle of its travel and confirm. Then move every joint except wrist roll through its whole travel, including the gripper, and confirm again. Wrist roll keeps a full turn. That writes `motors.json`. Later connects load it and update a servo whose midpoint or range differs. 0° is the calibrated midpoint.
+
+Connect the arm and the camera. The default camera is the reCamera at `ws://192.168.42.1:8090/ws/boxes`.
+
+## Calibration
+
+**Intrinsics.** The webcam and the reCamera do not report fx, fy, or distortion. The board has 8 × 11 inner corners (9 × 12 squares). Hold it in view, move it between captures (tilt it, and use different parts of the image), and take at least ten views. **Capture chessboard** is green only while the board is in view.
+
+**Hand-eye.** The camera stays fixed. The tag is tag36h11, id 0, 40 mm, mounted on the gripper. That mount is the `tag:` section of `robot.yaml`. With the arm and camera connected, torque on, and the tag in view, **Run auto calibration** moves through the poses, keeps the samples that see the tag, and saves `hand_eye.yaml`. **Stop** and the E-stop abort the tour. Clear the table first, because the arm moves by itself. Redo this if you move the camera. The hand-eye view shows the tag's XYZ in millimetres and RPY in degrees while the tag is detected.
+
+## Tasks
+
+**Teleop** uses the keyboard or the on-screen keypad. WASD or the arrows move x and y. Q/E move z and keep the current orientation. Z/C change base roll, F/V change base pitch, R rests, H homes, and space toggles the gripper. Keys follow the Teleop tab. **Key teleop** in the top bar keeps them on across tabs.
+
+**Click and go** treats a click as a ray onto the base plane z = 0, then moves the gripper there, 20 mm above the plane.
+
+**Click and pick** starts from rest with the gripper open, picks at the click, closes, returns to rest, and opens.
+
+**Detect and pick** uses the on-device YOLO boxes. Click inside a box and the arm picks that box's centre. Overlapping boxes: the smallest one wins. A click outside every box does not move the arm.
+
+Depth picking is not included.
+
+## Config
+
+Files live in the station directory (`config/` in a checkout, `~/.so101-workshop/config/` when installed).
+
+| File | What you edit |
+| --- | --- |
+| `robot.yaml` | port, arm id, joint limits, joint offsets, tag family/id/size and mount |
+| `camera*.yaml` | backend, device, url, resolution, fps, intrinsics |
+| `workshop.yaml` | feature flags, active camera profile, detection websocket and MQTT |
+| `hand_eye.yaml` | camera pose in the base frame, written by calibration |
+| `motors.json` | servo midpoint and range, written by motor calibration |
+
+Switch camera under **Hardware → Camera connection**. Intrinsics belong to that profile, so calibrate the camera you will use. For a webcam, `device` is the camera index: `/dev/videoN` on Linux, DirectShow on Windows, and AVFoundation on macOS.
+
+| Profile | Backend | Notes |
+| --- | --- | --- |
+| `camera_recamera.yaml` | `recamera` | Default. `ws://192.168.42.1:8090/ws/boxes`, 1280×720 |
+| `camera_logi.yaml` | `webcamera` | USB webcam, index 0 |
+| `camera_usbcam.yaml` | `webcamera` | Second USB webcam. Set `device` if that index is not this machine's camera |
+
+RealSense needs the vision extra: `uvx --with pyrealsense2 so101-workshop run`.
+
+`joint_limits_deg` and `joint_offsets_deg` in `robot.yaml` are this arm's limits and small zero corrections. Edit the offsets only if you re-measure them.
+
+## Scripts
+
+From a checkout, the same work is available as scripts. `--mock` draws the arm in Rerun and does not open the serial port. `--live` uses the arm. Clear the table first.
+
+```sh
+uv sync --locked --all-extras
+uv run python scripts/fetch_so101_assets.py
+```
+
+The asset script downloads the SO-101 URDF and its meshes once.
+
+```sh
+uv run python scripts/check_port.py
+uv run python scripts/calibrate_motors.py
+uv run python scripts/twin.py --mock
+uv run python scripts/twin.py --live
+uv run python scripts/get_pose.py --live
+uv run python scripts/arm_move.py --live
+uv run python scripts/gripper.py --live
+uv run python scripts/joint_jog.py --mock
+uv run python scripts/keyboard_control.py --live
+uv run python scripts/camera_view.py
+uv run python calibration/apriltag.py
+uv run python calibration/intrinsics.py
+uv run python calibration/hand_eye.py
+uv run python calibration/auto_hand_eye.py --live
+uv run python application/click_and_go.py --live
+uv run python application/click_and_pick.py --live
+uv run python application/detect_and_pick.py --live
+uv run python application/pick_and_place.py --live
+```
+
+`check_port.py` asks you to unplug the adapter and writes `port` in `config/robot.yaml`. `twin.py --live` only reads joint feedback; `--relax` lets `T` turn torque off while you pose the arm. `arm_move.py` homes (every arm joint to 0°) and visits three points; change `POINTS` in that file for different ones. Gripper percent is 0 closed and 100 fully open. `joint_jog.py` steps one joint by at most 2°: type `shoulder_pan 1`, then `q`.
+
+Keyboard teleop adds P to print the pose, +/- to change the step, and Esc as E-stop. Translation keys keep the current orientation.
+
+`camera_view.py` shows the live picture in Rerun. Q quits. `calibration/intrinsics.py` searches every frame for the chessboard, so that view updates more slowly. **Space** captures the current view, **Enter** solves and writes `config/camera.yaml`, **Q** quits.
+
+`calibration/apriltag.py` is the camera only. Ctrl-C stops. `calibration/hand_eye.py` records settled poses: **Enter** samples, **C** solves and writes `config/hand_eye.yaml` after four or more samples, **T** turns torque off (support the arm first), **Q** quits without saving. `calibration/auto_hand_eye.py` drives the poses in `calibration/poses.md`.
+
+`click_and_go.py --mock` still needs the camera, so the image and the ray are real. Only the arm is simulated. The click is on the printed browser page. Edit `PICK` and `PLACE` in `application/pick_and_place.py` before a live run. They are metres in the base frame.
+
+## Using the arm from Python
+
+```python
+from so101_control import SO101
+
+with SO101.connect(mock=True) as arm:
+    arm.home()
+    arm.rest()
+    arm.set_speed(60)
+    arm.move_to(0.20, 0.00, 0.10)
+    print(arm.get_pose())
+    arm.grip()
+    arm.release()
+```
+
+`SO101.connect(mock=False)` opens the follower on the port in `robot.yaml`.

so101_workshop-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "so101-workshop"
+version = "0.1.0"
+description = "SO-101 workshop: local arm control and a browser UI"
+readme = "README.md"
+authors = [{ name = "iltlo", email = "pypi@ianlo.net" }]
+requires-python = ">=3.12,<3.14"
+dependencies = [
+    "numpy>=2,<2.3",
+    "scipy>=1.14",
+    "PyYAML>=6",
+    "opencv-python-headless>=4.11,<4.14",
+    "fastapi>=0.115",
+    "uvicorn>=0.32",
+    "pyserial>=3.5,<4",
+    "feetech-servo-sdk>=1.0.0",
+    "paho-mqtt>=2.1",
+    "pupil-apriltags>=1.0.4",
+    "websockets>=13",
+    "rerun-sdk>=0.33,<0.34",
+]
+
+[project.scripts]
+so101-workshop = "so101_workshop.cli:main"
+
+[project.optional-dependencies]
+vision = ["pyrealsense2"]
+twin = ["pynput>=1.7.8,<1.9"]
+test = ["pytest>=8", "httpx>=0.27"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+so101_workshop = ["static/*", "templates/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.uv]
+package = true

so101_workshop-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

so101_workshop-0.1.0/src/so101_control/__init__.py

@@ -0,0 +1,5 @@
+"""SO-101 arm control. Poses are metres; joint angles are degrees."""
+
+from .arm import Pose, SO101
+
+__all__ = ["Pose", "SO101"]