Wirepas firmware v.3. User Guide

Wirepas Mesh 2.4GHz

Wirepas Mesh 2.4GHz is a wireless connectivity technology for massive IoT. Wirepas Mesh 2.4GHz running in the devices enables a scalable, reliable, and cost-efficient IoT solution.

The network provides one horizontal connectivity layer for all IoT use cases: collect data from your sensors to an IoT application in the cloud, control remotely located devices, communicate device-to-device in the network with or without cloud and track the location of moving assets.

All the networking intelligence is included in the Wirepas Mesh 2.4GHz software to form a resilient large-scale wireless network.

Wirepas Positioning Engine (WPE)

Wirepas Positioning Engine (WPE) is an RTLS solver which computes the position of mobile devices based on the position of Fixed Anchors.

Thanks to Wirepas Mesh 2.4GHz it allows to deploy fully battery-operated infrastructure of Anchors used both as locators and routers.

WPE is a stream-based processing engine which provides a position (WGS84 / GPS) for every measurement taken by the asset.

WPE uses RSSI based trilateration and supports services to:

  • Declare Anchors
  • Declare Buildings, Areas, Floors, Zones
  • Provide Tag position with matching of Building, Floor, Zone

WPE offers an open API based on MQTT or GRPC. WPE can be run on any cloud.

BlueUp Positioning Engine (BPE)

BlueUp Positioning Engine (BPE) is a IPS software based on RSSI and trilateration. It supports several technologies, including Wirepas Mesh 2.4GHz tags. MeshIPS is based on mesh infrastructure, where Wirepas anchors are used for positioning reference and Wirepas tags are used for tracking and locating people, assets, vehicles, …

BPE can be installed on a local server. Communication between BPE and host application is implemented using standard HTTP JSON REST APIs. MQTT server support is also available.

Wirepas-enabled positioning application

BlueUp positioning application for Wirepas-enabled devices runs on both moving tags and anchors. BlueUp positioning application introduces a series of advanced functionalities and allows to manage the positioning interval of moving tags on the basis of motion status (detected by the accelerometer), in order to get an optimal compromise between energy consumption (i.e. battery life) and refresh rate. Positioning app also allows to configure optional BLE beaconing functionality.

Positioning application Finite-State Machine for moving tags

BlueUp positioning application implements a Finite-State Machine (FSM) for moving tags, based on 4 different states:

DEFAULT: startup and default operating state of the tag, with a configurable positioning interval P1. If the accelerometer is not enabled and alarms are not triggered (e.g. button not mounted) tag remains in DEFAULT state permanently. Tag exits from DEFAULT state when motion is detected (entering MOTION state) or when an alarm is detected (entering ALARM state) or when no motion is detected for T1 interval (tag enters SLEEP state).

MOTION: state triggered by motion detection from the accelerometer. When motion is detected (3-axis acceleration over a configurable threshold THR), tag enters MOTION state, with a positioning interval P2, and remains there until the timeout T2 expires (with T2 configurable). After T2, if no motion is detected, tag returns in DEFAULT state. When accelerometer is not enabled, tag never enters MOTION state.

ALARM: state triggered by detection of an alarm condition (i.e. button pressed, man-down, shock detected). When an alarm is detected tag enters ALARM state, with a positioning interval P3, and remains there until the timeout T3 expires (with T3 configurable). After T3, if no motion is detected, tag returns in DEFAULT state, otherwise it returns in MOTION state. When alarm cannot be triggered, tag never enters ALARM state.

SLEEP: state mainly used for tag storage or for tracking tags with extremely long periods of absence of motion. When tag is in DEFAULT state, it enters SLEEP state when no motion is detected for at least T1 period (with T1 configurable). In SLEEP state tag has a configurable positioning interval (suggested value equal or higher than 24 hours). Tag exits from SLEEP state when motion is detected (entering MOTION state) or when an alarm is detected (entering ALARM state). If the timeout from DEFAULT state is set to 0 or if accelerometer is not enabled, tag never enters SLEEP state.

ALARM state has the highest priority. Possible ALARM events are:

  • Button pressed (single short press, single long press, double press)
  • Horizontal position detection
  • Free-fall detection
  • Shock detection
  • Man-Down detection

The following scheme highlights individual states and state transitions. The FSM parameters are configurable (either in production or using Application Data Configuration).

FSM for Tags

The parameters of the finite state machine are:

Parameter Definition
P1 Positioning interval in DEFAULT state
P2 Positioning interval in MOTION state
P3 Positioning interval in ALARM state
P4 Positioning interval in SLEEP state
T1 Timeout in DEFAULT state (to enter SLEEP state)
T2 Timeout in MOTION state (to return in DEFAULT state)
T3 Timeout in ALARM state (to return in DEFAULT or MOTION state)
THR Accelerometer threshold (to detect movement)

State Packet

Each time a state-transition is triggered a network scan is performed and a dedicated custom data message is sent to the MQTT broker over the mesh network.

Data message is sent on source/destination endpoint 73/73.

Tag State Packet format

Byte Description Value (hex) Bytes Details
1 Type 0x01 1 Packet type
2 Length 0x07 1 Length of the Data field
3 Data Variable 1 Firmware version
0x20 = 2.0
4 Variable 1 Tag state
0x00 = DEFAULT
0x01 = MOTION
0x02 = ALARM
0x03 = SLEEP
5 Variable 1 Alarm event
0x00 = no alarm
0x01 = button pressed (short)
0x02 = button pressed (long)
0x03 = button pressed (double click)
0x04 = Horizontal position detection
0x05 = Free-fall detection
0x06 = Shock detection
0x07 = Man-Down detection
6-7 Variable 2 (BE) Battery voltage (mV)
8 Variable 1 Node class
values 0xF9 to 0xFF
9 Variable 1 Tag operation mode
0x01 = NRLS tag
0x02 = Autoscan tag
0x03 = Autoscan anchor
0x04 = Opportunistic anchor

