MQTT Messages

An MQTT broker is provided on the device to handle messaging between the network server and applications. This provides an easy interface for an application to subscribe to relevant topics. Applications can be written in any language supported by the image installed on the device, MQTT libraries are available for most languages.

 

Input Topics

  • down – submit a packet to be queue for a device
    • topic: lora/<DEV-EUI>/down
    • message – JSON packet info
    • JSON fields
      • deveui – DevEUI of destination end device
      • data – base64 encoded data to be sent in downlink packet payload.
      • port – AppPort, 8-bit integer value to send packet, use 0 to send MAC commands.
      • ack – optional, request ACK of receipt of packet by end device. If enabled the end device should send an ACK in its next uplink packet after receiving the downlink. If the ACK is not seen in the uplink the same downlink packet may be sent again, depending on retry settings. In Class C the ACK will be expected soon after the downlink is transmitted, i.e. five seconds, otherwise a retry will be sent.
      • ack_retries – optional, number of re-transmissions to perform in sending the downlink. If network server is unable to schedule the downlink it will not be counted against the retries.
      • rx_wnd – optional, specify Rx window downlink should be scheduled for values (0, 1 or 2). If provided, and not 0, the network server will wait until the packet can be scheduled for the specified window before sending the packet to the radio for transmission. The packet will remain in the queue until scheduled. Set to 0 for Class C devices.
  • clear – clear the downlink queue for an end device
    • topic: lora/<DEV-EUI>/clear
    • message – none or empty string

 

 

Output Topics

Device Specific Messages

Events for specific DevEUI values can be subscribed to, useful for filtering. Messages published by the network server use QOS level 1.

Match all topics: lora/+/+

Fields: lora/<DEV-EUI>/<EVENT>

Event Topics

        • up – occurs when a packet is received and authenticated. Will be sent to application only once for each frame counter. Duplicate or retransmitted packets will be filtered by the network server. Payload has been decrypted with the Application Session Key.
        • down – occurs when an application submits a packet for downlink using MQTT
        • joined – occurs when an end-device join request is received, validated and join response is queued. If join request was serviced by remote join server “remote_js” in JSON will be set true.
        • join_request – occurs when a join request is received.
        • join_rejected – occurs when join request is denied due to a mismatched AppKey, UnknownDevEUI or Gateway Mismatch.
        • join_accept – occurs when a join request is valid and a response is ready to be sent.
        • down_queued – occurs when a downlink packet is successfully queued by an application.
        • down_dropped – occurs when a packet cannot be queued
        • mac_sent – occurs when a set of MAC commands are sent to the end device in a downlink packet
        • mac_recv – occurs when a MAC command is received in an uplink packet
        • packet_sent – occurs when a packet is sent to the radio for transmission
        • packet_ack – occurs when the network server receives an uplink with acknowledgement of successful receipt of a downlink packet.
        • packet_drop – occurs when a packet could not be scheduled for transmission in an Rx Window and cannot be resent later, i.e. join request cannot be rescheduled or ACK retries have been exhausted.
        • packet_missed – occurs when gap is detected in the frame counter of received frames. A count of the detected missed packets will be provided in the message.
        • packet_recv – occurs when a packet is received and authenticated. Duplicate packets will appear, data payload is encrypted.
        • queue_full – occurs when space is not available to queue a downlink for the end device
        • class – occurs when an end device operating class is updated.
        • clear – command sent to clear an end device downlink queue
        • cleared – occurs when an end device downlink queue is cleared.
        • gw_rejected – occurs when a UDP packet is received from an unknown gateway and a new record could not be created due to currently installed license information

Fields in up messages

  • time – UTC time of pkt RX, us precision, ISO 8601 ‘compact’ format
  • tmst – Internal timestamp of “RX finished” event (32b unsigned)
  • freq – RX central frequency in MHz (unsigned float, Hz precision)
  • chan – Concentrator “IF” channel used for RX (unsigned integer)
  • rfch – Concentrator “RF chain” used for RX (unsigned integer)
  • stat – CRC status: 1 = OK, -1 = fail, 0 = no CRC
  • modu – Modulation identifier “LORA” or “FSK”
  • datr – LoRa datarate identifier (eg. SF12BW500)
  • datr – FSK datarate (unsigned, in bits per second)
  • codr – LoRa ECC coding rate identifier
  • rssi – RSSI in dBm (signed integer, 1 dB precision)
  • lsnr – Lora SNR ratio in dB (signed float, 0.1 dB precision)
  • size – RF packet payload size in bytes (unsigned integer)
  • data – Base64 encoded RF packet payload, padded
  • ack – Set to true if uplink frame is acknowledging last received downlink
  • adr – Set to true if end-device has ADR enabled bit set in uplink packet
  • data – Decrypted payload (BASE64)
  • mhdr – LoRaWAN packet header (HEX)
  • opts – MAC commands (HEX)
  • port – Application port
  • fcnt – Packet sequence number 16-bit
  • seqn – Packet sequence number 32-bit
  • size – Size of “data” field
  • time – time packet was received by network server or packet-forwarder
  • cls – class bit in frame control byte
  • deveui – device EUI
  • appeui – application EUI
  • gweui – gateway EUI
  • mPower 6.0.x will add the following fields if configured in the device record
    • name – device name
    • product_id – device product ID
    • serial_number – device serial number
    • hardware_version – device hardware versionm
    • firmware_version – device firmware version

 

