Skip to content

v1.0.0

Choose a tag to compare

View all tags
@446564 446564 released this 08 Jun 23:16
v1.0.0
d5ebe0e
This commit was signed with the committer’s verified signature.
446564 Ded
GPG key ID: 2FE5B19B03656304
Verified
Learn about vigilant mode.

v1.0.0

This is the first public release of Beacon, a MeshCore network observation backend built by MeshCore Canada.

What is Beacon

Beacon connects to one or more MeshCore MQTT brokers, ingests LoRa packet traffic in real time, stores it in PostgreSQL, and serves it via a REST API and WebSocket stream. It is designed to be the data backbone for MeshCore network monitoring frontends and tools.

Features

Packet ingestion and storage

  • Subscribes to multiple MeshCore MQTT brokers simultaneously
  • Decodes all MeshCore packet types using meshcore-go
  • Deduplicates observations across brokers — the same packet heard by multiple brokers produces one observation per observer
  • Stores packets, observations, nodes, observers, traces, known routes, neighbors, and channel messages in PostgreSQL
  • Configurable retention for packets and telemetry

Node and observer tracking

  • Upserts nodes from advert payloads with name, type, location, and radio settings
  • Tracks observers from /status messages including hardware model, firmware version, battery level, uptime, and radio configuration
  • Detects multibyte path and trace firmware capability from path hash sizes
  • Records node neighbors from forwarded adverts
  • Builds and maintains known routes — fully resolved multi-hop paths where all nodes are identified with high confidence
  • Observer telemetry snapshots with configurable resolution and bucketed query support (1h, 6h, 24h intervals)

Channel messages

  • Decrypts group text messages for configured channel keys
  • Supports hashtag-derived PSKs (SHA256("#tag")[:16]) and explicit hex keys
  • Records channel hash observations even for unknown channels

Transport scopes

  • Matches TRANSPORT_FLOOD and TRANSPORT_DIRECT packets to configured scope keys
  • Tags nodes and observers with their default scope
  • Scope-filtered queries across packets, nodes, observers, channels, and traces

Geographic filtering

  • Optional ingest filter by country or continent using a compiled-in IATA → country/continent database sourced from OurAirports
  • Regions group IATAs for display and filtering

REST API

  • Full paginated REST API with cursor-based pagination across all resources
  • Endpoints for packets, observations, nodes, observers, channels, messages, traces, routes, regions, IATAs, scopes, and stats
  • Cross-IATA route search
  • Observer telemetry with bucketed aggregation
  • Swagger UI at /swagger/index.html

WebSocket

  • Real-time event stream with per-connection subscription filtering by IATA, region slug, region ID, payload type, channel hash, and event type
  • Events: packetObservation, observerStatus, nodeUpdate, channelMessage
  • Backpressure handling with lagged notifications and REST backfill support
  • Per-IP connection limits

Path resolution

  • Resolves path hash prefixes to node UUIDs using node_short_ids
  • Confidence levels: high (unambiguous), ambiguous (hash collision), none (unknown)
  • Resolved hop nodes included in packet observations, traces, and known routes

Project

  • AGPL-3.0-or-later license
  • Contributor Covenant code of conduct
  • Full contributing guide including database change, API change, and testing requirements
  • GitHub Actions CI with build, format, vet, test, and swagger doc checks
  • Docker image published to GitHub Container Registry on every push to main and dev
Assets 2
Loading