Anchor Tag Configuration Packet format

Byte Description Value (hex) Bytes Details
1 Type 0x03 1 Packet type
2 Length Variable 1 Length of the Data field
3-6 Data Variable 4 (BE) Sensor measure interval for Anchor Tags
7 Variable 1 Flags
Bit [0] = Leds_En/ Alert_En
Bit [1] = Button_En
8-9 Variable 2 ADV interval (msec)
10 Variable 1 ADV TX power (dBm)
11 Variable 1 BLE Beaconing
0x00 = disabled
0x01 = Quuppa Emulation Mode
0x02 = iBeacon
0x03 = Safety
0x04 = Eddystone-UID
Quuppa emulation - if enabled
Byte Description Value (hex) Bytes Details
12-17 Data (continued) Variable 6 (BE) Quuppa tag ID
iBeacon - if enabled
Byte Description Value (hex) Bytes Details
12-32 Data (continued) Variable 16 (BE) iBeacon UUID
Variable 2 (BE) iBeacon Major number
Variable 2 (BE) iBeacon Minor number
Safety - if enabled
Byte Description Value (hex) Bytes Details
12-30 Data (continued) Variable 10 (BE) Safety (iBeacon) UUID
Variable 2 (BE) Safety (iBeacon) Major number
Eddystone UID - if enabled
Byte Description Value (hex) Bytes Details
12-28 Data (continued) Variable 10 (BE) Eddystone-UID Namespace ID
Variable 6 (BE) Eddystone-UID Instance ID

Mobile Tag Configuration Packet format

Byte Description Value (hex) Bytes Details
1 Type 0x04 1 Packet type
2 Length variable 1 Length of the Data field
3-6 Data Variable 4 (BE) DEFAULT positioning interval P1 (sec)
7-10 Variable 4 (BE) DEFAULT timeout T1 (sec)
11-12 Variable 2(BE) DEFAULT beaconing ADV interval ADV1 (msec)
13 Variable 1 DEFAULT beaconing TX power TX1 (dBm)
14 Variable 1 Node class
DEFAULT state flag
0x00 = NRLS Mode
0x01 = Autoscan Mode
15-18 Variable 4 (BE) MOTION positioning interval P2 (sec)
19-22 Variable 4 (BE) MOTION timeout T2 (sec)
23-24 Variable 2 (BE) MOTION beaconing ADV interval ADV2 (msec)
25 Variable 1 MOTION beaconing TX power TX2 (dBm)
26 Variable 1 MOTION state flag
0x00 = NRLS Mode
0x01 = Autoscan Mode
27-30 Variable 4 (BE) ALARM positioning interval P3 (sec)
31-34 Variable 4 (BE) ALARM timeout T3 (sec)
35-36 Variable 2 (BE) ALARM beaconing ADV interval ADV3 (msec)
37 Variable 1 ALARM beaconing TX power TX3 (dBm)
38 Variable 1 ALARM state flag

0x00 = NRLS Mode
0x01 = Autoscan Mode
39-42 Variable 4 (BE) SLEEP positioning interval P4 (sec)
43-46 Variable 4 (BE) SLEEP timeout T4 (sec)
47-48 Variable 2 (BE) SLEEP beaconing ADV interval ADV4 (msec)
49 Variable 1 SLEEP beaconing TX power TX4 (dBm)
50 Variable 1 SLEEP state flag
0x00 = NRLS Mode
0x01 = Autoscan Mode
51 Variable 1 Flags
Bit [0] = Leds_En/ Alert_En
Bit [1] = Button_En
52 Variable 1 BLE Beaconing
0x00 = disabled
0x01 = Quuppa Emulation Mode
0x02 = iBeacon
0x03 = Safety
0x04 = Eddystone-UID
53- Variable Variable Beaconing Configuration Parameters (below)
x Variable 1 Accelerometer Mode
0 = Powerdown
1 = Motion Detection
2 = Position Detection
3 = Position + Motion (+Mandown)
4 = Free-fall Detection
5 = Free-fall + Motion (+Mandown)
8 = Shock Detection
9 = Shock + Motion (+Mandown)
(x+1)- Variable Variable Accelerometer Configuration Parameters (below)
Beaconing - Quuppa Emulation mode
Byte Description Value (hex) Bytes Details
53-58 Data (continued) Variable 6 (BE) Quuppa tag ID
Beaconing - iBeacon
Byte Description Value (hex) Bytes Details
53-73 Data (continued) Variable 16 (BE) iBeacon UUID
Variable 2 (BE) iBeacon Major number
Variable 2 (BE) iBeacon Minor number
Beaconing - Safety
Byte Description Value (hex) Bytes Details
53-71 Data (continued) Variable 16 (BE) Safety (iBeacon) UUID
Variable 2 (BE) Safety (iBeacon) Major number
Beaconing - Eddystone-UID
Byte Description Value (hex) Bytes Details
53-70 Data (continued) Variable 10 (BE) Eddystone-UID Namespace ID
Variable 6 (BE) Eddystone-UID Instance ID
Accelerometer - Motion Detection

In this mode the accelerometer will recognize whether the tag is still or moving.

The configuration parameters are:

  • Movement detection threshold (units of 16mg) - Range [1, 127] - Defines the intensity of movement. Acceleration needs to be greater than the threshold to detect movement. In real world physics, this value can be expressed in mg units, knowing that 1 LSb = 16 mg (1 mg = g / 1000, g is the gravitational acceleration).
  • Movement detection duration (seconds) - Range [0, 255] - Defines the minimum time period for which the acceleration must be greater than the threshold.
Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable Variable Motion Threshold in 16mg units [1, 127]
x+2 Variable Variable Motion Duration in sec [0,255]
Accelerometer - Position Detection

