LoRaWAN
The LoRaWAN page manages LoRaWAN gateways and sensor devices for long-range, low-power wireless communication with IoT sensors such as temperature probes, door contacts, and environmental monitors.
Tabs
The page has three tabs: Gateways, Devices, and Traffic.
Gateways Tab
The Gateways tab lets you create and manage LoRaWAN gateway devices. Gateways receive radio transmissions from LoRa sensors and forward them to GEM.
Gateway Table
The table lists all configured gateways with the following columns:
| Column | Description |
|---|---|
| Name | The gateway name. |
| UDP Port | The UDP port the gateway uses for the packet forwarder protocol (default: 1700). |
| Forwarder | Shows "Managed" if a binary path is configured (GEM manages the packet forwarder process), or "External" if left empty (you run the forwarder separately). |
| Status | Connection status badge: Connected (green) or Disconnected (red). |
Each row has these action buttons:
| Button | Description |
|---|---|
| Edit | Opens the gateway form pre-filled with this gateway's settings. |
| Reload | Restarts the gateway device driver. |
| Delete | Removes the gateway and all its sensor zones (with confirmation). |
Click New Gateway to add a new gateway.
Gateway Form
The gateway form has the following fields:
| Field | Description |
|---|---|
| Name | Required. The gateway name (used as the device name in GEM). |
| UDP Port | The UDP port for the packet forwarder protocol. Default: 1700. |
Packet Forwarder Section
| Field | Description |
|---|---|
| Binary Path | Path to the lora_pkt_fwd binary on the GEM server. Leave empty if you run the packet forwarder externally. |
| Compile / Recompile | Clones and compiles the sx1302_hal packet forwarder from source. This may take several minutes. On success, the binary path and gateway EUI are populated automatically. |
| Gateway EUI | 16 hex character unique gateway identifier (e.g., AA555A0000000000). May be auto-detected during compilation. |
The following fields appear only when a Binary Path is configured (managed mode):
| Field | Description |
|---|---|
| Com Type | Connection type to the LoRa concentrator: USB or SPI. Changing this updates the Com Path default. |
| Com Path | Device path for the concentrator. Default: /dev/ttyACM0 for USB, /dev/spidev0.0 for SPI. When Com Type is USB, the gateway driver promotes this to a stable /dev/serial/by-id/... symlink at start-up so the dongle survives replug/reboot reordering. Set the usb_auto_discover device attribute to false to disable that promotion (recommended only on hosts running multiple identical concentrators). |
| Frequency Plan | Regional frequency plan: US915, EU868, AU915, AS923, or IN865. |
| Reset GPIO | GPIO pin number for the SPI concentrator reset line. Only shown when Com Type is SPI. |
Click Save to create or update the gateway. Click Cancel to close the form.
Devices Tab
The Devices tab manages LoRa sensor nodes. Each sensor is represented as a GEM zone belonging to a gateway.
Gateway Selector
Select a gateway from the dropdown to view and manage its sensors. If only one gateway exists, it is selected automatically.
Sensor Table
The table lists all sensor zones for the selected gateway:
| Column | Description |
|---|---|
| Label | The sensor display name. |
| DevAddr | The 4-byte hex device address (shown in monospace). For OTAA sensors this is the current session DevAddr (rotates on every Join); for ABP sensors it is the static DevAddr programmed into the sensor. |
| Mode | Activation mode: OTAA (green badge when joined, gray when not yet joined) or ABP. |
| Status | Online (green), Offline (red), or No data (gray). A sensor is considered offline if no uplink has been received within its offline threshold (default: 24 hours). Set the offline_threshold attribute on a zone (in seconds) to override the default per sensor. |
| Battery | Battery level if reported by the sensor. Shows percentage or voltage with color coding: green (good), yellow (low), red (critical). |
| Last Uplink | Time since the last received packet (e.g., "5m ago", "2h ago"). Hover to see the full timestamp. |
| RSSI | Signal strength of the last received packet. |
Each row has these action buttons:
| Button | Description |
|---|---|
| Edit | Opens the sensor form pre-filled with this sensor's settings. |
| Duplicate | Creates a new sensor form pre-filled with the same subsystem and payload decoder, but generates new random keys and clears the name. |
| Delete | Removes the sensor zone (with confirmation). |
Click New Sensor to add a new sensor.
Sensor Form
| Field | Description |
|---|---|
| Name | Required. Lowercase zone name (e.g., temp_sensor_1). |
| Label | Display name (e.g., Temperature Sensor 1). |
| Subsystem | The GEM subsystem this sensor belongs to (e.g., climate, security). |
Activation
GEM supports both LoRaWAN activation modes. Select the mode that matches how the physical sensor is configured:
- ABP (Activation By Personalization) — session keys and DevAddr are pre-programmed on the sensor and entered into GEM.
- OTAA (Over-The-Air Activation) — the sensor joins the network by exchanging keys with GEM. DevAddr and session keys are derived on each Join and rotate automatically.
ABP Fields
| Field | Description |
|---|---|
| DevAddr | Required. 4-byte (8 character) hex device address. |
| NwkSKey | Required. 16-byte (32 character) hex network session key. |
| AppSKey | Required. 16-byte (32 character) hex application session key. |
| Generate All | Button that generates random values for all three ABP fields. Only shown when creating a new sensor (not when editing). |
OTAA Fields
| Field | Description |
|---|---|
| DevEUI | Required. 8-byte (16 character) hex unique device identifier. Static — programmed into the sensor at manufacture. |
| AppKey | Required. 16-byte (32 character) hex application key used to derive session keys during Join. |
| JoinEUI | Optional. 8-byte hex join server identifier. Defaults to zeros if omitted. |
For OTAA sensors, the DevEUI is the static identifier used to match incoming Join requests. After a successful Join, GEM derives the current DevAddr, NwkSKey, and AppSKey and stores them as zone attributes. The DevAddr column in the sensor table reflects the current session DevAddr; dev_addr is a read-only attribute that rotates on every re-join. The NwkSKey and AppSKey fields are not shown in the OTAA form — they are populated automatically.
Payload Decoder Section
| Field | Description |
|---|---|
| Template | Select a pre-built decoder template from the dropdown. Selecting a template populates the decoder text area with its code. |
| Decoder | JavaScript function body that decodes the raw payload bytes into meaningful attribute values. Receives bytes (Buffer) and port (fPort). Must return an object of attribute name/value pairs. |
Example decoder:
// Decode a temperature sensor payload
return { temperature: bytes.readInt16BE(0) / 100 };
Click Save to create or update the sensor. The gateway device is automatically reloaded to pick up the new zone. Click Cancel to close the form.
Traffic Tab
The Traffic tab shows a live log of LoRa packets received by a gateway.
Gateway Selector
Select a gateway to monitor. If only one gateway exists, it is selected automatically. Click Refresh to manually reload the traffic log.
The traffic log auto-refreshes every 5 seconds while a gateway is selected.
Traffic Table
| Column | Description |
|---|---|
| Time | The time the packet was received. |
| DevAddr | The device address of the sending sensor (shown in monospace). For OTAA sensors this is the current session DevAddr assigned at Join. |
| Zone | The GEM zone name matched to this device address, or "<unknown>" if no matching zone exists. Matching uses a DevAddr index that is kept in sync as OTAA sensors re-join. |
| RSSI | Received signal strength indicator. |
| SNR | Signal-to-noise ratio. |
| Freq | The radio frequency used. |
| Data Rate | The LoRa data rate (spreading factor and bandwidth). |
| FCnt | The frame counter value. |
| MIC | Message Integrity Code verification: OK (green badge) or FAIL (red badge). A FAIL indicates the session keys may not match. |
| Decoded | The decoded payload values (if a payload decoder is configured for the zone). Shows key/value pairs. |
Use the Traffic tab to verify that sensors are communicating correctly. If you see packets with MIC FAIL, the NwkSKey or AppSKey on the sensor does not match what is configured in GEM.