Introduction

In this How to you will see how to communicate with a Wirepas Massive Network when a fully operational infrastructure is set up by relying upon the Wirepas gateway to Cloud API. 

What you’ll learn

• Communicate with a Wirepas gateway from an MQTT client coded with Python
• Send and receive data from and to the node(s) via a gateway (i.e. remote communication through the internet)
• What is “Wirepas-mqtt-library“ and how to use it
• How a simple remote communication script is structured

What you’ll need

Prerequisites

This how-to document assumes that you already have a Wirepas Massive network and a Gateway in place.

Please make sure you go through the 2 following documents to set up your system prior to this tutorial:

• “How To set up and use your first Wirepas local network“ [1].
• “How To set up a Wirepas gateway on a Raspberry Pi with Wirepas prebuilt image” [4]

Basic knowledge of Wirepas Massive is also needed and can be found in the “Wirepas Massive Concepts“ [2] document.

Requirements

Hardware:

• A configured Wirepas Massive network with [1]
• A configured Wirepas gateway with [4] and associated cables

Software & system:

• A computer running Windows 10 operating system.
• some knowledge of MQTT terminology (mostly: broker, client, publish, subscribe, topic).
  • this link and this one can be helpful.
• Internet connection to download software components.

Getting started

In this how-to guide, you will communicate with a Wirepas Massive network set up as described in [1] when full Wirepas network infrastructure is available (mesh nodes + gateway), using an MQTT client integrated into the Wirepas MQTT library and the Wirepas Gateway API. This API allows to send and receive data to and from nodes and also to control and monitor a Wirepas network. A full description of the API is given in [3]. One of the main targets of this architecture is to provide a standardized Gateway(s) that communicate with the Wirepas Gateway API via MQTT broker. The API can be used for data configuration, device management and Over The Air Programming [2].

You will build a simple setup to understand the concepts of this architecture with few nodes and one gateway with local communication. The same architecture can be applied to larger networks with several gateways and a cloud infrastructure.

The setup can be summarized like this:

• The Wirepas nodes connect to the gateway (to be precise, to the sink attached to it). 
• The gateway is configured to connect to its integrated MQTT broker, designated as “built-in” or “local” in the rest of the document. NOTE: The use of a local MQTT broker is only to simplify the setup in this how-to. In a production-ready network architecture, the MQTT broker is running on a cloud server to which all the gateways connect.
• A single script is used to communicate with the gateway and the network (the script is written with Python). The script allows to:
  • Connect to the local MQTT broker
  • Receive, decode and display messages, if configured in “viewer mode “ , sent by the network nodes running the Evaluation application 
  • Send command to the network, if configured in “controller mode”, where nodes run the Evaluation application

The figure below summarizes the setup:

Two steps are proposed in this how-to to set up the system and communicate with it:

Step 1: System setup

• Wirepas gateway configuration
• Software components installation

Step 2: Communicate with the network

1. Receive data from the Wirepas Massive network: to discover how to receive data from the network via the Wirepas gateway API. The script configured in viewer mode will be described and executed to receive and display the periodic message and the button pressed notification.
2. Send data to the Wirepas Massive network: to discover how to send data to the network via the Wirepas gateway API. The script in controller mode will be described and executed to control the state of node’s LED.
3. Send a command and receive its result: a combination of the two previous steps to cover the full message and command sets supported by the nodes running the evaluation application.

Step 1: System setup

In this step, you will configure the Wirepas gateway and install the required software components to run the script which allows communicating with the Wirepas Massive network.

Gateway setup

To set up a Wirepas gateway you should follow the instructions given in “How To set up a Wirepas gateway on a Raspberry Pi with Wirepas prebuilt image“ [4] document.

Two files, sink.env and gateway.env, need to be adapted to be inline with the network and gateway setup.

The file configuration is described below:

sink.env

#

# Initial Sink configuration

#

# Node address of the sink (Ex: 12345)

WM_CN_NODE_ADDRESS=1

# Network address (Ex: 0xA1B2C3)

WM_CN_NETWORK_ADDRESS=0xD8D42B

# Network channel (Ex: 2)

