USB and Serial Troubleshooting for Robot Arms

An arm that has stopped answering looks identical in every log: a timeout. The process cannot reach motor 1, the teleoperation loop stalls, and the arm freezes or sags. Nothing in that message says whether the USB bridge chip fell off the bus, whether a background daemon opened the port first, or whether one servo stopped talking. Three problems, three fixes, and exactly one of them involves a screwdriver.

This is the triage order for SO-100 class arms, written for Linux because that is where the arms end up. Where macOS differs it is called out. If you are still assembling, start at the SO-100 getting started guide and come back here the first time it goes quiet.

The chain between your Python process and a servo horn

Seven layers sit between a call to bus.read('Present_Position', 'shoulder_pan') and a horn moving, and each fails with its own symptom. Most wasted debugging time comes from applying a fix from one layer to a fault in another: reinstalling drivers when the jumper is wrong, or resoldering a cable when a screen reader has the port.

Work down that table in order. Do not skip a row because you are sure about it. Arm not detected and servo not responding are separate pages here for exactly that reason: the boundary is whether a device node exists.

Read the node name first: ttyACM or ttyUSB

Linux exposes USB serial adapters through two unrelated paths. The usb-serial framework covers chips needing a vendor-specific protocol, uses major number 188 and names them /dev/ttyUSB0 upward. The CDC-ACM class driver covers chips that describe themselves as standard USB communications devices and names them /dev/ttyACM0 upward. Which one you get is a property of the chip, not of your distribution.

# 1. is the bridge on the bus at all?
lsusb
lsusb -t                 # tree view: shows which driver claimed which interface

# 2. what did the kernel decide to do with it?
sudo dmesg -w            # leave running, then unplug and replug the arm

# 3. which node appeared, and what are the stable aliases?
ls -l /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
ls -l /dev/serial/by-id/ /dev/serial/by-path/

On a healthy CH340 you want a dmesg pair like ch341-uart converter detected followed by ch341-uart converter now attached to ttyUSB0. A CDC device gives a line naming ttyACM0. An attach followed by a disconnect a second later means the chip is fine and userspace is taking it: skip to the traps.

Five minute triage: driver problem or servo problem

The useful boundary: can a process open the port. If it can, the kernel, the host cable and the bridge chip all work, and everything after that is the servo bus.

1. 1
   Confirm the bridge enumerates

   If the chip is not in lsusb, no driver work helps. Try a different cable first: charge-only USB cables look identical to good ones and are the most common cause of a device that never appears.

   bash

   lsusb | grep -iE '1a86|0403|10c4|067b'
   lsusb -t     # look for the Driver= field on the interface line

2. 2
   Confirm a node exists and nobody else holds it

   Wrong group is a permissions problem. Busy means another process got there first.

   bash

   ls -l /dev/ttyACM0
   stat -c '%G' /dev/ttyACM0        # which group owns it
   fuser -v /dev/ttyACM0            # who has it open (or: lsof /dev/ttyACM0)

3. 3
   Open the port with nothing but pyserial

   Take LeRobot out of the picture. If this succeeds, every remaining failure is on the servo side.

   python

   import serial
   s = serial.Serial("/dev/ttyACM0", 1_000_000, timeout=1)
   print("opened:", s.is_open, s.name)
   s.close()

4. 4
   Ask the bus which motors exist, at every baud rate

   LeRobot ships a scanner that broadcast-pings at each supported baud and reports every id that answered. The list runs 4800 through 1000000, and 1000000 is the Feetech default.

   python

   from lerobot.motors.feetech import FeetechMotorsBus
   
   # returns {baudrate: [motor ids that answered]}
   print(FeetechMotorsBus.scan_port("/dev/ttyACM0"))

5. 5
   Read the error text literally

   LeRobot and the Feetech SDK use distinct strings for distinct faults. Worth memorising.

   text

   Could not connect on port '/dev/ttyACM0'.   -> kernel refused: node, permission, or busy
   [TxRxResult] There is no status packet!     -> nobody answered: baud, power, wiring, id
   [TxRxResult] Incorrect status packet!       -> something answered but the framing was wrong
   [TxRxResult] Port is in use!                -> the SDK already has the port open elsewhere

The traps that eat a day

brltty takes your CH340

A braille display uses the same CH340 chip as half the hobby robotics world, so brltty ships a udev rule matching USB id 1a86:7523 and claims the device on sight. Ubuntu bug 1990357 records exactly that against brltty 6.4-4ubuntu3 on Ubuntu 22.04.1 and Linux Mint 21: lsusb lists the chip as 1a86:7523, nothing appears in /dev, and the device comes back as /dev/ttyUSB0 once brltty is removed. The report is still Confirmed.

# is brltty even here?
dpkg -l | grep -i brltty
systemctl status brltty-udev.service

# surgical: find the rule matching your chip and comment that one line out.
# on Ubuntu the generated file is 85-brltty.rules; the ids are lowercase hex
grep -n "1a86" /usr/lib/udev/rules.d/85-brltty.rules

