Introduction

This document's purpose is to describe the Low-Latency example application and to explain how to use it. 

What you’ll learn

• How to use the Low-latency application, and see the different functionalities available. 
• Understand Node to node, Adaptive flooding and Multicast addressing offered by Wirepas massive

What you’ll need

Prerequisites

This “Getting started” document assumes you already have a working Wirepas development environment and that you are able to flash a development board as described in those documents:

• “How To Install SDK and Build an Application” [2] (Installing Docker, git, Wirepas SDK, and Wirepas Massive Stack)
• “How to Flash Wirepas Application” [3] 

Make sure you go through them to set up your system prior to this How-To. A computer running Windows 10 operating system is needed, and a code editor, such as Microsoft Visual Studio Code available here can be useful. It is also possible to build it with a Linux OS, but the steps are not documented.

It helps also to go through “How To set up and use your first Wirepas local network” [4], which explains how to use Wirepas Terminal, how to prepare sinks and nodes, and how to communicate with the network with an evaluation application. 

Requirements

Hardware:

This How-To makes use of widely available reference boards. You need to have at least 5 boards:

• One used as a sink Node and connected to a PC via USB (to use Wirepas Terminal), OR connected to a gateway (to use pythons scripts to test communication).
• At least 4 boards to be used as nodes in the mesh network. Each board should have at least 2 buttons and one led.

Table 1 below gives the boards that are supported. Sink and nodes do not need to have the same radio chipset to be compatible with each other.  

Table 1: Wirepas Massive nodes’ role allowed depending on the target device 

USB cables (type A male USB to micro USB) to connect the boards to either a USB power supply or computer. 

Software & System:

• A computer running Windows 10 operating system
• Wirepas Terminal (Installation procedure is described in Step 1 of the document [4]).
• Wirepas Massive SDK >= v1.2.1

Getting Started

The application demonstrates some functionalities associated with the Low-Latency mode of operation. Low-latency is a node’s operation mode that intent to maximize communication performance with minimal latencies. It is for example well suited for Lighting application when both local communication and low latency are obviously required. 

This application also demonstrate the Adaptive Flooding feature, which consists on sending messages through the radio range independently of the established mesh routes. It is demonstrated for both node to node and downlink communications. 

Please refer to Wirepas Massive concept document [1] to learn more about Low-latency mode of operation and Adaptive Flooding. 

To summarize, this example application demonstrate the following functionalities : 

• Low-Latency
• Node to Node adaptive flooding in Broadcast addressing mode.
• Downlink adaptive flooding in Unicast, Multicast, and Broadcast addressing mode.

In the next chapter, you will set-up the demonstration in 4 steps : 

• Configure the gateway (optional)
• Build the application
• Flash the application on the nodes
• Configure Wirepas Terminal

Then you will be able to communicate with the network either through Wirepas Terminal, or via Wirepas MQTT Library Python script provided.

Set-up overview 

There is two possibilities to run this application. The simpler is to use only sinks and node and connect the sink to a PC running Wirepas Terminal software as the following picture shows : 

In this case, the communication can be done through the Wirepas terminal, as explained in the “Sending message with Wirepas Terminal” part below.

The second option is to set-up also a Wirepas Gateway, that can be connected to a Backend, or used with a local broker in case you use a Raspberry Pi prebuilt image [6].

The following drawing shows the corresponding setup : 

In this case, the script provided in the backend_scripts folder can be used to send messages, as explained in the “Sending message with backend script” part below.

• One sink, flashed with the dualmcu-app reference application provided in the Wirepas SDK in source/reference_apps folder.
• Four nodes, flashed with the low-latency-app provided in the Wirepas SDK.
• Eventually a Gateway, flashed as explained in the “How to set up a Gateway” document [5].

The nodes are connected wirelessly to form a Wirepas massive network. Four nodes are needed to properly demonstrate the multicast feature. The sink board is connected through USB to a PC running Wirepas Terminal. The Low-latency application will be flashed on the nodes, and the Dual-MCU application on the sink board. 

The application support the following use cases : 

• Send Data :
  • Packet “Button pressed” : Node to node adaptive Flooding in Broadcast. Sent to all nodes when a button is pressed on a board to switch light ON/OFF 
• Received Data : 
  • Packet to switch the led state (Reception of the Node-to-node “Button Pressed” message). 
  • Packet to set the led’s state (Downlink message).
  • Packet to add a node to a multicast group (Downlink message).

Set up the system step-by-step

The Low-latency example is located in the <sdk install path>/wm-sdk/source/example_apps/low-latency_app folder directory. 

Step 1 : Configure the gateway

The gateway can be configured following the process described in the “How to configure a gateway” [5] document. 

Be careful to fill the files gateway.env and sink.env with the same parameters used to build the application : network address, and channel discovery address.

Step 2 : Configure the Sink

The sink can be flashed with the “dualmcu_app” and configured as explained in the “How To set up and use your first Wirepas local network” [4], step 2.

Step 3 : Build the application

To build the application use the following command :

docker run --rm -v <path-to-wirepas-sdk>:/home/wirepas/wm-sdk -w /home/wirepas/wm-sdk -ti wirepas/sdk-builder:<tag version> make app_name=low_latency_app target_board=<BoardName>

where

• <BoardName> is the target board you are using listed in table 1 of this document [ref].
• <path-to-wirepas-sdk> is your SDK installation path with unix path format and not Windows one (i.e with “/” and no “\” between folders).
• <tag version>is the Wirepas SDK build environment version.
  • For all Wirepas Massive stack v5.x the tag version is v1.2

Step 4 : Flash the application on the nodes

