MQTT

MQTT connection

This connector allows you to connect a Network Server to your application using the MQTT protocol.

For message types, please refer to the corresponding section of Data API messages.

Argument Required Description
description no Description of connection
uri yes URI of the broker, please refer to the scheme
filter yes The Network Server Filter ID.
topic_up yes The topic name for messages the network server will publish to. IT supports real-time substitution with type and fields in ''meta'' This topic name may contain message type and fields from meta, e.g /messages/{type}/{device}/
topic_down no The topic name for the message network server will subscribe to.

List of schemes allowed to be used in the URI field:

Scheme Encrypted Default port Description
mqtt:// no 1883 Native MQTT TCP
mqtts:// yes 8883 Native MQTT TCP TLS, requires a valid certificate for the domain name
ws:// no 80 WebSocket MQTT, supports a custom path (/mqtt if not provided)
wss:// yes 443 Secured WebSocket MQTT, supports custom a path (/mqtt if not provided), requires valid certificate for domain name

The MQTT user and password fields are optional, but if present, they should be URLEncoded and passed via basic auth URI parameters.

mqtts://username:password@example.com:1234

List of fields could be substituted in topic_up field. Example: lora/{type}/{device}.
device The device EUI (dev_eui by LoraWAN specification)
device_addr The device address (dev_addr by LoraWAN specification)
application The application EUI (app_eui by LoraWAN specification)
gateway The gateway mac address
network The network of gateways identifier
type The type of message (uplink / join / error / e.t.c.)

QoS

All messages are sent using MQTT QoS = 1

It means, that your broker MUST acknowledge with PUBACK all of the messages.

The timeout for the one awaiting message is 1 second

The maximum awaiting messages is 100 messages

Reconnection

If the connection to the broker dropped, the connector is trying to reconnect to it. The timeout for that is the following. It starts with 0.1s and doubles every following fail, the maximum timeout is 60s.

Missed messages

During the reconnect, the connector requests old messages from the NS, since the time connection is dropped.

Adapter Working Cycle

Once the connection to the MQTT broker is established, the connector will start to PUBLISH data to the generated topic_up.

If the topic_down is provided, the connector will subscribe to it right after successful connection.

Publishing messages

For the format of the messages from the Network server, please refer to the corresponding section of Data API.

Subscribing for messages

For the format of the messages to the Network server please, refer to the corresponding section of Data API.

You need to send a proper Data API JSON message.

If your messages is not JSON it will be silently discarded.

Example of usage

What this example is about:

  • You have an MQTT broker with the following URI: mqtt://example.com
  • You will receive uplink messages to the topic /lora/uplink and downlink_request messages to /lora/downlink_request
  • You will send messages to the Network server by publishing to the topic /donwstream

What you should do:

  1. Create a filter in the NS for the data you want to receive. Select uplink and downlink_response types.

  2. Create an MQTT connection with the following

  3. URI = mqtt://example.com

  4. Filter ID = the one of the filter you have just created.
  5. Publish topic = /lora/{type}

  6. Subscribe topic = /downstream

  7. After creation, the connector connects to your broker and starts to send messages.

Example of an uplink message:

> Topic: /lora/uplink
{
  "params": {
    "payload": "MzQ3NjcwNjFiNDc3NGU2ZmFiZjBhNmY4YTJjYmI0Y2M=",
    "port": 7,
    "duplicate": false,
    "counter_up": 3,
    "rx_time": 1532073817.157281,
    "encrypted_payload": "pLgR8Tzh3JptkhtozJ5OlFuS3zQCygWD5hmx9zMjLnU="
  },
  "meta": {
    "network": "e23d2f31af81b25ef50375b5b7810c52",
    "packet_hash": "73465c1ed0cae413816d0f78baf3dcc2",
    "application": "1293e9e373666fd5",
    "device_addr": "d242b7a6",
    "time": 1532073817.175208,
    "device": "b2b48f713c2f973d",
    "packet_id": "f577207419bb4701ff9f7874c2e2808e",
    "gateway": "92a199d4e41ab64b"
  },
  "type": "uplink"
}

Example of a downlink_request message and a downlink_response message reply

> Topic: /lora/downlink_request
{
  "params": {
    "counter_down": 3,
    "max_size": 51,
    "tx_time": 1532075747.295559
  },
  "meta": {
    "network": "12b5d8a8df8d9255c65d6d565d836a9d",
    "packet_hash": "cf59f7bf410a9eb23383f41342c3c7fe",
    "application": "6264dd6a1b4e9ca1",
    "device_addr": "f22eef89",
    "time": 1532075746.335046,
    "device": "c20ba71a9affafc6",
    "packet_id": "a8b464039cca609bed00f8ec58f494fe",
    "gateway": "524d07d7ef40dea3"
  },
  "type": "downlink_request"
}


< Publish: /dowstream
{
  "meta": {
    "application": "6264dd6a1b4e9ca1", 
    "device": "c20ba71a9affafc6", 
    "device_addr": "f22eef89", 
    "gateway": "524d07d7ef40dea3", 
    "network": "12b5d8a8df8d9255c65d6d565d836a9d", 
    "packet_hash": "cf59f7bf410a9eb23383f41342c3c7fe", 
    "packet_id": "a8b464039cca609bed00f8ec58f494fe", 
    "time": 1532075746.335046
  }, 
  "params": {
    "counter_down": 3, 
    "payload": "220de733f4", 
    "port": 50
  }, 
  "type": "downlink_response"
}

Class C downlink_claim

To send a class C downlink message, you need to send a downlink_claim message

< Publish: /dowstream
{
    "meta": {
        "device": "d2953b67bca671a6", 
        "network": "12024f9efc46a98120a6fac272a9c3a4"
    }, 
    "type": "downlink_claim"
}

How to configure with Amazon AWS IoT

There is only one successful way to connect to the AWS IOT via MQTT.

  • The connection happens using MQTT over the WSS protocol on port 443. It means your endpoint URI would look like wss://<xxxxxxxxxxxxx>-ats.iot.<your_region>.amazonaws.com/mqtt.
  • The authentication method is Custom Authentication. It means that the Custom Authorizer AWS Lambda function should be implemented.

The process is quite complex, please read those docs carefully.

There are general documentation links

https://docs.aws.amazon.com/iot/latest/developerguide/protocols.html https://docs.aws.amazon.com/iot/latest/developerguide/custom-authentication.html https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html

To implement the Custom Authorizer , you should create a Lambda function that basically returns an AWS policy for your connection as well as some other meta parameters.

The authentication could be done using an MQTT user and passwords fields, as well as HTTP query. Note the usage of MQTT user field with query parameters. https://docs.aws.amazon.com/iot/latest/developerguide/custom-auth.html#custom-auth-mqtt

The procedure for the creation of an Authorizer by AWS docs. Do not forget to set the authorizer as default or set it via params specifically. https://docs.aws.amazon.com/iot/latest/developerguide/config-custom-auth.html

The policies that are returned by the Authorizer could be very complex, including special permission for AWS IoT Things, MQTT Client Id or MQTT Topics. https://docs.aws.amazon.com/iot/latest/developerguide/iot-action-resources.html https://docs.aws.amazon.com/iot/latest/developerguide/pub-sub-policy.html

It is important to verify the correctness of the Authorizer logic https://docs.aws.amazon.com/iot/latest/developerguide/config-custom-auth.html#custom-auth-testing

results matching ""

    No results matching ""