Status

Date

Doc Version

Applicable

Confidentiality

RELEASED

v1.4

Wirepas Massive v5.1 and v5.2

PUBLIC

Introduction

In this How To you’ll build a functional local Wirepas Massive Network with 3 nodes. You’ll be able to send and receive traffic to and from nodes from a local terminal software running on a PC.

What you'll learn

  • The basic roles and network parameters in Wirepas Massive and how configuring them
  • Building and Flashing nodes
  • Using Wirepas Terminal software
  • Configuring a sink node
  • Sending and receiving from and to node(s)
  • How a simple evaluation application is structured

What you’ll need

Prerequisites

This “How To” assumes you already have a working Wirepas build environment and that you are able to flash a board as described in documents:

  • “How To Install SDK and Build an Application” [1]
  • “How to Flash Wirepas Application” [2]

Make sure you go through them to setup your system prior to this How To.

Requirements

Hardware:

This How To makes use of widely available reference boards. You need to have a minimum of 3 boards:

  • One used as a sink Node and connected to a PC via USB
  • A minimum of 2 boards used as Nodes being part of the mesh network.

Table 1 below gives the boards supported and which node’s role are compatible. Sink and nodes do not need to embed the same radio chipset to be compatible with each other. Make sure to comply with Note 1 & 2. 

Chipset

Device

Board part number

Node’s role

nRF52832

nRF52832 Nordic development kit board 

nRF52 DK

sink and node

Ruuvi tags

RUUVITAG

node only

nRF52833

nRF52833 Nordic development kit board 

nRF52833 DK

sink and node

nRF52840

nRF52840 Nordic development kit board 

nRF52840 DK

sink and node

EFR32xG12

Silicon Labs TBSense2 SLTB004A board

SLTB004A

sink and node

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

  • Note 1 : Ruuvi tags cannot be configured to act as a sink but only as a node.
  • Note 2 : In case a RUUVI tag is selected as a node platform in order to be able to program it, it is highly recommended to buy a “RUUVI devkit“. More info available here and here

USB cables (type A male USB to micro USB) to connect the boards to either a USB power supply or computer (Ruuvi boards being battery operated do not require a USB cable).

Software & System:

  • A computer running Windows 10 operating system
  • Wirepas Terminal (Installation procedure is described below)
  • Wirepas Massive SDK >= v1.2.0

Getting Started

In this How To we will set up a local network composed of 3 nodes configured as below:

  • One supported device which will be programmed to act as a sink 
  • Two other devices also from the supported hardware programmed to act as mesh capable nodes

The sink will be connected to a computer via USB running Wirepas Terminal to be able to interact with the network. The nodes are connected wirelessly to form a Wirepas Massive network.

The nodes will be flashed with an Evaluation application which will allow to send and receive data from nodes via a Terminal software running on a PC and connected to the sink via USB

The following figure illustrates the setup

The Evaluation Application available from Github will be used to exchange data between the Terminal and the nodes. 

The application supports the following use cases:

  • Receive data
    • periodic data packet consisting of a counter value and an easy to spot data pattern
    • packet notifying a node’s button is pressed
    • packet giving the requested node’s LED state (i.e ON or OFF)
    • packet giving the packet travel time from sink to node in response to a calculation request
  • Send data
    • packet to set the period of the periodic data packet
    • packet to change a node’s LED state (i.e to switch it ON or OFF)
    • packet to request a node’s LED state (i.e is it switched ON or OFF ?)
    • packet to request packet travel time (from sink to node)

Four steps are proposed in this How To to setup this network and interact with it:

  • Step 1: Wirepas Terminal Setup
    Wirepas Terminal supports the Wirepas Dual MCU API [6] and offers a way to receive and send data from and to the mesh nodes 
    Note : this tool is not available for Linux and Mac operating systems. 
  • Step 2: Prepare the sink
     Compile and flash the sink application with the generated programming file
  • Step 3: Prepare the Nodes
     Compile and flash the Node application with the generated programming file and verify that network is properly configured
  • Step 4: Communicate with the Network

Step 1 : Wirepas Terminal Setup

This section lists the instructions to follow to install the Wirepas Terminal software.