# blunt: stop udev from starting brltty at all
sudo systemctl mask brltty-udev.service
sudo systemctl stop brltty-udev.service
sudo udevadm control --reload

ModemManager probes anything that looks like a port

ModemManager opens new serial ports to check for a modem behind them. The probe holds the port for a few seconds after every plug event, so the first lerobot-calibrate after connecting fails and the same command twenty seconds later works. Two details decide whether the fix takes: the property goes on the usb subsystem, not tty, because a device-level tag belongs on the device, and the ModemManager documentation asks for a 78-mm- or 79-mm- filename, because its own candidate rules are the 80-mm- file.

# /etc/udev/rules.d/79-mm-lerobot-ignore.rules
# the 79- prefix is not cosmetic: rules files from every directory are sorted
# together by filename, and ModemManager's candidate rules are the 80-mm- file
ACTION!="add|change|move|bind", GOTO="mm_lerobot_end"
# substitute the ids you actually saw in lsusb
SUBSYSTEM=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", ENV{ID_MM_DEVICE_IGNORE}="1"
LABEL="mm_lerobot_end"

# then
sudo udevadm control --reload
sudo udevadm trigger --subsystem-match=usb

# confirm the property landed where ModemManager will read it
udevadm info -p /sys/class/tty/ttyACM0 | grep ID_MM

Permissions, and why chmod 666 keeps coming back

Serial nodes are group-owned: dialout on Debian and Ubuntu, uucp on Arch. The LeRobot SO-101 guide suggests sudo chmod 666 /dev/ttyACM0, which works until the next replug, because udev recreates the node with the default mode. Group membership is durable and needs a fresh login.

ls -l /dev/ttyACM0
# crw-rw---- 1 root dialout 166, 0 Aug 24 09:14 /dev/ttyACM0

sudo usermod -aG "$(stat -c '%G' /dev/ttyACM0)" "$USER"
# log out and back in, or start a subshell with the new group:
newgrp dialout

# verify without replugging anything
id -nG | tr ' ' '\n' | grep -E 'dialout|uucp'

The jumper that is not a software problem at all

The second trap is the power rail. The SO-100 and SO-101 run Feetech STS3215 bus servos at 7.4 V. Koch v1.1 uses Dynamixel XL330 and XL430 parts on 5 V and 12 V rails, and LeKiwi is a 7.4 V arm on a 12 V base, the layout that invites the wrong barrel jack. Feeding 12 V into STS3215 servos destroys them, and the same Waveshare adapter wiki says the input voltage must match the servo voltage.

udev rules: stop chasing /dev/ttyACM0

tty numbers are handed out in bind order, which follows probe timing. With a leader-follower pair the leader is ttyACM0 today and ttyACM1 tomorrow, and hardcoded numbers mean driving the wrong arm at least once. A rule in the udev rule language fixes the name.

1. 1
   Walk the device tree and pick a discriminator

   The walk prints one block per ancestor device. You want a value unique to this arm and stable across reboots: ATTRS{serial} if the chip reports one, otherwise the parent kernel name, which encodes the socket.

   bash

   udevadm info --name=/dev/ttyACM0 --attribute-walk | head -60
   
   # the short version of the same question
   udevadm info --name=/dev/ttyACM0 --query=property | grep -E 'ID_VENDOR_ID|ID_MODEL_ID|ID_SERIAL|ID_PATH'

2. 2
   Write the rule

   Put it in /etc/udev/rules.d/, but know what that buys you. Rules files from every directory are sorted and processed together in lexicographic order by filename, so a 99- file runs last wherever it lives. The /etc/ precedence applies only to a file with the same name as one under /usr/lib/: that replaces a packaged rule, it does not outrank one.

   bash

   # /etc/udev/rules.d/99-lerobot-arms.rules
   
   # by serial number: survives moving the cable to any socket,
   # but only works if the bridge chip actually reports one
   SUBSYSTEM=="tty", ATTRS{idVendor}=="1a86", ATTRS{serial}=="58FD017123", \
     SYMLINK+="robot_follower", MODE="0660", GROUP="dialout"
   
   # by physical port: works with chips that report no serial at all,
   # but breaks the moment you move the plug
   SUBSYSTEM=="tty", KERNELS=="1-1.2", \
     SYMLINK+="robot_leader", MODE="0660", GROUP="dialout"

3. 3
   Reload, trigger, verify

   Reloading alone changes nothing for devices already plugged in. The trigger replays the events, so the rule applies without a replug.

   bash

   sudo udevadm control --reload
   sudo udevadm trigger --subsystem-match=tty
   ls -l /dev/robot_*
   
   # if the symlink does not appear, watch the events live
   udevadm monitor --udev --property --subsystem-match=tty

4. 4
   Use the stable name everywhere

   Once the symlink exists, no LeRobot command needs a number again.

   bash

   lerobot-calibrate \
       --robot.type=so101_follower \
       --robot.port=/dev/robot_follower \
       --robot.id=my_follower_arm

