mirror of
https://github.com/MeshCore-Beacon/beacon-docs.git
synced 2026-10-23 05:21:17 +00:00
MrAlders0n
f2728b059b
* docs: move design and API contract into docs/ * docs: add releases and versioning page * docs: add configuration reference for server and web * docs: add reverse proxy page * docs: add upgrading page * docs: add operations page and move backup and profiling docs * docs: add getting packets in and security pages * docs: add troubleshooting page * docs(api): fold admin, activity, route and summary notes into the contract * docs(deploy): add type 2 split deployment, finish the beacon rename, ignore secrets * docs: rewrite README as the front door and share the contributor workflow * docs: remove em dashes from prose and config comments * docs: apply review fixes to type 2, upgrading, troubleshooting and first-run notes * docs: fix upgrade order, restore steps, type 2 setup and contract details from review * docs: keep the gitignore to deployment secrets and runtime state
63 lines
3.2 KiB
Markdown
63 lines
3.2 KiB
Markdown
# Getting packets into Beacon
|
|
|
|
Beacon does not listen to the radio. It subscribes to one or two MeshCore MQTT brokers that
|
|
observers publish into, and stores what it hears. No broker, no data.
|
|
|
|
## How packets reach Beacon
|
|
|
|
An observer is a MeshCore device, or a bridge next to one, with a network link. It hears a LoRa
|
|
packet, notes the signal strength, and publishes it to a broker under its own IATA (airport
|
|
code) and public key. Beacon connects to the broker over secure WebSocket MQTT, decodes each
|
|
packet, works out whether it has already seen it through another observer or broker, stores it,
|
|
and streams it to anyone connected to the web app.
|
|
|
|
Two brokers can be configured. A packet heard by observers on both is stored once, with one
|
|
observation per observer.
|
|
|
|
## Which broker
|
|
|
|
- **Use an existing community broker.** The MeshCore Canada brokers (`mqtt1.meshcore.ca` and
|
|
`mqtt2.meshcore.ca`) feed the public Beacon instances. Ask on the
|
|
[MeshCore Canada Discord](https://discord.gg/Gz3KvJx2hf) for a subscriber account.
|
|
- **Run your own** with [meshcore-mqtt-broker](https://github.com/michaelhart/meshcore-mqtt-broker)
|
|
and point your observers at it. Beacon only needs a subscriber account on it.
|
|
|
|
## The account Beacon needs
|
|
|
|
The broker defines three subscriber roles:
|
|
|
|
| Role | Sees | Notes |
|
|
|---|---|---|
|
|
| 1, admin | Everything, including `/internal` topics and `$SYS` | Carries observer owners' personal data. Beacon does not need it. |
|
|
| 2, full | All public topics, nothing stripped | **This is the one Beacon needs.** |
|
|
| 3, limited | Public topics with `snr`, `rssi`, `score`, `stats`, `model` and `firmware_version` removed | Not enough: Beacon stores SNR and RSSI per observation. |
|
|
|
|
Ask the broker operator for a Role 2 subscriber username and password. Put them in
|
|
`MQTT_BROKER_1_USERNAME` and `MQTT_BROKER_1_PASSWORD` (and `_2_` for a second broker), and the
|
|
broker's WebSocket endpoint in `MQTT_BROKER_1_URL`, for example `wss://mqtt1.example.com:443`.
|
|
See [Configuration](configuration.md#server-environment-variables).
|
|
|
|
## Topics
|
|
|
|
Observers publish under `meshcore/{IATA}/{observer public key}/`:
|
|
|
|
| Subtopic | Contents | What Beacon does with it |
|
|
|---|---|---|
|
|
| `packets` | Raw LoRa packets with SNR and RSSI | Decode, dedupe, store, stream |
|
|
| `status` | Observer health, position and firmware | Update the observer record |
|
|
| `neighbors` | The observer's neighbour list | Update neighbour links |
|
|
| `internal` | Owner details from the broker login | Ignored. A Role 2 account is not sent it anyway. |
|
|
|
|
Beacon subscribes to `meshcore/#` and routes by subtopic. The IATA in the topic is where the
|
|
observer says it is. Beacon creates an IATA the first time it sees one; `iatas:` in
|
|
`config.yaml` only adds a name, coordinates and an optional border.
|
|
|
|
## Checking it works
|
|
|
|
- `GET /api/v1/brokers` shows each broker and whether it is connected.
|
|
- `docker compose logs -f app` shows a `connected` line per broker. Packets are not logged at
|
|
the default level, so do not wait for them there.
|
|
- `GET /api/v1/observers` fills in as observers publish.
|
|
- Within a few minutes the web app's Packets tab should be moving. If it is not, see
|
|
[Troubleshooting](troubleshooting.md#no-packets-are-arriving).
|