Quuppa Compatible Tag

The BlueUp Quuppa Compatible Tag is a category of products developed and manufactured by BlueUp Srl and certified compatible with the Quuppa Positioning system by Quuppa Oy.

The BlueUp Quuppa Compatible Tag firmware uses the Quuppa Tag Firmware Library development framework, which at the time of writing this document is released at version v. 1.101.

The following terminology will be used in this document:

  • QPE: Quuppa Positioning Engine, core application of the Quuppa system, which implements the tag placement system.
  • QSP: Quuppa Site Planner, tool for planning and managing an installation of a Quuppa system.
  • Focusing Locator: Quuppa antenna used in the installation phase of the Quuppa system is able to communicate directly with QSP.
  • Locator: Quuppa antennas installed within the system that communicate with QPE.

Features

Standard Features

The BlueUp Quuppa Compatible Tag firmware provides all the standard features of the Quuppa tags such as: Quuppa data advertising, Quuppa tag configuration, motion detection (tag must have accelerometer to use this feature), button press detection (tag must have button to use this feature), etc. For the configuration of the standard Quuppa features, refer to the Quuppa documentation.

Custom Features

In addition to the standard Quuppa features, the BlueUp Quuppa Compatible Tag, also provides additional features such as:

  • Device Firmware Update

  • Alert triggering (leds, buzzer, vibration) using both Quuppa Temporary Commands and/or Quuppa Backchannel Communication

  • Custom accelerometer management

    • Movement detection (moving / halted)
    • Position detection (vertical / horizontal), can also be combined with Movement detection to enable simultaneous Position+Movement detection
    • Freefall detection, can also be combined with Movement detection to enable simultaneous Freefall+Movement detection
    • Shock detection, can also be combined with Movement detection to enable simultaneous Shock+Movement detection
    • Position / Freefall / Shock detection modes, when combined with Movement detection, can be enabled to detect Man-Down events.

  • Tag configuration and runtime activity flags reported in real-time inside the user payload of Quuppa DF packets.

I/O Peripherals management

Button management

If the tag hardware is equipped with a button and the button is enabled, then the tag will have the following features when the button is pressed.

Event Feature User Feedback
Single-Click None Led 1 turns on when pressed and turns off when released
Click-Hold (5s) Reboot Led 1 lights up when the button is pressed.
At the end of the 5 seconds:
• Led 1 goes off
• Led 2 lights up
Click-Hold (10s) DFU Mode Led 1 lights up when the button is pressed.
At the end of the 5 seconds:
• Led 1 goes off
• Led 2 lights up
At the end of the 10 seconds:
• Led 1 lights up again (both leds are on)

Pressing the button always causes the buttonPressed flag to be sent on the Quuppa advertising packets. Button can be dynamically enabled or disabled by sending a Quuppa Backchannel request to the tag (see “Quuppa Backchannel Commands” section).

I/O management

To drive the I/O peripherals of the tag (leds, buzzer, vibration), the BlueUp Quuppa Compatible Tag firmware can use Quuppa Temporary Commands or Quuppa Backchannel requests.

I/O management with Quuppa Temporary Commands

This method takes advantage of the IO Settings byte of a Quuppa Temporary Command, to enable or disable the I/O peripherals of the tag. Temporary Commands are commands that must be defined during system setup on the QSP and subsequently must be synchronized on the QPE.

Quuppa Temporary Commands activate a state called Temporary State on the tag – so it is necessary to define for each Temporary Command also the advertising interval, tx power, state timeout and a whole series of parameters that are usually not of interest (but which are mandatory).

The IO Settings byte is used by Quuppa on its tags to drive up to 4 I/O peripherals, therefore, for defining commands using this byte, it was necessary to make a mapping between the values assigned by Quuppa and the custom ones implemented on BlueUp firmware.

I/O Settings

