SIP Message & SCAIP

SCAIP (Social Care Alarm Internet Protocol) is a SIP-based protocol standardised in SIS SS 91100:2014 and later also described in CENELEC 50134. It is used to send and receive alarms and notifications over an IP communication network such as the Internet.

iotcomms have implemented SCAIP as a cloud service converting SIP/SCAIP-signaling to standard HTTP messaging. The service connects the SCAIP capable devices with the alarm center. It communicates with the devices over SCAIP conformant SIP signaling and with the alarm center via a provisioned REST-based interface or using the AWS SNS/SQS services.

iotcomms implementation of SCAIP/CENELEC could be seen as a proxy translating between SCAIP and HTTP/SNS/SQS. Building the complete service logic is the customer responsibility e.g. handling of malfunctioning devices.

The API's are described on iotcomms developer portal. For the service SCAIP two sections are relevant. * Provisioning * SIP Message

SCAIP units needs to be provisioned in iotcomms servers for messages to be processed and forwarded for that unit. The provisioning API is described in detail at the developer portal under documentation.

There are two ways for the customer to trigger the provisioning of a unit * The first is to provision the unit with iotcomms servers before putting them in service. This ensures that the unit will work from start.

* The second is to provision a unit as a reaction to when a non-provisioned unit is discovered, iotcomms sends an alarm to the alarmEventRestEndpoint triggered when a unit is not recognized in the domain of the customer. Customer should then trigger an automatic provisioning of the unit if the unit is recognized by the customer. This method keeps down the number of provisioned units but require better back-end support at the customer side and creates background noice among alarms.

Provisioning is done using the provisioning API and the PUT /device/{domain} method. Depending on the units capabilities customer should use authType Credentials (for units that can authenticate themself) of deviceId (for units that are not capable of authenticating and are whitelisted) when provisioning and also provide the deviceId as a string value. The URL for the provisioning endpoint is found in the developer portal and is determined by what region the service is produced.

sip-message_0.mermaid.0.html

The format of the JSON document to be sent in the request is described in the development portal under documentation/Provisioning.

A unit can be removed/deleted by using DELETE /device/{domain}/{deviceId} in analogy with provisioning.

The unit will send and receive SIP messages that is translated to HTTP/SNS by iotcomms. There are restrictions on sending notifications to a unit described below due to constraints in the SCAIP protocol.

When a SCAIP unit wants to send a heartbeat or send an alarm a SIP-message is sent to iotcomms. Assuming the unit is previously provisioned at iotcomms the sip-request is transformed to either an AWS SNS message or a HTTP event sent to the sipEventRestEndpoint.

sip-message_0.mermaid.1.html

The format of the JSON body is described on the development portal under documentation/SIP Messages and implicit_callbacks and is sent to CALLBACK_BASE_URL/message.

Sending a notification to a unit is in most cases only possible during a short period of time after receiving an alarm/notification from a unit. The reason for this is that the unit often placed behind a NAT/firewall that opens up a pinhole when a message is sent out during a limited, allowing for a response to reach back. The pinhole is normally closed within 10s of seconds up to a few minutes. In addition UDP is often used for signaling not setting up any persistent connection only relying in the pinhole for the return path.

To reach the unit the replyTo header received in the original sipEventNotification is required in the request as the reqUri.

sip-message_0.mermaid.2.html

The format of the JSON body to be included in the request is described on the development portal under documentation/SIP Messages and /{domain}/message and should be sent to /sipmessage.

Base url: https://api.prod-eu-north-1.iotcomms.io/sipmessage

The SQS command queue listen for commands to be executed by the service related to SIP calls and messages.

This method is used to send a SIP MESSAGE to specified destination.

Parameters

Example

{
    "method": "MESSAGE",
    "reqUri": "sip:receiver@sipdomain.com",
    "from": "sip:sender@sipdomain.com",
    "contentType": "application/xml",
    "replyId": "<JWT token>",
    "body": "<text>Example</text>"
}

This SNS topic is used to listen for events generated by the SIP service. The event is a stringified JSON object passed in the message part published to SNS. Use JSON.parse to retrieve the object when receiving the notification.

This event is sent when a SIP MESSAGE is received by the service.

Parameters

Example

{
    "event": "MESSAGE",
    "callId": "fdkmlksfm38f8nf",
    "received": "192.168.0.1",
    "sourcePort": 5060,
    "fromDomain": "sipdomain.com",
    "fromUser": "fromuser",
    "fromURI": "sip:fromuser@sipdomain.com:5060",
    "to": "<sip:touser@sipdomain.com>",
    "targetDomain": "sipdomain.com",
    "contentType": "application/xml",
    "body": "<text>Example</text>",
    "protocol": "tls",
    "replyTo": "sip:fromuser@sipdomain.com:49500;transport=tcp;servingNode=172.17.0.2",
    "commandQueue": "https://sqs.us-east-1.amazonaws.com/1234567890/queueName",
    "commandRegion": "eu-west-1"
}

This SNS topic is used to listen for alarms generated by the SIP service.

This alarm is generated if a device is trying to utilize a service for the domain and authentication fails.

Parameters

Example

{
    "event": "authError",
    "domain": "sipdomain.com",
    "deviceId": 123456,
    "reason": "unconfiguredDevice",
    "method": "MESSAGE",
    "requestUri": "sip:device@domain.com"
}