Wirepas Terminal is a Microsoft Windows compatible software that can be used to connect to a sink from a computer typically via UART over USB connection. It allows to configure a Wirepas network, to display message coming from the network and to send single data messages or to automatically send messages with a specific time interval to network node (unicast, broadcast and multicast address mode are supported).

Follow the instructions given in the Wirepas Terminal Installer [4] document to download and install the software. The installer file is available at the end of the document. 

Finally you can refer to the Wirepas Terminal User Guide [5] for more information about how to use the tool.

Step 2 : Prepare the sink

In this step we will prepare and flash the application running on the sink device (entry/exit point of the network). In this document Nordic nRF52832 development kit will be used as reference but the same procedure can be easily applied with the other supported hardware platforms.

A sink must be programmed with a dedicated application called “dualmcu_app“. The dualmcu_app essentially exposes the Wirepas API over Serial Port (UART) called “Dual MCU API”. The Dual MCU API is described in Wirepas Massive Dual-MCU API Reference Manual [6].

The dualmcu_app is mainly used in 2 cases:

  • Inside Gateways where the node is configured as a sink and where Wirepas Gateway drivers implement the Dual-MCU API (available here)
  • Inside a dual MCU system where the radio chipset is connected to a second MCU

In both cases, the host CPU side can implement the C-Mesh API delivered as an open source component from Wirepas and available here.

The dualmcu_app is available from the Wirepas Massive SDK and does not require any modification. Its source code can be found in the SDK’s source folder.

Build the dualmcu_app application 

In order to build the application, the following command format is used :

docker run --rm -v <absolute path to Wirepas SDK folder>/wm-sdk:/home/wirepas/wm-sdk -w /home/wirepas/wm-sdk -ti wirepas/sdk-builder:<tag version> make app_name=<application name to build> target_board=<board name used for node> 

where:

  • <absolute path to Wirepas SDK folder>is the absolute path to the folder where Wirepas SDK is stored. 
    • For instance if the SDK is located in C:\dev\ then the full field value will be /c/dev/wm-sdk
      • Note : relative path (e.g ../dev/wm-sdk) are not supported
  • <tag version>is the Wirepas SDK build environment version.
    • For all Wirepas Massive stack v5.x the tag version is v1.2
  • <application name to build>
    • SDK folder name where is stored the application code to build
      • In this case it is “dualmcu_app
  • <board name used for node>
    • Board name used to implement the node functionnality (see translation table below)
      • Note : see “TARGET_BOARDS“ variable in “<absolute path to Wirepas SDK folder>\wm-sdk\source\reference_apps\dualmcu_app\config.mk” to know which board are supported and what name to use
      • In this case, a nFR52832 development kit board is used so the field value is pca10040

Device

command line “board name“

nRF52832 Nordic development kit board

pca10040

nRF52833 Nordic development kit board 

pca10100

nRF52840 Nordic development kit board

pca10056

Silicon Labs Thunderboard Sense 2 SLTB004A board

tbsense2

Assuming the Wirepas SDK is located into “C:/dev/” folder, the target board is “pca10040“ and the Wirepas build environment version is 1.2 the following command is used : 

docker run --rm -v /c/dev/wm-sdk:/home/wirepas/wm-sdk -w /home/wirepas/wm-sdk -ti wirepas/sdk-builder:v1.2 make app_name=dualmcu_app target_board=pca10040

Flash the dualmcu_app application 

After the build step is successfully executed, all the generated files are located in “<path to Wirepas SDK folder>\wm-sdk\build\<board name used for node>\dualmcu_app\”. Among all the generated file, only one is of interest for this How To : final_image_dualmcu_app.hex .

Follow the instructions described in the document How to Flash Wirepas Application [2] to flash the file final_image_dualmcu_app.hex to the sink device.

Once the flashing operation is completed the sink is almost ready, only the network parameters and node settings have yet to be defined using the Wirepas Terminal tool.

Configuring the sink node with Wirepas Terminal

Plug-in the sink Node to PC via USB connection (make sure the board is switched on if you use a nRF52xxx development kit)

Open Wirepas Terminal software on your computer, the following window is displayed