The I/O Settings byte, on the Quuppa Site Planner is divided into the following 4 sections:

  • Output 1 – drives output 1 peripheral
  • Output 2 – drives output 2 peripheral
  • Output 3 – drives output 3 peripheral
  • Output 4 – drives output 4 peripheral

Each output can assume the following 4 values:

  • Always Off
  • Always On
  • Blink Slow
  • Blink Fast

The Temporary Command I/O Settings byte is made up as follows:

BIT 7 - BIT 6 BIT 5 - BIT 4 BIT 3 - BIT 2 BIT 1 - BIT 0
Output 4 Output 3 Output 2 Output 1

Each output can assume the following values:

Value Name value (dec) Value (bin)
Always off 0 00
Always On 1 01
Blink Slow 2 10
Blink Fast 3 11

By exploiting the encoding of these values, it is therefore possible to define a subset of commands that the tag can decode to perform actions on its I/O peripherals.

Below are reported the mappings between the Quuppa Temporary Command IO Settings Output fields and the output peripherals of each BlueUp Quuppa Compatible Tag model.

Model Version Outputs Mapping
BlueBeacon Tag 2.0 03/2018 No I/O peripherals present on this device.
BlueBeacon Tag 3.0 11/2018 No I/O peripherals present on this device.
BlueBeacon Card 3.0 11/2018 Output 1 → Orange Led
Output 2 → Green Led
BlueBeacon Forte+ 3.0 06/2019 Output 1 → Orange Led
Output 2 → Red Led (high visibility)
BlueBeacon Forte+ 3.1 06/2019 Output 1 → Orange Led
Output 2 → RGB Led (high visibility)
BlueBeacon SafeX 1.0 04/2019 Output 1 → Orange Led
Output 2 → Red Led
Output 3 → Buzzer
Output 4 → Vibration
BlueBeacon SafeX 2.0 10/2019 Output 1 → Orange Led
Output 2 → Red Led
Output 3 → Buzzer
Output 4 → Vibration

I/O management with Quuppa Backchannel Request

This method is supported only on BlueUp Quuppa Compatible tags with firmware version v4.0 and above.

Quuppa Backchannel communication must be enabled on the QPE license to be able to use this feature.

This method takes advantage of the Quuppa Backchannel communication between the tags and the locators to enable or disable the I/O peripherals of the tag.

This method is more versatile than the Quuppa Temporary Commands, because here we can configure every parameter of the alert – we will call “alert” the I/O peripherals configuration.

An alert is built of these parameters:

  • Buzzer

    • Period, units of 100ms, range [0, 255]
    • Number of repeats, range [0, 255], 255 means active until explicitly disabled
    • Duty-Cycle, percentage value, range [0, 100]

  • Vibration

    • Period, units of 100ms, range [0, 255]
    • Number of repeats, range [0, 255], 255 means active until explicitly disabled
    • Duty-Cycle, percentage value, range [0, 100]

  • Led

    • Period, units of 100ms, range [0, 255]
    • Number of repeats, range [0, 255], 255 means active until explicitly disabled
    • Duty-Cycle, percentage value, range [0, 100]
    • RGB Color, color mask:
      • Blue = 0x01
      • Green = 0x02
      • Cyan = Blue + Green = 0x03
      • Red = 0x04
      • Magenta = Blue + Red = 0x05
      • Yellow = Red + Green = 0x06
      • White = Red + Green + Blue = 0x07
    • LED mask, to choose which led turn on

As we can see, the configuration of an alert is more accurate than the predefined configurations used with the Quuppa Temporary Commands.

In the alert configuration we can customize, for each I/O peripheral (buzzer, vibration, LEDs) the period, the number of repetitions and the duty-cycle of the alert.

Below is shown an image representing some sample period / duty-cycle combinations.

Duty Cycle

Alert parameters should be specified as follows:

  • Periods expressed in units of 100ms
  • Number of repeats should be in range [0, 255]
  • Duty-Cycle should be in range [0, 100]
  • Period = 0 OR Number of repeats = 0 OR Duty-Cycle = 0 means peripheral disabled
  • Duty-Cycle = 100 means peripheral always on
  • Number of repeats = 255 means loop (keep alert active until explicitly disabled)