Gateway Specific Messages

Events for specific Gateway EUI can be subscribed to, useful for filtering.

Fields: lora/<GW-EUI>/<DEV-EUI>/<EVENT>

Events:

      • packet_recv – occurs when a packet is received by the radio

Application Specific Messages

Events for specific Application EUI and Application Port values can be subscribed to, useful for filtering.

Fields: lora/<APP-EUI>/<DEV-EUI>/<EVENT>

Fields: lora/<APP-EUI>/<DEV-EUI>/<APP-PORT>/up

Events:

      • up – occurs when a packet is received and authenticated. Will be sent to application only once for each frame counter. Duplicate or retransmitted packets will be filtered by the network server. Payload has been decrypted with the Application Session Key.
      • packet_sent – occurs when a packet is sent to the radio for transmission

Subscribing to MQTT Messages

Below is an example of a device joining the network successfully. Then sending one uplink packet, receiving a confirmed downlink with MAC command requests and responding in a second uplink with MAC command answers and ACK set.

# mosquitto_sub -v -t lora/+/+

lora/00-80-00-00-00-00-e1-9c/join_request {"tmst":4167060148,"chan":7,...,"nonce":42137}
lora/00-80-00-00-00-00-e1-9c/class C
lora/00-80-00-00-00-00-e1-9c/joined {"remote_js":true}
lora/00-80-00-00-00-00-e1-9c/packet_sent {"appeui":"16-ea-76-...-3d-80","codr":"4/5",...,"powe":11,}
lora/00-80-00-00-00-00-e1-9c/packet_recv {"tmst":4237072364,..."data":"QFWKg1i...emStPVPg="}
lora/00-80-00-00-00-00-e1-9c/up {"tmst":4237072364,..."seqn":0,"appeui":"16-ea-76-...-3d-80"}
lora/00-80-00-00-00-00-e1-9c/packet_sent {"appeui":"16-ea-76...-80",...,"tmst":4238072364,"twnd":1}
lora/00-80-00-00-00-00-e1-9c/mac_sent {"deveui":"00-80-...-ee","opts":"0708f87d84...18477"}
lora/00-80-00-00-00-00-e1-9c/packet_recv {"tmst":4248407972,...,"data":"QFWKg1ikA...dgONV"}
lora/00-80-00-00-00-00-e1-9c/packet_ack {"seqn":0}
lora/00-80-00-00-00-00-e1-9c/mac_recv {"appeui":"1","data":"03","deveui":"2","gweui":"3","id":7}
lora/00-80-00-00-00-00-e1-9c/mac_recv {"appeui":"1","data":"03","deveui":"2","gweui":"3","id":7}
lora/00-80-00-00-00-00-e1-9c/up {"tmst":4248407972,...,"seqn":1,"appeui":"16-ea-76-...-3d-80"}
lora/00-80-00-00-00-00-e1-9c/packet_missed {"count":3}
lora/00-80-00-00-00-00-e1-9c/up {"tmst":4543408762,...,"seqn":5,"appeui":"16-ea-76-...-3d-80"}

Publishing MQTT Messages

# mosquitto_pub -t lora/<DEV-EUI>/down -m '{<JSON fields>}'
# mosquitto_pub -t lora/00-80-00-00-00-00-9d-b2/down -m '{"data":"dGVzdA=="}'

The “data” field of the message must be base64 encoded.
Commands can be issued through UDP on port 6677 or using the lora-query utility

Additional commands

Example returning the configuration settings of the Network Server:

# nc -u localhost 6677