Select File → Open Direct Connection and in the new displayed window select the proposed JLink device COM port and set Device Type as Custom device (125000bps) regardless of the target board used as the sink as shown below. Click OK to save the UART configuration.
Note : 125000bps is the default value used in the dualmcu_app code.

If the UART configuration is successful then the message “Connection opened to COMx” is displayed in the terminal.

By default the Wirepas Massive parameters are not configured in the sink. Minimum parameters to configure are:

  • Node address: A unique 32 bit number is used as a node address or node ID(identifier). The Node address identifies uniquely a device in a given network. All devices in the network must have different node addresses.
  • Network address: A unique 32 bit number is used as a network address, which is shared by all nodes in the network. All nodes in a given network must have same Network address.
  • Network channel: The network channel is the discovery channel (i.e radio channel used by default by all nodes within a network to discover each other). It has to be common for all nodes in the same network. Wirepas Massive uses 40 channels (1 to 40) on 2.4GHz based radio nodes.
  • Node Role: Node role sets the node’s behavior. A node can be configured as :
    • SINK: usually a node attached to a gateway – the other nodes will optimize the routing to access the sink
    • AUTOROLE: the node will be able to route depending on the network need for routing, it will automatically enable or disable its routing
    • HEADNODEthe node will be a router whatever the state of the network
    • SUBNODEa node which does not route (usually to save battery life)

Now let’s configure the sink node. To configure it select Tools → Node settings

  • In this How To the following node parameters have been selected and configured in the Node application “evaluation_app”. They must be aligned in the sink settings as described below:
    • Node Address = 1
    • Network Address = 0xD8D42B
    • Network Channel = 9
    • Node Role = Sink with Low-Latency

To configure the sink just apply the proper parameters in the Wirepas Terminal tool, don’t forget to press “Apply” for each line you modify. Other parameters are not used in this How To and can be left empty.

Now the sink node configuration is done. The next step is to set up the nodes and verify everything is properly configured before starting to experiment the Wirepas network capabilities.

Step 3 : Prepare the Nodes

In this step we will prepare and flash the application running on the Node devices. For this document’s purpose, the same hardware platform as the one for the sink will be used as a node.

The evaluation_app application is available from the Wirepas Massive SDK and does not require any modification. Its source code can be found in the SDK’s example_apps source folder.

Build the evaluation_app application

Let’s first look at the different files available in the evaluation application by going through the following folder:

<installation path of Wirepas SDK>\wm-sdk\source\example_apps\evaluation_app\

Three files are present : 

  • app.c: This files contains the application code which will run on the nodes. It is tightly integrated with the Wirepas Massive stack.
  • config.mkThis file contains the application specific parameters passed at compile time such as which boards are supported and what are the network parameters. You can see the same Network parameters as the one previously configured in the sink are used in this file. The device ID is automatically generated from the chipset ID. Please note these parameters cannot be edited with the Wirepas Terminal. One example of the file structure is listed below:
# Boards compatible with this app 
TARGET_BOARDS := pca10040 pca10056 pca10100 ruuvitag  tbsense2 
#
# Network default settings configuration
#
 
# If this section is removed, node has to be configured in
# a different way
default_network_address ?= 0xD8D42B
default_network_channel ?= 9
# !HIGHLY RECOMMENDED! : To enable security keys please un-comment the lines below and fill with a
#                        randomly generated authentication & encryption keys (exactly 16 bytes)
#default_network_cipher_key ?= 0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??
#default_network_authen_key ?= 0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??,0x??
 
#
# App specific configuration
#
 
# Define a specific application area_id
app_specific_area_id=0x8CEC79
 
#define node operating mode (i.e low-energy or low-latency : 0 => low-energy / 1 => low-latency)
default_operating_mode ?= 0
 
# App version
app_major=1
app_minor=0
app_maintenance=0
app_development=0
  • makefile: this file contains the application specific compilation option such as which external library to use, which additional source file to compile.

For the purpose of this How To, the files don’t need any modification. Additional information can be found in “Wirepas mesh SDK/SDK file structure/source/Application examples“ section of the Wirepas SDK documentation [7].

Then use this command format to build the app :

