Troubleshooting
Find your issue by symptom. Quick diagnostic matrices are below, followed by deep-dive resolution paths.
Quick Diagnostic Matrices
Motor Issues
| Symptom | Quick Fix |
|---|---|
| No motors move | Check 12V DC cable from battery to motor board |
| Permission denied | sudo chmod 666 /dev/ttyACM0 |
| Motor count mismatch | Run find_port.py and update script |
| Single unresponsive | Re-configure ID with Bambot |
| Arm jerks / wrong dir | Verify IDs match the motor map |
| Grinding noise | Inspect servo horn alignment; replace if stripped |
Camera Issues
| Symptom | Quick Fix |
|---|---|
| Camera not detected | ls /dev/video* to check path |
| Black frame | Check lens cap; test with cv2.VideoCapture |
| YOLO not tracking | Verify camera index in script |
Software Issues
| Symptom | Quick Fix |
|---|---|
| Import errors | pip install -e . in repository root |
| Files not found | Check /model, /robots, /example folders |
| Joy-Con not pairing | sudo apt install joycond, enable Bluetooth |
Assembly Issues
| Symptom | Quick Fix |
|---|---|
| Arm wobbles/play | Tighten servo horn screws; check bracket fit |
| Wheels not straight | Adjust z-axis scale in slicer or use printed washers |
| Cart tips reaching | Move battery to lowest shelf to lower CoG |
Deep Dive: Camera Not Detected
Hardware / USBSymptoms
ls /dev/video*shows no entries or fewer cameras than expected.cv2.VideoCapture()returnsFalseforret.- YOLO tracking script errors with “no camera found”.
- Camera LED is off even though it’s plugged in.
Likely Causes
- USB cable not seated: Loose connection or damaged cable.
- USB hub not powered: Hub can’t supply enough current for multiple cameras.
- Wrong device index: Camera is at a different path than the script expects.
- Kernel driver issue: Camera module not loaded (rare on Ubuntu).
Diagnostic & Fix Steps
1. Check Physical Connection: Unplug and replug the camera. Try a different USB port. Try without the USB hub (direct to PC) to isolate the issue.
2. Check USB Power: If using a USB hub, make sure it’s powered. Low-power hubs may not supply enough current for multiple cameras.
3. Check Device Detection: You should see even-numbered entries (/dev/video0, /dev/video2) — one per camera.
List Video Devices
$ ls /dev/video*
# To see detailed device paths:
$ v4l2-ctl --list-devices
# To see detailed device paths:
$ v4l2-ctl --list-devices
4. Test the Camera Directly: Use a one-line Python test to verify the OpenCV pipeline.
Quick Camera Feed Test
$ python -c "import cv2; cap = cv2.VideoCapture(0); ret, frame = cap.read(); print('OK' if ret else 'FAIL'); cap.release()"
Verification Checklist
ls /dev/video*shows the expected number of devices.- The Python camera test returns OK.
- YOLO or teleoperation scripts run without camera errors.
Prevention Tips
- Use a powered USB hub for multiple cameras.
- Always use the same USB ports—paths change when swapped.
- Label USB cables to avoid confusion during setup.