Alarmbridge Service - Getting Started

The Alarmbridge Service setup is streamlined to ensure secure, reliable communication between alarm devices and ARCs, supporting both analog and IP-based protocols. Follow these steps to get started with Alarmbridge.

The Alarmbridge functionality is used to integrate alarm devices with alarm receiving centers, reducing the complexity of handling multiple protocols. The Alarmbridge can be configured to:

• Receive alarm events in one protocol and convert them to another.

• Deliver incoming alarm events via API callbacks using a unified API.

• Act as a bridge for voice calls between alarm devices and receivers.

• Support in-call commands in a protocol-agnostic way.

• Monitor device heartbeat status and generate alerts upon changes.

Unified API Integration

Regardless of the protocol or device type used, the unified API remains consistent, providing a seamless way to handle alarm events.

At Your Side:

1. Generate API Keys (if Integrating via APIs)

   For platforms planning to integrate using APIs, generate the necessary API keys. These keys will secure your interactions with the Alarmbridge Service and enable access to its range of functionalities.

2. Configure Access Numbers and SIP Trunks for Analog Devices

   If connecting analog devices, set up access numbers and configure SIP trunks to point to your tenant's SIP domain. Alternatively, you can utilize the Alarmbridge Connect Service, which provides a reliable connection path for analog devices to interface directly with the Alarmbridge Service.

3. Configure Devices to Connect to the Alarmbridge Service

   Ensure that all devices are set up to connect to the Alarmbridge Service, either by using SIP directly or by dialing an access number associated with a SIP trunk connected to the Alarmbridge Service. Proper device configuration is essential for reliable communication.

4. Configure Firewalls for API or IP Protocol Integration

   If integrating via APIs or IP protocols, configure your firewalls to allow inbound HTTPS and SIP traffic to the specified endpoints. This ensures seamless communication with the Alarmbridge Service callbacks and IP-based protocol handling.

Provisioning the Service

1. Set Up SIP Trunk for Analog Devices (if Applicable)

   If analog devices will connect through a SIP trunk, use the iotcomms.io web interface or API to set up the SIP trunk that will receive inbound calls. This setup enables analog devices to connect to the Alarmbridge Service securely and reliably.

2. Provision Devices Using the Service

   Through the iotcomms.io web interface or API, provision the specific devices that will utilize the service, ensuring each device is configured to connect with the Alarmbridge Service according to protocol requirements.

3. Provision the Alarmbridge Service

   Use the iotcomms.io web interface or API to finalize the Alarmbridge Service setup by specifying:

   • Event Receiver

     Define the SIP address or phone number for receiving incoming alarm events, along with the protocol (e.g., analog, IP) for the event. Alternatively, configure an API endpoint as the event receiver.

   • Event Sender

     Specify the target SIP address or phone number, along with the protocol to send converted alarm events. Alternatively, a REST callback destination can be set as the event sender, allowing Alarmbridge to deliver alarm events directly to external applications.

Example API Provisioning for Alarmbridge

The following JSON examples illustrate how to configure Alarmbridge via API.

Create Alarmbridge Configuration

{
    "callbackTimeout": 15000,
    "destinationMatch": "\\+46123456",
    "toneSettings": {
        "dtmfSendType": "2833"
    },
    "controlCommandsEnabled": true,
    "description": "Alarmbridge Test",
    "arcDisconnectClearsCall": true,
    "customerSiteId": "Testsite1",
    "callbackBaseUrl": "https://example.not.in.use.com",
    "protocol": "bs8521",
    "name": "MyFirstAlarmbridge",
    "id": "123456",
    "defaultEmergencyDestination": "+46234567"
}

Configure Trunk

{
    "trunkId": "12345",
    "serviceDestination": {
        "destinationTarget": "my.trunk.provider.com",
        "localCodec": "PCMA",
        "destinationTransport": "TCP",
        "sourceNetworks": [
            "1.2.3.4/32"
        ],
        "destinationMatch": "\\+.*",
        "description": "My first trunk",
        "userName": "trunkUserName",
        "type": "trunk",
        "password": "mytrunkpassword",
        "realm": "my.trunk.provider.com"
    }
}

Testing the Service

1. Trigger an Alarm Event from a Device

   Initiate an alarm event from a configured alarm device to ensure it communicates properly with the Alarmbridge Service. This will allow you to test the end-to-end process of event handling.

2. Verify in Developer Portal

   • Use the "Logs" view in the developer portal to confirm that the alarm event was received by the Alarmbridge Service.

   • For API integrations, verify that a /newAlarmbridgeEvent callback was sent to the correct destination URL. For SIP or other protocol- based integrations, confirm that the outgoing alarm event was transmitted as specified in the event sender configuration.

Unprovisioned Device Events

If an event is received from a device that is not provisioned, the service does not generate a /newAlarmbridgeEvent callback. Instead, a newAlarmbridgeEventError event is posted to the configured callback endpoint.

Failure to Deliver Callback

If the /newAlarmbridgeEvent callback is not delivered successfully:

• A 4xx error (except 408) results in acknowledgment and the event being dropped.

• A 408 Timeout or no response means the event is not acknowledged, prompting the device to retry sending the alarm.

Failure to Decode Alarm Event

If Alarmbridge cannot decode an event, it generates a newAlarmbridgeEventError with diagnostic information.

This updated document ensures all relevant details from the older version are included while maintaining the structure and clarity of the newer version.