7. SOS Access v4 Protocol¶
SOS Access V4 protocol is intended for transmission of alarm signals between alarm transmitters and receivers.
Functions for monitoring the transmission link are included.
It is an XML based protocol and only printable 8-bits characters from ISO8859-1 are allowed.
The protocol consists of the following message types:
7.1. Alarm Requests¶
- <alarmrequest>
- Alarm, reset or information message
- <alarmresponse>
- Response message for <alarmrequests>
7.2. Change password¶
- <requestnewauthentication>
- Request new password
- <requestnewauthenticationresponse>
- Response message for <requestnewauthentication> messages, containing the new password
7.3. Monitored Links¶
- <pingrequest>
- Hearbeat message from the alarm transmitter
- <pingresponse>
- Response message for <pingrequest>
7.4. Client Implementation¶
In the sos-access client the messages are modeled by the following classes
<alarmrequest> -> AlarmRequest
<alarmresponse> -> AlarmResponse
<requestnewauthentication> -> NewAuthRequest
<requestnewauthenticationresponse> -> NewAuthResponse
<pingrequest> -> PingRequest
<pingresponse> -> PingResponse
8. Alarm Transmission¶
<alarmrequest> is the telegram that is used when an alarm is sent to the alarm receiver. The server responds with a <alarmresponse>
The maximum message size for a single telegram is limited to 100 000 characters including XML- header and XML-tags.
8.1. Alarm Requests <alarmrequest>¶
8.1.1. Element definitions¶
- <reference>
- OPTIONAL1-50 CharactersThis id is only a reference number/string. It is not treated by the receiver although it is returned in the <alarmresponse> and is stored in the log for trace purposes.
- <authentication>
- SUPPLIED BY ALARM OPERATOR15 CharactersPassword for the alarm transmitter
- <receiver>
- SUPPLIED BY ALARM OPERATOR1-20 CharactersDistribution information. Determines to which alarm monitoring center the alarm are distributed to if the alarm receiver has several monitoring centers.
- <transmittertime>
- OPTIONAL23 Characters.Ex.”2002-05-28 11:35:20.022” Time stamp from the transmitter. Only used for log/trace.
Todo
Contact SOS Alarm and double check if this only supports RFC-822 without timestamp.
- <alarmtype>
- “OPTIONAL” -> If not present the receiver will assume “AL”2 CharactersIndicates Alarm or Restore: “AL” = Alarm, “RE” = Restore
- <transmittertype>
- SUPPLIED BY ALARM OPERATOR5 CharactersType of transmitter. Ex: “MC200”
- <transmittercode>
- SUPPLIED BY ALARM OPERATOR1-15 CharactersAlarm transmitter number (customer code). Ex: “12345678”
- <transmitterarea>
- OPTIONAL1-5 CharactersDifferent areas on an alarm transmitter can be used to initiate a different action at the alarm receiver on the same alarm code and from the same alarm transmitter
- <eventcode>
- 1-25 CharactersThe event code is the carrier of the alarm event. The event codes need to be set up at the alarm operator so that an action will be initiated. The exact event code can technically be anything but it is common to use for example SIA codes, (FA = Fire Alarm, BA = Burglary Alarm)
- <section>
- OPTIONAL1-5 CharactersSection identification. Short code for the section where the alarm is active
- <sectiontext>
- OPTIONAL1-40 CharactersSection description. Long description of the section where the alarm is active
- <detector>
- OPTIONAL1-5 CharactersDetector identification. Short code for the detector that set the alarm active
- <detectortext>
- OPTIONAL1-40 CharactersDetector description. Long description of the detector that set the alarm active
- <additionalinfo>
- OPTIONAL1-2000 CharactersAdditional information about the alarm. Lines are separated by CR+LF or LF; (LF = ASCII 10 (0x0a) and CR= ASCII 13 (0x0d))
- <position>
- OPTIONALn CharactersContains inner element <pos> that holds the Geographical coordinate.RT90 (2,5 gon West): “xXXXXXXXyYYYYYYY” where x is the x-coordinate, y is the y- coordinate. Values are given in meters.
<position> <pos>x1234567y1234567</pos> </position>
WGS84 (Lat/Long): “NDDMMmmEDDDMMmm” where DD are degrees; MM minutes; mm decimal minutes (leading 0 shall be given on the longitude if needed).<position> <pos>N597295E0176288</pos> </position>
Todo
Contact SOS Alarm and clarify what happens when an alarm transmitter has a position in the receiving system but a different one is provided via the alarm.
8.1.2. XML Examples <alarmrequest>¶
<?xml version="1.0" encoding="ISO-8859-1"?>
<alarmrequest>
<authentication>hxp4x9nnwxjatv8</authentication>
<receiver>42</receiver>
<alarmtype>AL</alarmtype>
<transmittertype>SV300</transmittertype>
<transmittercode>1234567</transmittercode>
<eventcode>BA</eventcode>
</alarmrequest>
<?xml version="1.0" encoding="ISO-8859-1"?>
<alarmrequest>
<authentication>hxp4x9nnwxjatv8</authentication>
<reference>1</reference>
<receiver>42</receiver>
<alarmtype>AL</alarmtype>
<transmittertype>SV300</transmittertype>
<transmittercode>1234567</transmittercode>
<eventcode>BA</eventcode>
</alarmrequest>
<?xml version="1.0" encoding="ISO-8859-1"?>
<alarmrequest>
<authentication>hxp4x9nnwxjatv8</authentication>
<reference>13843</reference>
<receiver>42</receiver>
<transmittertype>SV300</transmittertype>
<transmittercode>1234567</transmittercode>
<alarmtype>RE</alarmtype>
<eventcode>FA</eventcode>
</alarmrequest>^
8.2. Alarm Response <alarmresponse>¶
8.2.1. Element definitions¶
- <reference>
- OPTIONAL1-50 CharactersThe transmitter reference from the <alarmrequest> if sent to the receiver.
- <status>
- Described in Response Codes
- <info>
- Status information in clear text. Also described in Response Codes
- <arrivaltime>
- The time when the receiver received the alarm message.
8.2.2. XML Examples <alarmresponse>¶
<?xml version="1.0" encoding="ISO-8859-1"?>
<alarmresponse>
<reference>001</reference>
<status>0</status>
<info>OK</info>
<arrivaltime>2006-12-24 15:00:00.000</arrivaltime>
</alarmresponse>
<?xml version="1.0" encoding="ISO-8859-1"?>
<alarmresponse>
<reference>001</reference>
<status>6</status>
<info>NOT_AUTHORIZED</info>
<arrivaltime>2006-12-24 15:00:00</arrivaltime>
</alarmresponse>
9. Requesting new authentication/password¶
Alarm receiver should implement a function to change the password.
This function should change the password after the first connection to the alarm receiver. The new password shall be stored in the transmitter and used here after. This prevents that and installation company or anybody else knows the password.
This makes it very hard to setup another transmitter to send false alarms.
The new password should not be visible in the configuration interface for the alarm transmitter.
If an error occurs during the password change, the old password will be valid until the first message with the new password is received.
If the NOT_AUTHORIZED reply is received from transmitter the receiver should alert the customer to take proper action. It might be necessary to contact the alarm operators customer support for a new password.
If the transmitter is replaced a new password is required from alarm operator.
The change off password is requested with <requestnewauthentication> and the response <requestnewauthenticationresponse> is sent back containing the new password.
9.1. New Auth Request <requestnewauthentication>¶
9.1.1. Element definitions¶
- <authentication>
- 15 CharactersAuthentication (current password)
- <reference>
- <transmittercode>
- <transmittertype>
9.1.2. XML Examples <requestnewauthentication>¶
<?xml version="1.0" encoding="ISO-8859-1"?>
<requestnewauthentication>
<authentication>l4x85dshyrbla27</authentication>
<reference>46</reference>
<transmittercode>1234567</transmittercode>
<transmittertype>ET800</transmittertype>
</requestnewauthentication>
9.2. New Auth Response <requestnewauthenticationresponse>¶
9.2.1. Element definitions¶
- <reference>
- 1-50 Characters
- <status>
- Described in Response Codes
- <info>
- Status information in clear text. Also described in Response Codes
- <newauthentication>
- 15 CharactersThe new password.
- <arrivaltime>
- The time when the receiver received the request.
9.2.2. XML Examples <requestnewauthenticationresponse>¶
<?xml version="1.0" encoding="ISO-8859-1"?>
<requestnewauthenticationresponse>
<reference>46</reference>
<status>0</status>
<info>OK</info>
<newauthentication>8usedlb54a234md</newauthentication>
<arrivaltime>2006-12-24 15:00:00</arrivaltime>
</requestnewauthenticationresponse>
10. Monitored Connection¶
Monitored connection is a function where the alarm receiver monitors that the transmitter sends heartbeat signals on a regular basis. The alarm transmitter is the initiating part in this function. If the receiver does not get a heartbeat signal in the agreed interval a line fault alarm is generated to the alarm operator.
The service is available in four different levels:
- 25 hours (90000 seconds)
- 5 hours (18000 seconds)
- 180 seconds
- 90 seconds
When using heartbeat levels 3 and 4 it is mandatory to implement failover functionality in transmitter. If the primary receiver fails to handle the incoming request, the transmitter should resend the alarm to failover receiver.
If the failover receiver fails as well the transmitter shall have alternative delivery way over example GPRS or/and UMTS.
Each service level requires that at least two heartbeat signals shall be sent within the interval.
It is recommend that the transmitter sends at least three heartbeat signals per service level time but no more than six.
Todo
There is a protection if sending <pingrequest> very shortly a after each other that the server responds with PING_TO_OFTEN. What is this exact time limit since it doesn’t seem to be bound to the service level? Contact SOS Alarm and ask.
If heartbeat signals is sent to frequent an error message will be replied in the ping request response (PING_TO_OFTEN).
The heartbeat is sent in a <pingrequest> and the server answers with a <pingresponse>
The alarm receiver sends a response message after receiving the ping request. In the response message, the time is attached; this can be used for synchronizing the clock in the transmitter.
10.1. Ping Request <pingrequest>¶
10.1.1. Element definitions¶
- <authentication>
- 15 CharactersAuthentication (current password)
- <reference>
- <transmittercode>
- <transmittertype>
10.1.2. XML Examples <pingrequest>¶
<?xml version="1.0" encoding="iso-8859-1"?>
<pingrequest>
<authentication>hxp4x9nnwxjatv8</authentication>
<reference>734632</reference>
<transmittercode>208013</transmittercode>
<transmittertype>SV300</transmittertype>
</pingrequest>
10.2. Ping Response <pingresponse>¶
10.2.1. Element definitions¶
- <reference>
- 1-50 Characters
- <status>
- Described in Response Codes
- <info>
- Status information in clear text. Also described in Response Codes
- <arrivaltime>
- The time when the receiver received the alarm message.
10.2.2. XML Examples <requestnewauthenticationresponse>¶
<?xml version="1.0" encoding="iso-8859-1"?>
<pingresponse>
<reference>734632</reference>
<status>0</status>
<info>OK</info>
<arrivaltime>2005-02-28 11:35:42.012</arrivaltime>
</pingresponse>
11. Response Codes¶
The following response codes with their status number and info description:
Status | Info | Description |
---|---|---|
0 | OK | OK |
1 | INVALID_LENGTH | Message to long. |
2 | INVALID_XML | Invalid xml content. |
3 | WRONG_CONTENT | Wrong data content, i.e. to long text for a field. |
4 | NOT_AUTHORIZED | Not authorized, wrong transmitter, instance or password |
5 | NOT_TREATED_NOT_DISTRIBUTED | Not treated or distributed. Fail over address should be used. |
7 | MANDATORY_DATA_MISSING | Mandatory XML tag missing |
9 | SERVICE_UNAVAIVABLE | Not authorized for heartbeat service. |
10 | DUPLICATED_ALARM | Same alarm received multiple times. |
98 | SERVER_ERROR | Unknown server error |
99 | OTHER_ERROR | Unknown receiver error, the transmitter should send alarm to failover address. |
100 | XML_HEADER_MISSING_OR_INVALID | Invalid or missing XML header. |
101 | PING_TO_OFTEN | Heartbeat is sent to often. |