MQTT Application

Application configuration

url: mqtts://test.mosquitto.org:8883
eui: filter end-devices joined to AppNet EUI
encodeHex: encode payloads to and from hex instead of default base64
options:
  check_hostname: enable hostname check for tls connection
  client_id: client id
  server_cert: server certificate
  client_cert: client certicate
  apikey: client private key
  username: MQTT username
  password: MQTT password
  uplinkTopic: override topic for uplinks to publish to
  downlinkTopic: override topic to subscribe to for downlinks
  overrideTopicsForAllApps: use custom topics for all apps
requestOptions:
  api: enable api requests
  log: enable log requests
  lora: enable lora query requests
backhaulDetect:
  enabled: turn backhaul detect messages on/off
  payload: hex payload of downlink packet to send to end-device when backhaul is down
  port: port to send downlink packet to end-device
  timeout: scheduling timeout limit the number of downlinks scheduled, default one per 5 minutes

AWS or MQTT Broker

AWS provides configuration for MQTT connections and topic based security and routing. The following MQTT topics can be configured in AWS policies. TLS Certificates and Keys are used to authenticate the AWS connection.

MQTT Protocol v1.0

Publishes

• lorawan/<APP-EUI>/<GW-UUID>/init

  lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/init
  

  {
    "gateways_euis": ["00-80-00-00-d0-00-01-1a", "00-80-00-00-d0-00-01-ff"],
    "time": "2023-03-04T23:08:26.021832Z",
    "api_version": "1.0"
  }
  

  or

  {
    "gateways_euis": ["00-80-00-00-d0-00-01-1a", "00-80-00-00-d0-00-01-ff"],
    "time": "2023-03-04T23:08:26.021832Z"
  }
  

• lorawan/<APP-EUI>/<GW-UUID>/close

  lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/close (null)
  

• lorawan/<APP-EUI>/<GW-UUID>/disconnected

  lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/disconnected (null)
  

• lorawan/<APP-EUI>/<DEV-EUI>/up

  lorawan/8b-6c-f0-8e-ee-df-1b-b6/00-80-00-ff-ff-00-00-03/up
  

  {
    "jver": 1,
    "tmst": 561224395,
    "time": "2023-03-04T23:14:39.522787Z",
    "tmms": 1362006897523,
    "chan": 6,
    "rfch": 1,
    "freq": 903.5,
    "mid": 8,
    "stat": 1,
    "modu": "LORA",
    "datr": "SF9BW125",
    "codr": "4/5",
    "rssis": -14,
    "lsnr": 9.2,
    "foff": -2769,
    "rssi": -13,
    "opts": "03070307",
    "size": 8,
    "fcnt": 1,
    "cls": 0,
    "port": 33,
    "mhdr": "80cb80d000840100",
    "data": "dGVzdGRhdGE=",
    "appeui": "8b-6c-f0-8e-ee-df-1b-b6",
    "deveui": "00-80-00-ff-ff-00-00-03",
    "joineui": "16-ea-76-f6-ab-66-3d-80",
    "name": "JSR-DEBIAN-PC-DOT2",
    "devaddr": "00d080cb",
    "ack": false,
    "adr": true,
    "gweui": "00-80-00-00-d0-00-01-ff",
    "seqn": 1
  }
  

• lorawan/<APP-EUI>/<DEV-EUI>/joined

  lorawan/8b-6c-f0-8e-ee-df-1b-b6/00-80-00-ff-ff-00-00-03/joined
  

  {
    "joineui": "16-ea-76-f6-ab-66-3d-80",
    "name": "JSR-DEBIAN-PC-DOT2",
    "appeui": "8b-6c-f0-8e-ee-df-1b-b6",
    "gweui": "00-80-00-00-d0-00-01-ff",
    "remote": true,
    "time": "2023-03-04T23:07:11.360064Z"
  }
  

