Introduction

In this tutorial you will set-up a complete system to create your first Wirepas 5G Mesh network. This tutorial is not intended to dive into deep details but more to be seen as a quick go through. For deeper details on what is Wirepas 5G Mesh network, you may start from and refer to the Wirepas 5G Mesh Overview document.

You will be guided for each of the steps and details for each of them will be found in each related and linked documentation.

This tutorial will allow you to set-up all the different components required to establish and control a minimal Wirepas 5G Mesh network locally from your PC.

Minimal requirements

Hardware:

• 1 PC with Windows 10 or Windows 11 or newer running (other platforms are possible, but not documented here)
• An Internet connection
• 3 nrf9161-DK boards
  Note: for more information on the supported chipsets see Hardware Reference Manual.
• 1 Raspberry Pi Model 3/4 with a Micro SDCard of 8Gb Classe 10. Associated adaptors to flash it from your PC (if necessary).
  • A wired Internet connection or wireless connection

Software:

• On the PC :
  • Your favorite Integrated Development Environnement such as Visual Studio Code from Microsoft
  • Windows Subsystem for Linux 2 (WSL2)
  • Docker and Docker Desktop
  • Devkit Programming Tools : JLink / nrfjprog
  • SD Card flashing utility: BalenaEtcher
• For the devkits
  • The Wirepas 5G Mesh stack. It is made available by Wirepas under a license agreement. It can be downloaded from Wirepas ShareFile.
  • The DECT-2020 NR Modem Firmware, available from Wirepas ShareFile.
• For the Raspberry Pi
  • The Raspberry PI ISO image provided by Wirepas and available from Wirepas Github.

Set-up your PC

To run this tutorial, your PC needs some tools, some of which will also be used along your product development journey with Wirepas 5G Mesh.

Please note that for this Tutorial, we use Ubuntu from Canonical as the distribution installed for WSL. Tested version is 22.04.3 LTS. This tutorial may also apply for other version and other distributions.

You will need:

• Windows 10/11 (other platforms such MacOS or Linux are supported but not documented here)
• WSL2 installed. Instructions can be found here.
• Your favorite IDE. Our customers generally use Visual Studio Code, if you do not have any yet. Please install from this link. If you need further help, please follow this link.
• Docker to ease the compilation process of the SDK applications. It can be downloaded from here. To dive deeper into the provided docker images, please refer to this link
• Git in the WSL environment to get the Wirepas SDK. Please follow instructions from this link.
• Nordic Semiconductor tool, nrfjprog (version 10.24.0 and onward)
• SEGGER programming tool, JLink (version 7.94k and onward)
• BalenaEtcher to flash your Raspberry Pi image downloaded from here
• A Web browser (tested on Edge / Chrome / Firefox and Safari)

Basic tools

Windows and WSL2 installations are out of the scope of this tutorial. Ensure, WSL2 is installed.

• Press Windows button and type Ubuntu to open an Ubuntu Shell (in case of other distribution, open an associated shell).

Docker

The Docker environment is provided by Wirepas to ease the process of compiling the SDK apps. Feel free to follow this link if you want further details on the package we are providing and what are your alternatives.

Install Docker Engine from here and follow the instructions to ensure the installation is completed.

Start your Docker Desktop app.

• Press Windows button and type Docker Desktop, select the app.
  • A screen stating the Docker engine is started and waiting for container to be run appears.

Note that to facilitate usage of Docker in the WSL terminal, you need to activate the WSL integration in the Docker Engine. This can be found in the Resources / WSL integration item.

Test Docker installation:

• In a WSL2 Terminal, type :

docker --version

Nordic Semiconductor tools and SEGGER Tools

• Install nrfjprog from this link : nRF Command Line Tools. Minimal version is 10.24
• Install JLink SEGGER tools from this link : SEGGER. Minimal version is 7.94k. Please, note that this tool is installed by default on Windows OS with the nRF Command Line Tools. On Linux and MacOS, it must be installed manually and a special attention should be paid to the installed version.

To ease the use of the nrfjprog command, you may create an alias and store it into your .bash_aliases file such as

alias nrfjprog="nrfjprog.exe"

if [ -f ~/.bash_aliases ]; then
    . ~/.bash_aliases
fi

• In a WSL2 Terminal, type

nrfjprog --version

Now that you have your environment set-up, we can proceed further.