In this mode the accelerometer will recognize tag position changes: vertical position or horizontal position of the tag. The horizontal / vertical position is detected against the accelerometer Z axis, that is the axis orthogonal to the device board.

The configuration parameters are:

  • Angle (degrees) - Range [1, 90] - Defines the angle that the board uses to detect the horizontal / vertical position.
  • Position detection duration (seconds) - Range [1, 255] - Defines the minimum time period that the device should be stable in the position.
Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable Variable Position Angle in degree [1, 90]
x+2 Variable Variable Position Duration in sec [1, 255]
Accelerometer - Position + Motion Detection
Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable Variable Position Angle in degree [1, 90]
x+2 Variable Variable Position Duration in sec [1, 255]
x+3 Variable Variable Motion Threshold in 16mg units [1, 127]
x+4 Variable Variable Motion Duration in sec [0,255]
x+5 Variable (optional) Variable Debounce Duration in sec [0, 255]
x+6 Variable (optional) Variable Stationary Duration in sec [0, 255]
x+7 Variable (optional) Variable Alert Duration in sec [0, 255]
Accelerometer - Freefall Detection

In this mode the accelerometer will recognize tag freefall events.

The configuration parameters are:

  • Minimum fall height (centimeters)
    • Range [50, 255]
    • Defines the minimum fall height for which the freefall will be recognized at the lowest sensitivity. Any fall below this height won’t be detected.
  • Sensitivity (units of 50mG)
    • Range [1, 10]
    • Defines the sensitivity to use for freefall detection.
      A low sensitivity will recognize only freefall events very close to the 0g acceleration – lowering the probability of false positives, but increasing the probability of missing detection.
      A high sensitivity will be more permissive with freefall detection – this will increase the probability of false positives but decrease the missing falls detection.
Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable Variable Freefall Height in cm [50, 255]
x+2 Variable Variable Freefall Sensitivity [1, 10]
Accelerometer - Freefall + Motion Detection
Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable Variable Freefall Height in cm [50, 255]
x+2 Variable Variable Freefall Sensitivity [1, 10]
x+3 Variable Variable Motion Threshold in 16mg units [1, 127]
x+4 Variable Variable Motion Duration in sec [0,255]
x+5 Variable (optional) Variable Debounce Duration in sec [0, 255]
x+6 Variable (optional) Variable Stationary Duration in sec [0, 255]
x+7 Variable (optional) Variable Alert Duration in sec [0, 255]
Accelerometer - Shock Detection

In this mode the accelerometer will recognize an unexpected strong acceleration of the tag.

The configuration parameters are:

  • Shock intensity (units of 50mg)
    • Range [1, 10]
    • Defines the intensity to be recognized as a shock. Min = 1: small shock detected; Max = 10: only big shocks are detected
    • The shock intensity starts from 1500 mg, following the equation
MathJax TeX Test Page $$ Shock = 1500mG + (Shock\_intensity \cdot 50mG) $$
Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable Variable Shock Intensity [1, 10]
Accelerometer - Shock + Motion Detection
Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable Variable Shock Intensity [1, 10]
x+2 Variable Variable Motion Threshold in 16mg units [1, 127]
x+3 Variable Variable Motion Duration in sec [0,255]
x+4 Variable (optional) Variable Debounce Duration in sec [0, 255]
x+5 Variable (optional) Variable Stationary Duration in sec [0, 255]
x+6 Variable (optional) Variable Alert Duration in sec [0, 255]

Important notes

  • Positioning rate P4 in SLEEP state is strongly suggested to be set to a relatively high value, such as 1 per day or less frequently

  • When positioning rate is set less then 60 seconds the tag automatically enters Autoscan mode. Please be aware of energy consumption since in Autoscan mode the tag maintains the connectivity to the network (see below for details on various tag/anchor modes).

  • Carefully take into consideration your use-case to program the parameters positioning interval (P1, P2, P3, P4), timeout (T1, T2, T3) and accelerometer threshold THR, in order to avoid excessive energy consumption (due, for instance, to too-short positioning interval or too-long timeout values or extremely-low accelerometer threshold that triggers unwanted movement detection). Not properly designed values could impact on battery operating life.

  • Consider that each time a state transition occurs, a network scan is performed: avoid configurations that could lead to excessive state transitions.

BLE Beaconing

BLE beaconing can be enabled on both moving tags and anchors. Enabling BLE beaconing allows to manage advanced functionalities such as:

  • hybrid RTLS system with sub-areas covered with specific antenna systems such as Quuppa RTLS platform or BlueUp ZoneRTLS platform (beaconing enabled in moving tag);
  • enabling proximity detection systems for smartphone-based applications (beaconing enabled in anchors).

Beaconing functionality is disabled by default (unless requested in production), and can be enabled and configured with Application Data Configuration.

Mobile Tag Beaconing

BlueUp firmware introduced specific support for different BLE packet types:

  • Quuppa Emulation Mode: packet format compatible with Quuppa localization platform, allows a sub-meter accuracy;
  • iBeacon: standard BLE advertising format specified by Apple for proximity applications;
  • Safety: BlueUp proprietary format, using iBeacon format with minor number used for broadcasting tag internal information like battery voltage, motion status, button pressure, …

In case of moving tags, beaconing follows the same FSM behavior of the figure above: advertising interval ADVn (n=1,2,3,4) and transmission power TXn (n=1,2,3,4) vary depending on tag state (DEFAULT, MOTION, ALARM, SLEEP) and are configurable.

Anchor Tag Beaconing

