Troubleshooting

Common Issues

Serial Port Not Found

Symptom:

[SERIAL] Error: /dev/ttyUSB0 not found

Solutions:

  1. Check USB connection: ls /dev/tty*

  2. Verify ESP32 is powered (LED on DevKit)

  3. Try alternative ports: /dev/ttyACM0, /dev/ttyAMA0

  4. Check Docker device mount: /dev:/dev in docker-compose

  5. Add user to dialout group: sudo usermod -a -G dialout pi

No Sensor Data

Symptom: /api/latest returns empty or zero values

Solutions:

  1. Check serial monitor for ESP32 boot messages

  2. Verify sensor wiring (I2C pull-ups, UART TX/RX not swapped)

  3. Restart ESP32: unplug/replug USB

  4. Check CRC errors: /api/status → crc_errors should be 0

  5. Reflash ESP32 firmware

Kogger Not Detected

Symptom: ka.alive == false or kb.alive == false

Solutions:

  1. Check Kogger power (12V supply, LED indicator)

  2. Verify UART baud rate (921600 on both sides)

  3. Check GPIO pins (16/17 for A, 25/26 for B)

  4. Test Kogger with desktop KoggerApp (USB-UART adapter)

  5. Check BB55 frame parsing: enable debug logs

IMU No Data

Symptom: imu.alive == false, roll/pitch/yaw = 0

Solutions:

  1. Verify SoftwareSerial pins (GPIO 13 RX, 15 TX)

  2. Check HWT905 power (3.3V or 5V, check datasheet)

  3. Test IMU standalone with Serial Monitor @ 9600 baud

  4. Verify binary protocol (0x55 packets)

  5. Check for SoftwareSerial conflicts (max 3 active instances)

GPS No Fix

Symptom: gps.alive == true but lat == 0, lon == 0

Solutions:

  1. GPS needs outdoor clear sky view (no fix indoors)

  2. Allow 30-60s cold start acquisition time

  3. Check NMEA sentences with Serial Monitor

  4. Verify SoftwareSerial RX (GPIO 27) → GPS TX

  5. Check antenna connection (active antenna needs power)

I2C Sensors Fail

Symptom: MS5837 or TSYS01 not detected

Solutions:

  1. Check pull-up resistors (4.7kΩ on SDA+SCL to 3.3V)

  2. Verify I2C addresses (0x76 MS5837, 0x77 TSYS01)

  3. Shorten I2C wires (<10cm for reliability)

  4. Test with i2cdetect -y 1 on Raspberry Pi

  5. Check for address conflicts (no other devices on 0x76/0x77)

WebSocket Connection Failed

Symptom: Dashboard can’t connect to WS

Solutions:

  1. Check service is running: docker ps

  2. Verify port mapping: netstat -tuln | grep 8766

  3. Check firewall: sudo ufw status

  4. Test with websocat ws://192.168.0.174:8766

  5. Check browser console for CORS/network errors

High CRC Errors

Symptom: /api/status → crc_errors > 100

Solutions:

  1. Check USB cable quality (use shielded cable)

  2. Verify baud rate match (115200 both sides)

  3. Reduce USB cable length (<3m)

  4. Check for EMI sources (motors, servos)

  5. Try lower baud rate (57600)

Docker Container Crashes

Symptom: Container exits immediately

Solutions:

  1. Check logs: docker compose logs slam-hub

  2. Verify Python dependencies: rebuild image

  3. Check serial device permissions

  4. Run container manually: docker run -it --rm bluerov-slam-hub:latest

  5. Check for port conflicts (8099/8766 already in use)

Waterfall Display Not Rendering

Symptom: Kogger viewer loads but no waterfall data

Solutions:

  1. Check UDP packets arriving: tcpdump -i any port 14555

  2. Verify kogger-viewer logs: docker compose logs kogger-viewer

  3. Check BB55 parsing stats: /api/status → a_bb55, b_bb55

  4. Test with desktop KoggerApp (should also receive UDP)

  5. Check for BB55 frame corruption

Performance Issues

High Latency (>500ms)

Causes:

  • Network congestion

  • CPU overload on Raspberry Pi

  • Large WebSocket message queue

Solutions:

  1. Reduce sensor polling rate (ESP32: increase delay)

  2. Limit WebSocket clients (close unused connections)

  3. Check Pi CPU usage: htop

  4. Optimize Docker resource limits

  5. Use Ethernet instead of WiFi

Dropped Frames

Causes:

  • Serial buffer overflow

  • USB bandwidth limits

  • Slow disk I/O (JSONL logging)

Solutions:

  1. Increase serial buffer size (ESP32 code)

  2. Reduce Kogger data rate (lower ping frequency)

  3. Disable JSONL logging if not needed

  4. Use faster SD card (UHS-I or better)

  5. Mount logs to tmpfs (RAM disk)

Debugging Tools

Serial Monitor

Real-time ESP32 debug output:

pio device monitor --baud 115200

Docker Logs

Service debug output:

docker compose logs -f --tail=100 slam-hub
docker compose logs -f --tail=100 kogger-viewer

HTTP Debug

API endpoint testing:

curl -v http://192.168.0.174:8099/health
curl http://192.168.0.174:8099/api/status | jq

WebSocket Debug

Real-time message inspection:

websocat ws://192.168.0.174:8766
websocat ws://192.168.0.174:8101

Network Debug

UDP packet capture:

# Capture Kogger UDP
tcpdump -i any -n port 14555 -w kogger_a.pcap

# Capture MAVLink
tcpdump -i any -n port 14401 -w mavlink.pcap

I2C Debug

Scan I2C bus:

# On Raspberry Pi (if sensors connected directly)
i2cdetect -y 1

GPIO Debug

Check ESP32 pin state:

// Add to ESP32 code
Serial.printf("GPIO16 (Kogger A RX): %d\\n", digitalRead(16));
Serial.printf("GPIO21 (I2C SDA): %d\\n", digitalRead(21));

Known Limitations

  • SoftwareSerial: Max 3 active instances (ESP32 interrupt limit)

  • I2C bus length: <10cm for reliable 100kHz operation

  • USB serial baud: 115200 max (Pi USB-UART chip limitation)

  • Kogger compression: 4:1 decimation — some detail loss

  • MAVLink: No acknowledgments (fire-and-forget UDP)

Getting Help

  1. Check this troubleshooting guide

  2. Review logs (docker compose logs)

  3. Test with minimal configuration (disable non-essential sensors)

  4. Open GitHub issue: https://github.com/flagabat/bluerov-slam/issues

  5. Contact: baptiste.moulin@gmail.com