Usage

Device Lifecycle

OTAA Join Process

Registration: Register device with DevEUI and AppKey
Device Power On: Device sends JoinRequest
Server Validation: Module verifies MIC and checks DevNonce
Session Creation: Server generates session keys and DevAddr
JoinAccept: Server sends encrypted JoinAccept via gateway
Ready: Device is now joined and can send data

ABP Activation

Registration: Register device with DevEUI, DevAddr, NwkSKey, AppSKey
Device Power On: Device immediately sends data frames
Ready: No join procedure needed

Uplink Data

When a device sends an uplink:

Gateway receives the LoRa transmission
Gateway forwards to Ignition via UDP
Module processes the frame:
- Verifies MIC (Message Integrity Code)
- Validates frame counter
- Decrypts payload
- Runs payload decoder (if assigned)
Tags are updated in real-time
Device state is persisted

Multi-Gateway Deduplication

When multiple gateways receive the same uplink:

First reception is fully processed
Duplicates with better signal update gateway routing only
Duplicates with worse signal are ignored
5-second deduplication window

Downlink Messages

Queue via REST API

Endpoint: POST /data/lorawan/devices/:devEui/downlink

curl -X POST "http://localhost:8088/data/lorawan/devices/A358C4B192543F75/downlink" \
  -H "Content-Type: application/json" \
  -d '{
    "fPort": 10,
    "payload": "48656C6C6F",
    "confirmed": false
  }'

Field	Type	Required	Description
`fPort`	integer	Yes	LoRaWAN port (1-223)
`payload`	string	Yes	Hex-encoded payload
`confirmed`	boolean	No	Request device acknowledgment

View Queued Downlinks

curl "http://localhost:8088/data/lorawan/devices/A358C4B192543F75/downlinks"

Cancel Downlink

curl -X DELETE "http://localhost:8088/data/lorawan/devices/A358C4B192543F75/downlinks/{id}"

Transmission Timing

Device Class	Timing
Class A	RX1 window (+1s after uplink) or RX2 (+2s)
Class C	Immediate (no wait for uplink)

RX Window Fallback

If RX1 transmission fails (gateway error), the module automatically retries via RX2:

RX2 uses regional default frequency and data rate
Only retries on recoverable errors (TOO_LATE, COLLISION)

Device Status

Automatic Status Requests

The module automatically requests device status every 100 uplinks.

On-Demand Status Request

Via API:

curl -X POST "http://localhost:8088/data/lorawan/devices/A358C4B192543F75/status-request"

Via Tag: Write true to [LoRaWAN]/Devices/{Name}/Status/Request

Status Information

Field	Description
Battery	0 = External power, 1-254 = Battery level, 255 = Unknown
BatteryLevel	Human-readable: "External", "XX%", "Unknown"
Margin	SNR margin in dB (-32 to +31)

Adaptive Data Rate (ADR)

The module implements ADR to optimize device transmission parameters.

How It Works

Server collects SNR history (last 20 uplinks)
Calculates optimal data rate based on link margin
Sends LinkADRReq MAC command
Device adjusts spreading factor and TX power

ADR Formula

Margin = Max SNR - Required SNR (SF7) - Installation Margin (5dB)
If margin >= 0: Use SF7 (fastest)
If margin < 0: Use higher SF based on margin deficit

REST API Reference

Device Status

# Get all devices status
curl "http://localhost:8088/data/lorawan/devices/status"

# Response
{
  "devices": {
    "A358C4B192543F75": {
      "joined": true,
      "devAddr": "26011234",
      "fCntUp": 142,
      "fCntDown": 5,
      "lastSeen": 1706180000000,
      "rssi": -85,
      "snr": 7.5,
      "battery": 180,
      "margin": 12
    }
  }
}

Gateway Status

# Get all gateways status
curl "http://localhost:8088/data/lorawan/gateways/status"

# Response
{
  "gateways": {
    "A840411234567890": {
      "connected": true,
      "address": "192.168.1.100",
      "port": 54321,
      "lastSeen": 1706180000000
    }
  },
  "connectedCount": 1
}