BlueUp firmware introduced specific support for different BLE packet types:

  • iBeacon: standard BLE advertising format specified by Apple for proximity applications;
  • Eddystone-UID: BLE packet format specified by Google.

In case of anchor tags, DEFAULT-state beaconing settings are used.

Sensors Packet Structure

BlueBeacon Wirepas FW v.3 supports Sensors packet frame type. The BlueBeacon Wirepas Ultra Deluxe is the most suitable device for Sensing purpose and, at the moment, is equipped with temperature, humidity, pressure and CO2 sensors.

Data message is sent on source/destination endpoint 238/238.

The following table contains the Sensor Packet format.

Byte Description Value (hex) Bytes Details
0 Type 0x71 1 Sensors packet type
1 Length Variable 1 Length of the Data field
2- Data Variable Variable Array of Sensor Data Structures

Data is an array of array of Sensor Data Structures.

Each Sensor Data Structure has the following format:

Byte Description Value (hex) Bytes Details
0 Sensor Type See Sensor Types Table 1 The sensor type (i.e. temperature, humidity, etc.)
1 Sensor ID See Sensor IDs Table 1 A unique ID assigned to sensor from the firmware
2- Sensor Data See Sensor Types/Data Table Variable Data measured from the sensor

Since the hardware board can have multiple sensors that are measured simultaneously, Sensor Packet Data can be interpreted as an array of Sensor Data Structures, one for each measured sensor, i.e.:

SENSOR_TYPE_1, SENSOR_ID_1, SENSOR_DATA_1, SENSOR_TYPE_2, SENSOR_ID_2, SENSOR_DATA_2, SENSOR_TYPE_3, SENSOR_ID_3, SENSOR_DATA_3, ...

Sensor Types Table

Value Sensor Type
0 sensor_type_temperature
1 sensor_type_humidity
2 sensor_type_temperature_humidity
3 sensor_type_temperature_humidity_co2
4 sensor_type_pressure
5 sensor_type_light
6 sensor_type_voc
100 sensor_type_pir
101 sensor_type_hall

Sensor IDs Table

Value Sensor ID Sensor Type Description
1 ens210 Temperature ScioSense ENS210
5 bmp38x Pressure Bosch Sensortech BMP384/388
8 scd41 CO2 Sensirion SCD41
100 Pir sensor PIR Generic PIR Sensor
101 Hall sensor Hall Generic Hall Sensor

Sensor Types / Data Table

Sensor Type Data Format Sensor Data Description
_temperature int32 (BE) temperature_m_deg_c Milli-degree Celsius
_humidity int32 (BE) humidity_m_percent Milli-percent
_temperature_humidity int32 (BE) temperature_m_deg_c Milli-degree Celsius
int32 (BE) humidity_m_percent Milli-percent
_temperature_humidity_co2 int32 (BE) temperature_m_deg_c Milli-degree Celsius
int32 (BE) humidity_m_percent Milli-percent
int32 (BE) co2_ppm Parts-Per-Million
_pressure int32 (BE) pressure_pa Pascal
_light int32 (BE) light Not present yet
_voc int32 (BE) eco2_ppm Equivalent PPM
int32 (BE) tvoc_ppb Total volatile organic compound – PPB
_pir uint8 pir [0,1] value to indicate whether PIR sensor has detected
_hall uint8 hall [0,1] value to indicate whether Hall sensor has detected

Operation Modes

Two operating modes are dedicated to tag (Autoscan and NRLS) and two operating modes are dedicated to anchors (Opportunistic and Autoscan).

Tag: NRLS mode

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 WM, send the collected measurements, receive application configuration, disconnect from WM and finally change to sleep mode.

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.

Even if in NRLS mode the tag maintains connectivity only as long as is required to deliver the measurements there are two advantages: power consumption is reduced given that the tag is in sleep mode most of the time and 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 wake-up.

NRLS mode is the recommended mode for a standard asset tracking tag.

Tag: Autoscan mode

In the autoscan mode the tag is a standard low-energy subnode. 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 to detect and collect 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.

Since the tag in Autoscan mode maintains the connectivity, the power consumption is higher than in NRLS mode especially when the tag is moving around.

For this reason its use is recommended only in special use cases.

Anchor: Opportunistic mode

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 headnodes/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 mode

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

Configuration over Wirepas network

It is possible to modify configuration parameters of the tags and trigger specific actions (like switching ON and OFF of LED, vibration, buzzer, …) by using the “Application Data Configuration” for the Wirepas network.

Commands have the following syntax: [Class] [Type] [Length] [Value] where each field is described in the following.

[Class] enables to differentiate among tag groups, if necessary.

By default, the “Class” is assigned to BlueUp tags and anchors according to the following table:

Tag function Class
Anchor tags (router mode) 0xF9
Moving tags (non-router mode) 0xFA

Sent commands are addressed to one or more Class(es). It is required to know the tag Class for sending commands.

Custom Class can be applied to tags/anchors in production, based on customer specifications. Custom Class must be specified when ordering.

[Type] identifies the chosen functionality or parameter to modify. [Length] defines data size (in bytes). [Value] to be updated or activation/deactivation data.

Anchor Tag Configuration command

Byte Description Value (hex) Bytes Details
1 Class Variable 1 0xF9 (Anchor Tag)
2 Type 0xA2 1 Packet type
3 Length Variable 1 Length of the Data field
Min 4 = Beaconing Disabled
Max 25 = Beaconing Enabled
4-5 Data Variable 2 (BE) Sensing interval (sec)
6 Variable 1 Flags:
Bit [0] = Leds/Alerts Enable
Bit [1] = Button Enable
Bit [2] = Off by Position (from v3.12)
Bit [3-5] = Max TxPower (from v3.14)
7 Variable 1 Enable BLE Beaconing
0x00 = Disabled
0x02 = iBeacon
0x04 = Eddystone-UID

