12. API Reference

12.1. Client

class sos_access.client.SOSAccessClient(transmitter_code, transmitter_type, authentication, receiver_id, receiver_address, secondary_receiver_address=None, use_single_receiver=False, use_tls=False)[source]

Client implementing the SOS Access v4 protocol to be used for sending Alarm Requests to alarm operators.

Parameters:
  • transmitter_code (str) – The code that identifies the transmitter. Supplied by alarm operator
  • transmitter_type (str) – The transmitter type. Supplied by alarm operator
  • authentication (str) – Password for the alarm transmitter. Supplied by alarm operator
  • receiver_id (str) – ID for the receiving system. Needed for the protocol, but might not be needed by the alarm operator.
  • int) receiver_address ((str,) – Tuple of host (IP or FQDN) and port
  • int) secondary_receiver_address ((str,) – Tuple of host (IP or FQDN) and port
  • use_single_receiver (bool) – To enable not supplying secondary_receiver_address
  • use_tls (bool) – Indicates if the transmission of alarm should be encrypted using TLS. This library does not support SSLv3 since it is insecure.
ping(reference=None) → sos_access.schemas.PingResponse[source]

Sends a heart beat message to indicate to the alarm operator that the alarm device is still operational

Parameters:reference (str) – Is used as reference for the request and can be searched for in logs.
Returns:PingResponse
request_new_auth(reference=None) → sos_access.schemas.NewAuthResponse[source]

Send a request for new password on the server. This is used so that you can have a standard password when deploying devices but it is changed to something the alarm installer does not know when the alarm is operational

Parameters:reference (str) – Is used as reference for the request and can be searched for in logs.
Returns:NewAuthResponse
restore_alarm(event_code, transmitter_time=None, reference=None, transmitter_area=None, section=None, section_text=None, detector=None, detector_text=None, additional_info=None, position=None) → sos_access.schemas.AlarmResponse[source]

Restores an alarm in the receiver.

Parameters:
  • event_code (str) – The event code of the alarm.
  • transmitter_time (str) – Time of the device or system sending the alarm
  • reference (str) – A reference that will show up in logs on the alarm receiver.
  • transmitter_area (str) – Can be used to control different action at the alarm operator on the same transmitter and event_code.
  • section (str) – Section ID
  • section_text (str) – Section Description
  • detector (str) – Detector ID
  • detector_text (str) – Detector Description
  • additional_info (str|dict|list|set|tuple) – Extra information about alarm
  • position (str) – Position data
Returns:

AlarmResponse from alarm receiver

Todo

Is all the extra fields necessary on alarm restore?

send_alarm(event_code, transmitter_time=None, reference=None, transmitter_area=None, section=None, section_text=None, detector=None, detector_text=None, additional_info=None, position=None) → sos_access.schemas.AlarmResponse[source]

Sends an alarm in the receiver.

Parameters:
  • event_code (str) – The event code of the alarm.
  • transmitter_time (datetime.datetime) – Time of the device or system sending the alarm
  • reference (str) – A reference that will show up in logs on the alarm receiver.
  • transmitter_area (str) – Can be used to control different action at the alarm operator on the same transmitter and event_code.
  • section (str) – Section ID
  • section_text (str) – Section Description
  • detector (str) – Detector ID
  • detector_text (str) – Detector Description
  • additional_info (str|dict|list|set|tuple) – Extra information about alarm
  • position (str) – Position data
Returns:

AlarmResponse from alarm receiver

transmit(data, response_schema, secondary=False)[source]

Will create a TCP connection and send the request and received the response and then close the TCP connection.

Parameters:
  • data (str) – The SOS Access XML data to be sent.
  • response_schema (AlarmResponseSchema|PingResponseSchema|NewAuthResponseSchema) – The schema used to deserialize the response.
  • secondary (bool) – Indicates if to use the secondary receiver.
class sos_access.client.TCPTransport(address, secure=False, timeout=5)[source]

A context manager for TCP sockets to make sure the are closed correctly. Can create both secure and non secures sockets.

receive()[source]

Receive data on socket and decode using correct encoding

send(data)[source]

Send data over socket with correct encoding

12.2. Schemas and models

sos-access uses marshmallow and xmltodict to first make objects into dicts and then into xml when dumping data and the opposit when loading data

class sos_access.schemas.SOSAccessRequest[source]

Base SOS Access Request class

class sos_access.schemas.SOSAccessSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)[source]

Main Schema for serializing and deserializing SOS Access XML data

class sos_access.schemas.AlarmRequest(event_code, transmitter_type, transmitter_code, authentication, receiver, alarm_type=None, transmitter_time=None, reference=None, transmitter_area=None, section=None, section_text=None, detector=None, detector_text=None, additional_info=None, position=None)[source]

Represents an AlarmRequest

additional_info_text

Additional info is extra info about the alarm. Input is added using the additional_info but we are under constraint to format the output properly. We accept a list of values. Each item should be printed on a separate line. We use CR+LF to separate lines. If we dont get a list we try to make a string of it and send it on. We must keep the resulting text under 2000 chars. On list input we truncate the last input that makes the message go over the limit On single row we truncate the data and add … to it.

Returns:text
class sos_access.schemas.AlarmRequestSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)[source]

Schema for dumping and loading a AlarmRequest

class sos_access.schemas.AlarmResponse(status, info, arrival_time=None, reference=None)[source]

Represents an AlarmResponse

class sos_access.schemas.AlarmResponseSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)[source]

Schema for dumping and loading a AlarmResponse

class sos_access.schemas.PingRequest(authentication, transmitter_code, transmitter_type, reference=None)[source]

Represents a PingRequest

class sos_access.schemas.PingRequestSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)[source]

Schema for dumping and loading a PingRequest

class sos_access.schemas.PingResponse(status, info, arrival_time=None, reference=None)[source]

Represents a PingResponse

class sos_access.schemas.PingResponseSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)[source]

Schema for dumping and loading a PingResponse

class sos_access.schemas.NewAuthRequest(authentication, transmitter_code, transmitter_type, reference=None)[source]

Represents a NewAuthRequest

class sos_access.schemas.NewAuthRequestSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)[source]

Schema for dumping and loading a NewAuthRequest

class sos_access.schemas.NewAuthResponse(status, info, new_authentication=None, arrival_time=None, reference=None)[source]

Represents a NewAuthResponse

class sos_access.schemas.NewAuthResponseSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)[source]

Schema for dumping and loading a NewAuthResponse