• lorawan/<GW-UUID>/<DEV-EUI>/joined

  lorawan/029998E06156CDD44523264B523115C1/00-80-00-ff-ff-00-00-03/joined
  

  {
    "joineui": "16-ea-76-f6-ab-66-3d-80",
    "name": "JSR-DEBIAN-PC-DOT2",
    "appeui": "8b-6c-f0-8e-ee-df-1b-b6",
    "gweui": "00-80-00-00-d0-00-01-ff",
    "remote": true,
    "time": "2023-03-04T23:07:11.360064Z"
  }
  

• lorawan/<APP-EUI>/<DEV-EUI>/moved
  • Array of GW-EUIs

  • ["00-80-00-0d-00-00-00-01"]
    

• lorawan/<APP-EUI>/<GW-UUID>/lora_res
  • Responses to lora query requests, see subscribed topics to make requests
• lorawan/<APP-EUI>/<GW-UUID>/log_res
  • Responses to log requests, see subscribed topics to make requests
• lorawan/<APP-EUI>/<GW-UUID>/api_res
  • Responses to API requests, see subscribed topics to make requests

Subscribed

Subscribed topics allow communication to the gateway to issue downlinks, clear a downlink queue or request info.

• It is recomended to use topic access control to limit the clients that are able to make calls to the gateway to your back-end services
  • Mosquitto Dynamic Security
  • MQTT Multiple User Accounts