WM_CN_NETWORK_CHANNEL=9

# 16 bytes authentication key for the network (Ex:000102..0F)

#WM_CN_AUTHENTICATION_KEY=

# 16 bytes cipher key for the network (Ex:000102..0F)

#WM_CN_CIPHER_KEY=

# Set node role to sink csma-ca (shouldbn't be changed)

WM_CN_NODE_ROLE="sink csma-ca"

gateway.env

• WM_GW_SINK_UART_PORT=
  • /dev/ttyAMA0 if the sink is a raspberry Pi HAT
  • /dev/ttyACM0 (usually if the sink is a development kit board i.e from Nordic Semiconductor or Silicon Labs connected to a gateway’s USB port)
    Note: If you are not using the Pi HAT, a good way to know which value to use is to connect to the gateway using ssh. When you are logged in, execute the dmesg command before and after plugging the sink into the gateway. You should get the following output:

• WM_GW_SINK_BITRATE=125000
• WM_SERVICES_MQTT_HOSTNAME=localhost to use the built-in broker
• WM_SERVICES_MQTT_PORT=
  • 1883 (usually for insecure connection mode) if connecting to the local mqtt broker
• WM_GW_ID=wp_eval_app_gw
• leave WM_SERVICES_MQTT_USERNAME and WM_SERVICES_MQTT_PASSWORD lines commented
• uncomment WM_SERVICES_MQTT_FORCE_UNSECURE line and set parameter value to true

An example of how the gateway.env could look like after the configuration is given below in case a Nordic development kit, connected via USB, is used as a sink:

#

# Sink service configuration

#

# On which port the sink is attached (ex: /dev/ttyACM0 or /dev/ttyAMA0 if using a rpi hat)

WM_GW_SINK_UART_PORT=/dev/ttyACM0

# Uart bitrate of the sink. It depends on the build configuration of dualmcu_app (ex: 115200, 125000, 1000000)

WM_GW_SINK_BITRATE=125000

#

# Transport service configuration

#

# If you need more Mqtt settings; please check https://github.com/wirepas/gateway/blob/master/python_transport/wirepas_gateway/utils/argument_tools.py for additional parameters.

# Address of the broker to connect

WM_SERVICES_MQTT_HOSTNAME=localhost

# MQTT port (usually 8883 for secure access, or 1883 for unsecure)

WM_SERVICES_MQTT_PORT=1883

# Username to connect to broker

#WM_SERVICES_MQTT_USERNAME=

# Password to connect to broker

#WM_SERVICES_MQTT_PASSWORD=

# Uncomment following line to skip TLS check on brocker (uncomment it for local brocker)

WM_SERVICES_MQTT_FORCE_UNSECURE=true

# Gateway unique id (used also as mqtt client name)

WM_GW_ID=wp_eval_app_gw

The final action is to plug the Wirepas network sink to the gateway via a USB cable.

Software setup

Python interpreter should be installed on the host computer in order to run the script. It can be downloaded from here.

Note 1: At least a version 3.5 is required to ensure the proper operation of the script.

Note 2: Do not forget to check the “add Python 3.x to PATH“ when running the installer (see troubleshooting section for a detailed explanation).

Then the following additional Python module needs to be installed:

• wirepas-mqtt-library (from Wirepas). To install it:
  • launch “windows PowerShell“
  • in the prompt enter

pip install wirepas-mqtt-library

Now everything is set up to execute the script. The next step is to receive data from the Wirepas network connected to a Wirepas gateway.

Step 2: Communicate with the network

In order to communicate with the network a Python script, called script_evaluation_app.py, is provided (located in <wm-sdk folder>\source\example_apps\evaluation_app\backend_scripts) which can operate in two modes: viewer or controller. 

The viewer mode allows to receive, decode and display messages that are transmitted from the evaluation application.

The controller mode allows sending commands to the evaluation application.

Please note that this is the only way to communicate remotely with this network i.e do not try from the Wirepas Network Tool client (if already installed)

Receive data from the Wirepas Massive network

The objective of this part is to demonstrate how a user can receive data sent by a Wirepas Massive network by communicating with the gateway via a MQTT client and the Wirepas Gateway API both implemented by the wirepas-mqtt-labrary Python package).