Once the build is successful, the application can be flashed on a board following the document “How To Flash Wirepas Application” [3] document, step 3. Depending on the board you are using you may use or Simplicity Commander or nrfjprog to flash the nodes with the application. 

The following command can be used to flash nrf boards : 

nrfjprog.exe --recover

nrfjprog.exe -f NRF52 --program <path to your application file>\final_image_<application name>.hex --reset --verify

using <your sdk path>/build/<your board name>/low_latency_app/final_image_low_latency_app.hex as application path.

To flash a silicon lab board you may use the following commands : 

.\commander.exe device unlock --device <device name>

.\commander.exe flash <path to your application file>\final_image_<application name>.hex --address 0x0

Use the same application path as the previous one but for the correct board name (tbsense2 folder).

Step 5 : Configure Wirepas Terminal

Once all your nodes and sink are flashed, you can configure Wirepas Terminal as follow : 

• Open Wirepas Terminal. This window appears : 

Click on “File” → “Open direct connection” and select the COM port corresponding to your Sink. Select also in the field “Device type” the “Custom Device (125000 bps). Then click OK. To check the sink status, click on “Tools” and “Status Report”. The connection must be established as follow :

In the same way you can check that your nodes are present in “Tools” and “Neighbor Report”.

How to use the Low Latency example application

The below procedure can be used to demonstrate the functionalities of the low-latency Application : 

1. Node to node message

This message is made to demonstrate the node to node adaptive flooding functionality. 

Once a button is pressed on one node (but not the sink), this node will send a message through wireless connection directly to other nodes to switch a led ON or OFF, depending on which button was pressed. 

The following diagram shows the repartition of the buttons on both Nordic and Silicon Labs boards and the associated functionalities : 

Use cases example : 

• Yellow button pressed on one node board ==> A led switches ON on each other node board.
• Red button pressed on one node board ==> The led switches OFF on each other node board.

2. Downlink broadcast, multicast or unicast message

An other switch ON/OFF message can be sent with adaptive flooding downlink from the sink to the nodes, in Unicast (only to one node), Multicast (to some nodes identified by the same group address), or in Broadcast (to all the nodes in the network). This message can be sent using Wirepas Terminal or the backend python script contained in the “backend_scripts” folder. Both of the methods will be presented.

Sending message with Wirepas Terminal : 

• The source and destination endpoints are y default set to 25 in this application. To know more about the endpoints, refer to the “Wirepas Massive Concept” [1]. In the main Wirepas Terminal window bottom configuration menu, enter 25 in “From Endpoint” and “To Endpoint” fields.
• Depending on which type of send you want, the “To address” field must be fill as follow : 

Note: Default multicast value set is 0x80000001.

• Fill the “Data to send” field. The message to send is composed as follow : 

So for example, to send a set led 1 on message, the “Data to Send field will be filled with “0x020101” : 

Sending message with backend script : 

Open a new command window and navigate to the “backend_scripts” folder in the Low_latency application folder. 

Launch the “script_lowlatency_app” by typing the following command : 

py script_lowlatency_app.py -s <MQTT broker host address> -p <MQTT broker port> -u <username (optional)> -pw <password (optional)> -fu

Where : 

• <MQTT broker host address> is the address of your MQTT broker, for example “wirepasdemo.prod-wirepas.com” if you have a backend instance, or you can use the IP address of your gateway to connect to the built-in broker. 
• <MQTT broker port> which is usually 8883, and 1883 for built-in broker. 
• -fu option is used to indicates the broker to use unsecure connection.

Once the command is properly sent, you must see the following proposals : 

Three commands can be sent : send_led_on_command, send_led_off_command and send_multicast_grouping. 

“send_led_on_command” and “send_led_off_command” correspond to this downlink message, and can be sent with the following options : 

 send_led_on_command <gateway_name> <sink_name> <destination address>

Where:

• <gateway_name>, <sink_name>are respectively the name of the gateway and the sink set in the gateway.env and sink.env (refer to the “Configure the gateway” part of this document to recover them.)
• <destination address> can be either : the id of the node you want send the instruction to in case of a unicast send; a multicast group address, to send to all nodes in a multicast group; or the broadcast address : “to send to all nodes in the network. 

This command will by default set led 1 of the selected node ON or OFF.

3. Multicast grouping message

The last command that can be received by the low_latency_app is the “grouping” command, which contains a multicast id that will be applied to the node concerned. This means that the node is added to the Multicast group, and will receive the multicast commands. 

Sending message with Wirepas Terminal :

The same procedure as described for the downlinks messages can be used, with Wirepas terminal. This command can be send in unicast to set a new multicast group for only one node, or in Multicast to change the multicast address for all nodes in the group. 

The multicast address has a specific format, on 32 bit, contained between 0x80000000 and 0x80FFFFFF. For example, to add a node to the group number 2, the multicast group address sent will be 0x80000002.

Caution : The multicast address must be send in little endian.

For example, to change the multicast address to 0X80000004, the command to send will be “0x0304000080”

Sending message with backend script : 

With the backend script, the command is send_multicast_grouping, and can be used as follow : 

send_multicast_grouping <gateway ID> <sink ID> <destination address> <multicast address>

Where

• <gateway ID>, <sink ID> and <destination address> are the same parameters as those described for the previous command
• <multicast address> is the new multicast address that will be set to one or several nodes, depending on the destination address used. 

References

[1] Wirepas Massive concepts
[2] How to install SDK and build an application
[3] How to flash Wirepas application
[4] How To set up and use your first Wirepas local network
[5] How To set up a Gateway on Raspberry pi
[6] Wirepas gateway images

Revision History

Legal Notice

Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.

Copyright © 2021 Wirepas Oy