Alarmbridge Service - Heartbeat Function

The Alarmbridge Service heartbeat function offloads the remote alarm receiving system from regular device check-in traffic. Alarmbridge Service handles these check-ins locally and sends an alarm event through the configured event sender only when a device becomes online or offline.

The Alarmbridge Service heartbeat function supports two monitoring mechanisms:

• Alarm Unit heartbeat monitoring uses periodic heartbeat messages sent by an alarm unit.
• Alarmbridge Connect Device online/offline monitoring uses the Alarmbridge Connect device's SIP registration and its expiry time.

The sections below explain how to configure each type, what triggers an offline alarm, and how recovery is reported.

Event Delivery and Protocol Mapping

Availability events are created in the iotcomms.io common event format, with deviceType: "heartbeat" and statusCode: "online" or "offline".

The configured event sender determines how these events reach the remote system:

• For an alarm protocol event sender, Alarmbridge maps the common event into the protocol specified by the event sender and sends it to the configured destination.
• For a REST API callback event sender, the common format is used directly in the alarmEvent object of the newAlarmbridgeEvent callback.

The outgoing alarm protocol can therefore differ from the protocol used by the alarm unit. The JSON examples in this document show common-format event fields; they do not represent the message format of every outgoing alarm protocol.

A heartbeat is a regular check-in message from an alarm unit. Each received heartbeat restarts a monitoring timeout: the maximum time Alarmbridge will wait for the next heartbeat.

While the unit remains online, Alarmbridge acknowledges regular heartbeats without forwarding them to the remote system. If a heartbeat is missing for longer than the configured timeout, Alarmbridge generates an offline event. A later heartbeat restores the unit to online and generates an online event.

Enabling the Heartbeat Function

Configure the alarm unit, the Alarmbridge event receiver, and its associated event sender:

The unit's heartbeat transmission frequency and Alarmbridge's monitoring timeout are separate settings. Changing the timeout in Alarmbridge does not change how often the physical unit sends heartbeats.

Set the monitoring timeout longer than the normal time between heartbeats, allowing a margin for transmission delays. For example, a unit sending a heartbeat every 5 minutes could use a monitoring timeout of 10 minutes.

If you want to accept one or more missing heartbeat messages before an offline event is sent, set the Alarmbridge Service heartbeatInterval to a longer timeout that covers the missed messages and allows the next expected heartbeat to arrive. Include a small additional margin for transmission delays.

For example, if the alarm unit sends a heartbeat every 10 minutes and you want to tolerate two missed heartbeats, set heartbeatInterval to 35 minutes (2,100,000 milliseconds). After the last received heartbeat, the messages expected at 10 and 20 minutes may be missed. The next heartbeat, expected at 30 minutes, still has 5 minutes to arrive before the timeout expires. If no heartbeat arrives within 35 minutes, the next scheduled check generates an offline event, normally between 35 and 40 minutes after the last received heartbeat.

Alarmbridge measures the time since the last received heartbeat rather than counting missed messages. Each received heartbeat restarts the full timeout. The same guidance applies to defaultHeartbeatInterval when configuring a shared timeout on the event receiver.

The lowest configurable monitoring interval is 5 minutes (300,000 milliseconds), because Alarmbridge checks for missing heartbeats every 5 minutes. Values are specified in milliseconds.

If neither a device-level interval nor a receiver-level default is configured, heartbeat suppression and timeout monitoring are not enabled for that unit. Heartbeat events are then handled like other incoming alarm events.

Monitoring starts when the first heartbeat is received. Provisioning a unit alone does not start a countdown or generate an offline alarm for a unit that has never checked in.

Event Receiver-Level Default Heartbeat Interval

The following example shows the relevant event receiver settings:

{
  "eventReceiver": {
    "name": "Alarm Unit Heartbeats",
    "protocol": "scaip",
    "destinationMatch": "^scaipalarms$",
    "defaultHeartbeatInterval": 600000
  }
}

