lerobot-setup-can

The lerobot-setup-can command helps setup and debug CAN (Controller Area Network) interfaces for Damiao motors used in robots like OpenArms.

Command

lerobot-setup-can [OPTIONS]

Location: src/lerobot/scripts/lerobot_setup_can.py

Overview

This utility:

Configures CAN interfaces with CAN FD support
Tests motor connectivity on CAN bus
Performs speed and latency benchmarks
Supports multiple CAN interfaces (can0, can1, can2, can3)
Validates Damiao motor communication

Key Options

--mode

str

default:"test"

Operation mode: setup, test, or speed.

--interfaces

str

default:"can0"

Comma-separated CAN interface names (e.g., "can0,can1,can2,can3").

--bitrate

int

default:"1000000"

CAN bitrate in bits/second (1 Mbps default).

--data_bitrate

int

default:"5000000"

CAN FD data bitrate in bits/second (5 Mbps default).

--use_fd

bool

default:"true"

Enable CAN FD (Flexible Data-rate).

--motor_ids

list[int]

default:"[1,2,3,4,5,6,7,8]"

Motor IDs to test (0x01-0x08).

--timeout

float

default:"1.0"

Motor response timeout in seconds.

--speed_iterations

int

default:"100"

Number of iterations for speed test.

Usage Examples

Setup CAN Interfaces

Configure CAN interfaces with CAN FD:

lerobot-setup-can --mode=setup --interfaces=can0,can1,can2,can3

This:

Sets bitrate to 1 Mbps
Sets data bitrate to 5 Mbps (CAN FD)
Brings up all specified interfaces
Requires sudo permissions

Test Motors on Single Interface

lerobot-setup-can --mode=test --interfaces=can0

Tests motors 0x01-0x08 on can0 and reports:

Which motors respond
Response data from each motor
Summary of found motors

Test Motors on All Interfaces

lerobot-setup-can --mode=test --interfaces=can0,can1,can2,can3

Tests all four CAN interfaces and shows motors on each bus.

Speed Test

Benchmark communication speed:

lerobot-setup-can --mode=speed --interfaces=can0 --speed_iterations=100

Reports:

Average latency (ms)
Success rate
Maximum achievable frequency (Hz)

Custom Configuration

lerobot-setup-can \
  --mode=setup \
  --interfaces=can0,can1 \
  --bitrate=500000 \
  --data_bitrate=2000000 \
  --use_fd=true

Mode Details

Setup Mode

Configures CAN interfaces:

lerobot-setup-can --mode=setup --interfaces=can0

Executes:

Brings down interface: sudo ip link set can0 down
Configures CAN: sudo ip link set can0 type can bitrate 1000000 dbitrate 5000000 fd on
Brings up interface: sudo ip link set can0 up

Output:

==================================================
CAN Interface Setup
==================================================
Mode: CAN FD
Bitrate: 1.0 Mbps
Data bitrate: 5.0 Mbps

Configuring can0...
  ✓ can0: UP (CAN FD)

Setup complete!

Next: Test motors with:
  lerobot-setup-can --mode=test --interfaces can0

Test Mode

Tests motor connectivity:

lerobot-setup-can --mode=test --interfaces=can0

For each motor:

Sends enable command (0xFC)
Waits for response
Sends disable command (0xFD)
Reports findings

Output:

==================================================
CAN Motor Test
==================================================
Testing motors 0x01-0x08
Mode: CAN FD

can0: UP (CAN FD)
  Motor 0x01 (joint_1): ✓ FOUND
    → Response 0x01 [FD]: ffffffffffff7ffc
  Motor 0x02 (joint_2): ✓ FOUND
    → Response 0x02 [FD]: ffffffffffff7ffc
  Motor 0x03 (joint_3): ✗ No response
  Motor 0x04 (joint_4): ✗ No response
  Motor 0x05 (joint_5): ✓ FOUND
    → Response 0x05 [FD]: ffffffffffff7ffc
  Motor 0x06 (joint_6): ✓ FOUND
    → Response 0x06 [FD]: ffffffffffff7ffc
  Motor 0x07 (joint_7): ✗ No response
  Motor 0x08 (gripper): ✓ FOUND
    → Response 0x08 [FD]: ffffffffffff7ffc

  Summary: 5/8 motors found

==================================================
Summary
==================================================
Total motors found: 5

Speed Mode

Benchmarks communication performance:

lerobot-setup-can --mode=speed --interfaces=can0

Output:

==================================================
CAN Speed Test
==================================================

can0: Running speed test (100 iterations)...
  Testing with motor 0x01...
  ✓ Success rate: 100/100
  ✓ Avg latency: 1.23 ms
  ✓ Max frequency: 813.0 Hz

Motor Mapping

Default motor ID to joint mapping:

ID	Joint Name
0x01	joint_1
0x02	joint_2
0x03	joint_3
0x04	joint_4
0x05	joint_5
0x06	joint_6
0x07	joint_7
0x08	gripper

Troubleshooting

Interface Not Found

Output:

can0: Interface not found - skipping

Causes:

CAN hardware not connected
Wrong interface name
Driver not loaded

Solutions:

# List available network interfaces
ip link show

# Check for CAN interfaces
ls /sys/class/net/ | grep can

