Documentation Index
Fetch the complete documentation index at: https://motorbridge.seeedstudio.com/llms.txt
Use this file to discover all available pages before exploring further.
Best Practices: Troubleshooting
CAN Communication Errors
”socketcan write failed: No buffer space available (os error 105)”
Cause: CAN TX buffer overflow - sending too many messages too fast.
Solutions:
-
Increase control period:
# Change from 5ms to 20ms or more
dt_s = 0.02 # 50Hz instead of 200Hz
-
Increase TX queue length:
sudo ifconfig can0 txqueuelen 1000
-
Stop other CAN senders:
# Check for other processes using CAN
lsof | grep can0
-
Reduce feedback request frequency:
# Only request every N iterations
if i % 5 == 0:
motor.request_feedback()
“CAN interface not found”
Cause: CAN interface not configured or not up.
Solutions:
# Load CAN modules
sudo modprobe can
sudo modprobe can_raw
sudo modprobe can_dev
# Configure interface
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up
# Verify
ip link show can0
“Permission denied on /dev/ttyACM0”
Cause: User doesn’t have permission to access serial port.
Solutions:
# Add user to dialout group
sudo usermod -a -G dialout $USER
# Log out and back in for changes to take effect
# Or temporary access
sudo chmod 666 /dev/ttyACM0
Motor Response Issues
”state = None”
Cause: No feedback frame received yet.
Solutions:
# Implement retry loop
import time
def get_state_with_retry(motor, max_attempts=10):
for _ in range(max_attempts):
motor.request_feedback()
state = motor.get_state()
if state is not None:
return state
time.sleep(0.05)
return None
state = get_state_with_retry(motor)
if state:
print(f"Position: {state.pos}")
else:
print("No feedback after retries")
Check:
- Motor powered on
- CAN wiring correct (CAN_H, CAN_L)
- Correct motor_id and feedback_id
- Bitrate matches motor configuration
”Mode switch timeout”
Cause: Motor not responding to mode change command.
Solutions:
-
Verify motor ID:
motorbridge-cli scan --vendor damiao --start-id 1 --end-id 32
-
Check motor status:
state = motor.get_state()
if state:
print(f"Status: 0x{state.status_code:02X}")
-
Clear errors first:
motor.clear_error()
time.sleep(0.1)
motor.ensure_mode(Mode.MIT, 1000)
-
Increase timeout:
motor.ensure_mode(Mode.MIT, timeout_ms=2000)
“Motor not moving”
Cause: Motor disabled, wrong mode, or command not being sent.
Checklist:
# 1. Motor enabled?
ctrl.enable_all()
# 2. Correct mode?
motor.ensure_mode(Mode.MIT, 1000)
# 3. Commands being sent?
motor.send_mit(0.5, 0.0, 30.0, 1.0, 0.0)
# 4. Check status
motor.request_feedback()
state = motor.get_state()
if state:
print(f"Status: 0x{state.status_code:02X}")
print(f"Position: {state.pos:.3f}")
Error Code Reference
Damiao Status Codes
| Code | Meaning | Action |
|---|
| 0 | Normal | None |
| 1 | Over-voltage | Check power supply |
| 2 | Under-voltage | Check power supply |
| 3 | Over-current | Reduce load |
| 4 | MOSFET over-temp | Cool down, reduce load |
| 5 | Rotor over-temp | Cool down, reduce load |
| 6 | Communication timeout | Check wiring |
Handling Errors
def handle_motor_error(motor, status_code):
"""Handle motor error based on status code."""
if status_code == 0:
return True # OK
print(f"Motor error: 0x{status_code:02X}")
if status_code in (1, 2): # Voltage errors
print("Check power supply voltage")
return False
if status_code in (3, 4, 5): # Current/temperature
print("Reduce load and wait for cooling")
motor.disable()
return False
if status_code == 6: # Timeout
print("Check CAN wiring")
motor.clear_error()
motor.enable()
return True
return False
Import Errors
”ImportError: cannot import name ‘Controller’”
Cause: Package not installed or ABI library missing.
Solutions:
# Reinstall package
pip install --upgrade --force-reinstall motorbridge
# Verify installation
python3 -c "import motorbridge; print('OK')"
# Check ABI library (for source builds)
ls -la /path/to/motorbridge/lib/libmotor_abi.so
export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH
“AbiLoadError: Failed to load libmotor_abi”
Cause: ABI shared library not found or incompatible.
Solutions:
# Find library
find /usr -name "libmotor_abi.so" 2>/dev/null
# Set library path
export LD_LIBRARY_PATH=/path/to/lib:$LD_LIBRARY_PATH
# Or install from wheel (includes library)
pip install motorbridge
High CPU Usage
Causes & Solutions:
-
Tight loop without sleep:
# Bad
while True:
motor.send_mit(...)
# No sleep - 100% CPU
# Good
while True:
motor.send_mit(...)
time.sleep(0.02) # 50Hz
-
Excessive polling:
# Bad — polling without requesting feedback
while True:
ctrl.poll_feedback_once() # No new data unless request_feedback() was called
# Good — request then poll
while True:
motor.request_feedback()
ctrl.poll_feedback_once()
state = motor.get_state()
Inconsistent Timing
Solutions:
import time
DT_S = 0.02
next_time = time.time()
for i in range(100):
# Work
motor.send_mit(...)
motor.request_feedback()
# Sleep until next period
next_time += DT_S
sleep_time = next_time - time.time()
if sleep_time > 0:
time.sleep(sleep_time)
else:
print(f"Overrun: {-sleep_time*1000:.1f}ms")
next_time = time.time() # Reset timing
Debugging Tips
Enable Verbose Logging
import logging
# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
Check CAN Traffic
# Monitor CAN bus
candump can0
# Send test frame
cansend can0 001#0102030405060708
Test with CLI
# Scan for motors
motorbridge-cli scan --vendor all --channel can0
# Test single motor
motorbridge-cli run --vendor damiao --motor-id 0x01 --mode enable --loop 1
# Dump registers
motorbridge-cli id-dump --motor-id 0x01 --rids 7,8,9,10
Isolate Problem
# Minimal test case
from motorbridge import Controller
with Controller("can0") as ctrl:
motor = ctrl.add_damiao_motor(0x01, 0x11, "4340P")
# Test enable
try:
motor.enable()
print("Enable: OK")
except Exception as e:
print(f"Enable: FAILED - {e}")
# Test feedback
motor.request_feedback()
state = motor.get_state()
print(f"Feedback: {'OK' if state else 'FAILED'}")
# Test command
try:
motor.send_mit(0.0, 0.0, 10.0, 1.0, 0.0)
print("Command: OK")
except Exception as e:
print(f"Command: FAILED - {e}")
Getting Help
If issues persist:
-
Check documentation:
-
Gather information:
# System info
uname -a
python3 --version
pip show motorbridge
# CAN status
ip link show can0
-
Report issue with:
- Full error message
- Code snippet
- System information
- CAN configuration
Next Steps