Alarm Receiver

The Alarm Receiver decodes alarms that arrive over the phone. When an alarm call comes in, it works out which alarm protocol the caller is using and turns the call into a signal for SBN.

Overview

The Alarm Receiver listens on every line that has alarm protocols configured. When a call arrives on a line, it tries the protocols set for that line - in the order they are listed - until it recognizes the one the caller is using, decodes the alarm, and passes it on. The decoded alarm is delivered to SBN through the SBN Frontend.

Which protocols a line expects, and the order to try them, are set in the line configuration - not on this page. The Alarm Receiver does the decoding; the line configuration says what to expect on each line.

1. Runs: When configured. A deployment can run more than one to handle more concurrent alarm calls.
2. Required: Required to receive alarms delivered over the phone. Not needed on a host that only handles video.
3. Depends on: NATS, the SIP Server (alarm calls arrive over SIP), the line configuration (which protocols each line uses), and the SBN Frontend (to deliver the decoded alarm to SBN).

Configuration

The Alarm Receiver is configured under the alarmreceiver namespace. View the defaults with ./sbn-media config eject and set host-specific overrides in sbn-media.local.yaml.

The list of alarm protocols themselves is not set here - it is part of each line's settings in the line configuration.

Accessing the recordings

Recorded alarm calls are retrieved through the API Proxy, not from the Alarm Receiver directly. To make them available:

1. Turn on capture: set alarmreceiver.captureEnabled to true.
2. On the API Proxy, enable the recordings route and set an admin token: apiproxy.routes.signalTrace: true and apiproxy.adminToken. The route is off by default and will not work until an admin token is set.

Then, supplying the admin token:

1. List the available recordings at /signal-trace on the API Proxy.
2. Download one at /signal-trace/{id} on the API Proxy, which returns it as a .tar file.

On the host itself you can also work with the recordings from the command line:

replay re-runs a captured call through the alarm decoding, which is the quickest way to see why a particular alarm did not decode.

Recordings are kept for alarmreceiver.captureRetentionDays (90 days by default).

Protocol timing (advanced)

A few protocols have timing settings that most installations leave at their defaults. These can be reloaded:

1. alarmreceiver.cpc.resendDelayInMs (3000) and alarmreceiver.cpc.invalidChecksumDelayInMs (500) - timing for the CPC protocol.
2. alarmreceiver.tsa.resendDelayInMs (3000) and alarmreceiver.tsa.handshakeToneDelayInMs (250) - timing for the TSA protocol.

SCAIP care alarms

SCAIP care alarms have their own settings under alarmreceiver.scaip - for example the statuses that open a voice channel (statusWithMedia), the media reply (whether and how a two-way voice call is opened), the callback response, and the callback addresses. SCAIP sources can also be given per-source overrides, including a tenant, for multi-tenant setups.

After changing these settings in sbn-media.local.yaml, apply them with ./sbn-media config reload.

FAQ

Where do I set which alarm protocols a line uses?

In the line configuration, not on the Alarm Receiver. Each line lists the protocols to expect, in priority order; the Alarm Receiver decodes using that list. See the Line Configuration page.

An alarm is not decoding correctly. What should I check?

Confirm the line's protocol list includes the right protocol and in the right order (in the line configuration). Turn on alarmreceiver.captureEnabled to record the call audio, then use ./sbn-media alarm capture replay <id> to re-run the captured call through the decoder and see exactly where it fails. If the service will not start, run it in the foreground with sbn-media service exec alarmreceiver -ld to see the error.

Can I record alarm calls to troubleshoot?

Yes. Set alarmreceiver.captureEnabled to true, and retrieve the recordings through the API Proxy as described in Accessing the recordings above. Recordings are kept for alarmreceiver.captureRetentionDays (90 days by default). Leave capture off in normal operation.

What happens to an alarm once it is decoded?

It is delivered to SBN through the SBN Frontend, which files it as a signal. If the SBN Frontend cannot reach SBN, the alarm cannot be delivered - see the SBN Frontend page.

Related pages

1. SBN Media Overview (SBN-Media/overview)
2. Installing and Configuring SBN Media (SBN-Media/installation)
3. Line Configuration (SBN-Media/Configuration/line-configuration)
4. SIP Server (SBN-Media/Telephony/sip-server)
5. SBN Frontend (SBN-Media/Platform/sbn-frontend)
6. API Proxy (SBN-Media/Platform/api-proxy)
7. Alarm Protocols (SBN-Media/Configuration/protocols)