Device Registration

# Register OTAA device
curl -X POST "http://localhost:8088/data/api/v1/resources/com.operametrix.ignition.lorawan/device" \
  -H "Content-Type: application/json" \
  -d '[{
    "name": "A358C4B192543F75",
    "config": {
      "name": "TempSensor_01",
      "devEui": "A358C4B192543F75",
      "appKey": "925742558798bfb46e938d7a5a1b161f",
      "mode": "OTAA",
      "deviceClass": "A"
    }
  }]'

Ignition Integration

Tag Bindings

Bind device data to Ignition components:

[LoRaWAN]/Devices/TempSensor_01/temperature
[LoRaWAN]/Devices/TempSensor_01/Radio/RSSI
[LoRaWAN]/Devices/TempSensor_01/Status/Connection

Historian

Enable history on LoRaWAN tags to store time-series data:

Right-click a device tag
Select Edit Tag
Enable History
Configure sample mode (typically "On Change")

Alarming

Create alarms on LoRaWAN device data:

[LoRaWAN]/Devices/TempSensor_01/temperature > 80
[LoRaWAN]/Devices/TempSensor_01/Status/Connection == "Offline"
[LoRaWAN]/Devices/TempSensor_01/Status/Battery < 50

Scripting

Access LoRaWAN data in scripts:

# Read device temperature
temp = system.tag.read("[LoRaWAN]/Devices/TempSensor_01/temperature").value

# Check device status
status = system.tag.read("[LoRaWAN]/Devices/TempSensor_01/Status/Connection").value

# Request device status
system.tag.write("[LoRaWAN]/Devices/TempSensor_01/Status/Request", True)

Troubleshooting

Issue	Possible Cause	Solution
Gateway not connecting	UDP blocked	Check firewall for port 1700
Gateway not connecting	Wrong server address	Verify gateway configuration
Device not joining	Wrong AppKey	Verify 32-character hex key
Device not joining	DevNonce replay	Device may need factory reset
Uplinks not processed	Gateway not registered	Add gateway in web UI
Decoder errors	JavaScript syntax	Check decoder console output
Downlinks not received	Class A timing	Device must uplink first
Downlinks not received	RX window missed	Check gateway TX capability

Best Practices

Register gateways first - Unregistered gateways can connect but payloads may be dropped
Use OTAA - Provides better security than ABP
Assign decoders - Convert raw payloads to meaningful tags
Enable historian - Store time-series data for analysis
Monitor battery - Set up alarms for low battery levels
Use Class A - Unless immediate downlinks are required
Check signal quality - Low RSSI/SNR indicates poor coverage
Backup device keys - Store AppKeys securely outside Ignition

Device Lifecycle​

OTAA Join Process​

ABP Activation​

Uplink Data​

Multi-Gateway Deduplication​

Downlink Messages​

Queue via REST API​

View Queued Downlinks​

Cancel Downlink​

Transmission Timing​

RX Window Fallback​

Device Status​

Automatic Status Requests​

On-Demand Status Request​

Status Information​

Adaptive Data Rate (ADR)​

How It Works​

ADR Formula​

REST API Reference​

Device Status​

Gateway Status​

Device Registration​

Ignition Integration​

Tag Bindings​

Historian​

Alarming​

Scripting​

Troubleshooting​

Best Practices​

Device Lifecycle

OTAA Join Process

ABP Activation

Uplink Data

Multi-Gateway Deduplication

Downlink Messages

Queue via REST API

View Queued Downlinks

Cancel Downlink

Transmission Timing

RX Window Fallback

Device Status

Automatic Status Requests

On-Demand Status Request

Status Information

Adaptive Data Rate (ADR)

How It Works

ADR Formula

REST API Reference

Device Status

Gateway Status

Device Registration

Ignition Integration

Tag Bindings

Historian

Alarming

Scripting

Troubleshooting

Best Practices