In this step you will receive some messages sent by node(s) that runs the “Evaluation application“:

• A periodic message sent with a configurable interval
• A notification when a button is pressed

To achieve that you will use the script in viewer mode. 

Running the script in viewer mode

First start a Windows PowerShell instance:

and enter the following command to go where the viewer script is located:

cd <path to Wirepas Massive SDK folder>\source\evaluation_app\backend_scripts

Now to launch the script enter this command format :

python.exe script_evaluation_app.py -s <MQTT broker address> -p <connection port> -fu

where 

• <MQTT broker address>is the address to access the MQTT broker. In this particular case it corresponds to the Gateway IP address.
  • to connect to the built-in broker use the IP address assigned to your Wirepas gateway (methods to get your gateway IP address are given here)
• <connection port> is the port number where the broker is listening and sending its data.
  • for the built-in MQTT broker, the value 1883 must be used as this is the value defined in the gateway.env file
• -fu is an option to tell the script to use the unsecure connection mode to the broker.

Note : as an unsecure connection is used, username and password parameters are not needed to connect to the local MQTT broker. 

A full command can look like this to connect to the Wirepas gateway’s built-in broker:

python.exe script_evaluation_app.py -s 192.168.2.87 -p 1883 -fu

After the script is launched if the connection to the MQTT broker is successful (connection process can take up to a few seconds to establish) your prompt display should look like this :

The list of all the available shell commands is displayed. 

If for some reason the connection cannot be established a message giving the cause of error will be displayed.

Then in the interactive command prompt enter:

enable_messages_reception

A full setup illustration is given below: 

After some time you should see some messages displayed. Two different types of message can be seen (one for the “periodic message” and one for the “button pressed notification”).

To exit the script press “Enter” key and then the command “bye“.

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.

A periodic message travels to the viewer script with the following path:

• A node sends a periodic message to an available sink in the network.
• The sink transmits the message data to the gateway via UART 
• The transport service running on the Wirepas gateway encodes the message’s payload into protobuf format. Then the service publishes the protobuf to the MQTT broker’s topic “gw-event/received_data/wp_eval_app_gw/sink1/0xD8D42B/1/1“ (see this link for the general format of all available MQTT topics)
• The broker then informs all the MQTT clients subscribed to this topic that a new message is available
• The viewer script reads and decodes it with the wirepas-mqtt-library
  • Note: the decoding part is based on the wirepas-mesh-messaging Python package
• The decoded data is then printed to the PowerShell prompt

The display format of the periodic message is the following:

<timestamp> received from gateway <gateway ID>, sink <sink ID>, node <node ID> :

<message type>

Raw data -> <periodic message payload data in binary format>

Message ID -> <periodic message's message ID (value is 0)>

Counter value -> <counter value in decimal format>

Data pattern -> <fixed data pattern in binary format>

where

• <timestamp> is the time at which the message is received by the gateway
• <gateway ID> is the gateway ID from which the message was received. In our case it is “wp_eval_app_gw”.
• <sink ID> is the ID of a sink that received the node message. In our case, the ID will be “sink1“.
• <node ID> is the address of the node which sent the message.
• <message type> is the evaluation application message name. Here it will be “periodic message“.

The picture below shows how the display looks like in a prompt:

Button pressed notification

Each node has some buttons available to the user. The application running on the node sends a message every time a user button is pressed.

When such a message is received by the viewer script its display is:

<timestamp> received from gateway <gateway ID>, sink <sink ID>, node <node ID> :

<message type>

Raw data -> <button pressed message payload data in binary format>

Message ID -> <button pressed message's message ID (value is 1)>

Button ID -> <Id of the pressed button (value range is [0,3])>

Button state -> PRESSED

where

• <timestamp>, <gateway ID>, <sink ID> and <node ID> have the same meaning as for the “periodic message“.
• <message type> is the evaluation application message name. Here it will be “button pressed notification“.

The picture below shows how the display looks like in a prompt:

Send data to the Wirepas Massive network

