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, 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 a copy of the URDF meshes in ~/.so101-workshop/; the package ships those files, so no download is needed. Override that directory with --config-dir or SO101_WORKSHOP_HOME.
macOS and Linux:
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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uvx so101-workshop@latest run
From a checkout of this repository:
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
dialoutgroup. 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.
uv sync --locked --all-extras
The pinned URDF and meshes are already in assets/SO101/, and the package ships them, so there is nothing to fetch. scripts/fetch_so101_assets.py only refreshes them when the pinned upstream commit changes.
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
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.
Metadata
Release files for so101-workshop 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| so101_workshop-0.1.1.tar.gz | 6.1 MB | Without provenance | Details for so101_workshop-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| so101_workshop-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for so101_workshop-0.1.1-py3-none-any.whl |
Total release size: 12.2 MB
Release files / so101_workshop-0.1.1.tar.gz
| Download URL | so101_workshop-0.1.1.tar.gz |
|---|---|
| Size | 6.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8da319f6353ec2a444588d110079e92f62855b9a54f0a3bbaaf45668f1763c6e
|
|
BLAKE2b-256 checksum How to use checksums |
f17ecaa60a7355b47e5d5348eeb558374c20a3b8c45290c0bd7da696e7ea6816
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / so101_workshop-0.1.1-py3-none-any.whl
| Download URL | so101_workshop-0.1.1-py3-none-any.whl |
|---|---|
| Size | 6.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2bb705bcfe927748acaeb3c2c465409a1345e2154116085fe8761d35410aa92e
|
|
BLAKE2b-256 checksum How to use checksums |
0655b6c82011f466a777375194493f95a6ab045de49709a186b4fe2df71e47dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.8 {"installer":{"name":"uv","version":"0.12.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"22.04","id":"jammy","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for so101-workshop 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.