⚓ BoatOS

GitHub Sponsors Patreon

Modern Marine Navigation System — Open Source, Touch-Optimized, Offline-First

A complete marine navigation system for inland waterways and coastal navigation. Built for Raspberry Pi with touchscreen, runs completely offline, no subscriptions, no cloud lock-in.

No Linux, no terminal, no config files needed.

The BoatOS MBTiles Creator is a standalone Windows app that downloads, converts, and uploads offline map tiles directly to your BoatOS Pi — one click per region.

What it does:

• Downloads OSM map data for any region (60+ countries and states pre-configured)
• Converts to .mbtiles using tilemaker (downloaded automatically on first run)
• Uploads the finished file directly to your Pi via WiFi — no USB stick, no SSH

Supported regions include: Germany (all 16 states), Netherlands, Belgium, France, Switzerland, Austria, Norway, Sweden, Denmark, Great Britain, Ireland, USA (state-level), Canada, and more.

→ Source & instructions: tools/mbtiles-creator/
→ Detailed docs: docs/tileserver.md

PCBWay sponsors the PCB manufacturing for BoatOpenIO, the sensor gateway of this ecosystem — thank you!

👉 Order the boards directly: PCBWay shared project

License Platform Python Flutter Status

No touchscreen required. BoatOS runs fully through Deck, the browser-based web frontend — accessible from any phone, tablet, or laptop on the same network. The touchscreen with Helm is optional and turns the setup into a full helm station.

• 🗺️ Two UIs — Deck (browser-based web frontend) + Helm (native Flutter app, flutter-pi)
• 🧭 Inland waterway routing — OSRM-optimized for rivers, canals & locks
• 📡 Live AIS — Real-time vessel traffic (Europe) via AISStream.io
• ⚠️ Weather & alerts — DWD API with severe weather warnings
• 📖 Digital logbook — GPS tracks, crew, water levels, export
• 🔌 Sensor dashboard — MQTT integration, DSL-configurable layout, animated gauges
• 🛰️ Satellite maps — ESRI World Imagery with offline caching
• 👆 Touch-optimized — Large targets, no 300ms delay, perfect for on-the-water use

Demos: Check Instagram @bigbrainlabs

┌──────────────────────────────────────────────────────────────────┐
│ Raspberry Pi 4 │
│ │
│ ┌──────────────────────┐ ┌──────────────────────────────┐ │
│ │ Deck Web Frontend │ │ Helm Flutter App (flutter-pi) │ │
│ │ (Nginx + HTTPS) │ │ Native Kiosk, lightdm │ │
│ └──────────┬───────────┘ └──────────────┬───────────────┘ │
│ │ HTTP/WS │ HTTP/WS │
│ └─────────────┬─────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ BoatOS Backend │ FastAPI, Port 8000 │
│ │ (main.py) │ WebSocket, REST API │
│ └────┬──────┬─────┘ │
│ │ │ │
│ ┌────────────┘ └──────────────┐ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ Mosquitto │◄── ESP32/Sensors │ SignalK │ │
│ │ MQTT │ (boot/+) │ Port 3000 │ │
│ │ Port 1883 │ │ GPS + NMEA │ │
│ └─────────────┘ └────────┬────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ GPS Receiver │ │
│ │ /dev/ttyUSB0 │ │
│ └─────────────────┘ │
│ │
│ ┌────────────────────────────┐ │
│ │ Martin Tile Server │ Port 8081, local vector maps │
│ │ OSRM Routing Server │ Port 5000, inland waterways │
│ └────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘

• Vector nautical charts — OpenMapTiles via Martin (local, offline), Deck Light style
• Sea marks — OpenSeaMap overlay
• Satellite maps — ESRI World Imagery with passive + active offline caching (SW/Cache API)
• AIS — Live vessel traffic via AISStream.io, filtered to Europe bounding box
• Lock database — OSM-based, 300m deduplication, VHF/hours/dimensions
• Water level data — PEGELONLINE API, live water levels on the map
• Auto-follow — EMA-filtered GPS, smooth marker animation (α=0.35, ~4s ease-out)
• Routing — OSRM waterway routing, drag-and-drop waypoints, save/load routes
• Route simulation — ×ばつ1000 speed, speed slider, GPS blocked during simulation
• Navigation — Bearing & distance to next waypoint, automatic advance

• DSL layout — Text-based configuration (GRID, GAUGE, SENSOR, ROW)
• Gauge styles — arc180, arc270, arc360, bar — all with animated needle (500ms ease-out)
• SensorCards — card, hero, compact — with SHOW/HIDE filter, status LED
• MQTT data — all sensor topics auto-discovered, string values correctly parsed
• Visual Editor (Deck) — Drag & drop, undo/redo, bi-directional DSL sync