The objective of this part is to demonstrate how a user can send data to a Wirepas Massive network by communicating with a Wirepas gateway via a MQTT client and the Wirepas Gateway API.

In this step you will send a message to one (unicast mode) or all nodes (broadcast mode) within the Wirepas network to switch a LED on or off. 

To achieve that you will use the script in controller mode.

Running the script in controller mode

As previously done start a Windows PowerShell prompt, go to the Python script location and start it using the same parameters values. 

Do not enter the “enable_messages_reception“ command.

Note: At any time by entering the command format listed below you can know the controller mode command format:

help <prompt command name> 

After the script is launched if the connection to the MQTT broker is successful, you can now learn how to send command to the network by reading the next section.

Control LED state

Each node 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).

To change the LED state of one or all the Wirepas network’s nodes enter a command which has the following format:

send_led_set_state_command <gateway ID> <sink ID> <destination address> <LED ID> <LED state> 

where

• <gateway ID> is the ID of the gateway to which send the message to. In this tutorial it is “wp_eval_app_gw”.
• <sink ID> is the ID of the sink which will have to relay the message to its tree. In this tutorial it will be “sink1“.
• <destination address> is the node address (in decimal or hexadecimal format) from which you want to control the LED
  • Note : to send the command to all the node (broadcast message) the address value to use is 0xFFFFFFFF 
• <LED ID> is the LED number to change state from (in decimal). A value of 0 corresponds to the first user available LED on the node.
  • Note : if an invalid LED ID is given (e.g only two LEDs on the node but value 3 is sent) then at the node side the command will not be considered valid but no error message will be displayed.
• <LED state> is the LED state (i.e switched ON or OFF) to apply. To request to switch it on use the string “on“ and to switch it off the string “off“.

As an example if you enter the command given below, you should see the second user LED of all connected nodes being switched ON after a few seconds.

send_led_set_state_command wp_eval_app_gw sink1 0xFFFFFFFF 1 on

The image below shows the sent led_set_state command with the parameters:

Send command and receive its result

The objective of this section is to show how to send requests with responses to the network. To demonstrate this functionality, three request-response interactions are tested with a node:

• Request the periodic message interval
• Request node’s LED state (i.e switched ON or OFF) 
• Send an echo request to get the roundtrip time of a message (i.e from sink to node(s))

The request will be done via the script running in controller mode and the response will be displayed by another instance running in viewer one. So both need to be executed at the same time. The following paragraph will describe the procedure.

Running the viewer and the controller script at the same time

The viewer and the controller script can be run followingly:

• Open two Windows Powershell 
• Launch in one of them the script in viewer mode as described in this section (referred as “viewer prompt” in this part of the document)
• Launch in the other one the script in controller mode as described in this section (referred as “controller prompt” in this part of the document)

Once done the set up should look like below (top: viewer prompt and bottom: controller one) :

You will now be able to send request and see the linked response.

Set periodic message period

By default each connected node sends a particular message (periodic message) every ten seconds. It is possible to set this value individually or for all in the range of two seconds to twenty minutes.

To do that, in the controller prompt the following command format must be used:

send_periodic_msg_period_set_command <gateway ID> <sink ID> <destination address> <period value>

where

• <gateway ID> is the ID of the gateway to which the message is sent to. In this tutorial, it is “wp_eval_app_gw”.
• <sink ID> is the ID of the sink that relays the messages to its tree. In this tutorial, it is “sink1“.
• <destination address> is the node address (in decimal or hexadecimal format)
  • Note : to send the command to all the nodes (broadcast message) the address is 0xFFFFFFFF 
• <period value> is the new period in milliseconds (decimal format).
  • Note : valid range is 2000 to 1200000. An error will be generated if an invalid value is given.

For instance, if you enter in the command prompt the following command, you should get a periodic message from each node every 3 seconds : 

send_periodic_msg_period_set_command wp_eval_app_gw sink1 0xFFFFFFFF 3000

The picture below illustrates the process:

Get LEDs state

To request state of a particular LED from one or all nodes, the following command format is used in the controller prompt :

send_led_get_state_command <gateway ID> <sink ID> <destination address> <LED ID> 

where

