| name | xlerobot-onboard |
| description | Set up XLeRobot from scratch — clones lerobot + XLeRobot, grafts the robot classes into the lerobot tree, installs deps, then walks through motor configuration to first teleop. Use when the user types /xlerobot-onboard, asks to "set up" or "install" XLeRobot, or wants to onboard a new XLeRobot kit. |
XLeRobot Onboard
Take a developer with an XLeRobot kit and a laptop, get them to "first teleop episode" without hitting the install footguns that have broken past hackathon teams.
The deterministic install is handled by the xlerobot-install script in this repo (or, when called outside the repo, fetched from https://raw.githubusercontent.com/ScavieFae/xlerobot-onboard/main/xlerobot-install). Your job is the orchestration around it: env setup, error recovery, and the post-install hardware steps that need a human.
Workflow
Step 1 — Pre-flight
Detect and report:
python3 --version — need ≥ 3.12. Older = bail with a fix-recipe (Step 2).which uv — if present, prefer uv for venv + pip (faster). If not, fall back to python3 -m venv + pip.uname — Mac vs Linux. On Mac, surface brew install libusb upfront if the user hasn't installed it.echo $VIRTUAL_ENV — if a venv is already active, use it. Otherwise ask where to create one (default: ./xle-onboard/.venv).
Step 2 — Venv
If no venv is active, create one inside the user's chosen working directory:
- With uv:
uv venv --python 3.12 .venv && source .venv/bin/activate
- Without uv:
python3.12 -m venv .venv && source .venv/bin/activate (Python 3.12 must already be installed — point at pyenv / Homebrew / conda if not).
Step 3 — Install
Run ./xlerobot-install --use-uv (or omit --use-uv if uv isn't available) from the repo root. Default install location is ./lerobot-xlerobot/. The script:
- Pre-checks Python ≥ 3.12.
- Clones huggingface/lerobot
v0.5.1 and Vector-Wangel/XLeRobot at a pinned SHA.
- Copies the xlerobot robot folder + IK solver into the lerobot tree.
- Runs
pip install -e ".[feetech]" against the modified tree.
- Verifies the imports actually resolve.
If the user is running this skill outside the cloned repo, fetch the script first:
curl -sSL https://raw.githubusercontent.com/ScavieFae/xlerobot-onboard/main/xlerobot-install -o xlerobot-install
chmod +x xlerobot-install
Step 4 — Recover
If the script fails, classify the error and propose the fix. Don't apply it without asking.
| Symptom | Cause | Fix |
|---|
Python <X.Y> is too old | lerobot v0.5.1 needs ≥ 3.12 | uv venv --python 3.12 .venv && source .venv/bin/activate, retry |
libusb-1.0 not found (Mac) | feetech needs libusb at link time | brew install libusb |
Could not build wheels for hidapi | system deps missing | Mac: brew install hidapi · Linux: sudo apt install libhidapi-dev |
| Verify imports fail after install succeeds | egg-info stale from a prior install attempt | cd lerobot && pip install -e ".[feetech]" --force-reinstall --no-deps |
git clone … XLeRobot fails or hangs | network / GitHub rate limit | retry; or pre-clone manually then re-run with the dirs already populated |
If the failure isn't here, dump the error verbatim and ask the user how they want to proceed. Don't guess.
Step 5 — Motor IDs (user action — pause)
Tell the user:
- XLeRobot has 17 Feetech sts3215 motors across 2 buses.
- Bus 1 (8 motors): left arm 1–6, head pan/tilt 7–8.
- Bus 2 (9 motors): right arm 1–6, base wheels 7–9.
- All Feetech motors ship with default ID 1. Each one must be programmed to its target ID before assembly, one at a time through the daisy chain.
- Easiest tool: https://bambot.org/feetech.js (browser, any OS).
- This is the #1 hidden footgun — see XLeRobot issue #85, where users replaced motors / cables / boards over multiple days before realizing the IDs were never written.
Ask: "Have you already programmed the motor IDs?" Wait for confirmation before continuing.
Step 6 — USB ports
Run python -m lerobot.find_port. It's interactive — asks the user to unplug then replug each cable. Walk them through it. Output: two /dev/tty… (Mac) or /dev/ttyACM… (Linux) paths.
Order matters. Port 1 = bus with arm-1 + head. Port 2 = bus with arm-2 + base. If the user got them backwards, swap before calibrating.
Save the two ports for Step 7.
Step 7 — Calibrate
Default (manual): lerobot-calibrate --robot.type=xlerobot --robot.port1=<port1> --robot.port2=<port2>. The user moves each joint through its full range, then to mid-position. Output saved under ~/.cache/huggingface/lerobot/calibration/.
If the autocalibrator (lerobot PR #3282 by Isaac Sin) is merged or available, prefer lerobot-auto-calibrate-feetech — drives joints to mechanical limits via stall detection, no manual sweeping required. Check PR status before recommending.
Footgun: if any joint reads way past its expected range — classic case is wrist_roll wrapping to a negative magnitude > 2047 — power-cycle the Waveshare board (unplug the barrel jack, position the joint to mid-range, plug back in). Don't rotate the joint by hand to "fix" the reading.
Step 8 — First teleop
python lerobot/examples/xlerobot/5_xlerobot_teleop_xbox.py (Xbox controller) or 4_xlerobot_teleop_keyboard.py (keyboard).
If the follower tracks the leader (or controller) — done. Acknowledge the user and stop. The next steps (recording episodes, training a policy) are out of scope for this skill.
Anti-patterns
- Don't pip-install dependencies the user didn't ask for. The script handles that.
- Don't try to script motor-ID programming or calibration. Both need physical access.
- Don't speculate on hardware failures. If a motor reports an error, the user has eyes on the robot — surface the error verbatim and ask.
- Don't keep going after a step fails. Stop, report, ask.
End state
User has:
lerobot/ cloned and extended with xlerobot.- A working venv with feetech extras.
- Verified imports.
- Programmed motor IDs (their action).
- Discovered USB ports.
- Calibrated arms.
- A successful teleop session.
That's "ready for record/train." Stop here.
