Lekiwi Xbox Teleop

cd ~/projects/lerobot
source .venv/bin/activate
python examples/phone_to_lekiwi/teleoperate.py

Controls

Calibration

1. Hold phone flat (screen up), top edge pointing AWAY from you
2. Press and hold B1 until calibrated
3. Release, then hold B1 again to drive

Method 2: Xbox Controller

Prerequisites

• LeKiwi base assembled with 3 omni wheels
• Feetech motors connected: ID 7=left, 8=back, 9=right
• Xbox controller paired over Bluetooth
• LeRobot minimal runtime installed

Hardware Setup

# Verify motors detected
ls -la /dev/ttyACM0

# Pair Xbox controller
bluetoothctl scan on
# Press PAIR button on controller (3 sec, fast flash)
bluetoothctl pair <MAC>
bluetoothctl trust <MAC>
bluetoothctl connect <MAC>

# Verify controller visible
ls -la /dev/input/js*

Running Teleop

Quick Start (Global Command)

# Put Hermes wrappers on PATH (one-time setup in ~/.bashrc)
case ":$PATH:" in
    *":$HOME/.hermes/bin:"*) ;;
    *) export PATH="$HOME/.hermes/bin:$PATH" ;;
esac

# Start host first (dry-run for smoke test)
lekiwi-zmq-host --dry-run

# In another terminal, run teleop against that host
lekiwi-teleop --host localhost

# Real hardware host
lekiwi-zmq-host --port /dev/ttyACM0

Manual Run (from lerobot directory)

cd ~/projects/lerobot
source .venv/bin/activate

# Base only
python lekiwi_xbox_base_only.py

# With camera view
python lekiwi_teleop_with_cameras.py --cam 0

# Test controller without robot
python lekiwi_teleop_with_cameras.py --dry-run

Controls

Base teleop

Arm teleop (--arm) - Direct Joint Control

