Status

Date

Doc Version

Applicable

Confidentiality

RELEASED

v1.5

PosApp v1.2.x.x

PUBLIC


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 (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.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 (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 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.

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] in source/reference_apps/positioning_app/docs 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 Massive 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] in source/reference_apps/positioning_app/docs).

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

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: dedicated

Up to version PosApp v1.2.2.x (PosLib v1.0.0) it was only possible to set Wirepas Massive routers as anchors. From PosApp version v1.2.3.x (PosLIb v1.1.0) onwards Wirepas Massive 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] in source/reference_apps/positioning_app/docs). 

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.

Positioning app version

Eddystone URL

Eddystone UID

iBeacon

v4.0.0

X


X

v4.0.1


X

X

v5.0.0


X

X

v1.2.x.x


X

X

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.

Header

Record 1

Record n

Octet 0…1

Octet 2...x

Octet z...101

Table 2: Positioning app data message format

Field Name

Size

Description

Seq

2

Sequence number. Incremented for every data packet

Table 3: Header format

Record type [hex]

Description

0x00

Reserved (used only in 4.0.x)

0x01 – 0x03

Reserved for Wirepas

0x04

Battery voltage

0x05

Tag RSSI measurement, 4 byte node address, v5.0.x and v1.2.x.2

0x06

Tag operation info record

0x07

Directed-advertiser record

0x08 – 0x6F

Reserved for Wirepas

0x70 – 0xEF

Reserved for customer

0xF0

Reserved (used only in 4.0.x)

0xF1 – 0xF4

Reserved for Wirepas

0xF5

Anchor RSSI measurement, 4 byte node address, v5.0.x and v1.2.x.2

0xF6 – 0xFF

Reserved for Wirepas

Table 4: Record type description

RSSI measurement record

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

Field Name

Size

Description

Type

1

Record type. See Table 4

Length

1

Payload length. N x 5 (v1.2.x.x)

Repeated N times

Node address

4

Node address has 4 bytes from v5.0.0, v1.2.x.x

Scaled RSS

1

RSSI value. Convert dBm as: value * -0.5

Table 5: RSSI measurement record

Battery voltage measurement record

Field Name

Size

Description

Type

1

Record type. (set to 0x04)

Length

1

Payload length (set to 2)

Voltage

2

Battery voltage [mV] (uint16)

Table 6: Battery voltage measurement record

Tag operation info record

Field Name

Size

Description

Type

1

Record type. (set to 0x06)

Length

1

Payload length (set to 10)

Update time

4

Time to next update [s] (uint32)

Features

4

Tag active feature flags (see Table 8) (uint32)

Node mode

1

Tag operating mode (see Table x ) (uint8)

Node class

1

Node class (uint8)

Table 7: Tag operation info record

Tag operation info - features flags

Feature name

Bits

Valid from version

Description

Version

0-3

0

Features flags version. Flags below are valid only for specific versions

Motion

4

0

Motion detection: 1- enabled, 0 - disabled

Is static

5

0

Indicates if node was static since previous update. 1-static, 0- dynamic. Only valid if motion detection is enabled 

BLE Eddystone

6

0

BLE Eddystone beacon sending is: 1-active, 0 - not active

BLE iBeacon

7

0

BLE iBeacon beacon sending is: 1-active, 0 - not active

Mini-beacons

8

1

Mini-beacon sending is: 1-active, 0 - not active

RFU

9-31

-

Reserved for future use

Table 8: Tag operation info record

Directed-advertiser tag record

Field Name

Size

Description

Type

1

Record type. (set to 0x07)

Length

1

Payload length (variable)

Tag address

4

The node address of the tag from which this record originated

Tag payload

variable

The complete measurement message sent by the tag including sequence, and RSSI, voltage, info records

Table 9: Directed-advertiser tag record

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 9. 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 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]

Shared app config identifier

(2 bytes)

Shared app config count

(1 byte)

App 1 type

(1 byte)

App 1 length

(1 byte)

App 1 extended type

(1 byte)

App 1 payload

(variable)

0xF67E

1…255

0…255

1…127

included only is MSB of length is set




repeated for each application

Table 10: 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). 

Class (0xFF…0xF9)

(1 byte)

Length

(1 byte)

ConfCmd 1

 

ConfCmd n

0xFF…0xF9

1…255




Table 11: 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.

Class 0xF8

(1 byte)

Length

(1 byte)

NodeSelectionCmd 

(5 bytes)

ConfCmd 1

ConfCmd n

 Table 12: 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.

TLV format

PosApp old

Type (1 byte)

Length (1 byte )

Value (variable bytes)

PosLib new

Length bit 7..5 | Type bit 4..0

Value (variable bytes)

 Table 13: 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.

Config command

Length

Type

Length | Type

Value range

Description

Meas. rate static

2

0x01

0x41

1 … 65535 sec

Measurement rate if node is static or motion monitoring not supported [sec]

4

0x81

1 … 86400 sec

Meas. rate dynamic

2

0x03

0x43

0 … 65535 sec

Measurement rate if node is dynamic (i.e. moving) [sec]

Not used if set to 0 or motion monitoring not supported

4

0x83

0 … 86400 sec

Meas. rate offline

2

0x05

0x45

0 … 65535 sec

Measurement rate when the node is outside Wirepas network coverage. Not used if set to 0. [sec]

4

0x85

0 … 86400 sec

Operating mode

1

0x02

0x22

1

Tag NRLS

2

Tag autoscan

3

Anchor autoscan

4

Anchor opportunistic

5

Directed-advertiser tag

OTAP

1

0x04

0x24

1…254

Value is the OTAP sequence number to which the node should update if the scratchpad is available

BLE beacon

2

0x08

0x48

0

BLE beacon broadcast disabled

1… 65534

BLE enabled when node is offline (outside Wirepas network) for as long as the set value f[sec]

65535

BLE beacon broadcast enabled always

Device class change

1

0x0A

0x2A

0xF9...0xFF

Changes the device class. To be used only inside a class 0xF8, ignored for all other classes.

Node selection

4

0x06

0x86

node

valid address

Indicates the node address to which the configuration applies. To be used only for class 0xF8, ignored for all other classes.

Motion threshold

2

0x0B

0x4B

100…65535

Acceleration threshold above which motion will be detected [mg].

Value of 65535 will disable the motion monitoring (range <tbd>)

Motion duration

2

0x0C

0x4C

0…2000

Duration for acceleration to be above threshold for motion to be detected [ms] 

Positioning library auxiliary settings

LED on duration

2

0x0E

0x4E

0…65535 sec

Duration in seconds for the LED to be on

Value 0 will turn the LEd off

LED command sequence

1

0x0F

0x2F

0…255

Command sequence for LED control message. This value shall be incremented every time a new LED command is added

 Table 14: 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
[4] SDK v1.2.3

Revision History

Date

Version

Notes

v1.5

Initial release

Legal Notice

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

Copyright © 2021 Wirepas Oy