TABLE OF CONTENTS

• Introduction
• Summary
  • Network parameters 
• Network Parameters
• Device Parameters
  • Node Address
  • Application Area ID
  • Bootloader Keys
  • Pre-Shared key and ID
  • Other parameters
• References
• Revision History
• Legal Notice

Introduction

This document provides guidelines for product developers related to the parameters required in a Wirepas device and how to define them.

Parameters can be listed in two main categories :

• Network parameters : network-wide - usually configured for each network.
• Device parameters : device-specific - usually provisioned once at manufacturing

Parameters are described in more details in the Wirepas Mesh Concept document [1].

Summary

The table below summarizes both the Network and Device parameters

Network parameters 

Network parameters are network wide and are usually changed during the device provisioning.

Device parameters that cannot be changed after flashing:

Network Parameters

Only nodes with the same network parameters can connect together.

Network parameters consist of three network-wide parameters:

• Network address (24 bits): the network identification.
• Network discovery channel: 1 channel among the 40 channels to be used for node discovery and connection. Note: this parameter is used for device discovery but is not sufficient to isolate networks.
• Security keys:
  • AES128 encryption key
  • Message Integrity Code (MIC) 

When nodes have the same parameters they can automatically form a network without any user interaction. 

Because these parameters are network-specific, they are configurable at the installation (as different networks need to be secured and isolated from each other).

Two options are available to change the network parameters at the installation:

• Wirepas remote and local provisioning 
• Out-of-Band provisioning (e.g. NFC) that enables provisioning via a Smartphone or an NFC reader.

Wirepas Provisioning application note [2] provides more details on these different options.

Special care must be taken to define those parameters prior to installation; the network address should not contain repetitive bytes (0xAA…), and the channel should be chosen to avoid Wifi and BLE radio channels.

After the installation, Network parameters can be changed through the Remote API [5]. 

Device Parameters

Device parameters are usually specific to a device or a group of devices and are normally defined once at device flashing. For this reason, it is very important to understand, define and handle them carefully.

The parameters are the following : 

• Node address (32 bits): used to uniquely identify each device. The device ID must be unique within a network. 
• Application Area ID: used to identify different device firmware during the firmware update process. The ID is usually the same for a given device hardware/software combination.
• Bootloader keys: used to secure update images. They can be common to a manufacturer, to a family of products or to a network.
• Pre-shared key and ID : Used to secure provisioning

CAUTION : The Application Area ID and bootloader keys are defined at build time and cannot be changed afterward. The node address can be changed through the Remote API [5], as the Network parameters. 

Node Address

The Node address can be set in two different ways : 

• Either by the Wirepas SDK, which will automatically generate and program a random address during first boot. Then this address can be read back by the application.
• Or manually during production. The node address can be written to a certain part of the flash memory, e.g. the application persistent storage, during device flashing. Different hardware vendors also have separate registers for setting the address during the flashing. It is then up to the application to read the address from the register and configure it for the node.

The application is responsible to give this address to the stack with the configureNode function when the node is initialized. The node address is given to the function as a parameter so it can be defined freely. The node address is then copied to the flash memory. Note that the configureNode function does not change the address after it has been set during the first boot. 

If two devices in the network have the same node address the only way to fix the collision is to remove the other node from the network and re-flash it so that it gets a new address.

Application Area ID

Wirepas provides an Over-the-Air Programming (OTAP) [3] mechanism to update the network. The update packet, called a “scratchpad”, consists of one or multiple images that have an ID (called an AreaID). There are three types of AreaIDs:

• Wirepas stack firmware AreaID (Stack AreaID): The Stack Area.
• Application AreaID (App AreaID): The Application Area.
• Data Storage AreaID : to store specific data related to the user application or system, and which can be updated by the user via the Wirepas OTAP mechanism.

The AreaID in the scratchpad should match the AreaID in the device to update the software. If the scratchpad has multiple matching AreaID’s (for example stack and app), they both are updated.

Each application shall have a unique 32-bit AreaID, called Application AreaID, which is stored in the device’s memory. Because the Application AreaID is used by the Bootloader to identify if a scratchpad update shall be applied or not, it shall be different for all different application firmware or user areas. 

Important guidelines: Application AreaID is defined during the device firmware build process and can not be changed after device flashing. AreaIDs must be selected so that different hardware devices or devices with different applications never have the same. 

Note: If two different devices run two different applications with same area ID then the OTAP program cannot distinguish which application it should pick. Thus in this case, after an OTAP is complete the two devices will run the same application.

Bootloader Keys

The bootloader in a Wirepas device is responsible for processing the OTAP scratchpad [3]. The scratchpad is always secured. The bootloader contains a set of AES-128 symmetric keys for authenticating and decrypting the OTAP scratchpad. The same keys should be used when generating the scratchpad so that the device’s bootloader keys match with the scratchpad keys. 

Important guidelines: 

• Bootloader keys are very important to ensure the protection of scratchpad images. Hence they should be carefully generated, stored, and managed.
• Bootloader keys are set during the device firmware build process in the custom_bootloader_keys.ini file [4]. They cannot be changed afterward.

Pre-Shared key and ID

In case the Wirepas Provisioning is used [2], pre-shared key and application specific ID must be previously stored by the proxy and joining nodes. 

If provisioning is enabled in a network, the specific 4 bytes ID is broadcasted in joining beacons by all nodes of the network. This ID is associated with a Pre-shared-key, and nodes will only try to join the network with the same Pre-Shared-key. 

Those parameters can be set through application configuration. The format is detailed in the Open Joining and Provisioning application note [6].

Below are summary table of the possible configuration : 

Other parameters

Some other parameters can be set in the network, they are listed in the dual-mcu API reference manual [7].

Two can be interesting to set: 

• cOfflineScan, which determine the frequency of the scan done by a node when he has lost the network. 
• MSAP-MAX_MESSAGE_QUEUING, which corresponds to the time a message will be kept in the node's queue before it is discarded. 

References

[1] Wirepas Massive Concepts
[2] Wirepas Massive provisioning application note
[3] Wirepas Massive OTAP Application Note
[4] Wirepas Massive Flash structure and Bootloader application note
[5] Wirepas Massive remote API reference manual
[6] Open Joining and Provisioning Reference Manual
[7] Dual-MCU API Reference Manual

Revision History

Legal Notice

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

Copyright © 2022 Wirepas Oy