docker run --rm -v <absolute path to Wirepas SDK folder>/wm-sdk:/home/wirepas/wm-sdk -w /home/wirepas/wm-sdk -ti wirepas/sdk-builder:<tag version> make app_name=<application name to build> target_board=<board name used for node> 

where:

  • <absolute path to Wirepas SDK folder>is the absolute path to the folder where Wirepas SDK is stored. 
    • For instance if the SDK is located in C:\dev\ then the full field value will be /c/dev/wm-sdk
      • Note : relative path (e.g ..\dev\wm-sdk) are not supported
  • <tag version>is the Wirepas SDK build environment version.
    • For all Wirepas Massive stack v5.x the tag version is v1.2
  • <application name to build>
    • SDK folder name where is stored the application code to build
      • In this case it is “evaluation_app
  • <board name used for node>
    • Board name used to implement the node functionnality
      • Note : see “TARGET_BOARDS“ variable in config.mk to know which board are supported and what name to use. The same table from the “Prepare sink” step can be used to know the correspondance between hardware platform and board name to use in build process if Silicon Labs or Nordic semiconductor development kits are selected as node. In case of RUUVI tag command line “board name” is “ruuvitag
      • In this case, a nFR52832 development kit board is used so the field value is pca10040 

A full command will look like : 

docker run --rm -v /c/dev/wm-sdk:/home/wirepas/wm-sdk -w /home/wirepas/wm-sdk -ti wirepas/sdk-builder:<tag version> make app_name=evaluation_app target_board=pca10040

Note: <tag version> must be replaced by the proper Wirepas build environment version.

Flash the evaluation_app application

After the build step is successfully executed, all the generated files are located in <path to Wirepas SDK>\build\<board name used for node>\evaluation_app\. Among all the generated files, only one is of interest for this How To : final_image_evaluation_app.hex .

Note: Information about the other generated files can be found in “Wirepas mesh SDK/SDK file structure/makefile” section of the Wirepas SDK documentation [7].

Use the same process as the one followed to program the sink. In case of RUUVI tags with a RUUVI devkit the process is exactly the same as with Nordic Semiconductor development kits. 

The final step is to check everything is working as expected.

Verify setup is properly configured

At this point the setup should be like this assuming nRF52DK is the selected platform for all nodes

Now let’s connect the sink node to the PC via USB and the 2 other nodes to a USB power source.

  • Select File → Open Direct Connection and in the new displayed window select the proposed JLink device COM port and set Device Type as Custom device (125000bps) regardless of the target board used as the sink. Click OK to save the UART configuration.
  • Start the sink node Massive stack by clicking: Tools → Start Stack. Just after having selected the “start stack“ option the message ”Stack started” message should be displayed in the terminal console. At this stage the stack is started and the node will establish the connection to it.
  • Wait for some time (30 seconds should be enough)
  • To check the nodes are seen by the sink select Tools → Neighbor Report.
  • If all the nodes are properly configured the terminal console should look like the image shown below and some data packet might already have been received (see “Periodic message“ section for details). Two sink’s neighbors should be detectedif the two nodes are switched on.
    • Note : if this is not the case wait for some more time and retry or go to the “troubleshooting“ section of this manual. Otherwise the setup is up and running and it is possible go to the next step

Step 4 : Communicate with the Network

The evaluation application embeds some use cases to send and receive data from the nodes, the objective for the user is to understand how a message is sent or received from a sink node.
 The services offered by the evaluation application are as follow and how to invoke them will be explained in the next sections:

  • Receive messages from a node to the sink:
    • a periodic message is sent at a configurable interval
    • a message is sent when a button is pressed
  • Send a message from the sink to a node or all nodes:
    • to control the LEDs state (i.e switch ON or OFF) 
    • to change the period of the periodic message
  • Send a command message and receive its response
    • to know the LED state (i.e is the LED ON or OFF ?)
    • Echo command to know the packet travel time from sink to node(s)

The next chapters describe how to exercise those different scenarios, we recommend you follow them in the logical order as they gradually add features.

Receive data from the network

The goal here is to receive messages from node(s) either generated automatically (periodic message) or triggered by the user via a button. 

Before going into the description of the packet received, let’s see the different fields in the terminal.

Terminal message structure description

