TABLE OF CONTENTS

Status	Date	Doc Version	Applicable	Confidentiality
RELEASED	23 Jun 2022	V1.0	5.2	PUBLIC

Introduction

This document explains how to set up a local provisioning demonstration, using the local_provisioning example application. The objective is to demonstrate how new nodes can be added to an existing network using the Wirepas Provisioning mechanism using few nodes and a gateway.

What you’ll learn

Install and control the Local Provisioning library.
Add new nodes to a network.

What you’ll need

A good understanding of Wirepas Provisioning concepts by reading “Wirepas Massive Provisioning Application Note” [2] document.
A functional build and programming environment based on:
- Wirepas Mesh 2.4 GHz version v5.2 and above
- Wirepas SDK version v1.3.0 and above
- Shall you need to setup your environment, please follow the “Getting started with Wirepas Massive for developers” [4] document.
A functional Wirepas gateway with Wirepas gateway drivers v1.4.0 and above ( In example a Raspberry Pi configured as described in [9])
At least two boards compatible with Wirepas to be used as sink and nodes. The list of the compatible chipsets is available in [1].
A configured and working Wirepas Backend (either self-hosted or Wirepas hosted) or at least a MQTT broker where the Gateway is connected to.

Getting Started

This documents details the following steps :

Step 1 : Configure the sink as a proxy-node

Step 2 : Flash some nodes with the local_provisioning example application

Step 3 : Provision the joining nodes

Step 4 : Disable Provisioning

Step 5 : Customize the local_provisioning example application

In the proposed configuration, the sink act as a proxy-node and is configured to send joining beacons. The node flashed with the local_provisioning application receives those beacons and sends a request to join the network. The request is received by the proxy-node which sends the network parameters to the joining-node. Once the joining-node is provisioned, it becomes also a proxy-node and is able to provision new nodes.

Step 1 : Set up the gateway and configure the Sink

Set up the Gateway :

The gateway should be configured to communicates with a Wirepas backend instance, as explained in the “How to set up a Wirepas Gateway” [9] document. The gateway.env file can be configured as explained in the document, but configuring the sink with sink.env is not needed at that stage.

Flash the Sink :

The Sink must be flashed with the dual_mcu application, without any modification, as explained in the step 2 of the “How to set up your first Wirepas Network document” [1].

The commands to use to flash can be found in the “How To flash Wirepas Application” document at [5] for a Nordic board, and at [6] for a Silicon Labs Board.

Configuring the Sink and enable provisioning with the backend script :

A script build on top of mqtt_wirepas_library [10] to configure the Sink node and to enable provisioning is included in the local provisioning library folder [3].

No previous configuration of the sink is needed, the backend script is made to provide any new sink not associated to a network with hardcoded parameters. The following parameters shall all be set, and can be changed directly in the script :

Node address : random 4 bytes
Network address : random 3 bytes
Network channel : any number from 1 to 40
Node role : Sink
Encryption key : random 16 bytes (ex : 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10)
Authentication key : random 16 bytes

# Hardcoded config as an example

new_config = {

    "node_role": 17, # Sink with Low Latency flag: 0x11

    "network_address": 123456,

    "network_channel": 16,

    # Fake keys to illustrate the concept

    "cipher_key": bytes([0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88]),

    "authentication_key": bytes([0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88,0x11,0x22,0x33,0x44,0x55,0x66,0x77,0x88]),

    "started": True

Pre-shared Key and Key ID should also be given to the sink in the python script as follow :

#Hardcoded Pre-shared key and ID as an example

custom_psk_config = {

    "custom_psk_id": bytes([0x12, 0x34, 0x56, 0x78]),

    "custom_psk": bytes([0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7, 0xa8, 0xa9, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7, 0xb8, 0xb9, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7, 0xc8, 0xc9, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5])

Once the sink is connected to the gateway, the backend script “local_provisioning_tool.py” can be run with the following command, updated to your configuration :

python local_provisioning_tool.py --host <yourInstanceDomainName> --port 8883 --username mqttmasteruser --password <mqttmasteruserPassword>

It should immediately configure the sink and print out the following :

Sink <gateway_name>/sink1 not configured yet

Configuring the sink for new network

Node address not set, generate one by hashing sink name

New node address is  <new generated sink node address>

(E)nable local provisioning, (D)isable local provisioning, (Q)uit:

Then the provisioning must be enabled by typing “E”. The Application Configuration to enable provisioning will be sent to the sink, and the node will begin to emit joining beacons. This is mandatory to perform next steps properly.

Step 2 : Flash some nodes with the local_provisioning example application

The local_provisioning application can be found in the “Unitary_app” folder in github [7].

The local provisioning example application can be now built and flashed on the nodes. The commands used in the first step can be reused to build and flash, by replacing “dualmcu_app” by “local_provisioning”.

The joining node sends a request that is received by the proxy-node. The proxy node will then send back a message with the network parameters encrypted with the pre-shared key. The joining node will be able to decrypt the message only if he already has the same pre-shared key and id.

The pre-shared keys should be customized inside the application as follow :

static local_provisioning_psk_t m_psk = {

    //EXAMPLES KEY ID AND PRESHARED KEY TO BE REPLACED

    // 4 bytes id

    .id = 0x12345678,

    // 32 bytes psk

    .psk = {0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7, 0xa8, 0xa9,

            0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7, 0xb8, 0xb9,

            0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7, 0xc8, 0xc9,

            0xd1, 0xd2, 0xd3, 0xd4, 0xd5}

};

Those pre-shared key and ID should correspond to the one used in the python script !

Once the application is flashed, you can see Led 1 lights ON on the node as shown in the picture below for Nordic board :

Step 3 : Provision new nodes.

In order to see in details what is happening on the joining node, you can connect it to your PC and open a terminal to see the logs as explained in this article [8].

The process to begin the provisioning is described below :

Press Button 1 on joining-node. The Led 1 is blinking to show that the Node is scanning joining beacons.
Once the node detect the joining beacons, the provisioning starts.

Note : If Led 1 stop blinking and stay fix again, it means that provisioning failed and config should be verified.

Led 2 lights on once provisioning is over :

4. The Application Configuration will propagate the info that local provisioning is enabled in the network. Led 2 starts to blink to indicates that the node became a proxy-node and now sends joining beacons.

Below are the logs you should see on the joining node :

Step 4 : Disable the provisioning

The provisioning can be disabled by typing “D” on the terminal running the backend script. This will send the correct application configuration to the network, and all nodes will stop emitting joining beacons.

Step 5 : Customize the local provisioning application

The local_provisioning application is an example application to customize for your own needs.

The Local provisioning documentation [3] explains the use of all functions.

The first to look at, is the “Local_provisionig_init” functions which can be used to set Key ID and Pre-shared key to private values defined only for your network.

Once the node is provisioned, the app can be customized to fit your use case and do other actions.

Conclusion :

Configuring the provisioning into a network makes addition of any new node very easy and secured.

Provisioning a network can also be done with Remote provisioning; in this case, a provisioning server is used to validate the entrance of any new node to the network, as explained in the Application Note [2].