Set-up your Boards

This tutorial relies on development kits provided by Nordic Semiconductor. You may want to use your own boards. However, please make sure your platform follows the Wirepas Hardware Reference Manual for full compatibility.

Wirepas 5G Mesh is supported by the Nordic Semiconductor nrf91X1 product range. The associated development boards are provided with a default Modem firmware that needs to be updated to operate with DECT-2020 NR. We will start by updating the modem, then get the Wirepas 5G Mesh SDK and eventually compile and flash the apps on the boards.

Wirepas 5G Mesh SDK

Use Git to clone the Wirepas SDK in your working directory. Please refer to this link for further details.

1 - Open a WSL2 Terminal. Navigate toward your working folder.

2 - Enter these commands

git clone https://github.com/wirepas/wm-sdk-5g.git
git checkout v1.1.0

Second command will allow you to get the desired stable version of the SDK.

Nordic Semiconductor NR+ Modem Firmware

To enable the DECT-2020 NR (New Radio) on these development kits, one needs to flash the adequate firmware for the modem. Access to this Firmware is made available by Wirepas through Wirepas Sharefile. Please, use the Nordic Semiconductor NR+ modem firmware version recommended in the release note of the Wirepas 5G Mesh product version you are using.

Once downloaded, do not unzip it. We will flash it to each of the devkits.

1 - Plug your Development Kit to your PC and power it on. The LED 5 should on and stable (not blinking).

2 - Open a WSL Terminal, navigate to the folder with the downloaded firmware image. Recover the chip by typing:

nrfjprog -f nrf91 --pinreset
nrfjprog -f nrf91 --recover

nrfjprog -f nrf91 --erasepage 0

nrfjprog -f nrf91 --program <modem_firmware_name>.zip --verify

Now, unzip Nordic Semiconductor NR+ Modem Firmware zip file in the image directory of the SDK.

Wirepas 5G Mesh stack

To enable the Wirepas 5G Mesh, you need the Wirepas 5G Mesh stack. It is made available by Wirepas on the Wirepas Sharefile under licence agreement.

Download the file and unzip it.

The uncompressed folder contains different files:

where you have the Bootloader and the Stack. Please note that the stack and the bootloader are compatible with nrf9161/nrf9151/nrf9131 hardware versions.

Copy all the files in the image directory of the SDK.

You are now ready to compile your first Wirepas 5G Mesh application.

Build your Sink

1 - Start your Docker engine

2 - Open a WSL Terminal and navigate to the SDK folder

cd ~/<path to SDK root folder>

docker run --rm -v $(pwd):/home/wirepas/wm-sdk-5g -w /home/wirepas/wm-sdk-5g -ti wirepas/sdk-builder:v1.5 make app_name=dualmcu_app target_board=pca10153

For further details, you can refer to this link.

Flash the Sink

1 - Connect a Development Kit to your PC

2 - Open a WSL Terminal and navigate to the SDK folder (if not already done)

3 - You simply need to type:

nrfjprog -f nrf91 --program $(pwd)/build/pca10XXX/dualmcu_app/final_image_dualmcu_app.hex --verify --pinreset

Your sink is now ready. However, it should be used along with your gateway, we will set-up later. As for now, let’s move to the nodes of the Wirepas 5G Mesh network.

Build your App

For this tutorial, we suggest to compile our Evaluation App.

1 - Start your Docker engine (if not already started)

2 - Open a WSL Terminal and navigate to your SDK folder (if not already done)

3 - Using the Docker container provided by Wirepas, you simply need to type:

docker run --rm -v $(pwd):/home/wirepas/wm-sdk-5g -w /home/wirepas/wm-sdk-5g -ti wirepas/sdk-builder:v1.5 make app_name=evaluation_app target_board=pca10153

Flash the Nodes

1 - Connect a Development Kit (different from your Sink) to your PC

2 - Open a WSL Terminal and navigate to the SDK folder (if not already done)

3 - You simply need to type:

nrfjprog -f nrf91 --program $(pwd)/build/pca10XXX/evaluation_app/final_image_evaluation_app.hex --verify --pinreset

Repeat the process for the remaining nodes. Power your boards one after the other.

Set-up your Wirepas Gateway

To control your Wirepas 5G Mesh network, you need to connect it to an MQTT broker.

