Thread MQTT-SN Sleepy Nodes Example

Table of Contents

• Description
• Setup
  • Sleepy subscriber
    • Sleepy subscriber button assignments
    • Sleepy subscriber LED assignments
  • Sleepy publisher
    • Sleepy publisher button assignments
    • Sleepy publisher LED assignments
• Testing

This information applies to the following SoCs: nRF52833 and nRF52840.

The Thread MQTT-SN sleepy nodes example demonstrates interaction between sleeping nodes with the use of OpenThread and built-in MQTT-SN protocol.

• Thread MQTT-SN Sleepy Subscriber subscribes to a topic corresponding to its LED3 state.
• Thread MQTT-SN Sleepy Publisher publishes data on that topic.

The purpose of this example is to toggle the LED on the subscriber board by publishing LED_ON and LED_OFF commands from the publisher board with the use of MQTT-SN sleepy client support. Since the MQTT-SN network topology demands a gateway, which serves as a translator between MQTT-SN clients and MQTT broker, a third-party MQTT-SN gateway has been used. It has been taken from the Eclipse Paho project. For additional information on the gateway used, see Eclipse Paho MQTT-SN C/C++ client for Embedded platforms.

As the MQTT-SN network in this example runs on Thread, the MQTT-SN Gateway plays the role of a Thread Border Router, which means it is a gateway between the Internet and the Thread Network. It can be run on a Raspberry Pi with Raspbian-based firmware. To connect the MQTT-SN Gateway to the Thread network, you need Nordic's nRF52840 or nRF52833 Development Kit running the Network Co-Processor (NCP). For details on how to set up a Thread Border Router and run MQTT-SN Gateway, refer to the Thread Border Router documentation.

Description

Both client nodes indicate their Thread network state on LED1. When the device is not connected to the network, the LED blinks at a 100-ms period. Once the device connects to a network, the LED stops blinking and remains turned on. On startup, nodes automatically enter the Thread network with default parameters. The sleepy subscriber and sleepy publisher nodes both start as MED (Minimal End Device) and switch to SED (Sleepy End Device) after establishing connection with the MQTT broker. The MQTT-SN gateway becomes a Leader of the network.

The MQTT-SN network state of the clients is indicated on LED4. When the device is not connected to the network, the LED is off. Once the device connects to a network, the LED is turned on.

---

Setup

You can find the source code and the makefiles in the following folders:

• <InstallFolder>\examples\thread\mqttsn_sleepy_publisher
• <InstallFolder>\examples\thread\mqttsn_sleepy_subscriber

Sleepy subscriber

When an MQTT-SN client subscribes to a topic, every message published by other nodes on that topic is forwarded to the subscribing client. However, when a client is in the Asleep state, all incoming messages are buffered by the MQTT-SN gateway and forwarded to the subscribing client when it is in the Awake state. In this example, the client's sleep period is set to 10 seconds. Therefore, the sleepy subscriber node receives data once every 10 seconds. As the client serves as Thread SED (Sleepy End Device), it can only receive messages through a parent-polling mechanism. When it receives sleep permission from the gateway, the sleepy subscriber changes its polling time to a bigger value to save energy. To improve responsiveness, the polling time is decreased significantly upon changing the client's MQTT-SN state to Awake.

The subscriber node is controlled by specific actions triggered by pressing the buttons. The effect of pressing the buttons is reflected on the LED state.

Sleepy subscriber button assignments

The following buttons reserved for user application purposes are assigned in this example:

• Button 2 (BSP_BUTTON_1): Search for a gateway.
  • Pressing sends a multicast SEARCH GATEWAY message, which launches the gateway discovery procedure. It is necessary to connect to the gateway.
• Button 3 (BSP_BUTTON_2): Connect or disconnect from the MQTT-SN network.
  • Pressing sends the following unicast messages:
    • If the node is not connected to the gateway: a CONNECT message to the gateway, which connects the node to the MQTT-SN network. Once the connection is established, a topic is registered with a unicast REGISTER message.
    • If the node is connected to the MQTT-SN network: a DISCONNECT message to the gateway, which disconnects the node from the MQTT-SN network.
• Button 4 (BSP_BUTTON_3): Send a SUBSCRIBE/UNSUBSCRIBE message.
  • Pressing sends the following unicast messages:
    • When the client is not subscribing: a unicast SUBSCRIBE message to the gateway.
      • When the subscription has been confirmed, a unicast DISCONNECT message is sent to the gateway, which puts the node into the Asleep state.
    • When the client is subscribing: a unicast UNSUBSCRIBE message to the gateway.
  • If the node is not connected to the network, pressing the button has no effect.

Sleepy subscriber LED assignments

The sleepy subscriber uses LED assignments as described in Thread BSP LED and button reference for the following LEDs:

• LED1 – Used to indicate the network connection state.

The following LED reserved for user application purposes are assigned in this example on sleepy subscriber:

• LED3: Toggled by Publisher (see Sleepy publisher button assignments).
• LED4: MQTT-SN network state:
  • Off - Asleep.
  • On - Awake.

Sleepy publisher

The publisher node also serves a Thread SED role and changes its polling time to switch between low energy consumption and improved responsiveness. It does not sleep on MQTT-SN layer though – the client's state is connected and it does not change. According to the MQTT-SN protocol specification, to send a message a node has to be in the Connected state. If the client slept on MQTT-SN, it will have to change its state from Asleep to Connected and back. To change the state, the sleepy publisher will then have to send CONNECT and DISCONNECT messages every time it will publish data. As it has no subscriptions and the MQTT-SN gateway message-buffering feature is not needed, this will be an additional, unnecessary data to send.

The publisher node is controlled by specific actions triggered by pressing the buttons. The effect of pressing the buttons is reflected on the LED state.

Sleepy publisher button assignments

The button assignments are identical to Sleepy subscriber button assignments, with the exception of the following button:

• Button 4: Send a PUBLISH message.
  • Pressing sends a unicast PUBLISH message to the gateway.
  • If the node is not connected to the network, pressing the button has no effect.

Note

The publisher node sends LED_ON and LED_OFF commands alternately, regardless of the state of LED3 on the subscriber board. It might happen that the state of LED4 on the subscriber board and the published command are the same. In such a situation, pressing Button 4 on the publisher board will have no effect on the state of LED3 on the subscriber board, despite fully functional and working network. Pressing Button 4 on the publisher board again will change the command and the publisher will toggle the LED3 state.

Sleepy publisher LED assignments

The sleepy publisher uses LED assignments as described in Thread BSP LED and button reference for the following LEDs:

• LED1 – Used to indicate the network connection state.

The following LED reserved for user application purposes are assigned in this example on sleepy publisher:

• LED4: MQTT-SN network state:
  • Off - Disconnected.
  • On - Connected.

---

Testing

1. Build the example according to the instructions in Building examples.
2. Turn the MQTT-SN gateway on according to the instructions in Thread Border Router.
3. Program a development board with the MQTT-SN Sleepy Subscriber application.
4. Program another development board with the MQTT-SN Sleepy Publisher application.
5. Let the clients find the MQTT-SN gateway by pressing Button 2 on both boards.
6. Connect the clients to the gateway by pressing Button 3 on both boards.
7. Subscribe by pressing Button 4 on the subscriber client board. The subscriber board is in the Asleep state now. Note that LED4 is off.
8. Try toggling LED3 on the subscriber by pressing Button 4 on the publisher board. To see the LED toggle, you must wait for the subscriber board to go into the Awake state, which on average happens every 10 seconds.
9. When the subscriber client board goes into the Awake state (it sends a PINGREQ message to the gateway), the LED toggles.