Deployment Guide
================

Prerequisites
-------------

- Raspberry Pi 4 with BlueOS installed
- ESP32-WROOM-32UE DevKit-C v4
- PlatformIO CLI or VSCode with PlatformIO extension
- Docker (included in BlueOS)
- Git

ESP32 Firmware Deployment
-------------------------

1. Install PlatformIO
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   # Option A: CLI
   curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -o get-platformio.py
   python3 get-platformio.py

   # Option B: VSCode extension
   # Install "PlatformIO IDE" extension

2. Flash Firmware
^^^^^^^^^^^^^^^^^

.. code-block:: bash

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

**Troubleshooting flash:**

- If port not found: ``ls /dev/tty*`` and check USB connection
- If permission denied: ``sudo usermod -a -G dialout $USER`` (logout/login)
- If ESP32 not detected: Hold BOOT button while connecting USB

3. Verify Serial Output
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   pio device monitor --baud 115200

Expected output::

   [SERIAL] Opening /dev/ttyUSB0 @ 115200...
   [MS5837] OK C1=46372 C2=42768
   [TSYS01] OK k0=63258
   [IMU] HWT905 ready
   [KOGGER] A: UART1 ready
   [KOGGER] B: UART2 ready

Docker Services Deployment
---------------------------

1. Clone Repository
^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   ssh pi@192.168.0.174
   cd /home/workspace
   git clone ssh://git@192.168.0.82:10022/floppyrj45/bluerov-slam.git slam

2. Build Docker Images
^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   cd slam/blueos-extension
   docker build -t bluerov-slam-hub:latest .

   cd ../kogger-viewer
   docker build -t bluerov-kogger-viewer:latest .

3. Create docker-compose.yml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create ``/home/workspace/slam/docker-compose.yml``:

.. code-block:: yaml

   version: "3.8"

   services:
     slam-hub:
       image: bluerov-slam-hub:latest
       container_name: slam-hub
       restart: unless-stopped
       network_mode: host
       privileged: true
       environment:
         - SERIAL_PORT=/dev/ttyUSB0
         - BAUD=115200
         - WS_PORT=8766
         - HTTP_PORT=8099
         - MAVLINK_ENABLED=1
         - MAVLINK_TARGET=192.168.2.2
         - MAVLINK_PORT=14401
       devices:
         - /dev:/dev
       volumes:
         - /usr/blueos/extensions/slam-hub:/app/logs

     kogger-viewer:
       image: bluerov-kogger-viewer:latest
       container_name: kogger-viewer
       restart: unless-stopped
       network_mode: host
       environment:
         - HTTP_PORT=8100
         - WS_PORT=8101
         - UDP_PORT_A=14555
         - UDP_PORT_B=14556

4. Start Services
^^^^^^^^^^^^^^^^^

.. code-block:: bash

   docker compose up -d

5. Check Status
^^^^^^^^^^^^^^^

.. code-block:: bash

   docker compose ps
   docker compose logs -f slam-hub
   docker compose logs -f kogger-viewer

   # API health checks
   curl http://localhost:8099/health
   curl http://localhost:8100/health

Rebuild & Update
----------------

Update Code
^^^^^^^^^^^

.. code-block:: bash

   cd /home/workspace/slam
   git pull origin master

Rebuild Images
^^^^^^^^^^^^^^

.. code-block:: bash

   docker compose down
   docker compose build --no-cache
   docker compose up -d

Rebuild ESP32 Only
^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   cd esp32-sensor-hub
   pio run --target upload

View Logs
---------

Docker Logs
^^^^^^^^^^^

.. code-block:: bash

   # Real-time logs
   docker compose logs -f slam-hub
   docker compose logs -f kogger-viewer

   # Last 100 lines
   docker compose logs --tail=100 slam-hub

JSONL Session Logs
^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   # On Pi
   ls -lh /usr/blueos/extensions/slam-hub/

   # View latest session
   tail -f /usr/blueos/extensions/slam-hub/session_*.jsonl | jq

Serial Monitor (ESP32)
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   pio device monitor --baud 115200

Monitoring & Health Checks
---------------------------

Service Status
^^^^^^^^^^^^^^

.. code-block:: bash

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

Expected healthy output::

   {
     "frames": 12345,
     "serial_connected": true,
     "ws_port": 8766,
     "crc_errors": 0
   }

WebSocket Test
^^^^^^^^^^^^^^

.. code-block:: bash

   # Install websocat
   cargo install websocat

   # Listen to sensor frames
   websocat ws://192.168.0.174:8766

   # Listen to waterfall pings
   websocat ws://192.168.0.174:8101

Automatic Startup
-----------------

BlueOS Extension (Recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1. Register as BlueOS extension (UI or manifest)
2. Auto-starts on boot via BlueOS extension manager

Systemd Service (Alternative)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create ``/etc/systemd/system/slam.service``:

.. code-block:: ini

   [Unit]
   Description=BlueROV SLAM Services
   After=docker.service
   Requires=docker.service

   [Service]
   Type=oneshot
   RemainAfterExit=yes
   WorkingDirectory=/home/workspace/slam
   ExecStart=/usr/bin/docker compose up -d
   ExecStop=/usr/bin/docker compose down

   [Install]
   WantedBy=multi-user.target

Enable:

.. code-block:: bash

   sudo systemctl daemon-reload
   sudo systemctl enable slam.service
   sudo systemctl start slam.service

Production Checklist
--------------------

Before Deployment
^^^^^^^^^^^^^^^^^

- [ ] ESP32 firmware flashed and tested
- [ ] Serial port permissions configured (``/dev/ttyUSB0`` accessible)
- [ ] Docker images built successfully
- [ ] Health endpoints return ``200 OK``
- [ ] WebSocket connections stable
- [ ] Sensor data flowing (check ``/api/latest``)
- [ ] Kogger sonars powered and detected
- [ ] MAVLink bridge tested (if enabled)

Post-Deployment
^^^^^^^^^^^^^^^

- [ ] Monitor logs for errors (first 10 minutes)
- [ ] Verify waterfall display renders correctly
- [ ] Check JSONL log file creation
- [ ] Test auto-restart (``docker compose restart``)
- [ ] Document any custom configuration
- [ ] Backup configuration files to Git

Backup & Restore
----------------

Backup Configuration
^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   cd /home/workspace/slam
   tar czf slam-backup-$(date +%Y%m%d).tar.gz \
       docker-compose.yml \
       blueos-extension/ \
       kogger-viewer/ \
       esp32-sensor-hub/

Restore from Backup
^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   tar xzf slam-backup-20260327.tar.gz
   cd slam
   docker compose up -d