To do so, Wirepas provides an easy way to install all required services on a Raspberry Pi.

Flash your Raspberry Pi

1 - Ensure BalenaEtcher is installed. This tool eases the process of flashing an .iso image on an SDCard

2 - Download the Raspberry Pi image from here. Get the most recent version (tested here on 1.4.1 version). Both headless and Desktop versions can be used.

3 - Flash the image using BalenaEtcher tool. When flashed, remove the card and reinsert it into your PC. A new volume should appear named boot.

Configure your Wirepas Gateway

Wirepas Gateway driver and sink configuration with our Raspberry PI images can be fully managed via 2 text files located in the micro SD card. To do so, download the sample configuration files from Wirepas GitHub Repository:

• gateway.env is used to configure the Sink and Transport services. One may refer to this document for further details.
• sink.env is optional and can be used to configure the sink node locally. One may refer to this document for further details.

Configure your gateway.env

The gateway.env file is used to configure the Wirepas Gateway drivers (sink and transport service).

Open the file gateway.env on your computer with a text editor like Notepad application to reflect your configuration (don’t use Wordpad as it will change the file encoding which must be UTF-8).

# Select the version of wirepas Gateway to use:

#   - "latest" (default if  not set): the gateway will use the latest official release,
#     and at each reboot, the gateway will check if there is a new release to upgrade
#   - "edge":  the gateway will use the top of gateway master branbch. At each reboot,
#     the gateway will check if there is a new release to updgrade
#   - "v1.4.0", "v1.5.0"...: any tag available from docker hub
#
GATEWAY_TAG="latest"
# Gateway unique id (used also as mqtt client name)
# If left blank, id will be automatically generated as a uuid based on your hardware
# Id can be any string as long as it is unique in your network. 
WM_GW_ID=my_first_5G_mesh_gw

# 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

For further details, please refer to this link.

Configure your sink.env

On your own computer, edit the sink.env in the same way as gateway.env file to reflect the following configuration.

# Initial Sink configuration

# Node address of the sink (Ex: 0x12345 32 bits max can be Hex or Decimal)
WM_CN_NODE_ADDRESS=0x000001
# Network address (Ex: 0xA1B2C3 24bits max  can be Hex or Decimal)
WM_CN_NETWORK_ADDRESS=0xD8D42B

# Network channel (Ex: 4 valid numbers 1-11)
WM_CN_NETWORK_CHANNEL=9

# 16 bytes authentication key for the network (Ex:000102..0F leave empty if not used)
WM_CN_AUTHENTICATION_KEY=

# 16 bytes cipher key for the network (Ex:000102..0F leave empty if not used)
WM_CN_CIPHER_KEY=

# Set node role to sink csma-ca (shouldn’t be changed)
WM_CN_NODE_ROLE="sink csma-ca"

Note: sink.env file will be automatically renamed to sink.success if the setup is properly applied to the sink at boot.

Copy configuration files to uSD Card

When both gateway.env and sink.env are ready, copy them to the uSD card in the wirepas folder

Once done eject the uSD Card and insert the card to the Raspberry Pi.

Start your Gateway

1 - Plug the Sink to the Gateway through a USB cable.

2 - Start the gateway (by plugging it). Consider connecting a wired ethernet cable (connected to the Internet) before booting the Gateway, if possible.

3 - Wait for your Wirepas Gateway to boot and initialize.

To confirm your gateway has correctly started, you can connect to it through SSH.

The hostname of your gateway is wirepasgw by default. If this is the sole gateway installed on your network, it should be accessible through that hostname. If multiple gateways are on the same network, hostname should be changed (please refer to this link). If the gateway is not accessible using the hostname, then, you need to retrieve the IP address of the Raspberry. 

ssh wirepas@hostname
ssh wirepas@XX.XX.XX.XX

where:

• hostname is wirepasgw (as default hostname)
• XX.XX.XX.XX is your IP address (if access through the host name does not work)

A default account with a default password are created as referenced here.

Once connected through SSH, type:

docker ps

This should be printed:

CONTAINER ID      IMAGE                                         COMMAND                  CREATED       STATUS        PORTS     NAMES

