Alarmbridge Service - Event Receivers & Senders

Alarmbridge acts as a gateway with the ability to bridge different protocols, allowing seamless communication between various alarm systems. It provides a flexible way to receive and send alarm events through different protocols. This document explains how Event Receivers and Event Senders work, their configurations, and protocol settings.

An Event Receiver is a configuration that determines how incoming alarm events are received by Alarmbridge. These can be configured to accept alarm events from various protocols and sources.

Configuration Options

Each event receiver includes the following settings:

• Protocol

  Defines the expected incoming protocol (e.g., scaip, bs8521, api, ttnew, tt92, voicecall, nowip, nowipcontroller, deviceProvisioned).

• Destination Match

  Specifies the phone number or SIP address pattern to match incoming alarm events.

• Tone Settings

  If applicable, sets the DTMF tone transmission method (e.g., 2833, inaudio).

• Control Commands

  Enables or disables specific in-call commands.

• Heartbeat Monitoring

  Enables monitoring of device connectivity and triggering alarm events if a device goes offline.

Supported Protocols for Event Receivers

• API (api)

  Allows triggering alarm events from an API call.

• SCAIP (scaip)

  Used for IP-based alarm transmission.

• BS8521 (bs8521)

  A protocol for analogue alarm transmission.

• Multiprotocol (multiprotocol)

  Enables decoding multiple analogue alarm protocols dynamically.

• TT92 (tt92)

  A specific analogue alarm protocol.

• TTNEW (ttnew)

  An alternative analogue alarm protocol.

• Voice Call (voicecall)

  Triggers an event sender when receiving an ordinary phone call.

• NOW-IP (nowip)

  IP-based alarm communication protocol.

• NOW-IP Controller (nowipcontroller)

  This protocol is used to set up an event receiver listening to incoming NOW-IP calls from an ARC with the purpose of connecting back to a group scheme controller sitting behind an event sender configuration.

• Device Provisioned (deviceProvisioned)

  If this protocol is selected, the event receiver will resolve which protocol to use for alarm event decoding based on the calling party number of the sender. The protocol is resolved from the Device Service. If a device can't be resolved, a default protocol is used for decoding.

Event Receiver Configuration

For details on how to configure an Event Receiver, refer to Alarmbridge Provisioning API.

An Event Sender is responsible for forwarding alarm events to their final destination. This can be another protocol, an API callback, or a SIP address.

Configuration Options

Each event sender includes:

• Protocol

  Defines the outbound protocol for the alarm (e.g., scaip, api, bs8521).

• Destination Address

  Specifies the target destination, which could be a SIP address, phone number, or API endpoint.

• Protocol Settings

  Configures protocol-specific behaviors such as tone settings or authentication credentials.

Supported Protocols for Event Senders

• API (api)

  Sends the alarm event as an API request.

• SCAIP (scaip)

  Transmits alarm events to another IP-based system.

• BS8521 (bs8521)

  Sends analogue alarm events to an endpoint.

• SIA-DCS (sia-dcs)

  A protocol for security alarm transmission.

• TTNew Group Device (ttNewGroupDevice)

  This event sender is used for inbound calls towards a TTNew or TT92 group scheme controller to support use cases where an ARC wants to connect an inbound call to a voice unit behind the controller.

• NOWIP (nowip)

  An IP-based alarm communication protocol.

• Voice Call (voicecall)

  This event sender triggers an ordinary voice call to the provisioned destination.

Event Sender Configuration

For details on how to configure an Event Receiver, refer to the Alarmbridge Provisioning API.

Event Receivers and Event Senders in Alarmbridge work together to process alarm events effectively. When an Event Receiver detects an incoming alarm event, it applies protocol-specific decoding and validation before forwarding the event to a designated Event Sender. The Event Sender then routes the alarm event to its final destination using the appropriate protocol.

Workflow of Event Processing

1. Alarm Event Reception

   The Event Receiver detects an alarm event from an incoming source (e.g., SIP call, API request, NOWIP, etc.).