Max TxPower

Value Bitmask Description
0 000 AUTO (+4 dBm)
1 001 -20 dBm
2 010 -20 dBm
3 011 -16 dBm
4 100 -12 dBm
5 101 -8 dBm
6 110 -4 dBm
7 111 0 dBm

Beaconing - if enabled

Byte Description Value (hex) Bytes Details
8-9 Data (continued) Variable 2 (BE) Beaconing ADV interval ADV (msec)
10 Variable 1 Beaconing TX power TX (dBm)

iBeacon - if enabled

Byte Description Value (hex) Bytes Details
11-26 Data (continued) Variable 16 (BE) iBeacon UUID
27 Variable 1 iBeacon Major format
0x00 = 0
0x01 = Tag model number
0x02 = Tag serial number
0x03 = MSB (NodeAddress)
28 Variable 1 iBeacon Minor format
0x00 = 0
0x01 = Tag model number
0x02 = Tag serial number
0x03 = LSB (NodeAddress)

Eddystone-UID - if enabled

Byte Description Value (hex) Bytes Details
11-20 Data (continued) Variable 10 (BE) Eddystone-UID Namespace ID
21 Variable 1 Eddystone-UID Instance ID format
0x00 = 0
0x01 = Tag model/serial number
0x02 = NodeAddress

Mobile Tag Configuration command

Byte Description Value (hex) Bytes Details
1 Class Variable 1 0xFA (Mobile Tag)
2 Type 0xB2 1 Packet Type
3 Length Variable 1 Length of the Data field
Min 18 = Beaconing Disabled
Max 37 = Beaconing Enabled
4-5 Data Variable 2 (BE) DEFAULT positioning interval P1 [10-64000](sec)
6-7 Variable 2 (BE) MOTION positioning interval P2 [10-64000](sec)
0 if Motion Threshold 0
8-9 Variable 2 (BE) ALARM positioning interval P3 [10-64000](sec)
0 if Alerts disabled
10-11 Variable 2 (BE) SLEEP positioning interval P4 [10-64000](sec)
12-13 Variable 2 (BE) DEFAULT timeout T1 [60-64000](sec)
14-15 Variable 2 (BE) MOTION timeout T2 [60-64000](sec)
0 if Motion Threshold 0
16-17 Variable 2 (BE) ALARM timeout T3 [60-64000](sec)
0 if Alerts disabled
18-19 Variable 2 (BE) Flags:
Bit [0] = Leds/Alerts Enable
Bit [1] = Button Enable
Bit [2-5] = Autoscan Enable (1-bit per state)
20 Variable 1 Accelerometer Mode:
0x01 = MOTION_DETECTION
0x03 = POSITION DETECTION
0x83 = POSITION + MAN_DOWN DETECTION
0x05 = FREEFALL
0x85 = FREEFALL + MAN_DOWN DETECTION
0x09 = SHOCK
0x89 = SHOCK + MAN_DOWN DETECTION
21- Variable Variable Accelerometer_CFG = Configuration Parameters
depending on Accelerometer Mode
x Variable 1 Enable BLE Beaconing
0x00 = Disabled
0x01 = Quuppa Emulation Mode
0x02 = iBeacon
0x03 = Safety

Accelerometer Modes Parameters

The default values of the parameters are listed below. In case of MANDOWN Detection Mode, the additional parameters are:

  • Debounce Duration [0, 255] sec = defines the maximum time interval in which the body of the fallen person or of the object bounces when hit on the ground.
  • Stationary Duration [0, 255] sec = defines the minimum time interval in which the body or the object should remain stationary on the ground to detect the ManDown event.
  • Alert Duration [0, 255] sec = defines the Alarm duration time interval, after the ManDown event has been detected, during which the tag emits an alarm sound and after which the tag starts sending data about the ManDown event detection. If the Alert Duration is equal to 0 the tag starts sending ManDown detection data immediately. If the Alert Duration is set to a non-zero value, the tag will wait for Alert Duration time to send data and at the same time will emit an alarm sound. If the alarm is disabled by button during this time, it means that it was a false detection and the tag will not send ManDown detection data.
