lcaloi/adsb2mqtt-node repository overview

⁠ADSB2MQTT

ADSB2MQTT is an open source platform for onboarding ADS-B receiver nodes and relaying raw Beast TCP streams into a shared seed infrastructure.

The current architecture is intentionally simple: nodes do not decode ADS-B, do not run an embedded MQTT broker, and do not publish MQTT topics. A node validates its network identity, sends a heartbeat to the server, and forwards the local Beast TCP stream to the official seed on port 30010.

⁠Architecture

flowchart TD
    antenna["Antenna / SDR"] --> dump1090["dump1090 / readsb"]
    dump1090 -->|"Beast TCP"| node["adsb2mqtt-node"]
    node -->|"register / validate ID + token + email"| server["adsb2mqtt-server API"]
    node -->|"heartbeat"| server
    node -->|"raw Beast TCP relay"| seed["Seed Beast TCP :30010"]
    server --> sqlite["SQLite node registry"]
    server -->|"ACL/password sync"| mqtt["MQTT seed :4222"]
    server -->|"publish heartbeat/<MQTT_USERNAME>"| mqtt

⁠Components

• adsb2mqtt-node: validates onboarding identity, sends heartbeat, and relays BEASTHOST:BEASTPORT to ADSBDB_SEED_BEAST_URL.
• adsb2mqtt-server: issues and validates ADSBDB_NODE_ID / ADSBDB_TOKEN, requires a valid node email, stores identities in SQLite, publishes heartbeat events, and keeps MQTT ACL/password files synchronized.
• adsb2mqtt-broker: central Mosquitto image exposed as the public MQTT seed. Nodes do not publish MQTT data directly.

⁠Quick Start: Node

docker run -d \
  --name adsb2mqtt-node \
  --restart unless-stopped \
  -e ADSBDB_NODE_EMAIL="[email protected]" \
  -e BEASTHOST="192.168.68.103" \
  -e BEASTPORT="30005" \
  lcaloi/adsb2mqtt-node:latest

On first boot, if ADSBDB_NODE_ID and ADSBDB_TOKEN are empty, the node registers a new network identity and prints MQTT seed access details in the container logs:

============================================
 ADSB2MQTT SEED MQTT ACCESS
--------------------------------------------
 Use these credentials to connect
 consumers to the public MQTT seed.

 MQTT_URL
 mqtt://seed.adsbdb.com.br:4222

 MQTT_USERNAME
 node_uuid_with_underscores

 MQTT_PASSWORD
 token-issued-by-the-network

 MQTT_READ_TOPICS
 adsb2mqtt/#

 Example:
 mosquitto_sub -h seed.adsbdb.com.br -p 4222 -u node_uuid_with_underscores -P 'token-issued-by-the-network' -t 'adsb2mqtt/#' -v

 These MQTT access details will be sent to [email protected] by email when email delivery is enabled.
============================================

Keep ADSBDB_NODE_EMAIL, ADSBDB_NODE_ID, and ADSBDB_TOKEN in your .env or docker-compose.yml before recreating the container. MQTT_PASSWORD is the same value as ADSBDB_TOKEN; MQTT_USERNAME is derived from ADSBDB_NODE_ID using the format node_<uuid_with_underscores>. Email delivery is planned but not enabled yet.

⁠Node Configuration

⁠Server API

⁠POST /v1/nodes/register

Issues a new identity. A valid email is required.

{
  "join_token": "adsbdb-node-dev",
  "name": "receiver-hostname",
  "version": "dev",
  "email": "[email protected]"
}

⁠POST /v1/nodes/validate

Validates an existing node before the TCP relay starts.

{
  "node_id": "uuid-issued-by-the-network",
  "token": "token-issued-by-the-network",
  "email": "[email protected]",
  "name": "receiver-hostname",
  "version": "dev"
}

⁠POST /v1/nodes/heartbeat

Receives a node heartbeat and publishes it to the MQTT seed as:

heartbeat/<MQTT_USERNAME>

⁠MQTT

MQTT is preserved on the server side for ACL/password management, heartbeat visibility, and future consumers, but nodes no longer publish to MQTT.

The server generates Mosquitto credentials for registered nodes and keeps the ACL/password files synchronized. Node credentials are read-only for adsb2mqtt/# and their own heartbeat/<MQTT_USERNAME> topic. The MQTT admin user has unrestricted access with topic readwrite #. Credentials can later be sent to the node operator by email; email sending is not implemented yet.