To send a Backchannel Request to a tag, the simplest way is to use the QPE API:

/qpe/sendQuuppaRequest

This API can take the followings parameters on the query string:

  • tag = tag_1, … , tag_n
  • requestData = request_Bytes
  • time = timeOutMs
  • humanReadable

When working with Quuppa Backchannel communication and BlueUp Quuppa Compatible tags, the requestData parameter must have a predefined format.

The first 3 bytes of the requestData parameter must be set to: ff1d00 (1d00 is the BlueUp Quuppa Company ID).

The 4th byte is the command command byte, the SET_ALERT command is specified as b3.

The next bytes are the command payload (alert parameters).

So, for example, an alert request could the following:

/qpe/sendQuuppaRequest?tag=fdda5ad6933c&requestData=0xff1d00b30a03320a0332 0a033241&humanReadable=true

Analyzing the command we find:

  • the fixed preamble ff1d00

  • the command byte b3

  • The buzzer parameters 0a0332

    • Period = 0x0a = 10 = 10·100ms = 1000ms
    • Number of repeats = 0x03 = 3
    • Duty-Cycle = 0x32 = 50 = 50%

  • The vibration parameters 0a0332

    • Period = 0x0a = 10 = 10·100ms = 1000ms
    • Number of repeats = 0x03 = 3
    • Duty-Cycle = 0x32 = 50 = 50%

  • The Leds parameters 0a033241

    • Period = 0x0a = 10 = 10·100ms = 1000ms
    • Number of repeats = 0x03 = 3
    • Duty-Cycle = 0x32 = 50 = 50%
    • The last byte should be split in the two nibs:
      • RGB Color: 0x04 (Red)
      • Leds mask: 0x01 (Led 1)

Note: In the LEDs peripheral configuration the last byte represents the RGB Color and the LEDs enable mask. This byte is interpreted as a bitmask should be formatted as follows:

BIT 7 BIT 6 BIT 5 BIT 4 BIT 3 BIT 2 BIT 1 BIT 0
- R G B Led 4 Led 3 Led 2 Led 1

Below are reported the mappings used for the LEDs peripherals of each BlueUp Quuppa Compatible Tag model.

Model Version Outputs Mapping
BlueBeacon Tag 2.0 03/2018 No I/O peripherals present on this device.
BlueBeacon Tag 3.0 11/2018 No I/O peripherals present on this device.
BlueBeacon Card 3.0 11/2018 Led 1 → Orange Led
Led 2 → Green Led
BlueBeacon Forte+ 3.0 06/2019 Led 1 → Orange Led
Led 2 → Red Led (high visibility)
BlueBeacon Forte+ 3.1 06/2019 Led 1 → Orange Led
Led 2 → RGB Led (high visibility)
BlueBeacon SafeX 1.0 04/2019 Led 1 → Orange Led
Led 2 → Red Led
BlueBeacon SafeX 2.0 10/2019 Led 1 → Orange Led
Led 2 → Red Led

Backchannel commands

The BlueUp Quuppa Compatible Tag firmware at version v4.0 and above is able to receive commands using Quuppa Backchannel Communication.

The firmware is able to receive commands sent using Quuppa Backchannel Communication to configure some tag features (i.e. enable / disable button, I/O, accelerometer) and perform actions on the tag (i.e. trigger alerts).

To send commands to the tags, the best way is to use the QPE API:

/qpe/sendQuuppaRequest

This API can take the followings parameters on the query string:

  • tag = tag_1, … , tag_n
  • requestData = requestBytes
  • time = timeOutMs
  • humanReadable

When working with Quuppa Backchannel Communication and BlueUp Quuppa Compatible tags, the requestData parameter must have a predefined format.

The first 3 bytes of the requestData parameter must be set to: ff1d00 – where 1d00 is the BlueUp Quuppa Company ID.