Direct joint control is recommended over IK. IK causes drift (up 3s then down 3s doesn't return to same position). AI policies use joint control anyway.

Parallel gripper velocity control: Parallel grippers must use velocity mode - position control would over-current fault when gripping objects. Servo stops moving on contact instead of fighting. Trigger mapping:

• Left trigger = Close gripper (negative velocity)
• Right trigger = Open gripper (positive velocity)

Velocity defaults: 150 servo units (floor 60 for auto-throttle protection). Positive velocity = open, negative = close. If claw moves wrong direction, swap velocity signs.

Speed Levels

• Level 1: 0.1 m/s linear, 30°/s angular (default)
• Level 2: 0.25 m/s linear, 60°/s angular
• Level 3: 0.4 m/s linear, 90°/s angular

Tuning Tips

Responsive arm control:

• Deadzone 0.15 works well; 0.35 feels dead
• Use direct joint control instead of IK for deterministic results
• Degree step 3.0 for responsive joint control

Parallel gripper velocity control:

# Tune gripper limits for your parallel gripper
python lekiwi_xbox_arm_teleop.py --gripper-open 85 --gripper-close 35

# Adjust velocity if too fast/slow
python lekiwi_xbox_arm_teleop.py --gripper-vel 150  # slower
python lekiwi_xbox_arm_teleop.py --gripper-vel 400  # faster

Deadzone adjustment: If robot drifts with stick centered, increase deadzone (default 0.15):

python lekiwi_xbox_base_only.py --deadzone 0.2

Speed tuning: Edit speed levels in script for personal preference. Default conservative for indoor use.

ZeroMQ Remote Control (NEW!)

ZeroMQ Remote Control (XLeRobot Compatible)

XLeRobot uses flat dict protocol - no message wrapping.

Protocol Format

Commands IN (port 5555, PULL):

{"x.vel": 0.1, "y.vel": 0.0, "theta.vel": 30.0}

Observations OUT (port 5556, PUSH):

{"x.vel": 0.1, "y.vel": 0.0, "theta.vel": 30.0, "cam_0": "/9j/4AAQ..."}

NOT wrapped format (wrong):

{"type": "response", "response": "video", "data": {"frame": "..."}}

The LeKiwi host sends raw flat dictionaries matching upstream LeRobot's lekiwi_host.py format.

Ports

• 5555 - Commands (PULL socket) - receives flat action dict from web GUI
• 5556 - Data (PUSH socket) - sends flat observation dict with base64 camera frames to web GUI

Running the Host

# On Pi 5 - start host
lekiwi-zmq-host

# With cameras
lekiwi-zmq-host --cam 0 --cam 1

# Flip camera vertically (upside-down mount)
lekiwi-zmq-host --cam 0 --camera-vflip

# Debug mode (verbose logging)
lekiwi-zmq-host --debug

Camera vflip: If camera is mounted upside-down on chassis, use --camera-vflip flag. This flips image vertically in software. The flip includes .copy() to ensure contiguous memory for JPEG encoding (OpenCV flip returns non-contiguous array which breaks cv2.imencode).

The host binds to 0.0.0.0:5555 and 0.0.0.0:5556 so any client can connect.

Web GUI Connection

In your XLeRobot web control, set:

ROBOT_HOST=<pi-ip-address>
ROBOT_PORT_CMD=5555
ROBOT_PORT_DATA=5556

Or if web GUI is on the same Pi:

ROBOT_HOST=localhost

Cameras

Innomaker U20 1080p USB Camera

LeKiwi uses Innomaker U20 1080p USB cameras (2x: base + wrist).

Specs:

• Resolution: 1920x1080 @ 30fps
• Interface: USB 2.0 UVC (plug-and-play on Linux)
• Lens: Wide angle (~120°)
• Works with OpenCV: cv2.VideoCapture(0)

Setup:

# Plug in cameras - should auto-detect
ls /dev/video*  # Look for new video devices

# Test camera
python ~/projects/lerobot/test_camera.py

# Check supported formats
v4l2-ctl -d /dev/video0 --list-formats-ext 2>/dev/null

Finding Camera Indices: USB cameras typically show as /dev/video0, /dev/video2, etc.

# In Python - try indices until one works
for i in range(10):
    cap = cv2.VideoCapture(i)
    if cap.isOpened():
        print(f"Camera {i} working")
        cap.release()

• Use Pi's MIPI CSI interface
• Mounted: base camera + wrist camera
• Need libcamera or picamera2 (not standard OpenCV)

USB Webcams:

• Standard UVC cameras
• Work with OpenCV out of the box
• Auto-detected by teleop script

Camera Setup

# Find available cameras
cd ~/projects/lerobot
source .venv/bin/activate
python test_camera.py

# List video devices
ls /dev/video*
v4l2-ctl --list-devices

Recording Data for Training

The teleop script with camera can be extended to record episodes for fine-tuning SmolVLA:

# Record episode (drive around, collect data)
python lekiwi_teleop_with_cameras.py --record --output dataset/

# Later: fine-tune SmolVLA on collected data

For now: drive and see camera feed before training.

Document progress with built-in log system:

cd ~/projects/LeKiwi/log

# Add entry with media
python add_entry.py "Arm mounted" "First servo attached" --image ~/Pictures/arm.png

# View log
cat PROJECT_LOG.md

Shoulder pan not working (RB + left stick):

• Bug: Code was reading left_y (vertical) instead of left_x (horizontal). Fixed - now RB + left stick LEFT/RIGHT controls shoulder_pan.
• Verify you have updated teleop: grep "shoulder_pan (left/right" ~/.hermes/projects/lekiwi-control/src/lekiwi/teleop/xbox.py

Son safety - Start button toggle:

• Press START to toggle left stick arm control on/off
• When disabled: left stick won't move arm (base d-pad still works)
• Useful when handing controller to kids

Shoulder lift doesn't go all the way back (heavy arm):

• With heavy arm attached, calibrated limits (-30°, 120°) may be too conservative. Mechanical range often wider.
• Fix: Expand software limits in teleop:

  # In ArmState.LIMITS - test mechanical range
  "shoulder_lift": (-90.0, 120.0),  # was (-30.0, 120.0)
  

• Gravity helps going DOWN (retracting), so if it still struggles, check for mechanical binding or increase servo torque limit.
• Add debug to see when clamping happens:

  if name == "shoulder_lift" and current != clamped:
      print(f"[CLAMP] shoulder_lift tried {current:.1f}, clamped to {clamped:.1f}")
  

Shoulder lift direction:

• Pygame Y-axis: -1 = UP (stick pushed away), +1 = DOWN (stick pulled toward you).
• Pulling DOWN on left stick = retract shoulder_lift (go to negative angles like -90°)
• Pushing UP on left stick = extend shoulder_lift (go toward positive angles like 120°)

Phone Teleop Troubleshooting

StopIteration error in motors_bus.sync_write:

• Root cause: sending None for arm positions when only controlling base
• LeKiwi.send_action() crashes when arm keys have None values (iterates over models, gets empty)
• Fix: Always read current arm positions from observation and pass them through:

  obs = robot.get_observation()
  arm_action = {}
  for key in obs:
      if key.startswith("arm_") and key.endswith(".pos"):
          arm_action[key] = obs[key]
  full_action = {**base_action, **arm_action}
  

Missing dependencies for phone teleop: If you get ModuleNotFoundError for uvicorn, starlette, python-dotenv, etc.:

cd ~/projects/lerobot
uv pip install uvicorn starlette python-dotenv

hebi-py and teleop packages require these but don't declare them properly.

Camera busy / ioctl errors: Phone teleop may fail if cameras are in use by another process (host, another teleop, etc.)

• Fix: Disable cameras in LeKiwiConfig:

  robot_config = LeKiwiConfig(
      port="/dev/ttyACM0",
      id="my_lekiwi",
      cameras={},  # Empty dict = no cameras
      disable_torque_on_disconnect=False,
  )
  

HEBI app not connecting:

• Verify iPhone and Pi on same WiFi (not Bluetooth!)
• In HEBI app: family="HEBI", name="mobileIO"
• Check Pi IP with hostname -I
• Ensure no firewall blocking UDP discovery (port 45454)

Phone arm teleop on LeKiwi: what actually worked / failed

• Base-only phone teleop works reasonably well.
• Arm phone teleop via IK is fragile on 5V power and rough in practice. Main failure modes were software jitter/dropout plus power limits.
• Better default for LeKiwi arm teleop is still Xbox direct joint control, not phone IK.

Critical fixes if experimenting with examples/phone_to_lekiwi/teleoperate_arm.py:

• Use the existing calibration file by setting LeKiwiConfig(id=None) so it loads ~/.cache/huggingface/lerobot/calibration/robots/lekiwi/None.json.
• After robot.connect(calibrate=False), cache calibration in software with:

  if robot.calibration:
      robot.bus.calibration = robot.calibration
  

  Do not call robot.bus.write_calibration(robot.calibration) on this setup — some homing offsets exceed Feetech sign-magnitude limits and crash.
• robot.get_observation() returns arm keys like arm_shoulder_pan.pos, not observation.state.arm_*. If you mirror current arm positions, read those exact keys.
• Phone / HEBI dropouts can return None feedback (fbk is None) and must be handled without exiting.
• EEBoundsAndSafety can throw ValueError: EE jump ... on normal phone jitter. Catch it and freeze/hold last action instead of letting the script die.
• Practical rule: on phone dropout or EE clamp trip, keep sending the last valid action and print a warning; do not exit.

Recommended control strategy on 5V power:

• Prefer direct-joint Xbox teleop for arm work.
• If using phone arm IK anyway: reduce end-effector step size, smooth phone pose, limit per-joint delta, and freeze on bad frames instead of crashing.
• Bad fix: "don't run random servos together." Good fix: smaller coordinated moves, lower acceleration, tighter joint-delta limiting.

Troubleshooting

Arm teleop crashes with KeyError: 'arm_shoulder_pan.pos':

• Current LeRobot LeKiwi.send_action() safety clamp path expects arm present-position keys without .pos, but arm actions include .pos.
• For now, run the arm teleop with max_relative_target=None (the current lekiwi_xbox_arm_teleop.py default) so commands bypass that broken clamp path.

Arm servos stuck/at limits (overload fault):

• Feetech servos have overload protection. When arm jams at limits too hard, servos fault and lock.
• Fix: Press Back button to reset arm - this cycles torque off/on to unlock servos.
• The reset function calls robot.bus.disable_torque(), sleeps 100ms, then enable_torque().
• If servos still stuck after reset, power cycle required.

Systematic Feetech servo debugging: When servos work briefly then stop, or feel weak, check these registers directly:

# Raw bus debug - works when LeRobot classes fail
from scservo_sdk import PortHandler, PacketHandler
port = PortHandler("/dev/ttyACM0")
packet = PacketHandler(1.0)
port.openPort()
port.setBaudRate(1_000_000)

# Read servo ID 2 (shoulder_lift) status
pos, _, err = packet.read2ByteTxRx(port, 2, 56)    # Present_Position
load, _, _ = packet.read2ByteTxRx(port, 2, 60)      # Present_Load
volt, _, _ = packet.read1ByteTxRx(port, 2, 62)      # Present_Voltage
temp, _, _ = packet.read1ByteTxRx(port, 2, 63)      # Present_Temperature
status, _, _ = packet.read1ByteTxRx(port, 2, 65)    # Status (overload bit)

if load > 32767: load -= 65536  # Sign conversion
overload = "OVERLOAD!" if status & 0x20 else "OK"
print(f"Pos={pos} Load={load} Volt={volt/10:.1f}V Temp={temp}C {overload}")

Key findings:

• Load creeping toward ±1000 then motor stops = torque limit reached
• Status bit 0x20 set = overload protection triggered, servo locked
• Voltage < 11V on 12V servos or < 6V on 7.4V servos = power supply sagging, insufficient torque
• Voltage sag under load = power supply can't deliver peak current

5V servos vs 7.4V/12V servos: Check servo label - STS3215 come in different voltage variants:

• 5V version (SCS0009/ST3215): Runs on USB power banks
• 7.4V version (STS3215-7.4V): Needs 2S LiPo or boost converter
• 12V version (STS3215-12V): Needs 12V supply

Common issue: Running 7.4V servos at 5V causes weak torque, stalling under heavy arm weight.

Servo stalls when arm extended (shoulder_lift maxes out):

• Symptom: Arm works retracted but stalls/"gives up" when extending past certain point
• Cause: 7.4V servos running on 5V power bank — insufficient torque at extension
• Quick diagnosis — check shoulder_lift servo under load:

  from scservo_sdk import PortHandler, PacketHandler
  port = PortHandler("/dev/ttyACM0")
  packet = PacketHandler(1.0)
  port.openPort()
  port.setBaudRate(1_000_000)
  
  # Monitor ID 2 (shoulder_lift) while moving arm
  volt, _, _ = packet.read1ByteTxRx(port, 2, 62)
  load, _, _ = packet.read2ByteTxRx(port, 2, 60)
  if load > 32767: load -= 65536
  print(f"Voltage: {volt/10:.1f}V  Load: {load:+d}")
  # Load approaching ±26000 = maxed out, will fault soon
  

• Expected: 7.4V servos should read ~7-8V, not 4.8-5.0V
• Workaround for 5V testing: Limit shoulder_lift range in teleop:

  # Cap at -30 instead of -90 to stay in mechanical advantage zone
  "shoulder_lift": (-30.0, 120.0),  # was (-90.0, 120.0)
  

  Less extension = less torque needed = works on 5V temporarily

Fixes for under-voltage:

1. Get proper voltage supply (7.4V for 2S, 12V for 3S)
2. Reduce teleop degree_step (smaller movements = less current spike)
3. Manually assist heavy joints during movement
4. Use gravity to help movements (DOWN for retract, UP with gravity assist)
5. Limit joint range (especially shoulder_lift) until proper voltage available

Servos drop torque when script exits (arm collapses):

• Default LeKiwiConfig disables torque on disconnect.
• Fix: Set disable_torque_on_disconnect=False in config:

  robot_config = LeKiwiConfig(
      port="/dev/ttyACM0",
      disable_torque_on_disconnect=False,  # Keep torque on exit
  )
  

• Also remove robot.disconnect() from finally blocks if you want immediate reconnect capability without re-homing.

Shoulder pan stops responding after hitting limit:

• Servo hits mechanical limit, overloads, and faults.
• Prevention: Clamp all action commands to joint limits before sending:

  for joint, target in target_positions.items():
      control = current[joint] + kp * (target - current[joint])
      # Clamp to prevent limit crashes
      low, high = JOINT_LIMITS[joint]
      control = max(low, min(high, control))
      action[f"arm_{joint}.pos"] = control
  

P-control clamping bug (wrong direction/interpolation):

• When applying joint limits with P-control interpolation, clamp the TARGET first, then interpolate:

  # WRONG - clamps control output, breaks direction
  control = current + kp * (target - current)
  control = max(low, min(high, control))  # Bad!
  

Gripper appears stuck closed (or open) at startup despite correct display values:

• The host may be running in --dry-run mode (simulation only, no hardware commands sent)
• Dry-run display shows correct values (e.g. grip=85.0) but servos never receive commands
• Fix: Check running processes, kill dry-run, start real host:

  # Check what's running
  ps aux | grep lekiwi
  
  # Kill dry-run host
  pkill -f lekiwi-host
  
  # Start real hardware host
  /home/rocky-1/.hermes/projects/lekiwi-control/.venv/bin/lekiwi-host --port /dev/ttyACM0
  
  # In another terminal, start teleop
  /home/rocky-1/.hermes/projects/lekiwi-control/.venv/bin/lekiwi-teleop
  

• Always verify the host is NOT using --dry-run when expecting physical movement

Gripper appears stuck closed (or open) at startup despite correct teleop display:

• The lekiwi-host may be running with --dry-run flag (simulation only, no hardware commands sent)
• Dry-run mode shows correct values on screen (e.g. grip=85.0) but servos never receive any command
• Always verify: ps aux | grep lekiwi-host — if it shows --dry-run, that's your problem
• Fix: kill dry-run, start real hardware host:

  pkill -f lekiwi-host
  /home/rocky-1/.hermes/projects/lekiwi-control/.venv/bin/lekiwi-host --port /dev/ttyACM0
  

Teleop connects, but host replies with Port is in use! on Goal_Position / Present_Position:

• Root cause: host is touching the Feetech serial bus from two threads at once.
• In lekiwi-control, the publish loop calls robot.get_observation() while the command thread calls robot.send_action().
• Feetech bus access must be serialized with a shared lock around both operations (and shutdown).
• Fix in src/lekiwi/host/__init__.py:

  from threading import Lock
  ...
  self.robot_lock = Lock()
  ...
  def publish_observation(self):
      with self.robot_lock:
          obs = self.robot.get_observation()
      ...
  
  def apply_action(self, action):
      with self.robot_lock:
          self.robot.send_action(action)
      ...
  

• Symptom looks like hardware flakiness, but it's really a host threading bug.

Ghost processes causing "Port is in use" errors in logs after supposed kill:

• systemctl kill fails if service isn't actually a systemd service
• pkill -9 -f lekiwi leaves defunct PIDs that keep serial port open
• ps aux | grep lekiwi and kill -9 <pid> manually, or just reboot
• Log timestamps lie — stale output from dead processes confuses debugging
• Always verify with fresh ps aux before trusting "fixed"

Servo intermittent on bus (ID 1 not found):

• Shoulder pan (ID 1) cable can be loose - servo drops off bus intermittently.
• If lerobot.connect() reports missing ID 1 but raw serial scan finds it, check/reseat cable.
• Retry connection 2-3 times before declaring hardware failure.

Shoulder_lift works briefly then stops (1-2 seconds): Heavy arm weight causes overload. Servo works until protection triggers.

Check with raw bus monitor:

from scservo_sdk import PortHandler, PacketHandler
port = PortHandler("/dev/ttyACM0")
packet = PacketHandler(1.0)
port.openPort()
port.setBaudRate(1_000_000)

# Read servo ID 2 (shoulder_lift)
load, _, _ = packet.read2ByteTxRx(port, 2, 60)  # Present_Load
status, _, _ = packet.read1ByteTxRx(port, 2, 65)  # Status

if load > 32767: load -= 65536  # Sign conversion
overload = status & 0x20  # Bit 5 = load overload

Look for:

• Load near ±1000 before stopping = torque limit reached
• Status bit 0x20 set = overload protection triggered
• Voltage drop below 11V = power supply sagging under load

Fix options:

1. Increase torque limit (register 16, default 1000 = max)
2. Reduce arm weight/counterbalance
3. Slow down acceleration (register 12/13)
4. Check power supply can deliver peak current

Avoiding overload in first place: Arm servos fault/lock up when hitting limits and don't respond until power cycle:

• Feetech servos have overload protection. Status register (addr 65) bit 5 (value 0x20) indicates load overload.
• When this triggers and Unloading Condition has bit 5 set, servo releases torque and locks.
• Fix: Monitor Status register every frame, auto-recover faulted servos with per-servo torque cycle:

  statuses = robot.bus.sync_read("Status", arm_motors)
  for motor, status in statuses.items():
      if status & 0x20:  # Load overload
          print(f"[OVERLOAD] {motor} faulted, recovering...")
          robot.bus.write("Torque_Enable", motor, 0)
          time.sleep(0.2)
          robot.bus.write("Torque_Enable", motor, 1)
          # CRITICAL: Use normalize=True to get degrees, not raw encoder counts
          pos = robot.bus.read("Present_Position", motor, normalize=True)
          self.target_positions[motor.replace("arm_", "")] = float(pos)
  

• CRITICAL BUG: Recovery must read with normalize=True — raw encoder counts (0-4095) vs degrees causes massive target jump and re-fault.
• Also clamp IK workspace (keep arm tip inside ~22cm radius) to prevent impossible targets.
• Recovery in Reset (Back button) should also use normalized position read.

Arm teleop crashes with KeyError: 'arm_shoulder_pan.pos':

• Current LeRobot LeKiwi.send_action() safety clamp path expects arm present-position keys without .pos, but arm actions include .pos.
• For now, run the arm teleop with max_relative_target=None (the current lekiwi_xbox_arm_teleop.py default) so commands bypass that broken clamp path.

Arm teleop buttons spam speed/reset/quit while held:

• Use edge-triggered button handling, not level-triggered polling, for Y/A/Back/Start.
• Track previous button state and only fire when a button changes from 0 -> 1.
• Otherwise the 30 Hz loop repeats actions like Reset arm or Base speed level every frame.
• Also remove Start button quit - use Ctrl+C instead to avoid accidental quits.

Left stick feels dead or unreliable in IK mode:

• XY step of 0.005m is too tiny - use 0.02m for responsive feel.
• Deadzone 0.35 is too aggressive - use 0.15.
• Normal mode uses IK which can hit joint limits quickly - LB + stick mode uses direct joint control and always works.

IK drift (doesn't return to same position):

• IK accumulates error each cycle. Up 3s then down 3s won't return to start.
• Fix: Use direct joint control instead. Left stick = shoulder/elbow directly.
• AI policies train on joint control anyway, not IK solutions.

Parallel gripper over-current fault:

• Claw grippers slip. Parallel grippers crush until servo faults.
• Fix: Switch gripper servo to VELOCITY mode:

  robot.bus.write("Operating_Mode", "arm_gripper", OperatingMode.VELOCITY.value)
  # Left trigger = positive velocity (close)
  # Right trigger = negative velocity (open)
  # Release = velocity 0 (stop)
  

• Servo stops on contact, no over-current.

Web UI shows "noise" or frozen frame:

• Check host uses flat dict protocol (no {type: "response", data: {...}} wrapping)
• Flat format: {"cam_0": "base64...", "x.vel": 0.0}
• Wrong format causes web UI to fail parsing

Camera vflip not working (corrupted image):

• OpenCV's cv2.flip() returns non-contiguous array
• JPEG encoder needs contiguous memory
• Fix: Add .copy() after flip: cv2.flip(frame, 0).copy()

Port already in use (Address already in use):

# Kill zombies on ports 5555/5556
sudo fuser -k 5555/tcp 5556/tcp
# Then restart host
lekiwi-zmq-host --cam 0

Host crashes immediately with SyntaxError: invalid syntax at type NameOrID = str | int:

• The installed lerobot package uses Python 3.12 type-alias syntax (type X = ...).
• If lekiwi-control is running under Python 3.11, host startup will fail before hardware connect.
• Check with:

  ~/.hermes/projects/lekiwi-control/.venv/bin/python --version
  

• If it reports Python 3.11, either rebuild the project venv with Python 3.12+ or pin/use a lerobot checkout compatible with Python 3.11.
• Current pyproject.toml saying requires-python = ">=3.11" is misleading if the bundled lerobot dependency needs 3.12 syntax.

Controller not detected:

bluetoothctl info <MAC>  # Check Connected: yes
# If not connected:
bluetoothctl connect <MAC>

Motors not responding:

# Check motor IDs
.venv/bin/python -c "
from lerobot.motors.feetech import FeetechMotorsBus
bus = FeetechMotorsBus('/dev/ttyACM0', {})
bus.connect()
print('Found:', bus.motors)
"

Implementation Notes

Why base-only approach:

• LeKiwi robot class requires all 9 motors (arm+base) to be present
• For arm-less builds, use LeKiwiBaseOnly minimal class that only talks to wheel motors (IDs 7,8,9)
• Bypasses calibration requirements and full config

Kinematics:

• 3 omni wheels at 240°, 0°, 120° mounting angles
• Matrix converts (x, y, theta) body velocities to wheel speeds
• Adapted from XLeRobot's approach

Exact mirror rule for lekiwi-control

If the user's ~/.hermes/projects/lekiwi-control teleop is misbehaving but ~/projects/lerobot/lekiwi_xbox_teleop.py is confirmed working on hardware, do not try to outsmart it.

Use the working lerobot script as the source of truth:

• copy ~/projects/lerobot/lekiwi_xbox_teleop.py over ~/.hermes/projects/lekiwi-control/src/lekiwi/teleop/xbox.py exactly
• keep lekiwi-control/src/lekiwi/teleop/__init__.py compatible by aliasing TeleopConfig = XboxTeleopConfig
• add a parity test so future edits fail fast if the local file drifts

Recommended parity checks:

cd ~/.hermes/projects/lekiwi-control
uv run pytest -q tests/test_xbox_teleop_parity.py tests/test_xbox_teleop_bdd.py
cmp -s src/lekiwi/teleop/xbox.py ~/projects/lerobot/lekiwi_xbox_teleop.py && echo EXACT || echo DIFFERENT
uv run lekiwi-teleop --help

Recommended regression files:

• tests/test_xbox_teleop_parity.py — byte-for-byte parity against upstream script
• tests/test_xbox_teleop_bdd.py + tests/bdd/features/xbox_teleop_parity.feature — critical-path Gherkin parity spec

This is one of those rare times where duplication is correct. Working beats elegant.

Mirroring the known-good lerobot teleop into lekiwi-control

If ~/projects/lerobot/lekiwi_xbox_teleop.py is the version that actually works on hardware, stop being clever and mirror it exactly into ~/.hermes/projects/lekiwi-control/src/lekiwi/teleop/xbox.py.

Rules:

• Copy the file byte-for-byte. Do not "adapt" it first.
• Keep lekiwi-teleop pointing at lekiwi.teleop.xbox:main.
• If package exports expect TeleopConfig but upstream renamed it to XboxTeleopConfig, fix the local package wrapper or tests around it — not the mirrored teleop file.
• Add parity tests so drift is obvious:
  • tests/test_xbox_teleop_parity.py
  • optional Gherkin parity test tagged @smoke
• Fast verify loop:
  • uv run pytest -q
  • uv run pytest -q -m smoke
  • uv run python -m py_compile src/lekiwi/teleop/xbox.py src/lekiwi/teleop/__init__.py
  • uv run lekiwi-teleop --help

What bit us:

• A stale export test still expected teleop_mod.TeleopConfig, but the mirrored upstream file exposed XboxTeleopConfig.
• Correct fix: update wrapper/tests to alias TeleopConfig = XboxTeleopConfig in src/lekiwi/teleop/__init__.py and adjust the export test.
• Bad fix: editing the mirrored upstream teleop file and losing exact parity.

File Locations

• Teleop package entry point: ~/.hermes/projects/lekiwi-control/.venv/bin/lekiwi-teleop
• Host package entry point: ~/.hermes/projects/lekiwi-control/.venv/bin/lekiwi-host
• Canonical wrapper dir: ~/.hermes/bin/
• LeRobot runtime dependency: ~/projects/lerobot/
• Project log: ~/projects/LeKiwi/log/PROJECT_LOG.md