Status

Date

Doc Version

Applicable

Confidentiality

RELEASED

v1.5.1

Wirepas Massive v5.x

PUBLIC

Important note

This document is only applicable to Wirepas Raspberry Pi prebuilt images prior to version 1.3.

Introduction

In this How To you’ll build a functional Wirepas Massive Gateway using Wirepas prebuilt images for evaluation. The Gateway will allow you to connect your local Wirepas Massive network to a server using MQTT interface.

What you'll learn

  • Building and Flashing a Raspberry Pi Image with Wirepas Massive drivers
  • Configuring the Wirepas Gateway Driver
  • Configuring the Wirepas Massive Sink node in the Gateway
  • Test the Wirepas Gateway API over MQTT
  • Understanding the Wirepas Gateway architecture

What you’ll need

Hardware: 

Software:

  • Balena Etcher software installed on your PC to flash the SD-Card: https://www.balena.io/etcher/
  • Wirepas Raspberry Pi image (desktop or lite version) downloaded from Github (v1.2) on your PC
  • Optionally: A Wirepas Backend with associated credentials and Wirepas Network Client available from Wirepas. In case you do not have a Wirepas Backend you will be able to use the built-in local MQTT broker running in the gateway to test the gateway.

System: 

The Raspberry Pi needs to be connected to internet for initial setup

By default the Raspberry Pi is enabled with Ethernet / DHCP which remains the preferred option to operate. 

You can also use Wi-Fi which can be configured via multiple options:

  • Using Desktop image and Screen and Keyboard/mouse connected respectively to HDMI and USB ports
  • Using Headless setup or Command line

Please refer to the official tutorial for detailed instructions : https://www.raspberrypi.org/documentation/configuration/wireless/

Shall you need static IP or a more complex IT setup, please refer to the Raspberry documentation.

The Gateway also needs to get access to some ports to operate:

Name

Item

Port TCP

Wirepas Backend 

MQTT

8883

RPi local MQTT Broker

MQTT

1883

ssh console (optional)

SSH

22

In addition if you use Wirepas Backend you will need to open the following ports on your PC for the client to access the backend server (in addition to internet connection):

Source

Destination

Port TCP

Customer Computer (WNT Client)

WNT Backend (AWS)

8811 (web socket)
8812 (web socket)
8813 (web socket)
 8886 (web socket)

Getting Started

In a nutshell, Wirepas Gateway is an open source implementation of Wirepas Gateway Drivers implementing a Gateway to cloud communication via MQTT. The official repository is located here

Wirepas Prebuilt Raspberry Pi image consists of a standard Raspbian image with:

  • Modifications to support Wirepas Pi HAT connected via UART (described here)
  • Wirepas Gateway driver Native installation (latest version)
  • Simple scripts executed at boot to configure Wirepas Sink and MQTT broker via text file located in the FAT partition of the Raspberry Pi SD-Card.
  • A local MQTT Broker for test purpose in case the gateway is not connected to a server (Wirepas Backend or other MQTT Broker)

Shall you need more details about how the image is generated, please refer to the Github repository available here

NOTE: This prebuilt image has been developed only for evaluation and prototyping purpose and is not targeted to be used in a production network. Default parameters are kept from all installed packages and images which can lead to security risks. More particularly, Raspberry Pi default logins are kept, SSH is enabled by default and there are no credentials on the local Mosquitto MQTT broker. You need to pay attention on securing your Gateway upon your need.

In the next chapters you will create and configure the Gateway going through 4 steps:

  • Prepare the Micro SD Card
  • Configure the Wirepas Gateway Drivers and the Wirepas Sink
  • Start the Raspberry Pi
  • Check the Gateway

Prepare the microSD Card 

  • Plug in the micro SD card to your computer either directly or via an USB adapter
  • Start Balena Etcher on your computer
  • Select the prebuilt image, previously downloaded from Wirepas GitHub repository
  • Select the micro SD card as target, and click “Flash!”

At the end of the flashing process unplug and replug the micro SD card to your PC. You should see a new drive called “boot” with several files and a “wirepas” directory

The Raspberry Pi image is now programmed. In next Chapter we will configure it with the Wirepas Gateway and Sink settings

Configure the Wirepas Gateway Drivers and the Wirepas Sink

Wirepas Gateway driver and sink configuration can be fully managed via text file located in the micro SD card. It avoids the need to connect to the gateway via screen or SSH to input parameters.

To do so, download the sample configuration files from Wirepas Github Repository:

  • gateway.env is used to configure the Sink and Transport services
  • sink.env is optional and can be used to configure the sink node locally

Configure your gateway.env

The gateway.env file is used to configure the Wirepas Gateway drivers (sink and transport service) as described here. The configuration file includes 2 parts: Sink service configuration and Transport service configuration.