Motion Detection
Byte Description Value (hex) Bytes Details
20 Data (continued) Variable 1 0x01 = MOTION_DETECTION
21 Variable 1 Motion Threshold in 16mg units [1, 127]
22 Variable 1 Motion Duration in sec [0,255]
Position Detection
Byte Description Value (hex) Bytes Details
20 Data (continued) Variable 1 0x03 = POSITION + MOTION_DETECTION
21 Variable 1 Position Angle in degree [1, 90]
22 Variable 1 Position Duration in sec [1, 255]
23 Variable 1 Motion Threshold in 16mg units [1, 127]
24 Variable 1 Motion Duration in sec [0,255]
Position + ManDown Detection
Byte Description Value (hex) Bytes Details
20 Data (continued) Variable 1 0x83 = POSITION + MOTION_DETECTION
21 Variable 1 Position Angle in degree [1, 90]
22 Variable 1 Position Duration in sec [1, 255]
23 Variable 1 Motion Threshold in 16mg units [1, 127]
24 Variable 1 Motion Duration in sec [0,255]
25 Variable 1 Debounce Duration in sec [0, 255]
26 Variable 1 Stationary Duration in sec [0, 255]
27 Variable 1 Alert Duration in sec [0, 255]
Freefall Detection
Byte Description Value (hex) Bytes Details
20 Data (continued) Variable 1 0x05 = FREEFALL_DETECTION
21 Variable 1 Freefall Height in cm [50, 255]
22 Variable 1 Freefall Sensitivity [1, 10]
23 Variable 1 Motion Threshold in 16mg units [1, 127]
24 Variable 1 Motion Duration in sec [0,255]
Freefall + ManDown Detection
Byte Description Value (hex) Bytes Details
20 Data (continued) Variable 1 0x85 = FREEFALL + MOTION_DETECTION
21 Variable 1 Freefall Height in cm [50, 255]
22 Variable 1 Freefall Sensitivity [1, 10]
23 Variable 1 Motion Threshold in 16mg units [1, 127]
24 Variable 1 Motion Duration in sec [0,255]
25 Variable 1 Debounce Duration in sec [0, 255]
26 Variable 1 Stationary Duration in sec [0, 255]
27 Variable 1 Alert Duration in sec [0, 255]
Shock Detection
Byte Description Value (hex) Bytes Details
20 Data (continued) Variable 1 0x09 = SHOCK_DETECTION
21 Variable 1 Shock Intensity [1, 10]
22 Variable 1 Motion Threshold in 16mg units [1, 127]
23 Variable 1 Motion Duration in sec [0,255]
Shock + ManDown Detection
Byte Description Value (hex) Bytes Details
20 Data (continued) Variable 1 0x89 = SHOCK + MOTION_DETECTION
21 Variable 1 Shock Intensity [1, 10]
22 Variable 1 Motion Threshold in 16mg units [1, 127]
23 Variable 1 Motion Duration in sec [0,255]
24 Variable 1 Debounce Duration in sec [0, 255]
25 Variable 1 Stationary Duration in sec [0, 255]
26 Variable 1 Alert Duration in sec [0, 255]
Accelerometer Modes default parameters values
Mode Parameter Value
Motion Detection (always on) Motion Threshold 10* (160 mG)
Motion Duration 3 (3 sec)
Position Detection Position Angle 45 (45 degrees)
Position Duration 3 (3 sec)
Free-fall Detection Free-fall Height 80 (80 cm)
Free-fall Sensitivity 5 (250 mG)
Shock Detection Shock Intensity 7 (1850 mG)
Man-Down Detection (additional detection mode) Debounce Duration 3 (3 sec)
Stationary Duration 10 (10 sec)
Alert Duration 60 (60 sec)

Motion Threshold equal to 10 is a sufficient value for both asset and people tracking to not to have false movement detection even if the tag is worn pendent around the neck and there are small oscillations of the tag.

Beaconing - if enabled

Common parameters in case beaconing is enabled

Byte Description Value (hex) Bytes Details
x+1 Data (continued) Variable 2 (BE) DEFAULT beaconing ADV interval ADV1 (msec)
x+2 Variable 2 (BE) MOTION beaconing ADV interval ADV2 (msec)
x+3 Variable 2 (BE) ALARM beaconing ADV interval ADV3 (msec)
x+4 Variable 2 (BE) SLEEP beaconing ADV interval ADV4 (msec)
x+5 Variable 1 ALL STATES beaconing TX power TX (dBm)
Quuppa - if enabled
Byte Description Value (hex) Bytes Details
x+6 Data (continued) Variable 1 Quuppa Tag ID format
0x00 = MAC address
0x01 = Tag model number + serial number
0x02 = NodeAddress
iBeacon - if enabled
Byte Description Value (hex) Bytes Details
x+6 Data (continued) Variable 1 iBeacon UUID
0x00=default BlueUp
x+7 Variable 1 Beacon Major format
0x00 = 0
0x01 = Tag model number
0x02 = Tag serial number
0x03 = MSB(NodeAddress)
x+8 Variable 1 iBeacon Minor format
0x00 = 0
0x01 = Tag model number
0x02 = Tag serial number
0x03 = LSB(NodeAddress)
Safety - if enabled
Byte Description Value (hex) Bytes Details
x+6 Data (continued) Variable 1 Safety (iBeacon) UUID
0x00=default BlueUp for Safety
x+7 Variable 1 Safety (iBeacon) Major format
0x00 = 0
0x01 = Tag model number
0x02 = Tag serial number
0x03 = LSB(NodeAddress)

IMPORTANT NOTES

  • A sent command is persistent in the network. Each tag in the network receives this command (if the tag Class coincides with the Class in the command), and each new tag entering the network (with Class coinciding with that of the command) also receives the command.

  • Each configuration command SHOULD include command for Mobile Tags (Type = 0xB2; default Class = 0xFA) and command for Anchor Tags (Type = 0xA2; default Class = 0xF9). Since the command is persistent on the network, any new tag (either Mobile or Anchor Tag) entering the network, will receive the configuration command. If only one type of tags (Mobile or Anchor Tags) needs to be updated, the configuration command SHOULD be sent also for the other type of tags (Anchor or Mobile Tags), by simply using the previous command settings.

  • A tag operating or configured for NRLS mode will receive the command and apply it only upon wake-up (during connection to the mesh network after scan for nearby anchors). Consequently, maximum time delay to receive command is equal to the configured positioning period.

Commands over Wirepas Network

The following paragraphs describe the BlueUp packet specifications for sending commands over Wirepas Network to a Wirepas Node.

Data message is sent on source/destination endpoint 73/73.

Reboot (0xB0)

This command is used to Reboot a Node.

Index Value Description
0 0xB0 Command Type 176
1 0 Length

API example to Gateway/api/sink/data1/sendMessage:

{
 “dst_addr” : 4000000,
 “src_ep” : 73,
 “dst_ep” : 73,
 “buffering_delay” : 1,
 “qos” : false,
 “is_unlock_csma_ca” : false,
 “hop_limit : 15,
 “data : [176, 0]
 }

Factory Reset (0xB1)

Index Value Description
0 0xB1 Command Type 177
1 0 Length

Button Configuration (0xB2)

This command is used to enable or disable the button on a device.