For a received single message, the log window will show

  1. Information of the received message including
  2. the date and time when the message was received from the connected device's Wirepas Massive stack (1)
  3. number of application data payload bytes in the message (1)
  4. the source node address (1)
  5. the source and destination endpoint (EP) (1)
  6. The travel time of the message in seconds (i.e. the network delay) (1)
  7. the QoS class (1)

2. Dump of the received message content, including

  • hex dump offset (2)
  • hex dump of the application data payload (3)
  • A text dump of the application data payload (4)

Periodic message 

This message is sent by all nodes at a regular (configurable) interval. This message requires no further action from the user as with its default parameters the application flashed into the nodes sends a data packet every ten seconds. Messages coming from the two nodes should be displayed in the terminal console.

The extract of the Wirepas terminal console given below illustrates two successive periodic packet (coming from the same node) dumped in hexadecimal format :

Periodic message description

The received data bytes are 00 xx xx xx xx 0A 0B 0B 0A 0A 0C 0D 0C and are encoded as follow:

  • first byte => message ID (fixed)
  • following 4 bytes => Running counter value(starting from 0 with an increment step of 1)
    • For instance if the value is 01 00 00 00 then 01 is the LSB byte and 00 the MSB byte
  • last 8 bytes => easy to spot fixed data pattern

Button pressed notification

Each supported node’s hardware platform has some buttons available to the user. The application running on the node sends a message every time a user button is pressed. The images given below show on each node supported hardware (Nordic development kits, Silabs tbSense2 and RUUVI tag) which buttons can generate a message : 

  • Nordic semiconductor development kits
    Note : the picture below display a NRF52833DK development kit but the same buttons are used for all the other development kit (i.e NRF52DK and NRF52840DK)

  • Silicon Labs Thunderboard Sense 2

  • RUUVI tag

For instance if on a Nordic development kit all buttons are successively pressed, the following extract of the Wirepas terminal console showing the packet data received (in hexadecimal format) can be obtained.

Button pressed message description

The received data bytes are 01 xx 02 and are encoded as follow:

  • first byte => message ID (fixed)
  • second byte => Button ID(a value of 0 corresponds to the first available user button on the board)
    • For instance if the value is 01 then the second user button was pressed
  • third byte => Button state (i.e pressed or not) expressed in binary format (a value of 2 indicates a press action).
    Note : A value of 2 must always be returned as the pressed action is the only one implemented in the node’s application

Sending data to the network

This chapter describes how to send data to the network to first change the periodic message’s period and then to control some LEDs available on the nodes.

Set periodic message period

It is possible to change the received message period from one node (unicast addressing mode) or from all at the same time (broadcast addressing mode) by sending an application specific packet. 

To do that, in the Wirepas terminal, the fields inside the red frames shown on the figure below must be filled.

  • Set the “type“ field on hex value
  • Enter these bytes into “Data to send”
80 B8 0B 00 00
  • Note : Bytes values are in hexadecimal format (LSB first) and it sets the period to 3 seconds.
  • Configure the endpoints and address like this (all values given below are expressed in decimal format except the one starting with the 0x prefix) :
    • From endpoint 
      • For this node’s application all messages are mapped to endpoint 1 as source endpoint, so enter the value 1
    • To address
      • the value to enter here will depend on the addressing mode used
        • in case of broadcast mode the value 0xFFFFFFFF is required
        • in case of unicast mode the value to select is the address of the node you want to send the packet to. 
          • To get a list of all the available node select Tools → Neighbor Report and wait for the report to appear in the terminal console.
          • Then seek for the following field (red square on the below image).
            Note : the values displayed will be different from the ones shown above

  • To endpoint
    • For this node’s application all messages are mapped to the endpoint 1 as destination endpoint, so entre the value 1
  • Finally click on the send button

The extract of the terminal console given below shows an example of the obtained output once the data are sent.

After the terminal message “PDU ID x sent“ (where “x” can be any number) is displayed a new message should be received every 3 seconds.

Set periodic message description