# Load CAN drivers (if needed)
sudo modprobe can
sudo modprobe can_raw
sudo modprobe vcan  # Virtual CAN for testing

Permission Denied

Error:

Failed to configure: Permission denied

Solution: Run with sudo or configure sudo access:

# Option 1: Run with sudo
sudo lerobot-setup-can --mode=setup --interfaces=can0

# Option 2: Add user to netdev group (then log out/in)
sudo usermod -a -G netdev $USER

No Motors Found

Output:

Total motors found: 0

⚠ No motors found! Check:
Motors are powered (24V)
CAN wiring (CANH, CANL, GND)
Motor timeout parameter > 0 (use Damiao tools)
120Ω termination at both cable ends
Interface configured: lerobot-setup-can --mode=setup --interfaces can0

Solutions:

Check Power: Ensure motors have 24V power
Check Wiring:
- CANH connected to CANH
- CANL connected to CANL
- GND connected
Check Termination: 120Ω resistors at both cable ends
Check Motor Configuration: Use Damiao software to verify:
- Motor IDs are correct (0x01-0x08)
- Timeout parameter > 0
- Motors are in correct mode

Test Interface:

# Verify interface is UP
ip link show can0

# Should show: "can0: <NOARP,UP,LOWER_UP,ECHO> ... state UP"

Connection Timeouts

Cause: CAN interface configuration or hardware issues. Solutions:

# Restart interface
sudo ip link set can0 down
sudo ip link set can0 up

# Reconfigure
lerobot-setup-can --mode=setup --interfaces=can0

# Test with lower bitrate
lerobot-setup-can \
  --mode=setup \
  --interfaces=can0 \
  --bitrate=500000 \
  --data_bitrate=2000000

Slow Communication

Speed test shows low frequency:

✓ Max frequency: 150.0 Hz  # Should be > 500 Hz

Solutions:

Use CAN FD: --use_fd=true
Increase data bitrate: --data_bitrate=5000000
Check cable quality (use short, high-quality cables)
Reduce number of motors per bus
Check CPU load during operation

Hardware Setup

CAN Bus Wiring

[Controller]     [Motor 1]     [Motor 2]     [Motor N]
   |               |             |             |
  CANH ---------- CANH -------- CANH -------- CANH
  CANL ---------- CANL -------- CANL -------- CANL
   GND ---------- GND --------- GND --------- GND
   |                                           |
  120Ω                                         120Ω

Termination Resistors

Place 120Ω resistors at both ends of the CAN bus
Required for signal integrity
Without termination: reflections cause errors

Cable Recommendations

Use twisted pair cable (CANH/CANL)
Keep cables short (under 5 meters ideal)
Use shielded cable in noisy environments
Connect shield to GND at one end only

Advanced Usage

Test Specific Motors

lerobot-setup-can \
  --mode=test \
  --interfaces=can0 \
  --motor_ids="[1, 2, 5, 8]"

Tests only motors 0x01, 0x02, 0x05, 0x08.

Extended Speed Test

lerobot-setup-can \
  --mode=speed \
  --interfaces=can0 \
  --speed_iterations=1000

Runs 1000 iterations for more accurate benchmarking.

Disable CAN FD

For compatibility with older devices:

lerobot-setup-can \
  --mode=setup \
  --interfaces=can0 \
  --use_fd=false \
  --bitrate=1000000

Core

Scripts

Utilities

lerobot-setup-can

Command

Overview

Key Options

Usage Examples

Setup CAN Interfaces

Test Motors on Single Interface

Test Motors on All Interfaces

Speed Test

Custom Configuration

Mode Details

Setup Mode

Test Mode

Speed Mode

Motor Mapping

Troubleshooting

Interface Not Found

Permission Denied

No Motors Found

Connection Timeouts

Slow Communication

Hardware Setup

CAN Bus Wiring

Termination Resistors

Cable Recommendations

Advanced Usage

Test Specific Motors

Extended Speed Test

Disable CAN FD

See Also

Build docs developers (and LLMs) love

Core

Scripts

Utilities

​Command

​Overview

​Key Options

​Usage Examples

​Setup CAN Interfaces

​Test Motors on Single Interface

​Test Motors on All Interfaces

​Speed Test

​Custom Configuration

​Mode Details

​Setup Mode

​Test Mode

​Speed Mode

​Motor Mapping

​Troubleshooting

​Interface Not Found

​Permission Denied

​No Motors Found

​Connection Timeouts

​Slow Communication

​Hardware Setup

​CAN Bus Wiring

​Termination Resistors

​Cable Recommendations

​Advanced Usage

​Test Specific Motors

​Extended Speed Test

​Disable CAN FD

​See Also

Build docs developers (and LLMs) love

Command

Overview

Key Options

Usage Examples

Setup CAN Interfaces

Test Motors on Single Interface

Test Motors on All Interfaces

Speed Test

Custom Configuration

Mode Details

Setup Mode

Test Mode

Speed Mode

Motor Mapping

Troubleshooting

Interface Not Found

Permission Denied

No Motors Found

Connection Timeouts

Slow Communication

Hardware Setup

CAN Bus Wiring

Termination Resistors

Cable Recommendations

Advanced Usage

Test Specific Motors

Extended Speed Test

Disable CAN FD

See Also