The 4th byte is the command command byte and the next bytes are the command payload (if command needs payload data).

Supported commands / Firmware version

In the following tables will be reported the supported commands for each firmware version.

Firmware v3.2 and above

Command Command ID Description
DFU Mode 0xb1 Reboot the tag in DFU (Firmware Update) Mode

Firmware v4.0 and above

Command Command ID Description
Reboot 0xb0 Reboot the tag
DFU Mode 0xb1 Reboot the tag in DFU (Firmware Update) Mode
Enable Button 0xb2 Enable or disable the button on the tag
Set Alert 0xb3 Set or unset an alert on the tag

Firmware v4.1 and above

Command Command ID Description
Reboot 0xb0 Reboot the tag
DFU Mode 0xb1 Reboot the tag in DFU (Firmware Update) Mode
Enable Button 0xb2 Enable or disable the button on the tag
Set Alert 0xb3 Set or unset an alert on the tag
Accelerometer 0xb4 Enable or disable custom accelerometer mode
Enable iBeacon 0xb5 Enable or disable iBeacon packet transmission
Enable Alerts 0xb6 Enable or disable all the alert peripherals of the tag
Factory Reset 0xb7 Perform factory reset

Backchannel commands

This section will explain all supported Backchannel commands and provide QPE API invocation examples.

Reboot (0xb0)

This command will reboot the tag. No payload needed.

Request example:

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b0

DFU Mode (0xb1)

This command will reboot the tag in DFU Mode. No payload needed.

Request example:

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b1

Enable Button (0xb2)

This command will enable or disable the button. Payload is built of a single byte:

  • If payload byte is equal to 0, button will be disabled
  • If payload byte is not equal to 0, button will be enabled

Request example (enable button):

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b201

Request example (disable button):

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b200

Set Alert (0xb3)

This command will enable or disable an alert on the tag. The payload of this command configures the alert parameters and should be 10 bytes long.

An alert is built of these parameters:

  • Buzzer

    • Period, units of 100ms, range [0, 255]
    • Number of repeats, range [0, 255], 255 means active until explicitly disabled
    • Duty-Cycle, percentage value, range [0, 100]

  • Vibration

    • Period, units of 100ms, range [0, 255]
    • Number of repeats, range [0, 255], 255 means active until explicitly disabled
    • Duty-Cycle, percentage value, range [0, 100]

  • LEDs

    • Period, units of 100ms, range [0, 255]
    • Number of repeats, range [0, 255], 255 means active until explicitly disabled
    • Duty-Cycle, percentage value, range [0, 100]
    • RGB Color, color mask:
      • Blue = 0x01
      • Green = 0x02
      • Cyan = Blue + Green = 0x03
      • Red = 0x04
      • Magenta = Blue + Red = 0x05
      • Yellow = Red + Green = 0x06
      • White = Red + Green + Blue = 0x07
    • Led mask, to choose which led turn on

Alert parameters should be specified as follows:

  • Period is expressed in units of 100ms
  • Period should be in range [0, 255]
  • Number of repeats should be in range [0, 255]
  • Duty-Cycle should be in range [0, 100]
  • Period = 0 OR Number of repeats = 0 OR Duty-Cycle = 0 means peripheral disabled
  • Duty-Cycle = 100 means peripheral always on
  • Number of repeats = 255 means loop (keep alert active until explicitly disabled)

Request example, will set an alert that will emit a 250ms beep, vibration and LEDs blink every second for 3 times. Such alert can be configured with the following settings:

  • Buzzer

    • Period: 10 (10 units of 100ms = 1s)
    • Number of repeats: 3
    • Duty-Cycle: 25 (25% of 1s = 250ms)

  • Vibration

    • Period: 10 (10 units of 100ms = 1s)
    • Number of repeats: 3
    • Duty-Cycle: 25 (25% of 1s = 250ms)

  • Led

    • Period: 10 (10 units of 100ms = 1s)
    • Number of repeats: 3
    • Duty-Cycle: 25 (25% of 1s = 250ms)
    • RGB Color mask: 0x07 (we choose WHITE to enable all color pins)
    • Led mask: 0x0F (enable all LEDs)

