This platform API allows the devices sending asynchronous events to notify extraordinary operational situations

The next figure shows the workflow of the events

opengate api south event workflow
Figure 1. Event flow

As it is shown in the image:

  • It is used HTTP request/response mechanism with and embedded JSON file

  • Platform implements a HTTP web service publishing the next URIs

Table 1. Event URI
URI Description

POST - /south/v80/devices/{device.id}/events/alarms

For device alarm events

Alarms Event

POST /south/v80/devices/{device.id}/events/alarms

JSON Object

Table 2. Alarm object attributes
Attribute Description

id

Unique identifier (platform generated) for the event. This will contain an string in UUID format

timestamp

Number with the time in seconds from epoch when platform has launched the event

deviceId(optional)

Only used when device that generates the operation is different than the device used as a gateway or proxy. Example: Event from a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated in the URI

path

Array of device identifiers traversed to reach gateway

Filled only when devices is not connected directly to the platform. See Device to Platform connection scenarios

name

String with the name or identifier of the type of event.

See Events examples

New events can be added depending on the device capabilities

specific

String with a device specific name for this type of event.

description

String describing the alarm or reason of raising it

variables[]

Array of variables associated to the operation request. See Parameter Object
AlarmEvent JSON example
{
    "event" :
    {
        "alarm" :
        {
            "id": "50dca9ab-f552-4805-9cff-019090d5b92b",
            "deviceId":"device_1",
            "severity": "CRITICAL",
            "priority" : "HIGH",
            "name": "Alarm_1",
            "specific" : "",
            "description": "alarm description",
            "timestamp" : 1432454275000,
            "variables": [
			    {
					"name" : "variable1",
					"value" : "value1"
				},
				{
					"name" : "variable2",
					"value" : 10
				},
				{
					"name" : "variable3",
					"value" : {
                        "variable3.1" : "value3.1",
                        "variable3.2" : 20
                    }
				}
			]
        }
    }
}