This receiver uses a default monitoring timeout of 600,000 milliseconds (10 minutes). Units using the receiver inherit this timeout unless an individual timeout is configured on the provisioned device.

Use the protocol and destination match appropriate for your incoming alarm traffic. Also associate the receiver with an event sender configured to deliver availability events to the remote system. The example above shows receiver settings only.

Device-Level Heartbeat Interval

To give an individual unit its own monitoring timeout, add the following settings to its provisioned device configuration:

{
  "serviceData": {
    "alarmBridge": {
      "heartbeatInterval": 900000
    }
  }
}

This unit uses a monitoring timeout of 900,000 milliseconds (15 minutes), overriding the event receiver's default. Other units using the receiver continue to use its default timeout.

This is a configuration excerpt, not a complete device provisioning request. The provisioned device identity must match the identity used to resolve the incoming alarm unit.

Handling Incoming Heartbeat Messages

Alarmbridge maps incoming alarm messages into its common event format. Heartbeat messages are identified from that mapping, including events with deviceType: "heartbeat" or statusCode: "heartbeat".

When heartbeat monitoring is enabled:

1. First heartbeat: Alarmbridge acknowledges the heartbeat, sets the unit online, starts the timeout, and sends an online event through the configured event sender.
2. Further heartbeats while online: Alarmbridge acknowledges each heartbeat and restarts the timeout. No additional online event is sent to the remote system.
3. Heartbeat received after an offline period: Alarmbridge acknowledges the heartbeat, restores the unit to online, restarts the timeout, and sends an online recovery event through the configured event sender.

The common-format fields identifying an online event are:

{
  "deviceType": "heartbeat",
  "statusCode": "online"
}

Other alarm messages continue through normal alarm handling. They do not restart the heartbeat monitoring timeout.

Detecting Offline Alarm Units

A heartbeat failure occurs when Alarmbridge has not received another heartbeat before the configured monitoring timeout expires.

Alarmbridge checks for expired timeouts every 5 minutes. When a check detects an expired timeout for an online unit, Alarmbridge generates an offline event and sends it through the configured event sender to the remote system.

The common-format fields identifying the offline event are:

{
  "deviceType": "heartbeat",
  "statusCode": "offline"
}

Once the unit is offline, subsequent checks do not generate a new offline event simply because it remains offline. A new heartbeat restores the online state and generates an online recovery event.

An offline event means the expected heartbeat has not arrived. It does not identify whether the cause is the unit itself, its power supply, or the communication path.

Example: When Is the Offline Alarm Sent?

Assume a unit sends heartbeats every 5 minutes and Alarmbridge is configured with a 10-minute timeout:

The check schedule is independent of the time a heartbeat arrives. An offline event may therefore be raised up to approximately 5 minutes after the configured timeout expires, plus processing and delivery time.

Alarm Unit State Changes

Heartbeat and Alarm Delivery Sequence

The following diagram shows the receiver, monitoring, and event sender working together. Background monitoring is shown alongside the event receiver for clarity.

Alarmbridge Connect gateway availability is monitored through SIP registration. A registration tells Alarmbridge that the Alarmbridge Connect device is available and specifies how long the registration remains valid. The device renews its registration periodically to remain online.

Each registration refreshes the availability deadline using the registration's expiry time. Regular registration renewals do not generate repeated online events for the remote system.

This monitoring uses the SIP registration lifetime, rather than heartbeatInterval or defaultHeartbeatInterval. The 5-minute minimum configurable heartbeat timeout described for Alarm Units does not set the Connect device's registration lifetime. Expired availability deadlines are still checked every 5 minutes.

Required Configuration

An optional top-level controllerId specifies the controller identity included in availability events. If omitted, Alarmbridge derives the controller identity from the provisioned device identifier.

Device-Level Configuration

The following excerpt shows the Alarmbridge heartbeat function settings for a Connect device:

