Protocol
(For version 0.900)
Protocol Schematics: AlertR System
- Client: All (General)
- Client: Sensor
- Client: Manager
- Client: Alert
Protocol Schematics: AlertR Server Alert Level Instrumentation
Protocol Schematics: AlertR Sensor Client FIFO
Protocol Schematics: AlertR Sensor Client Executer
Protocol Schematics: AlertR Manager Client Database
Protocol Schematics: AlertR Alert Client Push Notification
Protocol Schematics: Sensor Data
Protocol Schematics: Sensor Error State
The RTS/CTS messages are inspired from the WiFi standards. The used connection between client and server are a shared channel. Every side can start the communication any time. This means server and client can collide when they start to communicate with each other. In order to prevent this, the communication initiator has to request the channel (RTS - request-to-send) and the other side has to grant the channel (CTS - clear-to-send). When both parties collide during the RTS/CTS messages, each one backoffs a random time between 0 and 1 second. This assures that only one party will get the channel at a given time.
The error response of a client or server.
c->s/s->c:
{
# type of message this one respond to
"message": <string>,
# error description message
"error": <string>,
}The expired response of a client or server. This response is sent, if a received message is too old or lies too far in the future. Therefore, the time set on the client and server has to be loosely synchronized and cannot be too far off (it is recommended to use NTP or anything comparable to keep the time on the host machines up-to-date).
c->s/s->c:
{
# type of message this one respond to
"message": <string>,
"payload": {
"type": "response"
"result": "expired"
}
}A client initializes communication to the server (all clients).
# First part: version verification and authentication
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
# Size refers to the next message send by the initator
# to the receiver (in this case the registration
# "c->s" message).
"size": <int>,
"message": "initialization",
"payload": {
"type": "request",
# x.y for example 0.700
"version": <float>,
"rev": <int>
"username": <string>,
"password": <string>,
}
}
s->c:
{
"message": "initialization",
"payload": {
"type": "response",
"result": "ok",
# x.y for example 0.700
"version": <float>,
"rev": <int>
}
}
# Second part: registration
# for the details of the registration part of the communication look in the section of each clientA client Ping request that is sent to the server.
c->s:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "ping",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
s->c:
{
"message": "ping",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "ping",
"payload": {
"type": "request",
}
}
s->c:
{
"message": "ping",
"payload": {
"type": "response"
"result": "ok"
}
}The client initializes the communication to the server.
# First part: version verification and authentication
# For the details of the version verification and authentication part of the communication look in the "all clients" section.
# Second part: registration
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "initialization",
"payload": {
"type": "request",
"hostname": <string>,
"nodeType": "sensor",
# Instance name, e.g., sensorClientPing
"instance": <string>,
# Flag indicates if this client has constantly a connection
# to the server or is allowed to go offline
# (NOTE: sensor clients are always considered "persistent")
# 0 => False
# 1 => True
"persistent": <int>,
"sensors": [
{
"clientSensorId": <int>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
"alertDelay": <int>,
# List of Alert Levels the Sensor belongs to.
"alertLevels": [<int>, <int>, ...]
"description": <string>,
# 0 => normal
# 1 => triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
},
{
"clientSensorId": <int>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
"alertDelay": <int>,
# List of Alert Levels the Sensor belongs to.
"alertLevels": [<int>, <int>, ...]
"description": <string>,
# 0 => normal
# 1 => triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
},
# [...]
]
}
}
s->c:
{
"message": "initialization",
"payload": {
"type": "response"
"result": "ok"
}
}The client sends a complete sensor status update.
c->s:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "status",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
s->c:
{
"message": "status",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "status",
"payload": {
"type": "request",
"sensors": [
{
"clientSensorId": <int>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
# 0 => normal
# 1 => triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
},
{
"clientSensorId": <int>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
# 0 => normal
# 1 => triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
},
# [...]
]
}
}
s->c:
{
"message": "status",
"payload": {
"type": "response"
"result": "ok"
}
}The client sends the notification to the server that a sensor alert has been triggered.
c->s:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "sensoralert",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
s->c:
{
"message": "sensoralert",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "sensoralert",
"payload": {
"type": "request",
"clientSensorId": <int>,
# 0 = normal, 1 = triggered
"state": <int>,
# Sets if optional data is set in Sensor Alert.
"hasOptionalData": <bool>,
# A dictionary that is only set if hasOptionalData is set.
"optionalData": {...}
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
# Flag indicates if this sensor alert also holds
# the data the sensor has. For example, the data send
# with this alarm message could be the data that triggered
# the alarm, but not necessarily the data the sensor
# currently holds. Therefore, this flag indicates
# if the data contained by this message is also the
# current data of the sensor and can be used
# to update the data the sensor has.
"hasLatestData": <bool>,
# Flag indicates if this sensor alert also changes
# the state the sensor has. For example, a timeout sensor
# could watch multiple hosts and has the state "triggered"
# when at least one host has timed out. When one host
# connects back and still at least one host is timed out,
# the sensor can issue a sensor alert for the "normal"
# state of the host that connected back, but the sensor
# can still has the state "triggered".
"changeState": <bool>,
}
}
s->c:
{
"message": "sensoralert",
"payload": {
"type": "response"
"result": "ok"
}
}The optional data field is used by many sensors in order to give more detailed information about the occurred alarm. For example, the "message" attribute is used by multiple sensors to have a text message that can be displayed if the alert client supports it. The following gives a list of attributes that different sensors will send with their sensor alert message as optional data.
This optional data is sent when the executer sensor does not parse the output of the command.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# Exit code of command process as integer.
"exitCode": <int>
}
# [...]IMPORTANT: When the output of the executed command is parsed (configuration setting for the executer sensor) then the executed command decides the optional data that is sent with the sensor alert message. Please refer to the protocol schematics for the executer sensor to see how to send optional data.
When the data written into the FIFO file contains the optional data field, then the sensor alert that is sent will also contain it. Please refer to the protocol schematics for the FIFO sensor to see how to send optional data.
This optional data is sent when a reminder triggers an alarm.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
# name of the calendar as string
"calendar": <string>,
"type": "reminder",
# title of the event as string
"title": <string>,
# description of the event as string
"description": <string>,
# location of the event as string
"location": <string>,
# unix timestamp (UTC) when reminder of calendar event triggered
"trigger": <int>,
# unix timestamp (UTC) when calendar event starts
"start": <int>,
}
# [...]This optional data is sent when fetching the calendar fails multiple times.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
# name of the calendar as string
"calendar": <string>,
"type": "timeout",
}
# [...]This optional data is sent when the ping sensor triggers an alarm.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# address of host pinged as string
"host": <string>,
# processtimeout/reachable/notreachable
"reason": <string>,
# exit code of ping process as integer
"exitCode": <int>,
}
# [...]This optional data is sent when an alarm for a DS18b20 sensor occurs.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# name of DS18b20 sensor as string
"sensorName": <string>,
}
# [...]This optional data is sent when an alarm is generated by a temperature or humidity sensor.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# country as string
"country": <string>,
# city as string
"city": <string>,
# longitude of the city
"lon": <float>,
# latitude of the city
"lat": <float>,
# temperature/humidity
"type": <string>,
}
# [...]This optional data is sent when an alarm is generated by a temperature forecast sensor.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# country as string
"country": <string>,
# city as string
"city": <string>,
# longitude of the city
"lon": <float>,
# latitude of the city
"lat": <float>,
"type": "forecasttemp",
# LOW/HIGH
"kind": <string>,
# day of forecast as integer
"day": <int>,
}
# [...]This optional data is sent when an alarm is generated by a rain forecast sensor.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# country as string
"country": <string>,
# city as string
"city": <string>,
# longitude of the city
"lon": <float>,
# latitude of the city
"lat": <float>,
"type": "forecastrain",
# day of forecast as integer
"day": <int>,
}
# [...]This optional data is sent when a node timed out.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
# hostname of node as string
"hostname": <string>,
# username of node as string
"username": <string>,
# instance of node as string
"instance": <string>,
# type of node as string
"nodeType": <string>,
}
# [...]This optional data is sent when a node has reconnected.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
# hostname of node as string
"hostname": <string>,
# username of node as string
"username": <string>,
# instance of node as string
"instance": <string>,
# type of node as string
"nodeType": <string>,
}
# [...]This optional data is sent when at least one node is still timed out after a longer time period.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
"nodes": [
{
# hostname of node as string
"hostname": <string>,
# username of node as string
"username": <string>,
# instance of node as string
"instance": <string>,
# type of node as string
"nodeType": <string>,
},
{
# hostname of node as string
"hostname": <string>,
# username of node as string
"username": <string>,
# instance of node as string
"instance": <string>,
# type of node as string
"nodeType": <string>,
},
# [...]
],
}
# [...]This optional data is sent when a sensor error state changed.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
# username of node as string
"username": <string>,
# ID used by the client for this sensor.
"clientSensorId": <int>,
}
# [...]This optional data is sent when a new version is available.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
# hostname of node as string
"hostname": <string>,
# username of node as string
"username": <string>,
# instance of node as string
"instance": <string>,
# type of node as string
"nodeType": <string>,
# version of node as float
"version": <float>,
# revision of node as integer
"rev": <int>,
# new available version of node as float
"newVersion": <float>,
# new available revision of node as integer
"newRev": <int>,
}
# [...]This optional data is sent when at least one node had an update available and now all nodes were updated and have the newest version.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
}
# [...]This optional data is sent when the online update check failed multiple times in a row.
# [...]
# Contains additional data specific to sensor.
"optionalData": {
# message string
"message": <string>,
}
# [...]The client sends the notification to the server that the state of a sensor has changed (only sent if no sensor alert was triggered).
c->s:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "statechange",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
s->c:
{
"message": "statechange",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "statechange",
"payload": {
"type": "request",
"clientSensorId": <int>,
# 0 => normal
# 1 => triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
}
}
s->c:
{
"message": "statechange",
"payload": {
"type": "response"
"result": "ok"
}
}The client sends the notification to the server that the error state of a sensor has changed.
c->s:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "sensorerrorstatechange",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
s->c:
{
"message": "sensorerrorstatechange",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "sensorerrorstatechange",
"payload": {
"type": "request",
"clientSensorId": <int>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
}
}
s->c:
{
"message": "sensorerrorstatechange",
"payload": {
"type": "response"
"result": "ok"
}
}# First part: version verification and authentication
# for the details of the version verification and authentication part of the communication look in the "all clients" section
# Second part: registration
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "initialization",
"payload": {
"type": "request",
"hostname": <string>,
"nodeType": "manager",
# Instance name, e.g., managerClientConsole>
"instance": <string>,
# Flag indicates if this client has constantly a connection
# to the server or is allowed to go offline
# (NOTE: sensor clients are always considered "persistent")
# 0 => False
# 1 => True
"persistent": <int>,
"manager": {
"description": <string>,
}
}
}
s->c:
{
"message": "initialization",
"payload": {
"type": "response"
"result": "ok"
}
}
# When successfully registered, a complete system state update is sent to the client.A complete system state update is sent from the server to the client.
s->c:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "s->c" message).
"size": <int>,
"message": "status",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
c->s:
{
"message": "status",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
s->c:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "status",
"payload": {
"type": "request",
"options": [
{
"type": <string>,
"value": <int>,
},
{
"type": <string>,
"value": <int>,
},
# [...]
],
"profiles": [
{
"profileId": <int>,
"name": <str>,
},
{
"profileId": <id>,
"name": <str>,
},
# [...]
],
"nodes": [
{
"nodeId": <int>,
"hostname": <string>,
"nodeType": <string>,
"instance": <string>,
# 1 => connected
# 0 => disconnected
"connected": <int>,
"version": <float>,
"rev": <int>,
"username": <string>,
# 0 => False
# 1 => True
"persistent": <int>,
},
{
"nodeId": <int>,
"hostname": <string>,
"nodeType": <string>,
"instance": <string>,
# 1 => connected
# 0 => disconnected
"connected": <int>,
"version": <float>,
"rev": <int>,
"username": <string>,
# 0 => False
# 1 => True
"persistent": <int>,
},
# [...]
],
"sensors": [
{
"nodeId": <int>,
"sensorId": <int>,
"alertDelay": <int>,
"alertLevels": [<int>, <int>, ...],
"description": <string>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
# 0 => normal
# 1 => triggered
"state": <int>,
# ID used by the client for this sensor.
"clientSensorId": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
},
{
"nodeId": <int>,
"sensorId": <int>,
"alertDelay": <int>,
"alertLevels": [<int>, <int>, ...],
"description": <string>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
# 0 => normal
# 1 => triggered
"state": <int>,
# ID used by the client for this sensor.
"clientSensorId": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
},
# [...]
],
"managers": [
{
"nodeId": <int>,
"managerId": <int>,
"description": <string>,
},
{
"nodeId": <int>,
"managerId": <int>,
"description": <string>,
},
# [...]
],
"alerts": [
{
"nodeId": <int>,
"alertId": <int>,
"description": <string>,
"alertLevels": [<int>, <int>, ...],
# ID used by the client for this alert.
"clientAlertId": <int>,
},
{
"nodeId": <int>,
"alertId": <int>,
"description": <string>,
"alertLevels": [<int>, <int>, ...],
# ID used by the client for this alert.
"clientAlertId": <int>,
},
# [...]
],
"alertLevels": [
{
"alertLevel": <int>,
"name": <string>,
"profiles": [<int>, <int>, ...],
"instrumentation_active": <bool>,
# Only set if instrumentation_active is True.
"instrumentation_cmd": <string>,
# Only set if instrumentation_active is True.
"instrumentation_timeout": <int>,
},
{
"alertLevel": <int>,
"name": <string>,
"profiles": [<int>, <int>, ...],
"instrumentation_active": <bool>,
# Only set if instrumentation_active is True.
"instrumentation_cmd": <string>,
# Only set if instrumentation_active is True.
"instrumentation_timeout": <int>,
},
# [...]
],
}
}
c->s:
{
"message": "status",
"payload": {
"type": "response"
"result": "ok"
}
}The client sends an option change to the server.
c->s:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "option",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
s->c:
{
"message": "option",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "option",
"payload": {
"type": "request",
"optionType": <string>,
"value": <int>,
"timeDelay": <int>,
}
}
s->c:
{
"message": "option",
"payload": {
"type": "response"
"result": "ok"
}
}The server sends the notification to the client that a sensor alert has been triggered.
s->c:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "sensoralert",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
c->s:
{
"message": "sensoralert",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
s->c:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "sensoralert",
"payload": {
"type": "request",
"sensorId": <int>,
"alertLevels": [<int>, <int>, ...],
"description": <string>,
# 0 = normal, 1 = triggered
"state": <int>,
# Sets if optional data is set in Sensor Alert.
"hasOptionalData": <bool>,
# A dictionary that is only set if hasOptionalData is set.
"optionalData": {...}
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
# Flag indicates if this sensor alert also holds
# the data the sensor has. For example, the data send
# with this alarm message could be the data that triggered
# the alarm, but not necessarily the data the sensor
# currently holds. Therefore, this flag indicates
# if the data contained by this message is also the
# current data of the sensor and can be used
# to update the data the sensor has.
"hasLatestData": <bool>,
# Flag indicates if this sensor alert also changes
# the state the sensor has. For example, a timeout sensor
# could watch multiple hosts and has the state "triggered"
# when at least one host has timed out. When one host
# connects back and still at least one host is timed out,
# the sensor can issue a sensor alert for the "normal"
# state of the host that connected back, but the sensor
# can still has the state "triggered".
"changeState": <bool>,
}
}
c->s:
{
"message": "sensoralert",
"payload": {
"type": "response"
"result": "ok"
}
}The server sends the notification to the client that the state of a sensor has changed (only sent if no sensor alert was triggered).
s->c:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "statechange",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
c->s:
{
"message": "statechange",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
s->c:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "statechange",
"payload": {
"type": "request",
"sensorId": <int>,
# 0 => normal
# 1 => triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
}
}
c->s:
{
"message": "statechange",
"payload": {
"type": "response"
"result": "ok"
}
}The server sends the notification to the client that the error state of a sensor has changed.
s->c:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "sensorerrorstatechange",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
c->s:
{
"message": "sensorerrorstatechange",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
s->c:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "sensorerrorstatechange",
"payload": {
"type": "request",
"sensorId": <int>,
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>,
}
}
c->s:
{
"message": "sensorerrorstatechange",
"payload": {
"type": "response"
"result": "ok"
}
}The client initializes the communication to the server.
# First part: version verification and authentication
# for the details of the version verification and authentication part of the communication look in the "all clients" section
# Second part: registration
c->s:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "initialization",
"payload": {
"type": "request",
"hostname": <string>,
"nodeType": "alert",
# Instance name, e.g., alertClientDbus
"instance": <string>,
# Flag indicates if this client has constantly a connection
# to the server or is allowed to go offline
# (NOTE: sensor clients are always considered "persistent")
# 0 => False
# 1 => True
"persistent": <int>,
"alerts": [
{
"clientAlertId": <string>,
# List of Alert Levels the Sensor belongs to.
"alertLevels": [<int>, <int>, ...]
"description": <string>,
},
{
"clientAlertId": <string>,
# List of Alert Levels the Sensor belongs to.
"alertLevels": [<int>, <int>, ...],
"description": <string>,
},
# [...]
],
}
}
s->c:
{
"message": "initialization",
"payload": {
"type": "response"
"result": "ok"
}
}The server sends the notification to the client that a sensor alert has been triggered.
s->c:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "sensoralert",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
c->s:
{
"message": "sensoralert",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
s->c:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "sensoralert",
"payload": {
"type": "request",
"sensorId": <int>,
"alertLevels": [<int>, <int>, ...],
"description": <string>,
# 0 => normal
# 1 => triggered
"state": <int>,
# Sets if optional data is set in Sensor Alert.
"hasOptionalData": <bool>,
# A dictionary that is only set if hasOptionalData is set.
"optionalData": {...}
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
# Flag indicates if this sensor alert also holds
# the data the sensor has. For example, the data send
# with this alarm message could be the data that triggered
# the alarm, but not necessarily the data the sensor
# currently holds. Therefore, this flag indicates
# if the data contained by this message is also the
# current data of the sensor and can be used
# to update the data the sensor has.
"hasLatestData": <bool>,
# Flag indicates if this sensor alert also changes
# the state the sensor has. For example, a timeout sensor
# could watch multiple hosts and has the state "triggered"
# when at least one host has timed out. When one host
# connects back and still at least one host is timed out,
# the sensor can issue a sensor alert for the "normal"
# state of the host that connected back, but the sensor
# can still has the state "triggered".
"changeState": <bool>,
}
}
c->s:
{
"message": "sensoralert",
"payload": {
"type": "response"
"result": "ok"
}
}The server sends to the client that the used system profile has changed.
s->c:
{
# Size refers to the next message send by the initator
# to the receiver (in this case the next "c->s" message).
"size": <int>,
"message": "profilechange",
"payload": {
"type": "rts"
# Unique ID
"id": <int>
}
}
c->s:
{
"message": "profilechange",
"payload": {
"type": "cts"
# Unique ID from the rts message.
"id": <int>
}
}
s->c:
{
# unix utc timestamp when message was created on host
"msgTime": <int>,
"message": "profilechange",
"payload": {
"type": "request",
# ID of the system profile
"profileId": <int>,
# Name of the system profile
"name": <string>,
}
}
c->s:
{
"message": "profilechange",
"payload": {
"type": "response"
"result": "ok"
}
}The following describes the protocol that is used to communicate with the instrumentation scripts executed by the AlertR server when Alert Level instrumentation is activated.
When the AlertR Server executes an Alert Level instrumentation script, it passes the Sensor Alert object as argument in JSON format. The following shows the layout of this argument:
{
"sensorId": <int>,
"nodeId": <int>,
"description": <string>,
# Flag indicates if this sensor alert also holds
# the data the sensor has. For example, the data send
# with this alarm message could be the data that triggered
# the alarm, but not necessarily the data the sensor
# currently holds. Therefore, this flag indicates
# if the data contained by this message is also the
# current data of the sensor and can be used
# to update the data the sensor has.
"hasLatestData": <bool>,
# Flag indicates if this sensor alert also changes
# the state the sensor has. For example, a timeout sensor
# could watch multiple hosts and has the state "triggered"
# when at least one host has timed out. When one host
# connects back and still at least one host is timed out,
# the sensor can issue a sensor alert for the "normal"
# state of the host that connected back, but the sensor
# can still has the state "triggered".
"changeState": <bool>,
# Sets if optional data is set in Sensor Alert.
"hasOptionalData": <bool>,
# A dictionary that is only set if hasOptionalData is set.
"optionalData": {...}
# UTC timestamp when Sensor Alert was received.
"timeReceived": <int>,
# List of Alert Levels the Sensor Alert belongs to.
"alertLevels": [<int>, <int>, ...],
# The Alert Level that executes the instrumentation script.
"instrumentationAlertLevel": <int>,
# Delay this Sensor Alert has to wait.
"alertDelay": <int>,
# 0 = normal, 1 = triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
}When the instrumentation script finishes execution, it has to output the results. The results are again the Sensor Alert object in JSON format. However, the instrumentation script has two options:
- If the Sensor Alert should no longer be processed (meaning it will be suppressed) the following output should be created:
{}- If the Sensor Alert was processed and necessary changes were performed, the following layout is expected. IMPORTANT: Note that some fields are immutable and cannot be changed by the instrumentation.
{
# IMMUTABLE
"sensorId": <int>,
# IMMUTABLE
"nodeId": <int>,
# IMMUTABLE
"description": <string>,
# Flag indicates if this sensor alert also holds
# the data the sensor has. For example, the data send
# with this alarm message could be the data that triggered
# the alarm, but not necessarily the data the sensor
# currently holds. Therefore, this flag indicates
# if the data contained by this message is also the
# current data of the sensor and can be used
# to update the data the sensor has.
"hasLatestData": <bool>,
# Flag indicates if this sensor alert also changes
# the state the sensor has. For example, a timeout sensor
# could watch multiple hosts and has the state "triggered"
# when at least one host has timed out. When one host
# connects back and still at least one host is timed out,
# the sensor can issue a sensor alert for the "normal"
# state of the host that connected back, but the sensor
# can still has the state "triggered".
"changeState": <bool>,
# Sets if optional data is set in Sensor Alert.
"hasOptionalData": <bool>,
# A dictionary that is only set if hasOptionalData is set.
"optionalData": {...}
# IMMUTABLE
# UTC timestamp when Sensor Alert was received.
"timeReceived": <int>,
# IMMUTABLE
# List of Alert Levels the Sensor Alert belongs to.
"alertLevels": [<int>, <int>, ...],
# IMMUTABLE
# The Alert Level that executes the instrumentation script.
"instrumentationAlertLevel": <int>,
# IMMUTABLE
# Delay this Sensor Alert has to wait.
"alertDelay": <int>,
# 0 = normal, 1 = triggered
"state": <int>,
# IMMUTABLE
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
}The following describes the protocol that is used by the FIFO file of the AlertR Sensor Client FIFO. An example implementation for this protocol is shown in the Developer Tutorial for AlertR Sensor Client FIFO Write.
A sensor alert is triggered either for the state "triggered" or "normal". Optional data can be sent with a sensor alert as well as data the sensor normally holds.
{
"message": "sensoralert",
"payload": {
# 0 = normal, 1 = triggered
"state": <int>,
# Sets if optional data is set in Sensor Alert.
"hasOptionalData": <bool>,
# A dictionary that is only set if hasOptionalData is set.
"optionalData": {...}
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
# Flag indicates if this sensor alert also holds
# the data the sensor has. For example, the data send
# with this alarm message could be the data that triggered
# the alarm, but not necessarily the data the sensor
# currently holds. Therefore, this flag indicates
# if the data contained by this message is also the
# current data of the sensor and can be used
# to update the data the sensor has.
"hasLatestData": <bool>,
# Flag indicates if this sensor alert also changes
# the state the sensor has. For example, a timeout sensor
# could watch multiple hosts and has the state "triggered"
# when at least one host has timed out. When one host
# connects back and still at least one host is timed out,
# the sensor can issue a sensor alert for the "normal"
# state of the host that connected back, but the sensor
# can still has the state "triggered".
"changeState": <bool>,
}
}Example on a bash shell (triggers a sensor alert with the state "triggered" that does not hold sensor data but has a message as optional data):
sqall@pc:~/alertR/sensorClientFIFO$ echo '{"message": "sensoralert", "payload": {"state": 1, "hasOptionalData": true, "optionalData": {"message": "test sensor alert"}, "dataType": 0, "data": {}, "hasLatestData": false, "changeState": true}}' > sensor0fifo
The state of the sensor is set to either "triggered" or "normal". The sensor can also hold data. This message only changes the state of the sensor but does not trigger a sensor alert.
{
"message": "statechange",
"payload": {
# 0 = normal, 1 = triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
}
}Example on a bash shell (sets state of the sensor to "triggered" and also updates the integer data the sensor holds):
sqall@pc:~/alertR/sensorClientFIFO$ echo '{"message": "statechange", "payload": {"state": 1, "dataType": 1, "data": {"value:" 42, "unit": "$"}}' > sensor0fifo
The error state of the sensor can hold different states. Additionally, the error state contains a message for each non-OK state. This message only changes the error state of the sensor but does not affect any other data of the sensor (such as state or data).
{
"message": "sensorerrorstatechange",
"payload": {
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>
}
}Example on a bash shell (sets error state to "GenericError" and sets the message to "Some description message"):
sqall@pc:~/alertR/sensorClientFIFO$ echo '{"message": "sensorerrorstatechange", "payload": {"error_state": {"state": 1, "msg": "Some description message"}}}' > sensor0fifo
The following describes the protocol that is used by the executed command of the AlertR Sensor Client Executer. The executed command has to use the following protocol as generated output to control the sensor state. An example implementation for this protocol is shown in the Developer Tutorial for AlertR Sensor Client Executer Processable Output.
A sensor alert is triggered either for the state "triggered" or "normal". Optional data can be sent with a sensor alert as well as data the sensor normally holds.
{
"message": "sensoralert",
"payload": {
# 0 = normal, 1 = triggered
"state": <int>,
# Sets if optional data is set in Sensor Alert.
"hasOptionalData": <bool>,
# A dictionary that is only set if hasOptionalData is set.
"optionalData": {...}
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
# Flag indicates if this sensor alert also holds
# the data the sensor has. For example, the data send
# with this alarm message could be the data that triggered
# the alarm, but not necessarily the data the sensor
# currently holds. Therefore, this flag indicates
# if the data contained by this message is also the
# current data of the sensor and can be used
# to update the data the sensor has.
"hasLatestData": <bool>,
# Flag indicates if this sensor alert also changes
# the state the sensor has. For example, a timeout sensor
# could watch multiple hosts and has the state "triggered"
# when at least one host has timed out. When one host
# connects back and still at least one host is timed out,
# the sensor can issue a sensor alert for the "normal"
# state of the host that connected back, but the sensor
# can still has the state "triggered".
"changeState": <bool>,
}
}Example output of an executed command (triggers a sensor alert with the state "triggered" that does not hold sensor data but has a message as optional data):
{"message": "sensoralert", "payload": {"state": 1, "hasOptionalData": true, "optionalData": {"message": "test sensor alert"}, "dataType": 0, "data": {}, "hasLatestData": false, "changeState": true}}
The state of the sensor is set to either "triggered" or "normal". The sensor can also hold data. This message only changes the state of the sensor but does not trigger a sensor alert.
{
"message": "statechange",
"payload": {
# 0 = normal, 1 = triggered
"state": <int>,
# Gives the type of the carried data (0 = none, 1 = int, 2 = float, 3 = GPS).
"dataType": <int>,
# Layout described in section "Protocol Schematics: Sensor Data"
"data": <SensorData>,
}
}Example output of an executed command (sets state of the sensor to "triggered" and also updates the integer data the sensor holds):
{"message": "statechange", "payload": {"state": 1, "dataType": 1, "data": {"value": 42, "unit": "$"}}}
The error state of the sensor can hold different states. Additionally, the error state contains a message for each non-OK state. This message only changes the error state of the sensor but does not affect any other data of the sensor (such as state or data).
{
"message": "sensorerrorstatechange",
"payload": {
# Layout described in section "Protocol Schematics: Sensor Error State"
"error_state": <SensorErrorState>
}
}Example output of an executed command (sets error state to "GenericError" and sets the message to "Some description message"):
{"message": "sensorerrorstatechange", "payload": {"error_state": {"state": 1, "msg": "Some description message"}}}
The following describes the protocol that is used by the UNIX TCP socket server of the AlertR Manager Client Database. In this case, "s" (server) is the AlertR Manager Client Database and "c" (client) is any entity that connects to the local UNIX TCP socket server of the AlertR Manager Client Database.
When the AlertR Manager Client Database receives this message, it forwards the option change message to the server. Note, the only option that is allowed at the moment is the "profile" option.
A successful response message with "ok" as result only indicates that the option message is successfully queued by the client for transfer to the server. It does not mean that the server has received and processed it yet.
c->s:
{
"message": "option",
"payload": {
"optionType": <string>,
"value": <float>,
"timeDelay": <int>,
}
}
s->c:
{
"message": "option",
"payload": {
"type": "response"
"result": "ok"
}
}The following describes the protocol that is used by the push notification service. In this case, "s" (server) is the alertr.de push service and "c" (client) is the AlertR Alert Client Push Notification (or any entity that directly connects to the push service).
When the AlertR Alert Client Push Notification receives a sensor alert, it generates a notification message and sends it to the alertr.de push service.
c->s:
{
# alertr.de account username
"username": <string>,
# alertr.de account password
"password": <string>,
# channel the notification is sent to
"channel": <string>,
# current version: 0.1
"version": <float>,
# ENCRYPTED_DATA
"data": <string>,
}
s->c:
{
# error code
"Code": <int>,
}The ENCRYPTED_DATA is encrypted via a shared secret between the AlertR Alert Client Push Notification and the receiving devices. Only devices in possession of the shared secret are able to read the message. ENCRYPTED_DATA looks like the following:
base64(
<16 bytes of random data as IV>
aes256_cbc(
<4 bytes of random data>
{
# Subject of the notification
sbj: <string>,
# Message
msg: <string>,
# UTC time the sensor alert triggered
tt: <int>,
# UTC time the notification was sent
ts: <int>,
# is sensor alert? (true or false)
is_sa: <bool>,
# state of the sensor alert (0 or 1)
st: <int>,
}
)
)The following describes the layout of the Sensor Data (noted as <SensorData> in the protocol descriptions) inside the protocol messages (e.g., in the Sensor Alert Triggered Message).
If no data is hold by the message, the following format is expected:
{
}If an integer is hold by the message, the following format is expected:
{
# The value of the data.
"value": <int>,
# The unit of the data (e.g., "°C" or "$"")
"unit": <str>,
}If a floating point number is hold by the message, the following format is expected:
{
# The value of the data.
"value": <float>,
# The unit of the data (e.g., "°C" or "$"")
"unit": <str>,
}If a GPS position is hold by the message, the following format is expected:
{
# Latitude
"lat": <float>,
# Longitude
"lon": <float>,
# UTC timestamp
"utctime": <int>,
}The following describes the layout of the Sensor Error State (noted as <SensorErrorState> in the protocol descriptions) inside the protocol messages (e.g., in the Error State Change Of Sensor Message).
{
# 0 = OK
# 1 = GenericError
# 2 = ProcessingError
# 3 = TimeoutError
# 4 = ConnectionError
# 5 = ExecutionError
# 6 = ValueError
"state": <int>,
# A message to give additional information to the given error state.
# Is not allowed to be empty if error state is non-OK.
# Has to be set to "" if error state is OK.
"msg": <str>,
}