Request example:

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b30a03190a03190a03197f

Enable Accelerometer (0xb4)

This command will enable or disable the custom accelerometer management on the tag. The payload of this command configures the accelerometer mode and the accelerometer parameters. The payload of this command is variable, depending on the accelerometer mode configured.

The first byte of the payload must be the accelerometer mode. Currently supported accelerometer modes are:

  • Disabled = 00, accelerometer will be managed by the Quuppa Firmware Library.
  • Movement Detection = 01, accelerometer will detect tag movement / halted conditions.
  • Position Detection = 02, accelerometer will detect horizontal / vertical position of the tag.
  • Freefall Detection = 04, accelerometer will detect tag freefall events.
  • Shock Detection = 08, accelerometer will detect an unexpected tag acceleration.

The rules of accelerometer modes matching are the following:

  • Disabled and Movement detection modes can be used alone;
  • Position detection, Freefall detection and Shock detection are exclusive to each other and can be used together with Movement detection mode;
  • Position detection, Freefall detection or Shock detection can be also used for the Man-Down detection option. In this case the option must be matched with the Movement detection mode.
Disabled mode

In this mode the accelerometer will be managed by the Quuppa Firmware Library and the accelerometer will be set up according to the Quuppa tag configuration.

No accelerometer parameters are required for this command.

Request example:

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection mode = 00

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b400

Movement detection mode

In this mode the accelerometer will recognize tag movement events: moving vs halted conditions.