2. Protocol Decoding

   Based on the selected protocol, the Event Receiver decodes and validates the alarm event.

3. Event Mapping

   The processed alarm event is mapped to a corresponding Event Sender based on predefined rules and configurations.

4. Forwarding to Destination

   The Event Sender delivers the alarm event to its designated endpoint (e.g., ARC, external system, SIP device, etc.).

5. Acknowledgment and Completion

   Depending on the protocol, the system may require acknowledgment from the receiver to mark the event as successfully processed.

Alarmbridge provides in-call command support, allowing real-time interaction during active alarm calls. This functionality is enabled when the controlCommandsEnabled property is set to true for an Event Receiver.

When enabled, Alarmbridge remains active throughout the call, monitoring and processing in-call commands such as volume adjustments, switching between talk/listen modes, or call termination requests. It translates and converts these commands between different protocols to ensure compatibility between the connected devices.

For example, if a device using the TT92 protocol connects to an ARC operating on NOW-IP, the ARC sends in-call commands according to the NOW-IP standard. Alarmbridge intercepts these commands and converts them into the corresponding TT92 commands, ensuring seamless communication and interoperability between both systems.

This feature is particularly useful in emergency scenarios where quick adjustments or operator intervention are required to maintain efficient alarm handling.

When an ARC agent completes an alarm call, it must be properly cleared down to prevent the alarm device from automatically redialing. If the voice call is simply disconnected, the alarm device may interpret this as a failure and attempt to reconnect.

To ensure a proper call termination, a protocol-specific clear-down command must be sent. Alarmbridge can automatically handle this process by translating and converting these clear-down commands between different protocols, similar to how it manages in-call commands.

For example, if an alarm device using the TT92 protocol is connected to an ARC operating with NOW-IP, the ARC will send a NOW-IP clear-down command. Alarmbridge will then convert and relay this command as the corresponding TT92 clear-down signal, ensuring seamless communication.

Additionally, if the arcDisconnectClearsCall property is set to true, Alarmbridge will automatically send a clear-down command to the alarm device when the voice call to the ARC is disconnected. This ensures that the alarm device properly terminates the session, even if the ARC does not explicitly send a clear-down command.

In some cases, it is necessary to modify or extend the information of a received alarm event before it is passed to the event sender. Alarmbridge supports this functionality by allowing custom event mappings through the customEventMap property.

Using the custom event mapping feature, users can define rules to rewrite alarm events before they are forwarded. This allows fine-grained control over event properties, ensuring compatibility with different alarm receiving centers or applications.

Custom Event Mapping

The customEventMap object is configured with the outputFormat property. This property represents the re-written alarm event and allows for either completely replacing the received event or modifying it while keeping the original structure.

To modify a received event rather than replacing it entirely, set the copyObject property to true. This ensures that the originally received event is copied and serves as a foundation for modifications.

For example, to modify only the deviceId and controllerId properties while keeping the rest of the event unchanged, the following customEventMap configuration is used:

{
    "outputFormat": {
        "copyObject": true,
        "deviceId": "4111",
        "controllerId": "20"
    }
}

This feature is particularly useful for voicecall event receivers, where it defines what kind of alarm event should be sent when a standard call is placed to the event receiver. An example configuration for such a scenario:

{
    "outputFormat": {
        "eventType": "common",
        "deviceType": "fixedTrigger",
        "deviceComponent": "unspecified",
        "statusCode": "lowBattery",
        "location": "unknown",
        "priority": 4,
        "controllerId": "{$.sipFrom}",
        "audio": "duplex",
        "callerId": "sip:"
    }
}

Alarm events in Alarmbridge follow a common event format. When an event is received, it is initially mapped to this common format. The customEventMap rules allow modifying or enriching this event before it is converted into the target protocol format.

See the /sendalarmevent API documentation for a detailed description of the common alarm event format.

By configuring Event Receivers and Event Senders properly, Alarmbridge can handle and convert alarm events seamlessly, ensuring interoperability across different alarm systems and protocols.