The set periodic message data bytes are 80 xx xx xx xx and are encoded as follow:

  • first byte => message ID (fixed)
  • following 4 bytes => period value expressed in millisecond. The minimal allowed period is 2 seconds. The maximal one is 20 minutes. If an invalid period value is given it will not be updated at the node side.
    • For instance if the value is B8 0B 00 00 (sets a 3 seconds period) then B8 is the LSB byte and 00 is the MSB byte.

Control LEDs state

Each supported node’s hardware platform also features some LEDs available to the user. The application running on the nodes gives the possibility to control them individually (i.e switch ON or OFF). 

Moreover, depending on the network address mode used (i.e unicast or broadcast) it is possible to control only LEDs from one or from all nodes available at the same time. The images given below show on each node supported hardware which LEDs can be controlled : 

  • Nordic semiconductor development kits
    Note : the picture below display a nRF52833 development kit but the same LEDs are used for all the other development kit (i.e 832 and 840)

  • Silicon Labs Thunderboard Sense 2
    Note : Both red and green LEDs are used

  • RUUVI tags

To set a LED state the same process as the one from the setting periodic message period paragraph must be followed except the commands data from below (given in hexadecimal format) have to be used :

#### Switch ON
    81 00 01  // to switch ON led #1
    81 01 01  // to switch ON led #2
    81 02 01  // to switch ON led #3 (only if node's hardware platform is NRFxxx development kit)
    81 03 01  // to switch ON led #4 (only if node's hardware platform is NRFxxx development kit)
 
#### Switch OFF
    81 00 00  // to switch OFF led #1
    81 01 00  // to switch OFF led #2
    81 02 00  // to switch OFF led #3 (only if node's hardware platform is NRFxxx development kit)
    81 03 00  // to switch OFF led #4 (only if node's hardware platform is NRFxxx development kit)
  • Note 1 : There is no way to set all node’s LED on or off from a single message.
  • Note 2 : on Silicon Labs Thunderboard Sense 2 the green LED is led #2 and the red one the led #1.
  • Note 3 : on RUUVI tag the red LED is led #1 and the green one the led #2
  • Note 4 : if an invalid LED ID is given (e.g only two LEDs on the board but value 3 is sent) then at the node side the command will not be considered valid but no message will be displayed in the terminal console.

If the nodes are configured in low-energy mode (default Evaluation application’s mode) then a delay between the click on the send button and the effective LED action being applied will be observed. Now if the low-latency mode is used the delay will not be perceptible. 

An extract of the Wirepas terminal console given below illustrates the full log of the LED setting process.

After the terminal message “PDU ID x sent“ (where “x” can be any number) is displayed the command is sent to the node.

LED control message description

The LED control message data bytes are 81 xx xx and are encoded as follow:

  • first byte => message ID (fixed)
  • second byte => LED ID (a value of 0 corresponds to the first available user LED on the board)
    • As example, value 01 will state the second user LED on the board will change 
  • third byte => LED state (a value of 0 tells to switch the LED off and a 1 to switch it on)
    • As example, value 01 will turn the LED on

Sending a command and receiving its result

This section will focus on the communication with the network where a request to be processed by the nodes is sent and a node response is received. To demonstrate this functional aspect two process are implemented into the node. The first one is to request node’s LED state (i.e switched ON or OFF) and the second one is an echo request were we can get the roundtrip travel time of a message.

Get LEDs state

One of the following commands (given in hexadecimal format) shall to be send to the network to request a LED state using the same procedure as before : 

#### Requesting LED state
    82 00 // to request led #1 state
    82 01 // to request led #2 state
    82 02 // to request led #3 state (only if node's hardware platform is NRFxxx development kit)
    82 03 // to request led #4 state (only if node's hardware platform is NRFxxx development kit)
  • Note 1 : There is no way to request from a single message all node’s LED state.
  • Note 2 : if an invalid LED ID is given (e.g only two LEDs on the board but value 3 is sent) then at the node side the command will not be considered valid but no message will be displayed in the terminal console.

Get LEDs state message description

The Get LEDs state message data bytes are 82 xx and are encoded as follow

  • first byte => message ID (fixed)
  • second byte => LED IDfrom which to get state (a value of 0 corresponds to the first available user LED on the board)
    • For instance, if the value is 01 then the state of the second user LED on the board is requested