• Topics to manage the downlink queue
  • Multitech LNS MQTT Messages
  • lorawan/<APP-EUI>/<DEV-EUI>/+
  • lorawan/<GW-EUI>/<DEV-EUI>/+
  • lorawan/<GW-UUID>/<DEV-EUI>/+
  • Supported topics
    • down - downlinks to schedule
      • Fields
        • data – base64 encoded data to be sent in downlink packet payload. If Encode Payload as HEX is selected in Default App configuration a HEX payload should be provided for downlink as well.
        • 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. ```json $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/00-80-00-ff-ff-00-00-03/down -m ‘{“data”:”QA==”}’
    • clear - clear downlinks for a device

      $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/00-80-00-ff-ff-00-00-03/clear -m ""
      

Topics to request gateway info

Request ID

The “rid” field can be added to app-connnect lora_query, api_query and log_query requests and will be added to the response json to correlate the response to the request message in releases after mPower 6.3.0.

LoRa Query

• lorawan/<APP-EUI>/<GW-UUID>/lora_req - send request for lora-query utility
  • Multitech LNS LoRa Query
  • command - lora-query command to run
  • Example: retrieve count of device records

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/lora_req -m '{"command":"device count"}'
    

    or in releases after mPower 6.3.0 “rid” is an optional field

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/lora_req -m '{"command":"device count","rid":1}'
    

  • response

    lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/lora_res
    

    {
    "count" : 9
    }
    

    or in releases after mPower 6.3.0

    {
    "rid": 1,
    "result":
    {
      "count" : 9
    }
    }
    

    or

  • Example: queue a downlink

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/lora_req -m  $'{"command": "packet queue add \'{\\\"deveui\\\":\\\"00-80-00-ff-00-00-00-03\\\",\\\"data\\\": \\\"QA==\\\"}\'", "rid": 4}'
    

  • response

    lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/lora_res
    

    {
    "id":470,
    "status":"success"
    }
    

    or in releases after mPower 6.3.0 with optional “rid” field, command is moved to “result” field to be consistent with other message responses.

    {
    "rid": 4,
    "result":
        {
      "id":470,
      "status":"success"
    }
    }
    

  • Example: request pages of up to 500 records

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/lora_req -m '{"command":"device list json page 0"}'
    

  • response

    lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/lora_res
    

    [{
    "class" : "A",
    "created_at" : "2022-12-27T19:40:37Z",
    "deveui" : "00-80-00-00-04-00-59-04",
    "device_profile_id" : 0,
    "device_profile_updated_at" : "2022-12-27T19:40:37Z",
    "firmware_version" : "",
    "hardware_version" : "",
    "last_app_nonce" : 9,
    "last_nonce" : 14,
    "last_seen" : "",
    "name" : "",
    "network_profile_id" : 1,
    "network_profile_updated_at" : "2022-12-27T19:40:37Z",
    "product_id" : "",
    "rejoin_count" : 0,
    "serial_number" : "",
    "tags" : ""
    }]
    

    or in releases after mPower 6.3.0 with optional “rid” field, response is moved to “result” field to be consistent with other message responses.

    {
    "rid": 1,
    "result":
      [{
        "class" : "A",
        "created_at" : "2022-12-27T19:40:37Z",
        "deveui" : "00-80-00-00-04-00-59-04",
        "device_profile_id" : 0,
        "device_profile_updated_at" : "2022-12-27T19:40:37Z",
        "firmware_version" : "",
        "hardware_version" : "",
        "last_app_nonce" : 9,
        "last_nonce" : 14,
        "last_seen" : "",
        "name" : "",
        "network_profile_id" : 1,
        "network_profile_updated_at" : "2022-12-27T19:40:37Z",
        "product_id" : "",
        "rejoin_count" : 0,
        "serial_number" : "",
        "tags" : ""
      }]
    }
    

    Log Requests

• lorawan/<APP-EUI>/<GW-UUID>/log_req - send request for log file
  • lines - number of lines to returned
  • file - name of file to read from /var/log folder, only paths to /var/log are allowed.
  • filter - regex string to pass to grep -Ei ‘(REGEX)’ as a filter

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/log_req -m '{"file":"/var/log/messages","lines":100}'
    

    or in releases after mPower 6.3.0 “rid” is an optional field

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/log_req -m '{"file":"/var/log/messages","lines":100,"rid":1}'
    

  • response

    lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/log_res
    

    {
    "result": "2023-03-05T19:55:56.913366+00:00 mtcdt lora-app-connect: Call setup MQTT App\n2023-03-05T19:55:56.934340+00:00 mtcdt lora-app-connect: Setup MQTT App\n2023-03-05T19:55:57.014137+00:00 mtcdt lora-app-connect: MQTT connect mqtt://172.16.0.222:1883\n2023-03-05T19:55:59.985408+00:00 mtcdt lora-app-connect: Start client\n2023-03-05T19:56:00.039355+00:00 mtcdt lora-app..."
    }
    

    or in releases after mPower 6.3.0 with optional “rid” field

    {
    "rid": 1,
    "result": "2023-03-05T19:55:56.913366+00:00 mtcdt lora-app-connect: Call setup MQTT App\n2023-03-05T19:55:56.934340+00:00 mtcdt lora-app-connect: Setup MQTT App\n2023-03-05T19:55:57.014137+00:00 mtcdt lora-app-connect: MQTT connect mqtt://172.16.0.222:1883\n2023-03-05T19:55:59.985408+00:00 mtcdt lora-app-connect: Start client\n2023-03-05T19:56:00.039355+00:00 mtcdt lora-app..."
    }
    

    API Requests

    API Requests can get or change any configuration settings, restart services or reboot the gateway

• Multitech mPower API
• lorawan/<APP-EUI>/<GW-UUID>/api_req - send request for log file
  • method - GET, PUT, POST or DELETE
  • path - API path to call
  • body - JSON object to pass to the API

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/api_req -m '{"method":"GET","path":"/api/loraNetwork","body":""}'
    

    or in releases after mPower 6.3.0 “rid” is an optional field

    $ mosquitto_pub -t lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/api_req -m '{"method":"GET","path":"/api/loraNetwork","body":"","rid":1}'
    

  • response

    lorawan/8b-6c-f0-8e-ee-df-1b-b6/029998E06156CDD44523264B523115C1/api_res
    

    {
      "code" : 200,
      "result" :
      {
        "__v" : 1,
        "addressRange" :
        {
                "end" : "FF:FF:FF:FE",
                …
        },
        …
      }
    }
    

    or in releases after mPower 6.3.0 with optional “rid” field

    {
      "rid": 1,
      "code" : 200,
      "result" :
      {
        "__v" : 1,
        "addressRange" :
        {
                "end" : "FF:FF:FF:FE",
                …
        },
        …
      }
    }
    

  • Change LoRa Network Settings

    {
      "method": "PUT",
      "path": "/api/loraNetwork/lora",
      "body": "{\"channelPlan\":\"US915\"}"
    }
    

  • List device DevEUI and AppKey

    {
      "method": "GET",
      "path": "/api/loraNetwork/whitelist/devices",
      "body": ""
    }
    

  • Create device DevEUI and AppKey record

    {
      "method": "POST",
      "path": "/api/loraNetwork/whitelist/devices",
      "body": "{\"deveui\": \"00800000FFFF0001\",\"appeui\": \"0080000000000017\",\"appkey\": \"00800000FFFF000100800000FFFF0001\",\"class\": \"A\"}"
    }
    

  • Remove device DevEUI and AppKey, provide index or DEVEUI to record to delete

    {
      "method": "DELETE",
      "path": "/api/loraNetwork/whitelist/devices/0",
      "body": ""
    }
    

    Or

    {
      "method": "DELETE",
      "path": "/api/loraNetwork/whitelist/devices/00800000FFFF0001",
      "body": ""
    }
    

  • Restart LoRa services

    {
    "method":"POST",
    "path":"/api/lora/restart",
    "body":""
    }
    

Test brokers

• Mosquitto Test Broker
  • Supports TLS1.2 server certificate, client certificate and apikey settings for authentication
  • Application configuration
    • url: mqtts://test.mosquitto.org:8883
    • options:
      • server_cert: server certificate
      • clent_cert: client certicate
      • apikey: client private key
• FLESPI Test Broker
  • Supports authentication using username access token for authentication
  • Application configuration
    • url: mqtt://mqtt.flespi.io
    • options:
      • username: <FLESPI-TOKEN>

Gateway Settings

Fields

Enable - enable/disable the local app settings

• Check server hostname - enable checking the certificate hostname for TLS connections
• Server URL - server to connect to using HTTP,HTTPS,MQTT or MQTTS
• App EUI - appeui to filter device uplinks and downlinks
• MQTTS
  • Client ID - mqtt client id
  • Server Cert - server TLS certificate
  • Client Cert - client TLS certificate
  • Client Key - client TLS key
  • Username - mqtt username
  • Password - mqtt password
  • Clean Session - start with a clean MQTT session
• Encode Payload as HEX - change payload format from Base64 (default) to HEX string, used for uplink and downlink payloads
• Override Topics for All Apps - apps connections defined by LENS will also use the overriden topic values for publishing uplinks and subscribing for downlinks if enabled
• Enable LoraQuery Requests - allow the server to make lora-query requests through MQTT
• Enable Log Requests - allow the server to make log file requests through MQTT
• Enable API Requests - allow the server to make API requests through MQTT
• Backhaul Detect - enable/disable downlink messages to end-device is the backhaul connection to MQTT is disconnected
• Backhaul Port - port to send downlink messages
• Payload - payload to send downlink messages
• Timeout - timeout to wait before sending another downlink message to the end-device since last backhaul down message

Local Device Key Settings

Settings

• DevEUI - End-Device EUI
• AppEUI - AppEUI to assign device record on Join, must match Default App EUI setting to forward to application unless catch-all AppEUI FF-FF-FF-FF-FF-FF-FF-FF is used for the Default App (Cloud Connector) setting
• AppKey - AppKey of end-device to authenticate join and create session keys
• Device Profile - Default settings to assign device on join
• Network Profile - Class and RF settings to use for device session, MAC commands are sent to update the end-device