Bluzone Duress Integration

Owned by Robert Dare
Last updated: Jan 05, 2023
4 min read

The Bluzone Duress functionality enables the capturing of button press events from supported HID hardware to be recorded and potentially forwarded to a remote cloud instance. HID beacons that are equipped with buttons can be configured to pass button press events into the Bluzone Cloud. If a Bluzone Policy for Duress Events is configured, then a Policy Event will be generated for button press event. Third Party Integrations may consume these Policy-Events like any other Policy-Event in the Bluzone system.

Hardware Functionality

HID Beacons equipped with buttons and configured for Duress functionality come in several form factors. There may be different behaviors that can be configured, pending on the hardware type. For example, some beacons may have an LED indicator or audible indicator that can be activated with the button press.

A “Duress Beacon” (a beacon that supports and is configured for Duress functionality) has two states. Under normal operation, the beacon broadcasts the standard HID BLE telemetry packets. A beacon is considered under “Duress Mode” after the button was pressed. The duration of Duress Mode is configurable. While in “Duress Mode”, the beacon broadcast rate and power is increased. Additional visual and audible indicators may also be activated, if supported by hardware and configured.

Cloud Functionality

HID Beacons broadcast proprietary telemetry packets over Bluetooth Low Energy (BLE). HID Beacons equipped with buttons and configured for Duress functionality will maintain an internal count of how many times a button was pressed. The beacon’s telemetry packet includes the current button press count and the beacon timestamp of the last button press event. Bluzone continuously monitors the button press count and “last press timestamp”. Bluzone interprets a “duress event” when these values change.

There is a possibility that the end-user pressing the button may be out of Blufi coverage when the button is pressed. The Bluzone project can be configured with a timeout value that will ignore button press events that happened longer than the configured minutes in the past. For example: A nurse carries the HID button badge daily and brings the badge home over the weekend, and the button is accidentally pressed while away from work. If the Bluzone Project is configured to ignore button press events that occurred longer than four hours in the past, then there will be no Policy-Event created the nurse arrives back at work for the next shift.

Policy-Event Structure

Bluzone Duress functionality uses standard Bluzone Policy-Event paradigm. The Policy-Event metric type is “PANIC_BUTTON”, and the namespace is “BEACON”. The Policy-Event also contains the beacon device id, the beacon name, the policy id, and the policy name (read more about Policy-Event Structure).

Cloud Integrations

Bluzone connects Policy-Events to Third Party Cloud integrations using the Remote-Consumer component. Bluzone Projects can be configured to push Policy-Event messages to a user supplied AWS Kinesis or Azure EventHub stream. HID recommends the usage of Remote-Consumer with Kinesis or EventHub integration for the following reasons:

  1. High Availability: Both Azure and AWS support a scalable and highly available interface for consuming events. Both cloud providers offer high SLAs and robust infrastructure to ensure that message publishing and message consuming are not impacted by outages

  2. Durability: Messages published to these streams will remain available for up to 24 hours (or longer based on the cloud provider’s configurations). This enables consumers to restart or reconnect (such as when a maintenance period occurs) without a risk of loosing messages

  3. Scalable Push: Consumers of messages can consume messages at a rate that is supported by their architecture and infrastructure. There is no risk of the publisher (Bluzone) overwhelming the consumer by pushing too much data.

  4. Simple Integration: Both EventHub and Kinesis provide client libraries in all popular languages, provide detailed documentation, and provide working examples that make a low barrier to entry.

Typical Integration Example

Project A wishes to deploy HID Duress functionality and integrate the button press event into a workflow that includes custom actions. Integration engineers for “Project A” would be considering the following tasks:

  1. Obtain and configure the appropriate hardware and Bluzone project setup (configure Beacons, Blufis, Duress Policy)

  2. Obtain an AWS Kinesis or Azure EventHub service

  3. Configure Bluzone Project’s Remote-Consumer configuration to use the Kinesis or EventHub stream (read more about Bluzone Streaming APIs)

  4. Visit the EventHub or Kinesis documentation site and obtain appropriate client libraries

  5. Implement code that consumes messages from the EventHub or Kinesis stream and processes the event

  6. Handle the Policy-Event message for the duress event

Example with a custom workflow that fetches the beacon location

The Duress Event published to the Remote-Consumer stream can be considered a “trigger” for the remote integration to begin its custom workflow.