Index Value Description
0 0xB2 Command Type 178
1 0 Length
2 Variable Command argument
0 = disable
1 = enable

API example to Gateway/api/sink/data1/sendMessage:

Type: 178
Length: 1
Value: 1 (Button enable)

{
 “dst_addr” : 4000000,
 “src_ep” : 73,
 “dst_ep” : 73,
 “buffering_delay” : 1,
 “qos” : false,
 “is_unlock_csma_ca” : false,
 “hop_limit : 15,
 “data : [178, 1, 1]
 }

Alert Configuration (0xB3)

Node Alarm configuration (led / buzzer / vibration).

Index Value Description
0 0xB3 Command Type 179
1 10 Length
2 Variable Buzzer Period (unit 100ms)
3 Variable Buzzer Repeats
4 Variable Buzzer DutyCycle (%)
5 Variable Vibration Period (unit 100ms)
6 Variable Vibration Repeats
7 Variable Vibration DutyCycle (%)
8 Variable Leds Period (unit 100ms)
9 Variable Leds Repeats
10 Variable Led DutyCycle (%)
11 Variable Leds Color/Enable Mask

Leds Color / Enable Mask

BIT 7 BIT 6 BIT 5 BIT 4 BIT 3 BIT 2 BIT 1 BIT 0
Seq. R G B LED 3 LED 2 LED 1 LED 0

API example to Gateway/api/sink/data1/sendMessage:

Type: 179
Length: 10
Value: 0, 0, 0, 0, 0, 0, 10, 5, 50, 66

  • Leds Period: 10 (100ms)
  • Leds Repeats: 5
  • Leds DutyCycle: 50 (%)
  • Leds Color/Enable Mask: 66 = 0x42 =0b 0100 0010
    • Color: RED
    • Enable/Mask: LED1
{
 “dst_addr” : 4000000,
 “src_ep” : 73,
 “dst_ep” : 73,
 “buffering_delay” : 1,
 “qos” : false,
 “is_unlock_csma_ca” : false,
 “hop_limit : 15,
 “data : [179, 10, 0, 0, 0, 0, 0, 0, 10, 5, 50, 66]
 }

Accelerometer Configuration (0xB4)

Index Value Description
0 0xB4 Command Type 180
1 Variable Length of Data field
2 Variable Accelerometer Mode:
0x00 = POWERDOWN
0x01 = MOTION_DETECTION
0x02 = POSITION_DETECTION
0x03 = POSITION + MOTION_DETECTION
0x04 = FREEFALL_DETECTION
0x05 = FREEFALL + MOTION_DETECTION
0x08 = SHOCK_DETECTION
0x09 = SHOCK + MOTION_DETECTION
3- Variable Accelerometer_CFG = Configuration Parameters depending on Accelerometer Mode

To the underlined Accelerometer Modes (Position + Motion_Detection, Freefall + MotionDetection, Shock + Motion_Detection) it is possible to optionally add the MANDOWN Detection Mode. The additional parameters are:

  • Debounce Duration [0, 255] sec = defines the maximum time interval in which the body of the fallen person or of the object bounces when hit on the ground.
  • Stationary Duration [0, 255] sec = defines the minimum time interval in which the body or the object should remain stationary on the ground to detect the ManDown event.
  • Alert Duration [0, 255] sec = defines the Alarm duration time interval, after the ManDown event has been detected, during which the tag emits an alarm sound and after which the tag starts sending data about the ManDown event detection. If the Alert Duration is equal to 0 the tag starts sending ManDown detection data immediately. If the Alert Duration is set to a non-zero value, the tag will wait for Alert Duration time to send data and at the same time will emit an alarm sound. If the alarm is disabled by button during this time, it means that it was a false detection and the tag will not send ManDown detection data.

Power Down

Index Value Description
2 Variable 0x00 POWERDOWN
3 0x00 Null

Motion Detection

Index Value Description
2 Variable 0x01 = MOTION_DETECTION
3 Variable Motion Threshold in 16mg units [1, 127]
4 Variable Motion Duration in sec [0,255]

Position Detection

Index Value Description
2 Variable 0x02 = POSITION_DETECTION
3 Variable Position Angle in degree [1, 90]
4 Variable Position Duration in sec [1, 255]

Position + Motion Detection

Index Value Description
2 Variable 0x03 = POSITION + MOTION_DETECTION
3 Variable Position Angle in degree [1, 90]
4 Variable Position Duration in sec [1, 255]
5 Variable Motion Threshold in 16mg units [1, 127]
6 Variable Motion Duration in sec [0,255]
7 Variable (optional) Debounce Duration in sec [0, 255]
8 Variable (optional) Stationary Duration in sec [0, 255]
9 Variable (optional) Alert Duration in sec [0, 255]

Freefall Detection

Index Value Description
2 Variable 0x04 = FREEFALL_DETECTION
3 Variable Freefall Height in cm [50, 255]
4 Variable Freefall Sensitivity [1, 10]

Freefall + Motion Detection

Index Value Description
2 Variable 0x05 = FREEFALL + MOTION_DETECTION
3 Variable Freefall Height in cm [50, 255]
4 Variable Freefall Sensitivity [1, 10]
5 Variable Motion Threshold in 16mg units [1, 127]
6 Variable Motion Duration in sec [0,255]
7 Variable (optional) Debounce Duration in sec [0, 255]
8 Variable (optional) Stationary Duration in sec [0, 255]
9 Variable (optional) Alert Duration in sec [0, 255]

Shock Detection

Index Value Description
2 Variable 0x08 = SHOCK_DETECTION
3 Variable Shock Intensity [1, 10]

Shock + Motion Detection