• <gateway ID> is the ID of the gateway to which the message is sent to. In this tutorial, it is “wp_eval_app_gw”.
• <sink ID> is the ID of the sink that relays the messages to its tree. In this tutorial, it is “sink1“.
• <destination address> is the node address (in decimal or hexadecimal format)
  • Note: to send the command to all the nodes (broadcast message) the address is 0xFFFFFFFF 
• <LED ID> is the index of the queried LED (in decimal). LED index starts from 0.
  • Note: if an invalid LED ID is given (e.g only two LEDs on the node (0 and 1) but value 2 is sent) the node responds with an error message.

After a few seconds the following message should be displayed in the viewer prompt :

<timestamp> received from gateway <gateway ID>, sink <sink ID>, node <node ID> :

<message type>

Raw data -> <led get state response message payload data in binary format>

Message ID -> <led get state response message's message ID (value is 3)>

LED ID -> <led identifier (value range is [0,3])>

LED state -> <state> (value are "ON" or "OFF"")

where:

• <timestamp> is the time at which the gateway received the message
• <gateway ID> is the gateway ID from which the message was received. In this case, it is “wp_eval_app_gw”.
• <sink ID> is the sink ID that received the node message. In this case, it is “sink1“.
• <node ID> is the address of the node which sent the message.
• <message type> is the evaluation application message name. Here it will be “led get state response message“.

When you enter the following command, you will get the state of the second LED from all the nodes:

send_led_get_state_command wp_eval_app_gw sink1 0xFFFFFFFF 1

After a few seconds all the responses should be displayed as illustrated below:

Echo message

To initiate the calculation of message travel time from sink to node (echo command), the following command format shall be used: 

send_echo_command <gateway ID> <sink ID> <destination address>

where

• <gateway ID> is the ID of the gateway to which the message is sent to. In this tutorial, it is “wp_eval_app_gw”.
• <sink ID> is the ID of the sink that relays the messages to its tree. In this tutorial, it is “sink1“.
• <destination address> is the node address (in decimal or hexadecimal format)
  • Note: to send the command to all the nodes (broadcast message) the address is 0xFFFFFFFF 

After a few seconds, the following message should be displayed in the viewer prompt:

<timestamp> received from gateway <gateway ID>, sink <sink ID>, node <node ID> :

<message type>

Raw data -> <echo command response message payload data in binary format>

Message ID -> <echo command response message's message ID (value is 2)>

Travel time -> <echo command message travel time from sink to node (value expressed in ms)>

• <timestamp>, <gateway ID>, <sink ID> and <node ID> have the same meaning as for the “led get state response message“.
• <message type> is the evaluation application message name. Here it is “echo response message“.

For example, if you enter the following command, you will get the travel time between the sink and all the nodes:

send_echo_command wp_eval_app_gw sink1 0xFFFFFFFF

After a few seconds, all the responses should be displayed:

Going further

The tutorial showed how to set up a system that enables the communication between Wirepas Massive nodes and a computer using Wirepas Gateway API. The next steps to try:

• as an example to demonstrate the multi-tenant capability, on one computer run script in both mode and ask for some node LED state and on another one execute only the controller one to request this particular LED to change state. The state change will be visible on the computer running the viewer prompt.
• connect to a MQTT broker reachable from the internet
  • if a Wirepas Backend with associated credentials is available to you its integrated broker can be used as an example
• Explore the Wirepas network interface implemented by the wirepas-mqtt-library Python package. Its documentation is available here.
  • Note: the wirepas-mesh-messaging it is built on is available here.
• Set up Wirepas Network Tool backend. This document [5] will be helpful.
• Start to develop your own application.

The following sections describe more in-depth some topics listed above such as the Python script internal work and how to connect to a cloud-based MQTT broker.

Python script process explained

This section lists the steps followed by the Python script to establish a connection to the Wirepas Massive network and send/receive data to/from it. In addition to this short description, the associated Readme.md file will give a few more technical aspects.

Viewer mode

This mode implements the following set of action:

1. get network interface parameters from command line to connect to the Wirepas Massive network (custom code)
2. create a Wirepas network interface and connect to the Wirepas network (wirepas-mqtt-library Python package)
3. create a shell where the user will be able to configure the script to run in viewer mode
4. Register for incoming evaluation_app data 
5. Read data received and decoded by the wirepas-mqtt-library in the “on_message_event_data_received_callback” and print the content in the shell prompt

Controller mode

This mode implements the given set of action:

1. get network interface parameters from command line to connect to the Wirepas Massive network (same as in viewer mode)
2. create a Wirepas network interface and connect to the Wirepas network (same as in viewer mode)
3. create a shell where the user will be able to select which type of command to send to the network and gives the needed parameters
4. wait for user input
5. encode and send the requested message with the wirepas-mqtt-library via the “send_message“ method exposed by the Wirepas network interface.

Connection to a cloud-based MQTT broker

This section will explain how to configure the gateway to use a remote MQTT broker instead of the built-in one.

Following parameters have to be set in the gateway.env file:

1. WM_SERVICES_MQTT_HOSTNAME is the IP address or the domain name where your MQTT broker is running. 
2. WM_SERVICES_MQTT_PORT is the TCP port, set either to 1883 or to 8883 depending on your infrastructure configuration
3. WM_SERVICES_MQTT_USERNAME has to be set according to your configuration. Note: in the case of a Wirepas provided backend instance, the credentials will be given by the Wirepas support team in a .rst file.
4. WM_SERVICES_MQTT_PASSWORD has to be set according to your configuration. Note: in the case of a Wirepas provided backend instance, the credentials will be given by the Wirepas support team in a .rst file.
5. WM_SERVICES_MQTT_FORCE_UNSECURE line has to be commented

A complete gateway.env file looks for example like this:

#

# Sink service configuration

#

# On which port the sink is attached (ex: /dev/ttyACM0 or /dev/ttyAMA0 if using a rpi hat)

WM_GW_SINK_UART_PORT=/dev/ttyACM0

# Uart bitrate of the sink. It depends on the build configuration of dualmcu_app (ex: 115200, 125000, 1000000)

WM_GW_SINK_BITRATE=125000

#

# Transport service configuration

#

# If you need more Mqtt settings; please check https://github.com/wirepas/gateway/blob/master/python_transport/wirepas_gateway/utils/argument_tools.py for additional parameters.

# Address of the broker to connect

WM_SERVICES_MQTT_HOSTNAME=mywirepasinstance.prod-wirepas.com

# MQTT port (usually 8883 for secure access, or 1883 for unsecure)

WM_SERVICES_MQTT_PORT=8883

# Username to connect to broker

WM_SERVICES_MQTT_USERNAME=mosquittouser

# Password to connect to broker

WM_SERVICES_MQTT_PASSWORD=mysecurepassword

# Uncomment following line to skip TLS check on brocker (uncomment it for local brocker)

#WM_SERVICES_MQTT_FORCE_UNSECURE=true

# Gateway unique id (used also as mqtt client name)

WM_GW_ID=wp_eval_app_gw

Please note this is the minimal parameter set needed to connect the gateway to a MQTT broker in most of the cases. More options are listed here.

Troubleshooting

1. “python“ command not recognized when trying to execute it
   1. Relaunch the Python interpreter installer and do not forget to check the option underlined in red in the following image. When the installation is finished restart your computer.

1. After launching the script in viewer mode nothing is displayed
   1. periodic message should be displayed every 10 seconds given the application running on the node is in its default configuration. You can wait some more time or run the script in controller mode and force a new period value.
   2. if still unsuccessful check that the gateway receives the node(s) message by running the command wm-dbus-print on the gateway.
      1. if this is the case check that the MQTT broker address passed to the script is correct
      2. if this is not the case check the network settings in the sink.env/sink.success file matches the one configured in the sink and nodes.

References

[1] How To set up and use your first Wirepas local network

[2] Wirepas Mesh Concepts

[3] Wirepas Gateway API

[4] How To set up a Wirepas gateway on a Raspberry Pi with Wirepas prebuilt image

[5] Wirepas services installer user guide

Revision History

Legal Notice

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

Copyright © 2021 Wirepas Oy