For the MQTT connection, 2 options are possible with the prebuilt image:

  • Using a local MQTT broker running inside the gateway (mainly for evaluation and prototyping)
  • Using a MQTT broker either in a Wirepas Backend or on you own server

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 shall be UTF-8).

Configure the sink service

#
# 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=
# Uart bitrate of the sink. It depends on the build configuration of dualmcu_app (ex: 115200, 125000, 1000000)
WM_GW_SINK_BITRATE=

The sink service needs 2 parameters:

  • WM_GW_SINK_UART_PORT shall be configured with the peripheral on which the Wirepas Sink board is enumerated on the Raspberry Pi
  • WM_GW_SINK_BITRATE shall be configured with the baud rate configured in the board:
    Usual configurations are:
    • nRF52-DKs & TBsense2 boards (boards with onboard Segger): /dev/ttyACM0 and speed 125000
    • Raspberry Pi HAT: /dev/ttyAMA0 and speed 125000
    • Promistel USB Dongle (v1 3D-printed casing): /dev/ttyUSB0 and speed 125000
    • Promistel USB Dongle (v2 transparent casing): /dev/ttyUSB0 and speed 115000

Edit both WM_GW_SINK_UART_PORT & WM_GW_SINK_BITRATE in your editor to reflect your configuration

Configure the transport service

#
# 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=
# MQTT port (usually 8883 for secure access, or 1883 for unsecure)
WM_SERVICES_MQTT_PORT=
# 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=test_rpi_auto

The transport service configuration includes the parameters for the MQTT broker server and Gateway ID.

Gateway unique id configuration

The Gateway Unique ID is used to identify a Gateway in the Wirepas Gateway API (see: Wirepas Gateway API)
You can edit the WM_GW_ID upon your preference or keep the default setting.

Local MQTT Broker configuration 

Here are the parameters to apply if you use the local MQTT Broker

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

By default the local broker does not have secure access and does not have Username and Password.

Remote MQTT Broker example

Below a configuration example for a Raspberry Pi HAT with Wirepas Backend

#
# 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=<Your instance Name>.extwirepas.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=<Your User Name>
# Password to connect to broker
WM_SERVICES_MQTT_PASSWORD=<Your Password>
# Uncomment following line to skip TLS check on brocker (uncomment it for local brocker)
#WM_SERVICES_MQTT_FORCE_UNSECURE=true

In case of a Wirepas Backend your credentials have been delivered by Wirepas based on your server settings.

The MQTT broker credentials (username/password) to use are the ones defined for the “mosquittouser”.

Wirepas Hosted backend uses secured connection

Note1: In case you want to use you own broker with unsecure access you need to:

  • Set the WM_SERVICES_MQTT_PORT to your MQTT broker unsecured port, typically 1883
  • Uncomment the parameter WM_SERVICES_MQTT_FORCE_UNSECURE=true

Note2: In case you use a secure connection, you need to comment the line #WM_SERVICES_MQTT_FORCE_UNSECURE=true

Here is a configuration example using a Raspberry Pi HAT together with the local MQTT Broker

#
# 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/ttyAMA0
# 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
#
 
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=<Name of your Gateway>

Configure your sink.env

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

Below a configuration example 

#
# Initial Sink configuration
#
 
# Node address of the sink (Ex: 0x12345 32 bits max can be Hex or Decimal)
WM_CN_NODE_ADDRESS=0x12345
# Network address (Ex: 0xA1B2C3 24bits max  can be Hex or Decimal)
WM_CN_NETWORK_ADDRESS=0x123456
# Network channel (Ex: 2 valid numbers 1-40)
WM_CN_NETWORK_CHANNEL=2
# 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 are properly applied to the sink at boot. In case you want to change your sink settings or if you connect a new sink sink.success won’t be applied until you rename it to sink.env.

Copy configuration files to uSD Card

When both gateway.env and optionally 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 the Raspberry Pi

  • Connect the Wirepas sink
    • Make sure you have either a pre-flashed board or a board flashed with Wirepas Dual MCU application.
    • Connect your sink to either the HAT connector for the Wirepas Pi Hat or to a USB port on your Raspberry Pi.
  • Connect other peripherals: uSD, Ethernet (with Internet access), optionally HDMI, USB keyboard and mouse.
  • Connect power cable

Board startup

At boot the software will automatically:

  • Resize the file system
  • Reboot
  • Download and install the Wirepas Gateway drivers (native installation). Takes few minutes upon your internet connection speed
  • Reboot
  • Configure the Wirepas Drivers as per the gateway.env and sink.env files

During the initial setup the Raspberry Pi will reboot 2 times which is normal.

You can validate the drivers installation ended successfully by checking that the firstboot.sh file located in ~/wirepas is renamed firstboot.sh.done.

More details on the first boot process can be found here

Note:

  • you must execute the following command in order for the firstboot.sh file to execute properly
sudo apt-get update --allow-releaseinfo-change
  • after this wait a few seconds and the installation procedure should be automatically restarted