Index Value Description
2 Variable 0x08 = SHOCK_DETECTION
3 Variable Shock Intensity [1, 10]
4 Variable Motion Threshold in 16mg units [1, 127]
5 Variable Motion Duration in sec [0,255]
6 Variable (optional) Debounce Duration in sec [0, 255]
7 Variable (optional) Stationary Duration in sec [0, 255]
8 Variable (optional) Alert Duration in sec [0, 255]

GPIO Pin Configuration

Index Value Description
0 0xB5 Command Type 181
1 1 Length
2 Variable, range [0, 3] GPIO ID
3 Variable GPIO Mode
4 Variable (optional) GPIO Send Interval (min): if specified, it defines the
time Interval with which the Logic Level of the GPIO is sent

GPIO Mode

BIT 7 BIT 6 BIT 5 BIT 4 BIT 3 - BIT 2 BIT 1 BIT 0
RESET RFU RFU VALUE PULLCFG HIDRIVE OUTPUT
Bit Name Description
0 OUTPUT 0 = Input
1 = Output
1 HIDRIVE HIDRIVE Mode
Only if Output = 1
2-3 PULLCFG 0 = NoPull
1 = PullDown
3 = PullUp
Only if Output = 0
4 VALUE 0 = Low Logic Level
1 = High Logic Level
Only if Output = 1
5-6 RFU -
7 RESET If set to 1, the default configuration of the Pin is reset (HIGH-IMPEDANCE),
while other configuration bit are not considered.

API example to Gateway/api/sink/data1/sendMessage:

Type: 181
Length: 2
Value: 0, 17

  • GPIO ID: 0
  • GPIO Mode: 17 = 0x11 = 0b 0001 0001
    • Output: 1
    • Value: 1 (High)
      {
       “dst_addr” : 4000000,
       “src_ep” : 73,
       “dst_ep” : 73,
       “buffering_delay” : 1,
       “qos” : false,
       “is_unlock_csma_ca” : false,
       “hop_limit : 15,
       “data : [181, 2, 0, 17]
       }
      

Other API example to Gateway/api/sink/data1/sendMessage:

Type: 181
Length: 2
Value: 0, 128

  • GPIO ID: 0
  • GPIO Mode: 128 = 0x80 = 0b 1000 0000
    • Reset: 1
{
 “dst_addr” : 4000000,
 “src_ep” : 73,
 “dst_ep” : 73,
 “buffering_delay” : 1,
 “qos” : false,
 “is_unlock_csma_ca” : false,
 “hop_limit : 15,
 “data : [181, 2, 0, 128]
 }

Other API example to Gateway/api/sink/data1/sendMessage:

Type: 181
Length: 2
Value: 0, 12, 5

  • GPIO ID: 0
  • GPIO Mode: 12 = 0x0C = 0b 0000 1100
    • Output: 0
    • PullCFG: 3 (PullUp)
  • GPIO Send Interval: 5 min

The H/L Logic Level is sent every time a logic level transition HL/LH occurs and also every 5 minutes.

{
 “dst_addr” : 4000000,
 “src_ep” : 73,
 “dst_ep” : 73,
 “buffering_delay” : 1,
 “qos” : false,
 “is_unlock_csma_ca” : false,
 “hop_limit : 15,
 “data : [181, 3, 0, 12, 5]
 }

Sensors Configuration (0xB6)

Sensors Measure Interval configuration.

Index Value Description
0 0xB6 Command Type 182
1 0 or 4 Length
0 = Sensor Measure is disabled.
2-5 UINT32BE Measure Interval (sec) Only if Length = 4
Min = 300, Max = 86400

Sensors Calibrate (0xB7)

If available, performs a CO2 sensor calibration.

If Length is set to 0 or Target CO2 is set to a value below the minimum (400 ppm), the calibration is performed with a Target CO2 value = 400 ppm.

Index Value Description
0 0xB7 Command Type 183
1 0 or 2 Length
2-3 UINT32BE Target CO2 (ppm) Only if Length = 2
Min = 400, Max = 65535 (theoretically)*

The CO2 will be calibrated by a pre-calibrated CO2 measurement instrument, which will measure a variable CO2 within the ranges [400, 1600, .. max 2000] ppm.

Send Configuration (0xB8)

This command is used to request the current Node Configuration.

Index Value Description
0 0xB8 Command Type 184
1 0 Length

5.10. Send Positioning (0xB9)

This command is used to request the current Node Positioning Data.

Index Value Description
0 0xB9 Command Type 185
1 0 Length

Firmware update using Wirepas Network Tool (WNT)

The Firmware update can be performed using WNT v4 in Settings → Node Update. The Firmware Update operation can take some time to complete.

Node update

In the Scratchpad File field upload the otap file provided by BlueUp.

Scratchpad file

In this tab it is also possible to require the information about the nodes. By pressing the Run once button in Query Information.

Query information

After performing this operation, the WNT controls all the nodes and updates the information fields, as shown in the screenshots below.

Updated info

Updated info 2

Updated info 3

If there is “No otap” in Scratchpad Action field, this means that there is no otap pending in the network and the Firmware Update can be performed.

After pressing Continue, figure below will appear.

In the Scratchpad File Information, the Version refers to the FW version to be uploaded.

To start the otap procedure, press Start scratchpad status query.

Start status query

After the first step is completed (Responses: 1 / 2) the client has to choose the update method. The method to use is OTAP v2, for which the firmware was designed, that performs the update of the firmware automatically.

Start update

Status steps

Propagation

After the Propagation Step is completed, looking at the information of the Sink and the Nodes, the Scratchpad Action on the Sink is “Propagate and Process”, while on the Nodes is “No otap”. This means that the otap file has reached the Sink and it has to be propagated to the Nodes.

Propagation 2

Finish

After all the operations are completed, the Sink and Nodes tab contains updated information.

Information after FW Update

Information after FW Update 2

Information after FW Update 3