Unbind and rebind: resetting a wedged bridge without touching the cable

Sometimes the chip is present, the node is present, and writes go nowhere: the bridge has wedged. Manual driver binding through sysfs has existed since kernel 2.6.13-rc3 and gives two levels of reset short of pulling the cable.

PORT=/dev/ttyACM0
TTY=$(basename "$PORT")

# derive the ids instead of guessing them
IFACE=$(basename "$(readlink -f /sys/class/tty/$TTY/device)")
DRV=$(basename "$(readlink -f /sys/class/tty/$TTY/device/driver)")
DEV=${IFACE%%:*}
echo "interface=$IFACE driver=$DRV device=$DEV"
# e.g. interface=1-1.4:1.0 driver=cdc_acm device=1-1.4

# level 1: drop only the interface the tty hangs off, leave the device enumerated
echo -n "$IFACE" | sudo tee /sys/bus/usb/drivers/$DRV/unbind
echo -n "$IFACE" | sudo tee /sys/bus/usb/drivers/$DRV/bind

# level 2: re-enumerate the whole device, equivalent to a replug
echo -n "$DEV" | sudo tee /sys/bus/usb/drivers/usb/unbind
sleep 2
echo -n "$DEV" | sudo tee /sys/bus/usb/drivers/usb/bind

Level 2 re-runs udev, so symlinks and permissions come back as configured. That is why the udev rule comes before the rebind script. Level 3 cuts port power with uhubctl, with one caveat: on Raspberry Pi the ports are ganged. On the B+, 2B and 3B, ports 2 to 5 are controlled by port 2, and on the Pi 5 all four form one group. Cutting power to the arm cuts power to the cameras too.

When it really is the servo

Everything past a successful open is the half-duplex TTL bus, where the two Feetech SDK strings from step 5 earn their keep. There is no status packet means nothing replied within the timeout: power, baud or wiring. Incorrect status packet means something replied with wrong framing, which points at a baud mismatch or electrical noise, not at absence. Opposite fixes.

The last row is worth doing by hand: move a known-good 3-pin cable to the silent joint. If the joint answers, the cable was the fault; if not, the servo is. Both outcomes have a page, joint stops early and arm twitches then sags. A missing camera is a different subsystem again, at camera not detected.

The latency layer nobody measures

A link can be connected and still be too slow for a control loop. Three places add delay before a line of your code runs, and none report an error.

On an FTDI adapter one write removes the buffering. It does not survive a replug, so it belongs in your udev rule file or your startup script. CH340, CH343 and CDC-ACM devices have no equivalent knob.

# FTDI only: drop the receive buffering from 16 ms to 1 ms
cat /sys/bus/usb-serial/devices/ttyUSB0/latency_timer
echo 1 | sudo tee /sys/bus/usb-serial/devices/ttyUSB0/latency_timer

# keep the device awake regardless of power policy
echo on | sudo tee /sys/bus/usb/devices/1-1.4/power/control

# if you need to see the actual traffic, usbmon is the tcpdump of USB
sudo modprobe usbmon
ls /sys/kernel/debug/usb/usbmon
sudo cat /sys/kernel/debug/usb/usbmon/1u > /tmp/bus1.mon

Two ways to get an arm answering again

# lerobot 0.6.1, released 2026-08-03
pip install 'lerobot[core_scripts,feetech]'

lerobot-find-port                     # unplug when asked, it prints the node
sudo usermod -aG dialout "$USER"      # then log out and back in

# after writing /etc/udev/rules.d/99-lerobot-arms.rules
sudo udevadm control --reload
sudo udevadm trigger --subsystem-match=tty

lerobot-calibrate \
    --robot.type=so101_follower \
    --robot.port=/dev/robot_follower \
    --robot.id=my_follower_arm

A checklist you can run in ninety seconds

Save this next to your robot scripts. It answers, in order, the six questions that separate the layers.

#!/usr/bin/env bash
# triage.sh - ninety second check for an SO-100 class arm on Linux
PORT="${1:-/dev/ttyACM0}"

echo "== bridge on the bus?"
lsusb | grep -iE '1a86|0403|10c4|067b' || echo "  no known USB-serial bridge in lsusb"

echo "== which driver claimed which interface?"
lsusb -t

echo "== node and permissions"
ls -l "$PORT" 2>&1

echo "== stable aliases"
ls -l /dev/serial/by-id/ /dev/serial/by-path/ 2>&1

echo "== who is holding the port?"
fuser -v "$PORT" 2>&1

echo "== known port thieves"
systemctl is-active brltty-udev.service ModemManager.service 2>&1

echo "== last twenty kernel lines"
dmesg | tail -20

For the setup around this, the complete SO-100 setup guide covers assembly through calibration and first policy run, and the data collection guide picks up once the link stops dropping. SO-100 against SO-101 compares the two arms, and the SO-100 LeRobot page covers the software side.