This command requires the following accelerometer parameters:

  • Movement detection threshold (units of 16mg)

    • Range [0, 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.

Request example:

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 01
  • Movement detection threshold = 0x0a = 10 (160 mg)
  • Movement detection duration =0x03 = 3 (3 sec)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b4010a03

Horizontal / Vertical detection mode

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.

This command requires the following accelerometer parameters:

  • Angle (degrees)

    • Range [0, 90]
    • Defines the angle that the board uses to detect the horizontal / vertical position (see picture below).

  • Position detection duration (seconds)

    • Range [0, 255]
    • Defines the minimum time period that the device should be stable in the position.

Position detection

Request example:

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 02
  • Angle = 0x2d = 45 (45 degrees)
  • Position detection duration =0x03 = 3 (3 sec)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b4022d03

Freefall detection mode

In this mode the accelerometer will recognize tag freefall events.

This command requires the following accelerometer parameters:

  • Minimum fall height (centimeters)

    • Range [10, 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.

Request example:

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 04
  • Minimum fall height = 0x50 = 80 (80 cm)
  • Sensitivity =0x05 = 5 (250 mg)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b4045005

Shock detection mode

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

This command requires the following accelerometer parameters:

  • 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
  • Starting from 1500 mg
  • 1 = 1500 mg +(1 * 50 mg) = 1550 mg
  • 10 = 1500 mg + (10 * 50 mg) = 2000 mg

Request example:

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 08
  • Shock intensity = 0x07 = 7 (1850 mg)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b40807

Man-Down detection option

For the Man-Down detection theory please refer to the Man-Down Detection Documentation

When using this option the accelerometer will recognize man-down events. A man-down event can be described as a fall followed by a time interval in which the fallen person remains still on the ground. In this use case, the accelerometer will detect motion events (moving / stationary) and man-down events (a fall followed by a stationary interval).

In the Man-Down detection option it is strongly recommended to not to use a tag attached to a lanyard at the neck but to attach it with the clip at the pocket or to the belt to prevent tag swinging that interfere with the correct functioning of the Man-Down algorithm.

This option requires the following accelerometer parameters:

  • Debounce duration (seconds)

    • Range [0, 255]
    • Defines the maximum time interval in which the body of the falling person is bouncing when impacted on the ground.

  • Stationary duration (seconds)

    • Range [0, 255]
    • Defines the minimum time interval in which the body of the fallen person should remain stationary on the ground.

  • Alert duration

    • Range [0, 255]
    • Defines the Alarm duration time interval, after Man-Down has been detected, during which the tag emits an alarm sound and after which the tag starts sending data about the Man-Down option detection. If the Alert duration is equal to 0 the tag sends data about Man-Down immediately. If the Alert duration is not equal to 0 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 data about the Man-Down detection.

Request example (Man-Down detection option with Position detection mode):

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 03 = 02 + 01 (Position + Movement detection)
  • Angle = 0x2d = 45 (45 degrees)
  • Position detection duration = 0x03 = 3 (3 sec)
  • Movement detection threshold = 0x0a = 10 (160 mg)
  • Movement detection duration = 0x02 = 2 (2 sec)
  • Debounce duration = 0x03 = 3 (3 sec)
  • Stationary duration = 0x0a = 10 (10 sec)
  • Alert duration = 0x3c = 60 (60 sec)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b4032d030a02030a3c

Request example (Man-Down detection option with Freefall detection mode):

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 05 = 04 + 01 (Freefall + Movement detection)
  • Minimum fall height = 0x50 = 80 (80 cm)
  • Sensitivity 0x05 = 5 (250 mg)
  • Movement detection threshold = 0x0a = 10 (160 mg)
  • Movement detection duration = 0x02 = 2 (2 sec)
  • Debounce duration = 0x03 = 3 (3 sec)
  • Stationary duration = 0x0a = 10 (10 sec)
  • Alert duration = 0x3c = 60 (60 sec)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b40550050a02030a3c

Request example (Man-Down detection option with Shock detection mode):

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 09 = 08 + 01 (Shock + Movement detection)
  • Shock intensity = 0x07 = 7 (1850 mg)
  • Movement detection threshold = 0x0a = 10 (160 mg)
  • Movement detection duration = 0x02 = 2 (2 sec)
  • Debounce duration = 0x03 = 3 (3 sec)
  • Stationary duration = 0x0a = 10 (10 sec)
  • Alert duration = 0x3c = 60 (60 sec)

qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b409070a02030a3c

Other request examples

Request example (Position and Movement detection modes):

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 03 = 02 + 01 (Position + Movement detection)
  • Angle = 0x2d = 45 (45 degrees)
  • Position detection duration = 0x03 = 3 (3 sec)
  • Movement detection threshold = 0x0a = 10 (160 mg)
  • Movement detection duration = 0x02 = 2 (2 sec)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b4032d030a02

Request example (Freefall and Movement detection modes):

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 05 = 04 + 01 (Freefall + Movement detection)
  • Minimum fall height = 0x50 = 80 (80 cm)
  • Sensitivity 0x05 = 5 (250 mg)
  • Movement detection threshold = 0x0a = 10 (160 mg)
  • Movement detection duration = 0x02 = 2 (2 sec)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b40550050a02

Request example (Shock and Movement detection modes):

  • Fixed preamble = ff1d00
  • Enable Accelerometer = b4
  • Detection Mode = 09 = 08 + 01 (Shock + Movement detection)
  • Shock intensity = 0x07 = 7 (1850 mg)
  • Movement detection threshold = 0x0a = 10 (160 mg)
  • Movement detection duration = 0x02 = 2 (2 sec)

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b409070a02

Enable iBeacon (0xb5)

This command will enable or disable the iBeacon packet transmission. Payload is built of two bytes that specify the iBeacon packet transmission interval in Default state and in Triggered state. The transmission interval is a value that ranges between [1, 255] and is expressed in terms of Quuppa DF packets transmissions. For example setting a value of 5 means that the iBeacon packet will be sent every 5 Quuppa DF packets.

Note: the iBeacon packet is always transmitted on the BLE channel (even if the Quuppa tag is configured on the Proprietary channel).

The following rules apply:

  • The first payload byte is the Default state iBeacon Tx Interval, the second payloadbyte is the Triggered state iBeacon Tx Interval.
  • To enable the iBeacon transmission, both payload bytes should be set to a value different from 0.
  • To disable the iBeacon transmission, it’s sufficient to set at least one of the two payload bytes to 0.

The iBeacon packet contains a fixed UUID defined by Quuppa:

05735bd0-7aec-4257-a086-bc08c3b7b00c

The iBeacon Minor and Major numbers contain the two least significant bytes of the tag MAC address and the next two bytes respectively. For example, if a tag has a tag ID of a4:da:22:e1:23:45 the iBeacon Major number will be set to 0x22e1 (decimal 8929) and the iBeacon Minor number will be set to 0x2345 (decimal 9029).

Request example (enable iBeacon):

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b50a05

  • Default State iBeacon Tx Interval: 10 (0a)
  • Triggered State iBeacon Tx Interval: 5 (05)

Request example (disable iBeacon):

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b50000

  • Default State iBeacon Tx Interval: 0 (00)
  • Triggered State iBeacon Tx Interval: 0 (00)

Enable Alerts (0xb6)

This command will enable or disable all the alert peripherals of the tag (leds, buzzer and vibration). Payload is built of a single byte:

  • If payload byte is equal to 0, alert peripherals will be disabled
  • If payload byte is not equal to 0, alert peripherals will be enabled

Request example (enable alerts):

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b601

Request example (disable alerts):

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b600

Factory Reset (0xb7)

This command will perform a factory reset of the tag. No payload needed.

Note: only BlueUp settings will be erased, Quuppa tag configuration will remain the same.

Request example (enable alerts):

/qpe/sendQuuppaRequest?tag=<tag_id>&requestData=0xff1d00b601

DF Packets User Payload

Starting from firmware version v4.1 (that uses the Quuppa Firmware Library v1.200), it is possible to send three bytes of user data within the DF Packet payloads to the QPE.

BlueUp has decided to use these bytes to send information about the tag configuration and the runtime tag activity flags.

In the first byte of the user payload of the Quuppa DF Packet, BlueUp tag will send the current setup of the user configurable settings as shown below.

BIT 7 BIT 6 BIT 5 BIT 4 - BIT 3 - BIT 2 - BIT 1 BIT 0
RFU Alerts Enabled iBeacon Enabled Accelerometer configuration Button Enabled

In the second byte of the user payload of the Quuppa DF Packet, BlueUp tag will send the current active accelerometer flags as shown below.

BIT 7 - BIT 6 - BIT 5 BIT 4 BIT 3 BIT 2 BIT 1 BIT 0
RFU Mandown Shock FreeFall Motion Horizontal

In the third byte of the user payload of the Quuppa DF Packet, BlueUp tag will send the current active button flags as shown below.

BIT 7 - BIT 6 - BIT 5 - BIT 4 BIT 3 BIT 2 BIT 1 BIT 0
RFU Long push Push Double click Click

The button presses have different meanings based on the press duration:

  • Click: a press and release that is under 300ms duration.
  • Push: a press and release that is above 300ms duration.
  • Long-Push: a press and hold above 5s duration.

Note: a press and hold above 10s duration will switch the tag in reboot mode (for the duration of 5s). When the tag is in reboot mode, if the button is pressed again, it will reboot in DFU mode, otherwise after 5s the tag will reboot normally.

Developer Specific Packets Payload

BlueUp Quuppa compatible tags send information about the firmware version and the Quuppa Firmware Library version inside the DeveloperSpecific data payload.

The DeveloperSpecific data packet is sent at a lower rate than the DF packets, so it is possible that you will have to wait some time to receive the DeveloperSpecific data from a tag.

Below is reported the DeveloperSpecific data payload format used in all BlueUp Quuppa compatible tags.

Byte Description
[0 - 1] BlueUp Company ID (provided by Quuppa), fixed: 0x1d 0x00
[2] BlueUp Firmware version major number
[3] BlueUp Firmware version minor number
[4] Quuppa Firmware Library version major number
[5] Quuppa Firmware Library version minor number
[6 - 14] RFU

DeveloperSpecific data can be retrieved using the QPE API: getDeveloperSpecificData.

DFU Introduction

BlueUp Quuppa tags offer the DFU capability, that means that the firmware running on tags can be updated over-the-air using a Bluetooth Low Energy compliant hardware and a software able to update the firmware on the tags using the Bluetooth Low Energy peripheral.

How to reboot a tag in DFU mode

To trigger the DFU functionality on a tag, the tag must be rebooted in DFU mode. BlueUp Quuppa tags have a so-called bootloader firmware, that can be run to perform the firmware update procedure. There are 2 ways to reboot a BlueUp Quuppa tag in DFU mode:

  1. with a long-press on the button (>10 sec)
  2. sending a request to the tag using QPE (Quuppa Positioning Engine)

When a tag is rebooted in DFU mode, it will stay in this mode at most for 1 minute, waiting for a connection to perform firmware update, if no connections are detected after 1 minute, the tag will reboot with the standard firmware.

If the tag has one or more leds, when it is rebooted in DFU mode, the tag will blink its led(s) periodically to signal that the DFU mode is started.

DFU with button

To reboot in DFU mode using the button you have to push and keep the button pressed for at least 10 seconds. If the tags have leds, the first led will turn on after 5 seconds, then after 10 seconds the second led will also turn on and if you release the button the tag will enter in DFU mode.

DFU with QPE

To reboot the tag in DFU Mode, a Quuppa Backchannel Request should be sent to the tag using the QPE API.

The request data to send to the tag is the following: 0xff1d00b1

So, for example, if the QPE is located at 192.168.1.100:8080, the API to invoke to send a tag with id ca0800001234 in DFU mode will be the following:

http://192.168.1.100:8080/QPE/sendQuuppaRequest?tag=ca0800001234&requestData=0xff1d00b1

DFU Requirements

To enable to update the firmware of a BlueUp Quuppa tag you will need:

  • a Bluetooth Low Energy capable device (smartphone, tablet, PC or other hardware that includes a Bluetooth Low Energy peripheral)

  • the firmware package (.zip file) provided by BlueUp that will be uploaded on the tag

  • a software to use to upload the firmware package on the tag, that can be:

    • Nordic nRF Connect Android app
    • BlueUp custom software

DFU with Nordic nRF Connect Android app

Precondition Before using this app to upload the firmware on the tag, be sure that:

  1. the firmware package (.zip file) has been downloaded on the Android device in a known position
  2. the tag is already rebooted in DFU mode, otherwise the app will not detect the tag

Pros:

  • can perform the DFU from any consumer Android device (smartphone / tablet),
  • use a well-known stable app (nRF Connect) developed from the SoC manufacturer

Cons:

  • tag must be already in DFU mode (by button or QPE command)
  • no massive/scheduled DFU on a set of tags (requires human interaction)

Below is shown a complete DFU procedure using the Nordic nRF Connect Android app on a tag that is already in DFU mode.

  1. Discovering and connecting the DFU tag

    nRF Connect has detected a tag in DFU mode, the tag ID is FB:0A:00:00:01.

    Click on the black CONNECT button to connect the tag. DFU step 1

  2. Connection to the DFU tag

    Click on the rounded upper right DFU icon (near the DISCONNECT button). DFU step 2

  3. DFU file type selection

    Select the Distribution packet (ZIP) and click on the OK button. DFU step 3

  4. Firmware file selection (.zip)

    DFU step 4

  5. Starting DFU procedure

    DFU step 5

  6. Waiting for DFU to complete When the DFU procedure is completed the tag will be disconnected and then the tag will reboot the new firmware.

DFU step 6