• GPS track recording — Start/stop, pause, water levels per track point
• Crew management — Emoji avatars, roles (Skipper/Crew/Guest), contact details
• Archive — All trips with detail view: stats, track on map, weather, water levels, sensors
• Water level tracking — Nearby stations recorded every 15 min
• Logbook entries — Manual & automatic (trip start/end with weather snapshot)

• Auto-discovery — All MQTT topics automatically detected and stored
• Persistent topics — known_topics.json — sensor data survives restarts
• MQTT auto-reconnect — loop_forever() thread with 5s retry — survives broker restarts
• GPS synthetic sensors — Altitude, HDOP, satellites as dashboard sensors
• SignalK bridge — GPS & navigation data via SignalK, configurable in settings

• DWD integration — German Weather Service, automatically follows boat position
• Severe weather alerts — Live alerts with severity level, displayed on map
• Water level data — PEGELONLINE, tracked during trips for shallow-water analysis

Both UIs share the same backend and REST/WebSocket API.

• FastAPI — High-performance Python API
• paho-mqtt — MQTT client with auto-reconnect
• SignalK — Marine data server (GPS)
• uvicorn — ASGI server

• Vanilla JavaScript — ES Modules, no framework bloat
• MapLibre GL JS v4.7.1 — Vector maps (local)
• WebSocket — Real-time GPS & sensor data
• Service Worker — Offline caching (maps, satellite tiles)

• Flutter 3.x + flutter-pi — Native ARM64 AOT build
• flutter_map — Interactive maps
• vector_map_tiles — Vector tiles from local Martin
• provider — State management
• web_socket_channel — WebSocket connection to backend

• Nginx — Reverse proxy & SSL (Deck)
• Martin — Vector tile server (Port 8081)
• OSRM — Routing engine (Port 5000, IPv4-only)
• Mosquitto — MQTT broker (Port 1883)
• Raspberry Pi 4 — Hardware platform

• OpenSeaMap — Sea marks overlay
• OpenStreetMap / OMT — Vector maps & routing
• ESRI World Imagery — Satellite maps
• DWD API — German Weather Service
• PEGELONLINE — Water level data
• AISStream.io — Live AIS vessel data
• SignalK — Marine data standard

• Raspberry Pi 4 (min. 2 GB RAM, 4 GB recommended)
• GPS receiver — USB, e.g. BU-353N5 (/dev/ttyUSB0, 4800 baud)
• Touchscreen — e.g. QDtech MPI1001 10.1" (×ばつ800)
• SD card — Min. 32 GB
• Optional — ESP32/Arduino sensor board via MQTT

• Raspberry Pi OS Bookworm (64-bit)
• Python 3.9+
• Node.js (for SignalK)
• Flutter SDK + flutter-pi (only needed for Helm build)

The fastest setup — just flash and go:

1. Download image (v1.9.0): boatos_v1.9.0.img.gz (~8.8 GB)
2. Open balenaEtcher or Raspberry Pi Imager → select custom image
3. Flash → boot Pi → Helm starts automatically

Minimum 32 GB SD card or USB SSD. Partition is automatically expanded to full size on first boot.

git clone https://github.com/bigbrainlabs/BoatOS.git
cd BoatOS
chmod +x install.sh
./install.sh

https://<pi-ip>/

# On the development PC (Flutter SDK + flutterpi_tool required):
cd flutter_app
flutterpi_tool build --arch=arm64 --cpu=pi4 --release
# Deploy to Pi:
scp build/flutter-pi/aarch64-generic/app.so boatos@<pi-ip>:/home/boatos/BoatOS/flutter_app/app.so
ssh boatos@<pi-ip> "sudo systemctl restart lightdm"

Full instructions: docs/installation.md

BoatOS/
├── backend/ # FastAPI backend
│ ├── app/
│ │ ├── main.py # Main API, WebSocket, MQTT
│ │ ├── gps_service.py # GPS via SignalK
│ │ ├── logbook_storage.py # Logbook & tracks
│ │ ├── locks_storage.py # Lock database
│ │ ├── crew_management.py # Crew CRUD
│ │ ├── pegelonline.py # Water level data
│ │ ├── ais_service.py # AIS via AISStream
│ │ └── ...
│ └── requirements.txt
├── frontend/ # Deck web frontend
│ ├── index.html
│ ├── js/
│ │ ├── main.js # ES module entry
│ │ ├── map.js # Map, markers, GPS smoothing
│ │ ├── navigation.js # Routing & simulation
│ │ ├── logbook.js # Logbook & crew
│ │ ├── sensors.js # GPS fallbacks
│ │ ├── ais.js # AIS vessels
│ │ └── ...
│ ├── css/
│ └── sw.js # Service worker (offline caching)
├── flutter_app/ # Helm native Flutter app
│ ├── lib/
│ │ ├── main.dart
│ │ ├── screens/
│ │ │ ├── map_screen.dart # Map, GPS, routing, simulation
│ │ │ ├── dashboard_screen.dart # DSL dashboard, gauges
│ │ │ ├── logbook_screen.dart # Logbook, crew, archive
│ │ │ └── settings_screen.dart
│ │ ├── widgets/
│ │ │ ├── gauge_widget.dart # Animated gauges
│ │ │ └── route_planner.dart # Waypoints, route panel
│ │ └── services/
│ │ ├── websocket_service.dart
│ │ ├── settings_service.dart
│ │ └── logbook_service.dart
│ ├── assets/fonts/NotoColorEmoji.ttf
│ └── pubspec.yaml
├── data/ # Runtime data (not in repo)
│ ├── settings.json
│ ├── known_topics.json
│ └── crew.json
├── docs/
├── scripts/
├── DASHBOARD_DSL.md
└── README.md

