Introduction

In order to locate a node through the Wirepas Positioning System (WPS) the node will have to collect received signal strength indicator (RSSI) measurements of the signals broadcasted by the anchor nodes visible in its vicinity and send the measurements over the Wirepas Mesh (WM) to the Wirepas Position Engine (WPE).
 Positioning App implements the complete functionality required for collection and delivery of the RSSI measurements.

NOTE: This document describes the the Wirepas reference Positioning Application available as part of Wirepas Mesh SDK. This application being integrated by device manufacturers, please refer to the device manufacturer product documentation if you use off the shelf products.

User Guide

Operation modes

Positioning app was designed to run on both tags and anchor. At the moment the WM network role for a tag is non-router and for an anchor router.
 There are operation modes dedicated for both tag and anchor as described below.

Tag: autoscan

In the autoscan mode the tag is a standard low-energy non-router. The tag will detect the WM and connect to the best available router in the vicinity. Connectivity to the WM is maintained as long as possible throughout the lifetime of the tag. As the tag is continuously connected it is possible to send and receive data messages at any moment.
At periodic configurable intervals the positioning app running on the tag will trigger a network scan for the purpose of detecting and collecting RSSI measurements. Once the measurements are collected the tag will send them though a data packed towards the sink / gateway / backend.
Autoscan mode is recommended in use cases where the tag has to be connected all the time to the WM i.e. there is the requirement to send and receive data packets at random times. This is not the typical use case for a standard asset tracking tag and is usually used only when the positioning app is expanded with additional functionality.
Because the in autoscan the tag maintains the connectivity the power consumption is higher than of the NRLS mode especially when the tag is moving around.
 For this reason its use is recommended only in special use cases.

Tag: NRLS

In the non-router long sleep mode (NRLS) the tag is in sleep mode between two measurement updates. The tag will wakeup at periodic configurable intervals and perform a network scan, connect to WM, send the collected measurements, receive application configuration, disconnect from WM and finally go into sleep.
In this mode the positioning app does not trigger a network scan and the scan performed by the WM stack (required for establishing the connectivity) is used for collecting the RSSI measurements.
As in NRLS mode the tag maintains connectivity only as long is required to deliver the measurements there are two advantages: power consumption is reduced given that the tag is in sleep most of the time, the connection slot to the WM is freed allowing more tags to be served by the same anchors.
The disadvantage is that the tag cannot receive data while in sleep. The application configuration is used to provide configuration updates to the tag at wakeup.
 NRLS mode is the recommended mode for a standard asset tracking tag.

Anchor: opportunistic

An anchor (router) is connected at all times to the WM network. For the purpose of maintaining the connectivity the WM stack will perform network scans in order to detect routers/sinks in the vicinity. The positioning app will collect and send the measurements generated by these scans thus the opportunistic mode. Given that the positioning app does not trigger additional scans the power impact on the anchor is minimal (only the cost of sending a data packet).
 The opportunistic mode is the recommended mode to be used for an anchor.

Anchor: autoscan

The behavior of the anchor autoscan mode is identical to tag autoscan mode.
This mode was added for research and development and is not recommended to be used in a production system.

BLE beacons

The positioning app can be configured to send periodically BLE beacons (Eddystone / iBeacons) in all the operating modes i.e. both tags and anchors.
The BLE beacon configuration allows to send them all the time or only when outside WM coverage (e.g. this would allow to detect an asset tracking tag using a phone while outside the WM coverage).
The BLE beacon period is configurable and is possible to send Eddystone or iBeacon or both.
The supported beacon types are shown in Table 1.

Table 1: Supported BLE beacon types

The main data content of the beacons are as follows:
For all the physical address is set to:
 {0xC0, 0x00, NodeAdr[3], NodeAdr[2], NodeAdr[1], NodeAdr[0]}

• Eddystone URL

.url_advert = {'w', 'i', 'r', 'e', 'p', 'a', 's'}