Check the Gateway

You can check that your configuration is successful using a MQTT client software, alternatively using Wirepas Network Tool client if you have a Wirepas backend.

Using a MQTT client

You can use a MQTT client to connect the MQTT Broker (either the local one, a Wirepas Backend or your own broker running on your server).

In the example below we make use of MQTT.fx software which can be downloaded from: 

http://www.jensd.de/apps/mqttfx/1.7.1/mqttfx-1.7.1-windows-x64.exe

After installation, you need to configure your broker as per your settings:

  • Using your backend credentials if you use a Wirepas Backend (don’t forget to use the mqttmasteruser user)
  • Using the Raspberry Pi IP address if you use the local MQTT Broker. By default the Raspberry Pi are configured with DHCP enabled. To get the IP address of your Raspberry you need to get the allocated IP address from your DHCP server. Alternatively you can use tools like Angry IP Scanner or follow the tutorial from the Raspberry Pi fundation.
  • Using you own server settings

Once configured you should be able to connect to the broker and Subscribe the the topic: gw-event/status/# to list the connected gateways.

You should then see a message gw-event/status/ corresponding to the key previously configured in gateway.env file (ie: WM_GW_ID=test_RPI_image in below example)

If you see this result it means your gateway is properly configured and both the Sink and the Transport services are running.

Note: The Wirepas Gateway API encodes the payloads using Protocol Buffer encoding. That’s why the messages displayed in MQTT.fx are not decoded and not displayed properly.

Detailed description of the Wirepas Gateway API can be found here.

Using WNT client

Start your WNT client on your Windows machine, and connect to your Wirepas hosted backend using proper credentials

On the main page, at the top left corner you see the connection status icon, which should be green, indicating successful connection to the backend.

In the Setting then Network Menu you should see your network listed together with the Sink address

Please refer to the WNT Client User manual [1] for more information.

FAQ

Can I connect to the Raspberry Pi via SSH

Yes, SSH is enabled by default, you can use software like Putty to install a SSH client on your PC. Once you have it you need to get the IP address of your Raspberry Pi either on your network. You can also use a terminal window straight on the Raspberry Pi if you use the Desktop image and have connected screen & keyboard.

Username and password are default one: login: pi / password: raspberry

I have installed everything but it is not working

The root cause can come mainly from 2 reasons:

  • Sink not properly flashed - Make sure your sink is flashed with Dual MCU application compatible with you platform. If you sink is USB connected, you can check its status using Wirepas Terminal[2].
  • Wirepas Gateway drivers are not running:
    • To test status you should connect via SSH to the Raspberry Pi and check if both the Sink and Transport services are running.
    • To do so enter the following commands to check the status, you should see both services running
    • systemctl status wirepasSink1.service
systemctl status wirepasTransport.service

  • If the Sink service is not running, check you port configuration, it is usually because of improper :dev/tty selected or link speed.
    • To easily check the port, unplug the sink, plug it back and enter the following command:
dmesg command

There you will see what was the name given to your sink by Linux

How can I check the sink parameters ?

Just connect to the Raspberry Pi console (SSH or screen) and enter the following command:

  • if your prebuilt image version < v1.2
/home/pi/wirepas/configure_node.py list
  • if your prebuilt image version >= v1.2
wm-node-conf list

Here is below an example of what is returned by the command. Among others you can find the Nodes address, Network address, Network channel and stack version.

Note : the “Could not import WPE handles (No module named 'grpc')“ and the warning messages can be safely ignored. 

Can I see the traffic coming from nodes in the gateway ?

Yes, you can print the traffic between the Sink service and the Transport service via the following command:

wm-dbus-print

Here is below an example of what is returned by the command. 

Note : the “Could not import WPE handles (No module named 'grpc')“ and the warning messages can be safely ignored. 

Can I install other stuff on the Raspberry Pi ?

Yes, the release is based on a Raspbian image. You can find more details about the installation scripts in the Github repository

It is working, am I good to go into the production ?

This pre-built images are meant for quick setup and are not designed to be product. Nevertheless the Wirepas Gateway drivers are available either as native or Docker component for integration in your production Gateway.

References

[1] Wirepas Network Tool Client User Guide

[2] Wirepas Terminal v0.101 Release

Revision History

Date

Version

Notes

v1.0

Initial Version

v1.1

Improved version.

v1.2

Illustration updates and minor fixes

v1.3

Updated links to Wirepas Terminal

v1.4

Replaced reference to Wirepas Mesh by Wirepas Massive
Mention of wm-node-config tool in new prebuilt image
 Clarification on which MQTT credentials to use when connecting to a Wirepas hosted backend.

v1.5

Add automated installation error fix instructions

v1.5.1

Corrected Promistel USB Dongle UART baudrate values

Legal Notice

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

Copyright © 2021 Wirepas Oy