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 Massive to the Wirepas Position Engine (WPE).
 Positioning App implements the complete functionality required for collection and delivery of the RSSI measurements.

NOTE: This document applies to positioning application and positioning library version 1.2.x.x (and above) released with Wirepas Massive 5.1. For the previous version of the positioning app please refer to [2]. 

NOTE: This document describes the the Wirepas reference Positioning Application available as part of Wirepas Massive 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 Wirepas Massive 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: 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 the network, send the collected measurements, receive application configuration, disconnect from the network and finally go into sleep.
In this mode the positioning app does not trigger a network scan and the scan performed by the Wirepas 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 network 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.

Tag: autoscan

In the autoscan mode the tag is a standard low-energy non-router. This mode shall only be used when the application requires continuous connectivity to WM.

The tag will detect the Wirepas Massive and connect to the best available router in the vicinity. Connectivity to the network 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 network 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.

Anchor: opportunistic

An anchor (router) is connected at all times to the Wirepas network. For the purpose of maintaining the connectivity the 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.

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 the network coverage (e.g. this would allow to detect an asset tracking tag using a phone while outside the network 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', 0x00, 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) or based on the node motion state (if supported by hardware).

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. A special class (0xF8) was defined for the sole purpose to deliver a configuration update to a particular node. 

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 Wirepas Massive 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 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 Wirepas Massive 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.

Note that a tag set in NRLS mode will only receive the application configuration when the tag wake up for making a positioning update (i.e. it will not received it immediately as e.g. the autoscan mode). 

It is also important that note that the application configuration is individual per sink and shall be set for all sinks in the network. If the network is deployed on multiple sites (there is no Wirepas connectivity between them) then the application configuration shall be set on the sinks serving one site.

Configuration format

Shared application configuration

As mentioned above the shared application configuration is used to encapsulate the configuration. The generic format is shown in Table 7. and more details can be found in [3]. 

Table 7: Shared application configuration format

The positioning library predefined type is 0xC1. For example assuming that positioning is the only application using the app. config the encoding preamble will be (in hexadecimal):

F67E 01 C1 <payload length> <payload>

Positioning application configuration payload

The payload of the positioning configuration consists of one or several records encoded as shown in Table 8 (only one record for each used class). 

Each record starts with the class id followed the length (in bytes) of the included configuration commands (defined in Table 11). 

Table 8: Configuration record for one class 

For changing the configuration of an individual node the special class 0xF8 was defined as shown in Table 9. The encoding of the individual class 0xF8 follow the standard encoding of a record with the extra requirement that the first configuration command is the Node Selection (as defined in Table 11). In the positioning payload there can be one or several records for class 0xF8 each configuring an individual node.

 Table 9: Node individual configuration record 

The node individual configuration record is used to change a class of a particular node and it shall contain all settings for the respective class. The record shall be set temporarily for several positioning update periods (e.g. 3-4) and then can be removed as the node updated it’s settings.

Positioning configuration commands

In the new positioning application the configuration command is encoded as a compact TLV where the fields type and length are combined into a single byte (called TL byte) as:

• length:
  • will be encoded on the 3 bit MSB of the TL byte
  • value 0 indicates that the actual length will be on the next byte i.e. same with old format
  • value 1…7 indicates the number of bytes expected in the value
• type:
  • will be encoded into the 5 LSB bits of the TL byte with allowed values from 1…31. (0 is reserved)

Table below shows the difference between old and new encoding of the configuration command.

 Table 10: Configuration command TLV format

There will be a limitation of 31 different configuration parameters but given that there are 80 bytes available in the application configuration there is not much space to have many configuration parameters.

Table below shows the currently defined configuration commands.

NOTE:

• only the “Length | Type” and Value fields are encoded
• only the configuration values which are different than the application default’s shall be included in the app config (to save space as the whole application configuration limited 80 bytes)
• all multibyte fields are encoded as little endian 

The current supported configuration commands are shown in Table 11.

 Table 11: Configuration commands

The motion or LED notification commands are optional (consult the HW manufacturer if are supported). 

Note that LED notification command can be used to notify an entire class of nodes or an individual node. The notification will be active for the set duration, and every time a new command is set the command sequence shall be incremented (this is required to execute the notification command only once and prevent the LED to be on for long time which would drain the node battery). 

Encoding examples

• set static update to 300 sec, dynamic update to 60 sec for class 0xFB: 

F67E 01 C1 08 FB06412C01433C00

• set operating mode for class 0xFC as NRLS tag

F67E 01 C1 04 FC022201

• change node 1234 to class 0xFB (also set the class FB settings) 

F67E 01 C1 0F F80D86D20400002AFB412C01433C00

References

[1] Wirepas Massive Dual-MCU API Reference Manual
[2] Wirepas Positioning Application Reference Manual
[3] Shared application configuration 

Revision History

Legal Notice

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

Copyright © 2021 Wirepas Oy