BlueROV SLAM Documentation
===========================

**Underwater acoustic SLAM system for BlueROV2** combining dual side-scan sonar (Kogger), depth sensors, IMU, GPS, and temperature via ESP32 sensor hub.

.. image:: https://img.shields.io/badge/version-1.0.0-blue.svg
   :alt: Version
   
.. image:: https://img.shields.io/badge/python-3.11-blue.svg
   :alt: Python

.. image:: https://img.shields.io/badge/platform-ESP32-orange.svg
   :alt: Platform

Quick Start
-----------

**1. Flash ESP32 Firmware**

.. code-block:: bash

   cd esp32-sensor-hub
   pio run --target upload --upload-port /dev/ttyUSB0

**2. Start BlueOS Extensions**

.. code-block:: bash

   # On Raspberry Pi (BlueOS)
   docker compose up -d

**Dashboards:**

- **Sensor Hub**: http://192.168.0.174:8099
- **Kogger Viewer**: http://192.168.0.174:8100

**3. Check Status**

.. code-block:: bash

   curl http://192.168.0.174:8099/api/status
   curl http://192.168.0.174:8100/api/status

System Architecture
-------------------

::

   ┌──────────────────────────────────────────────────┐
   │ ESP32-WROOM-32UE (Sensor Hub)                    │
   │ ┌──────────────────────────────────────────────┐ │
   │ │ Kogger A → UART1 GPIO 16/17 @ 921600         │ │
   │ │ Kogger B → UART2 GPIO 25/26 @ 921600         │ │
   │ │ GPS      → Soft  GPIO 27/14 @ 9600           │ │
   │ │ K1 EZO   → Soft  GPIO 19/18 @ 9600 [SWAPPED] │ │
   │ │ IMU HWT  → Soft  GPIO 13/15 @ 9600           │ │
   │ │ MS5837   → I2C 0x76 (depth/pressure)         │ │
   │ │ TSYS01   → I2C 0x77 (temperature)            │ │
   │ └────────────────┬─────────────────────────────┘ │
   └──────────────────┼───────────────────────────────┘
                      │ USB Serial @ 115200
                      ↓
   ┌──────────────────────────────────────────────────┐
   │ Raspberry Pi (BlueOS)                             │
   │ ┌──────────────────────────────────────────────┐ │
   │ │ blueos-extension (Docker)                    │ │
   │ │   ├─ HTTP :8099 (dashboard)                  │ │
   │ │   ├─ WS   :8766 (live data)                  │ │
   │ │   ├─ UDP  :14555 (Kogger A → KoggerApp)      │ │
   │ │   ├─ UDP  :14556 (Kogger B → KoggerApp)      │ │
   │ │   └─ MAVLink :14401 (→ ArduPilot)            │ │
   │ └──────────────────────────────────────────────┘ │
   │ ┌──────────────────────────────────────────────┐ │
   │ │ kogger-viewer (Docker)                       │ │
   │ │   ├─ HTTP :8100 (waterfall viewer)           │ │
   │ │   └─ WS   :8101 (live waterfall data)        │ │
   │ └──────────────────────────────────────────────┘ │
   └──────────────────────────────────────────────────┘

Hardware Components
-------------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Component
     - Model
     - Interface
     - Role
   * - MCU
     - ESP32-WROOM-32UE
     - USB Serial
     - Sensor hub
   * - Sonar A
     - Kogger Side-Scan
     - UART1 921600
     - Starboard imaging
   * - Sonar B
     - Kogger Side-Scan
     - UART2 921600
     - Port imaging
   * - GPS
     - u-blox
     - SoftSerial 9600
     - Surface position
   * - EZO EC
     - Atlas Scientific
     - SoftSerial 9600
     - Conductivity/salinity
   * - IMU
     - HWT905 (WitMotion)
     - SoftSerial 9600
     - 9-axis attitude
   * - Depth
     - MS5837-30BA
     - I2C 0x76
     - Pressure/depth
   * - Temp
     - TSYS01
     - I2C 0x77
     - High-precision temp

Table of Contents
-----------------

.. toctree::
   :maxdepth: 2
   :caption: Documentation

   architecture
   hardware
   api
   deployment
   troubleshooting

.. toctree::
   :maxdepth: 1
   :caption: Development

   contributing
   changelog

Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

License
-------

MIT License - Copyright (c) 2026 Baptiste Moulin / Flag Labs