{
  "deviceId": "connect001",
  "deviceType": "alarmbridgeConnect",
  "controllerId": "1234",
  "alarmbridgeTargetSipUri": "sip:connectstatus@customer.example.com",
  "statusServiceAlarms": true
}

Replace the device identity, controller identity, and SIP domain with your deployment values. Configure the device's normal SIP authentication settings as part of provisioning; they are not included in this excerpt.

alarmbridgeTargetSipUri selects the receiver configuration used to deliver availability events. It is not the remote alarm receiving system's address. The associated event sender defines the remote destination.

statusServiceAlarms is optional and enables the additional service alarm notifications described below. It is not required for delivery of the normal online/offline alarm events through the event sender.

Event Receiver and Event Sender Configuration

For the device example above, the relevant receiver settings could be:

{
  "eventReceiver": {
    "name": "Connect Availability",
    "protocol": "scaip",
    "destinationMatch": "^connectstatus$"
  }
}

This example selects the receiver using the connectstatus destination in alarmbridgeTargetSipUri. Use the receiver protocol appropriate for your service configuration.

Associate this receiver with the event sender that should deliver availability events. Configure the sender's outgoing alarm protocol and destination, or its REST API callback destination. No defaultHeartbeatInterval is required for registration-based monitoring.

Registration, Offline Detection, and Recovery

1. First registration: Alarmbridge starts monitoring the Connect device and sends an online event through the configured event sender.
2. Registration renewal: Alarmbridge refreshes the availability deadline. If the device is already online, no additional online event is sent.
3. Registration expires without renewal: The next scheduled monitoring check detects the expired deadline and sends an offline event through the configured event sender.
4. Device remains offline: Subsequent checks do not generate repeated offline events simply because the device remains offline.
5. Registration resumes: Alarmbridge restores the online state and sends an online recovery event.

Monitoring begins with the first qualifying registration. A provisioned device that has never registered has not yet established an availability deadline.

The checks run every 5 minutes, so offline detection can occur up to approximately 5 minutes after the registration deadline expires, plus processing and delivery time.

Connect availability events use the same common-format deviceType: "heartbeat" and statusCode: "online" or "offline" fields as Alarm Unit availability events. The event sender maps them to its configured outgoing protocol. REST API callback event senders use the common format directly.

Optional Service Alarms

To receive additional service notifications for a Connect device, set the top-level device property statusServiceAlarms to true and configure the tenant's notificationConfiguration for service alarm delivery.

Service alarms use SNS through alarmTopic, or HTTP through alarmEventsRestEndpoint, according to the tenant's notification settings, including useHttpEvents.

These notifications have:

• type: "deviceStatusChange".
• error: "deviceOnline" when the device becomes online, or error: "deviceOffline" when it becomes offline.
• errorDetails identifying the device, controller, and availability status.

These service notifications are additional to the availability alarm events sent through the configured event sender. They use the tenant's service notification configuration rather than the event sender's alarm protocol and destination.

• Alarmbridge handles regular heartbeats and SIP registration renewals locally, reducing traffic and processing in the remote alarm receiving system.
• Alarm Units use periodic heartbeat messages. Configure their monitoring timeout on the event receiver, on the individual provisioned device, or both. The device-level value takes precedence.
• The lowest configurable Alarm Unit monitoring interval is 5 minutes (300,000 milliseconds). Allow a margin above the unit's normal heartbeat transmission frequency.
• Alarmbridge Connect uses SIP registration expiry to monitor availability. Configure the device type, alarmbridgeTargetSipUri, matching event receiver, and associated event sender.
• Both mechanisms generate online/offline events on state changes, including initial online detection and recovery. Regular check-ins do not generate repeated online events.
• Expiry checks run every 5 minutes. Offline detection can take up to approximately 5 additional minutes after a monitoring deadline expires.
• Availability events are mapped from the iotcomms.io common format into the event sender's configured alarm protocol. REST API callback event senders use the common format directly.