e4ba05123041      wirepas/gateway_transport_service:latest   "wm-gw"                  2 weeks ago   Up 39 hours                transport-service
40cf4d8774eb      wirepas/gateway_transport_service:latest   "wm-gw"                  2 weeks ago   Up 39 hours                transport-service-local
bcfd915787ae      wirepas/gateway_sink_service:latest        "stdbuf -oL -eL /hom…"   2 weeks ago   Up 39 hours                sink-service
76e277c459d1      wirepas/gateway_dbus_service:latest        "/etc/init/entrypoin…"   2 weeks ago   Up 39 hours                dbus

Your Wirepas 5G Mesh network

Once your Wirepas Gateway is up, your Sink is up, the nodes are operational, your network is ready.

Monitor your 5G Mesh network

In this tutorial, we will simply look at the messages received and sent from and to the Wirepas 5G Mesh network.

The Wirepas Gateway provides a local MQTT broker to which we can connect using the Wirepas MQTT Console.

1 - Download and extract the Wirepas MQTT Console from this link. Extract the full directory.

2 - Open in your favorite Web Browser the index.html file

3 - Connect to your Gateway. For further details on how to use our Wirepas MQTT Console, please refer to this link.

4 - To allow for data to be sent over the network regularly, configure the Diagnostics data with an interval of 30 seconds and using the fields presented here in the “Application and Diagnostics Configuration” section. Please note, that in a on field deployment Diagnostic data interval should be set as high as possible. Setting Diagnostic data interval to 30 seconds only serves for testing purposes.

5 - In the Wirepas MQTT Console, observe the messages arriving to the MQTT Broker located on your Wirepas Raspberry Pi Gateway.

And Play….

In the previous steps, we have compiled the Evaluation App.

This application allows to interact with the Development Kit using the Buttons and the LEDs available on the Development Kits.

Receive data from the network

The goal here is to receive messages from node(s) either triggered by the user via a button or sent periodically by the nodes.

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 nodes should be displayed in the Wirepas MQTT Console.

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

The application running on the node sends a message every time a button is pressed (not the RESET button).

Whenever a button is pressed, a message is sent through the Wirepas 5G Mesh network and hence received on the Wirepas MQTT Console.

The data is shown in hexadecimal format.

In the above example Button 1 from two different pca10153 has been pressed.

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

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 placeholder of the Wirepas MQTT Console, type:

80 B8 0B 00 00

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.

Press the send button and observe the periodicity of the message sent.

Controlling a LED

An other illustration of sending data on the Wirepas 5G Mesh network, is to control a LED available on the development kit. 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 one LED at a time from one or from all nodes available at the same time.

All the fields need to be filled with appropriate data. Namely Gateway ID, Sink ID, Destination Address, Source EndPoint (should be set to 1) and Destination EndPoint (should be set to 1).

#### 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
    81 03 01  // to switch ON led #4

#### 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
    81 03 00  // to switch OFF led #4

• Note 1 : There is no way to set all node’s LED on or off from a single message.
• 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 error message will be sent back.

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. We will request node’s LED state (i.e switched ON or OFF).

On the above screenshot, we can see that a command is sent to a node. The status is sent back asynchronously with the LED status.

One of the following commands (given in hexadecimal format) needs to be sent to the network in order to request the 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
    82 03 // to request led #4 state

• 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.

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

To go further

Now that you have set-up your first network, it is high time to go further.

As you may have understood, the Wirepas 5G Mesh profile is part of the Wirepas Connectivity Suite. Hence, it integrates into the global tools offered by Wirepas to monitor a all Wirepas radio profiles.

Hence, to go further, we may recommend you to look at different tools we are offering within the connectivity suite, but also documentation on how to do it your self.

• Using Wirepas Network Tool (WNT). It consists of a WNT backend that will collect the data from your networks and a WNT client that will allow you to visualize data from the backend. The backend installation guide can be found here and the client reference guide is here.
• Once you have played with the provided applications, you may want to create your own application. This document allows to discover another part of the available documentation on the Wirepas GitHub.
• If your application is developed, you may want to update your products with a new version of your application. Hence, we propose you to follow this tutorial to perform your first Wirepas 5G Mesh OTAP.
• On the Developer Portal documentation is here for you to dig. Should you have any information that cannot find, we will be happy to help develop amazing application relying on Wirepas 5G Mesh technology. If you have any questions regarding the licence agreement, feel free to get in touch with us.

Revision History

Legal Notice

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

Copyright © 2024 Wirepas Oy