• Eddystone UID

.nid ={'w','i','r','e','p','a','s', 0x00, 0x00, 0x00, NwAdr[2], NwAdr[1], NwAdr[0]}
.bid = {0x00, 0x00, NodeAdr[3], NodeAdr[2], NodeAdr[1], NodeAdr[0]}

• iBeacon

.uuid = {'w', 'i', 'r', 'e', 'p', 'a', 's',' ', 'm', 'e', 's', 'h', NwAdr[2], NwAdr[1], NwAdr[0] }
Where NwAdr is the node network address, and NodeAdr is the node address.

Measurement update rate

As mentioned in section Operation modes the measurement collection is done at periodic intervals set by the desired measurement update rate.
The measurement update rate is dynamically configurable through the application configuration (see section Positioning application configuration).

Device class

The tag and anchors can be grouped into classes. Currently there are 7 classes available. The tag/anchors in the same class will share the same configuration e.g. operating mode / update rate. It is recommended to use one class for the anchors and the other 6 for the tags. See more details in section Positioning application configuration.

Measurement message

The positioning app will send a data message on source/destination endpoint 238/238 containing the RSSI measurement and possibly other data.
The data message can contain up to 102 bytes and includes a header and one or several records. The records are encoded as type-length-value (TLV) and the record type is shown in Table 4.
Note that all multibyte fields are encoded as little-endian i.e. the least significant byte is first.

Table 2: Positioning app data message format

Table 3: Header format

Table 4: Record type description

RSSI measurement record

The definition of the measurement record is shown in Table 5.

Table 5: RSSI measurement record

Battery voltage measurement record

Table 6: Battery voltage measurement record

Positioning application configuration

In WM there is the possibility to deliver an application configuration data message to each node in the network (see [1] for further details). The application configuration data can be up to 80 bytes and is paired with a sequence number i.e. the application configuration version. A WM node will receive the latest application configuration upon connection and every time the configuration is updated. The application is set to the sink (through the gateway) and then is broadcasted in the entire network tree served by the respective sink (e.g. it can be set through the Wirepas Network Tool (WNT) client). Positioning app is using the WM application configuration to customize the behavior of the tags and anchors dynamically at run time.
 Prior to receiving the first configuration the node setting will be the default values set during manufacturing / initialization. If the node resets the default setting are used until the application configuration is received.

Format

In the positioning app configuration is formed by one or several configuration records representing the complete configuration for a device class (Table 7).

Table 7: Positioning app configuration format

A device class configuration record starts with the device class ID (encoded on first byte) followed by one or several configuration commands (encoded as type-length-value as shown in Table 8).
 The device class can be one of the following values: 0xF9 …0xFF. Note that the device class needs to be set to the node at manufacturing.

Table 8: Configuration commands

 Note that the multi byte values are encoded in little-endian format.

 (1) The node role is set at application build time. Only the Operating mode can be changed for a given node role (Tag or Anchor).

Example

• Device class: 0xF9
• Measurement rate: 300 s
• Operating mode: tag NRLS

0xF9 0x01 0x02 0x2C 0x01 0x02 0x01 0x01

Manufacturing provisioning

During the manufacturing it is possible to customize each node network parameters during the flashing process. This feature is available on nRF52x chip family.
 To use the feature the following steps are required:

1. set the parameter use_persistent_memory=yes in config.mk.
2. write the content of UICR registers according to Table 9.

Table 9: UICR register usage description

Notes:

• the configuration is only processed if CUSTOMER[31] register contains the magic key
• the multi byte parameters are expected to be encoded as little-endian
• if a parameter is set to 0xFF / 0xFFFFFFFF then it is considered invalid and ignored
• the parameters are only read and applied first time when the node boots

 For how to write the UICR registers please consult your flashing tool manual. Note that the writing must occur before the node boots for the first time.

References

[1] Wirepas Mesh 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 © 2021 Wirepas Oy