Skip to content

Gateways and connectivity

Gateways are separate objects from devices (architecture 20, decision D66). The registry is server level: one row per (data source, provider gateway id) with a name, location, state, last seen, the platform's latest counters and provider diagnostics as attributes. A project sees every gateway of the data sources its devices have an identity on, whether or not that gateway heard one of them (decision D175, ADR 0027); the all-projects scope sees the whole registry.

Where rows come from

  • Receptions: every uplink's gateway list (gateway_receptions) registers the gateway, marks it online and records the reception's location when the platform sends one.
  • Gateway events: the ChirpStack adapter subscribes to gateway/+/event/stats (counters and location) and gateway/+/state/conn (online, offline). They are stored as source events without a device and update the registry; nothing is published on the bus.
  • Gateway Mesh relays (ChirpStack 4.9 and later, decision D237): a relay gateway has no backhaul; its uplinks reach ChirpStack through a border gateway and are credited to that one, so a relay never has receptions of its own, and ChirpStack learns of it from the heartbeat it sends every stats interval. The sync reads the tenant's relay gateways with the ordinary ones and keeps them in the registry marked kind: relay (the 4-byte relay id as the external id, state, last seen, region), so the Gateways page and the map show them beside the border gateways with a "Relay (mesh)" mark; a person can set a relay's location like any gateway's. The relay path (which relay hears which, with the signal per hop) is only in the heartbeat on ChirpStack's MQTT broker, not in the API; reading it waits for a source whose broker is reachable (decision D238).
  • Sync: the ingest service reads every listing adapter's gateway list through the adapter's management connector (names, descriptions, locations, states) two minutes after start and every 24 hours after that, per data source with its API channel switched on, logging and skipping a source that fails (decision D176); Server admin, Data sources, Sync gateways does the same read immediately for one source. Public networks without a gateway API (KPN, Netmore, akenza) only ever show what receptions reveal.

Administrators can override the name and location of a gateway under PATCH /admin/gateways/{id}. A project admin places a gateway the network gave no location for (a Gateway Mesh relay, a gateway on a network without a gateway API), or corrects one, from the gateway's dialog on the Gateways page or its panel on the live map (decision D239): type the coordinates, click the small map, or take the browser's position while standing at the gateway; PATCH /projects/{id}/gateways/{gateway_id}/location, both coordinates empty clearing a location set by hand. A location set by a person is kept over the platform's.

Screens

Network, Gateways lists every gateway of the project's data sources: the ones that heard the project's devices in the window busiest first with state, source, receptions, devices, mean RSSI and SNR, last reception and location, then the ones that heard nothing, most recently seen first; a source filter narrows the list to one network and the footer says how many heard nothing in the window. The detail shows the platform counters, links to the platform (when the data source has a gateway link template), diagnostics and the devices heard.

Device connectivity lists every device with the number of gateways that heard it, the best gateway and its share of the device's uplinks, mean signal and last reception, least covered first. A device heard by one gateway only is at risk: when that gateway fails, the device is silent. Network health and device health stay distinct: a device can be healthy but poorly connected, or connected well while reporting internal faults.

Where a gateway's position comes from

The registry keeps one position per gateway with its source and time. A platform's gateway list or gateway event places it (platform); coordinates that a platform sends on an uplink for the receiving gateway place it as well (reception; ChirpStack, The Things Stack and LORIOT send them per gateway, KPN's ThingPark for the best receiving gateway only); a position set by an administrator on the gateway (admin) is kept whatever the platform sends afterwards. Every reception keeps the platform's gateway fields as they came, so nothing is lost for a later network map or coverage analysis.

Coverage

The live map's Coverage tab (decision D107) shows where the project's collars were heard. Every position is joined to the receptions of the same uplink, so a heard position carries the best RSSI among the gateways that heard it. Switch on "Heard positions", pick a period (a day to 90 days) and, if wanted, untick gateways to see the footprint of the rest. The positions show as dots coloured from red (weak, about -120 dBm) to green (strong, -80 dBm and better) at every zoom, the newest ten thousand in view when there are more (decision D123; the hexagon aggregation stays available to API users). Each gateway row shows how many heard positions it received and its share of all heard positions in view. The layer shows only where trackers were: a blank area may still have coverage. Positions that reached the platform without a LoRaWAN reception, such as a Bluetooth log, are not part of it.

API

GET /projects/{id}/gateways?hours=, GET /projects/{id}/gateways/{gateway_id}, GET /projects/{id}/connectivity?hours=, GET /admin/gateways, PATCH /admin/gateways/{id}, POST /data-sources/{id}/sync-gateways. - GET /projects/{id}/coverage?bbox=&zoom=&hours=&gateway_id=: heard positions in the window and viewport as points (the newest 10,000) or, with mode=hexagons, as hexagons, with the share per gateway.