config
{
"__v" : 3,
"addressRange" : {
"end" : "FF:FF:FF:FE",
"start" : "00:00:00:01"

# lora-query -x config


{
"__v" : 3,
"addressRange" : {
"end" : "FF:FF:FF:FE",
"start" : "00:00:00:01"

To list all commands

$ lora-query -x help

MTS Lora Server Command Help

Commands:

stats – list current stats

reset – reset stats for network, gateways and end-devices

gateway – gateway commands

list – list connected gateways

format: gateway list [json]

delete – remove a gateway from the list

format: device gateway <GW-EUI>

device – end-device commands

add – add a new end-device record

format: device add <DEV-JSON>

example: device add '{"deveui":"00-80-00-00-00-00-e1-9c","class":"C"}'

stats – show end-device statistics

update – update end-device configuration or session info

format: device update <DEV-EUI> <FIELD> <VALUE>

example: device update 00-80-00-00-00-00-e1-9c class C

fields: class, nskey, dskey, ulc, dlc

format: device update <DEV-JSON>

example: device update '{"deveui":"00-80-00-00-00-00-e1-9c","class":"C"}'

fields: deveui, class, name, serial_number, product_id, hardware_version, firmware_version, lorawan_version

delete – delete an end-device configuration, session and packet records

format: device delete <DEV-EUI>

config – show configuration for a specific device

reset – reset end-device session counters

format: device reset <DEV-EUI>

list – list end-devices configured in the network server

format: device list [json]

keygen – generate a unique end-device key using zero-touch settings

format: device keygen <DEV-EUI> [APP-EUI]

session – session commands

add – add a session for a device

format: session add <DEV-JSON>

example: session add '{"deveui":"008000000000e19c",...,"fnwk_sint_key":"531bd..ebe6"}'

JSON prettified:

{
"deveui":"00-80-00-00-00-00-e1-9c",
"dev_addr":"00112233",
"appeui":"00-88-88-88-00-00-e1-9c",
"joineui":"00-99-99-99-00-00-e1-9c",
"net_id":"000017",
"app_senc_key":"531bd9c5ec5d8ba5ef3b262cebfb3e66",
"fnwk_sint_key":"531bd9c5ec5d8ba5ef3b262cebfb3e66"
}

fields: deveui, appeui, joineui, dev_addr, net_id, app_senc_key, fnwk_sint_key

delete – remove a device session

format: session delete <DEV-EUI>

reset – reset session counters

format: session reset <DEV-EUI>

list – show current device sessions

format: session list [json]

packet – packet commands

join – list all validated join packets

format: packet join [json]

up – list all validated uplink packets

format: packet up [json]

down – list all downlink packets

format: packet down [json]

list – list all packets: join, up and down

format: packet list [json]

queue – list downlink queue packets to be sent to end-device

format: packet queue [json]

add – add a packet to the downlink queue

format: packet queue add <PACKET-JSON>

fields: deveui, data, ack, ack_retries, rx_wndMQ T T

delete – delete all downlinks for a specific device

format: packet queue delete <DEV-EUI>

delete – delete one downlink for a specific device

format: packet queue delete <DEV-EUI> <ID>

database – database commands

backup – backup database to flash memory

config – show network server configuration

debug – change debug level

ping – ping the network server command port

help – display this help

quit – command network server process to stop

– add ‘json’ modifier to request output in json

 

Message Format

Semtech Packet Forwarder Protocol
LoRaWAN 1.1

Packet forwarder message format for packet_recv and up topics

Name | Type | Function
:----:|:------:|--------------------------------------------------------------
time | string | UTC time of pkt RX, us precision, ISO 8601 'compact' format
tmst | number | Internal timestamp of "RX finished" event (32b unsigned)
freq | number | RX central frequency in MHz (unsigned float, Hz precision)
chan | number | Concentrator "IF" channel used for RX (unsigned integer)
rfch | number | Concentrator "RF chain" used for RX (unsigned integer)
stat | number | CRC status: 1 = OK, -1 = fail, 0 = no CRC
modu | string | Modulation identifier "LORA" or "FSK"
datr | string | LoRa datarate identifier (eg. SF12BW500)
datr | number | FSK datarate (unsigned, in bits per second)
codr | string | LoRa ECC coding rate identifier
rssi | number | RSSI in dBm (signed integer, 1 dB precision)
lsnr | number | Lora SNR ratio in dB (signed float, 0.1 dB precision)
size | number | RF packet payload size in bytes (unsigned integer)
data | string | Base64 encoded RF packet payload, padded

Additional info added by network server to up packets

{ ...
"ack": true,
"adr": false,
"data": "YWxzZGtqZg==",
"mhdr": "4006000000000100",
"opts": "",
"port": 1,
"seqn": 1,
"size": 12,
"timestamp": "2016-10-10T15:17:21.190132Z",
... }

      • ack – Set to true if uplink frame is acknowledging last received downlink
      • adr – Set to true if end-device has ADR enabled bit set in uplink packet
      • data – Decrypted payload (BASE64)
      • mhdr – LoRaWAN packet header (HEX)
      • opts – MAC commands (HEX)
      • port – Application port
      • fcnt – Packet sequence number 16-bit
      • seqn – Packet sequence number 32-bit
      • size – Size of “data” field
      • time – time packet was received by network server or packet-forwarder
      • cls – class bit in frame control byte
      • deveui – device EUI
      • appeui – application EUI
      • gweui – gateway EUI