BoatOS uses its own Domain Specific Language for dashboards:

GRID 4
ROW main
GAUGE boot/sensoren/motor/drehzahl MAX 6000 UNIT "RPM" DECIMALS 0
GAUGE boot/sensoren/motor/oeldruck MAX 7 UNIT "Bar" STYLE bar DECIMALS 2
SENSOR boot/sensoren/batterie STYLE hero
SENSOR boot/sensoren/lage SIZE 2 STYLE hero
SENSOR boot/sensoren/tank/diesel SIZE 2

Gauge styles: arc180, arc270 (default), arc360, bar
Sensor styles: card (default), hero, compact

Documentation: DASHBOARD_DSL.md

Full documentation: http://<pi-ip>:8000/docs

cd backend
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# No build needed — edit files directly
# Browser: https://localhost/ (kiosk) or https://<pi-ip>/

cd flutter_app
# Build for Pi 4 (ARM64)
flutterpi_tool build --arch=arm64 --cpu=pi4 --release
# Deploy
scp build/flutter-pi/aarch64-generic/app.so boatos@<pi-ip>:/home/boatos/BoatOS/flutter_app/app.so
ssh boatos@<pi-ip> "sudo systemctl restart lightdm"

# Follow all topics live
mosquitto_sub -h localhost -t '#' -v
# Send test data
mosquitto_pub -h <pi-ip> -t 'boot/sensoren/motor/drehzahl' -m '2500'

• GPS integration (SignalK, USB, phone fallback)
• Interactive vector maps (MapLibre / flutter_map, local)
• Waterway routing (OSRM)
• AIS live vessel traffic
• Weather alerts (DWD)
• Digital logbook with crew & water level tracking
• Dashboard DSL + visual editor (Deck)
• Animated gauge widgets (Helm)
• Lock database (OSM)
• Satellite maps + offline caching
• Route simulation
• Smooth GPS marker (EMA + interpolation)
• MQTT auto-reconnect

• Helm feature parity with Deck
• (削除) Distributable Pi image (削除ここまで) ✅ Ready-to-flash image available

• Anchor alarm with geofencing
• Tide predictions (BSH API)
• GPX import/export
• AIS target CPA calculation
• MOB (Man Over Board) alert

Pull requests are welcome!

1. Fork → branch → commit → PR
2. Code style: PEP8 (Python), standard JS / Dart
3. Commit messages: Conventional Commits
4. Please test on real Pi hardware

sudo systemctl status boatos
sudo journalctl -u boatos -f

ls -la /dev/ttyUSB* /dev/ttyACM*
curl http://localhost:3000/signalk/v1/api/vessels/self/navigation/position
sudo systemctl status signalk

sudo systemctl status mosquitto
mosquitto_sub -h localhost -t '#' -v
# Backend status:
curl http://localhost:8000/api/mqtt/topics

sudo systemctl status lightdm
# Logs:
sudo journalctl -u lightdm -f

More: docs/installation.md

BoatOS is open source and licensed under the GNU General Public License v3.0 .

This means: you can freely use, study, and modify the code. Derivatives must also be released under GPL v3.

• 📖 Book on Amazon (🇩🇪): Logbuch ohne Pose — Deutsch
• 📖 Book on Amazon (🇬🇧): Logbuch ohne Pose — English

If you want to support the project: read the book, leave a review — that helps more than you'd think and motivates me to keep going. I appreciate every piece of feedback! 🙏

• Development: bigbrainlabs
• AI pair programming: Claude Code (Anthropic)
• Maps: OpenSeaMap, OpenStreetMap, ESRI
• Data: DWD, PEGELONLINE, AISStream.io
• Libraries: FastAPI, flutter_map, MapLibre GL, SignalK, OSRM

• 🌐 Open Boat Projects: open-boat-projects.org/de/boatos
• 📦 GitHub: github.com/bigbrainlabs/BoatOS
• 🛒 Order BoatOpenIO boards (PCBWay): shared project
• 📖 Book (🇩🇪): Logbuch ohne Pose — Deutsch
• 📖 Book (🇬🇧): Logbuch ohne Pose — English