When the request is received by the intended node (unicast addressing mode) or all nodes (broadcast addressing mode) the LED state will be sent back.

An extract of the Wirepas terminal console given below illustrates the full log of the LED state process.

Get LEDs state response message description

The Get LEDs state response message data bytes are 03 xx xx and are encoded as follow

  • first byte => message ID (fixed)
  • second byte => LED ID from which state is requested (a value of 0 corresponds to the first available user LED on the board)
    • For instance, if the value is 01 then the state of the second user LED is provided
  • third byte => LED state (a value of 0 indicates LED is switched off and a value of 1 it is switched on)
    • For instance, if the value is 01 then the LED is switched on

Echo Message (from sink to node)

The Echo message consists of a message received after an Echo message is sent. The Echo message also includes the downlink message travel time and can be used to calculate the round trip delay of a message.

The Echo message consists of a packet send to a node or a group of node with the payload 0x83.

To start the process, just send the hexadecimal value 0x83 from the Wirepas terminal to the targeted node. After a short time (a few seconds by default if nodes are in low-energy mode), the response message is received.

The extract of the Wirepas terminal console given below illustrates the full process of the “echo“ message with a focus on the received response.

The first data dump is the “echo” message request then the next printed message indicates the packet was sent to the sink

After the message has been received by the destination node, the “echo” response message is sent and then received on the terminal. This message includes the travel time of the echo request (the message from the sink to the node(s)).

The Echo response message data bytes are 02 xx xx xx xx and are encoded as follow

  • first byte => message ID (fixed)
  • following 4 bytes => Packet travel timefrom sink to node in milliseconds
    • For instance, if the value is CF 18 00 00 then CF is the LSB byte and 00 the MSB byte. So it gives 6351ms or 6.351 seconds

With this final description, all the functions implemented by the node’s application are covered.

Going further

In this How To, a simple Wirepas network consisting of one sink and two nodes was set up. The communication principles with such a network were exposed. Now to go further two path can be followed:

  • the first one is to understand how the node application works. To that end, the Wirepas SDK documentation [7] and “evaluation_app“ readme file will help in addition to the source code of the “evaluation_app”
  • the second one is to add to the network the blocks required to allow a remote communication process with it (i.e access from different places and with multiple users).

Troubleshooting

No neighbors reported by the sink in Wirepas terminal

If when requesting a sink neighbor report from Wirepas terminal, no neighbors are reported check that the nodes are powered ON (i.e they are connected to a USB power supply). In case Nordic Semiconductor development kits verify the board’s power switch is on the “ON“ position.

Frequently Asked Questions

Q: How can I change the node operating mode (i.e from Low-Energy to Low-Latency) ?

A: The node operating mode is an option embeded into the application running on the node. It is configured at compile time. To change it, open the file “config.mk“ in <installation path of Wirepas SDK>\wm-sdk\source\example_apps\evaluation_app\ and then edit the following field:

#define node operating mode (i.e low-energy or low-latency : 0 => low-energy / 1 => low-latency)
default_operating_mode ?= 0

If its value is then the node operates in Low-energy and if the value is 1 then the Low-latency mode is selected.

Note 1: The sink operating mode should not be changed and stay configured in Low-latency mode.

Note2: If RUUVI tags are used as node and battery powered it is not advised to enable the Low-latency mode as it significantly increases the power consumption (autonomy is reduced to a few hours at best)

References

[1] How To Install SDK and Build an Application
[2] How to Flash Wirepas Application
[3] Wirepas Terminal v0.101 Release Notes
[4] Wirepas Terminal Installer
[5] Wirepas Terminal User Guide
[6] Wirepas Massive Dual-MCU API Reference Manual
[7] Wirepas SDK documentation

Revision History

Date

Version

Notes

v1.0

The first version.

v1.1

Fix incorrect path to sink settings menu in Wirepas terminal
Fix docker build command (to clean-up container’s file system)
Clarify compatibility matrix
 Typo, illustration and minor fixes

v1.2

Update to support v5.1 release

v1.3

Update Wirepas Terminal Installer links

v1.4

Add Wirepas build enviroment version

Legal Notice

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

Copyright © 2021 Wirepas Oy