Wirepas firmware v.4. User Guide

In the following are described the features of the Wirepas Firmware v.4.x developed for the BlueUp Positioning Application

BlueUp Custom Packets (73/73)

BlueUp custom packets are sent on source/destination endpoint 73/73.
In the following are described the BlueUp packets sent by Wirepas devices.

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.

Anchor Configuration Packet format

Quuppa emulation - if enabled

iBeacon - if enabled

Safety - if enabled

Eddystone UID - if enabled

Tag Configuration Packet format

Quuppa Emulation mode - if enabled

iBeacon - if enabled

Safety - if enabled

Eddystone-UID - if enabled

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.

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.

Accelerometer - Position + Motion Detection

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.

Accelerometer - Freefall + Motion Detection

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

Accelerometer - Shock + Motion Detection

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.

Sensor Info

Hardware Info

Packet introduced from FW v.4.x

Command Response

Packet introduced from FW v.4.x

Wirepas Measurement Packets (238/238)

The Wirepas Measurement packets are managed directly by Wirepas and are sent on source/destination endpoint 238/238.
For more information refer to Wirepas Positioning Application Reference Manual v1.5

Battery voltage

This is a Wirepas Standard TLV packet.

Tag RSSI Measurement

This is a Wirepas Standard TLV packet.

Anchor RSSI Measurement

This is a Wirepas Standard TLV packet.

GPIO State

This is a BlueUp custom TLV packet.

Sensors Measurement

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.

Data is an array of array of Sensor Data Structures.

Each Sensor Data Structure has the following format:

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

Sensor IDs Table

Sensor Types / Data Table

Radio Installation Quality

This is a BlueUp custom TLV packet.
This packet refers only to Anchors (Router nodes).

Device State

This is a BlueUp custom TLV packet, introduced from FW v.4.x

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:

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 Configuration command

Max TxPower

Beaconing - if enabled

iBeacon - if enabled

Eddystone-UID - if enabled

Tag Configuration command

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

Position Detection

Position + ManDown Detection

Freefall Detection

Freefall + ManDown Detection

Shock Detection

Shock + ManDown Detection

Accelerometer Modes default parameters values

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

Quuppa - if enabled

iBeacon - if enabled

Safety - if enabled

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.

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)

Button Configuration (0xB2)

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

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

Leds Color / Enable Mask

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)

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

Motion Detection

Position Detection

Position + Motion Detection

Freefall Detection

Freefall + Motion Detection

Shock Detection

Shock + Motion Detection

GPIO Pin Configuration

GPIO Mode

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.

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.

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.

Send Positioning (0xB9)

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