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 to the Wirepas Position Engine (WPE).
Positioning App (PosApp) with Positioning Library (PosLib) 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.3 and above initially released with Wirepas Mesh stack v5.1. For other versions, please refer to the table below. 

Table 1: Document version according to stack and PosApp/Lib version

NOTE: This document describes the Wirepas reference Positioning Application available as part of Wirepas Mesh SDK. If you use off the shelf products, please refer to the device manufacturer documentation.

User Guide

Operation modes

Positioning app (PosApp) was designed to run on both tags and anchor. There are operation modes dedicated for both tag and anchor as described below and can be categorized in two categories:

• Main Low Energy infrastructure operating modes: they are the ones covering most of the use cases
• Main Directed advertiser operating modes: they are the modes used in case of Directed Advertiser enabled Anchors and Tags
• Other modes: other modes covering specific use cases.

Main Low Energy infrastructure operating modes

Tag: NRLS

In the non-router long sleep mode (NRLS), the tag is in sleep mode between two measurement updates. The tag will wake up 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 as 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 wake up.
 NRLS mode is the recommended mode for a standard asset tracking tag.

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 a battery operated anchor.

Main Directed advertiser operating modes

Tag: directed-advertiser

In the directed-advertiser mode, the tag (DA tag) is set up as a non-router node with advertiser role (supported from PosApp v1.2.3 & PosLib v1.1.0 onwards). This is a special mode allowing higher tag density and power consumption savings. It is important to note the following characteristics of a DA tag:

• is not connected to the network and will only communicate with the mesh when a positioning update is performed
• can only communicate with the anchors set as low-latency routers and having directed-advertiser support enabled (see the Anchor: with directed advertiser support). 
• it performs the same positioning update sequence as a tag in NRLS or autoscan mode (see sections above)
• it receives and process the application configuration via Application Data Configuration similarly to any other tags types.

See instructions in [4] for configuring the directed-advertiser mode tag.

WARNING:  if you change the tags operation mode to DA mode and network does not support DA then the tags will not be able to communicate with the Wirepas Mesh network anymore.

Anchor: with directed-advertiser support

An anchor supporting directed-advertiser tags (PosApp v1.2.3, PosLib v1.1.0 onwards) is a node set as: opportunistic anchor, router role, low-latency mode and with directed-advertiser support enabled. These type of anchors are mandatory when tags are set in directed-advertiser mode (see instructions in [4]).

Other modes

Other modes are used to cover specific use cases and are having some special requirements. The basic description is provided here but it is recommended to contact Wirepas Support prior to use them.

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 the Wirepas Mesh network.

The tag will detect the Wirepas Mesh 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.
 As 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: dedicated

Up to version PosApp v1.2.2 (PosLib v1.0.0), it was only possible to set Wirepas Mesh routers as anchors. From PosApp version v1.2.3 (PosLIb v1.1.0) onwards, Wirepas Mesh non-router (or autorole) nodes can be also enabled as anchor. This is done by setting the node as opportunistic anchor and enabling additional beacon signals (miniBeacons). Note that enabling the miniBeacons can only be done at compile time (see instructions in [4]).

Anchor: Autoscan

This mode should never be used. It is reserved for Wirepas Internal use.

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 it is possible to send Eddystone or iBeacon or both.
The supported beacon types are shown in Table 2.

Table 2: 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 5.
Note that all multibyte fields are encoded as little-endian i.e. the least significant byte is first.

Table 3: Positioning app data message format

Table 4: Header format

Table 5: Record type description

RSSI measurement record

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

Table 6: RSSI measurement record

Battery voltage measurement record

Table 7: Battery voltage measurement record

Tag operation info record

Table 8: Tag operation info record

Tag operation info - features flags

Table 9: Tag feature flags

Directed-advertiser tag record

Table 10: Directed-advertiser tag record

Table 11: tag operating mode

Note on directed-advertiser tag message

The measurement message sent by a directed-advertiser tag will be re-routed by the low-latency router as a standard positioning measurement message containing the “directed-advertiser tag record” inside as shown in Table 10. Due to re-routing, the data message source address is the router address while the tag original address is included inside the DA tag record i.e. the observed data will be as: <seq router (2 bytes)> < DA tag record (variable)>. As a consequence, decoding a DA originated packet requires to extract the Tag source address from the actual payload instead of the source address from the Wirepas API.

Positioning application configuration

In Wirepas Mesh, there is the possibility to deliver an application configuration data message to each node in the network (see [1] for more information). 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 Mesh 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 to 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 12 and more details can be found in [3].

Table 12: 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 13 (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 16).

Table 13: Configuration record for one class 

For changing the configuration of an individual node, the special class 0xF8 was defined as shown in Table 14. 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 16). In the positioning payload, there can be one or several records for class 0xF8 each configuring an individual node.

 Table 14: 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 its 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:
  1. will be encoded on the 3 bit MSB of the TL byte
  2. value 0 indicates that the actual length will be on the next byte i.e. same with old format
  3. value 1…7 indicates the number of bytes expected in the value
• type:
  1. 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 15: 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 16 shows the currently supported 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

 Table16: Configuration commands

The motion or LED notification commands are optional (consult the HW manufacturer to know if they 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 Mesh Concepts
[2] Wirepas Positioning Application Reference Manual v1.4
[3] Shared application configuration
[4] Directed Advertiser configuration
[5] Wirepas Positioning Application Reference Manual v1.3

Revision History

Legal Notice

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

Copyright © 2021 Wirepas Oy