Troubleshooting =============== Common Issues ------------- Serial Port Not Found ^^^^^^^^^^^^^^^^^^^^^ **Symptom:** .. code-block:: text [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) MAVLink Not Working ^^^^^^^^^^^^^^^^^^^ **Symptom:** ArduPilot doesn't receive MAVLink messages **Solutions:** 1. Verify ``MAVLINK_ENABLED=1`` in docker-compose 2. Check target IP/port: ``MAVLINK_TARGET=192.168.2.2:14401`` 3. Test with MAVProxy: ``mavproxy.py --master=udp:192.168.0.174:14401`` 4. Check firewall on ArduPilot side 5. Verify SysID/CompID in QGroundControl settings 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: .. code-block:: bash pio device monitor --baud 115200 Docker Logs ^^^^^^^^^^^ Service debug output: .. code-block:: bash docker compose logs -f --tail=100 slam-hub docker compose logs -f --tail=100 kogger-viewer HTTP Debug ^^^^^^^^^^ API endpoint testing: .. code-block:: bash 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: .. code-block:: bash websocat ws://192.168.0.174:8766 websocat ws://192.168.0.174:8101 Network Debug ^^^^^^^^^^^^^ UDP packet capture: .. code-block:: bash # 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: .. code-block:: bash # On Raspberry Pi (if sensors connected directly) i2cdetect -y 1 GPIO Debug ^^^^^^^^^^ Check ESP32 pin state: .. code-block:: arduino // 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