SAN API and interfacing

This section will contain information on how SAN sends information to the HMI node, and how you can query and use the available data without HMI.

Standard entity format

SAN is connected to HMI (Human Machine Interface) in OPIL, which processes the received data and monitors it/redirects to TP. However, because the end result is present in Orion Context Broker, HMI can be replaced by your solution/system. Alternatively, you can even replace SAN with your solution, but if you want to link it to HMI, you will have to keep the entity format what is output by SAN.

First, introduce yourself with how entities and attributes in Orion Context Broker.

Next, observe the example of a generic entity output by SAN:

{
    "measurementType": {
        "type": "string",
        "value": "boolean"
    },
    "modifiedTime": {
        "type": "string",
        "value": "2019-07-18T10:23:21Z"
    },
    "readings": {
        "type": "array",
        "value": [
            {
                "type": "SensorReading",
                "value": {
                    "reading": {
                        "type": "boolean",
                        "value": true
                    }
                }
            }
        ]
    },
    "sanID": {
        "type": "string",
        "value": "SAN1"
    },
    "sensorID": {
        "type": "string",
        "value": "sensor7"
    },
    "sensorManufacturer": {
        "type": "string",
        "value": "IDec"
    },
    "sensorType": {
        "type": "string",
        "value": "IR"
    }
}

Below is the explanation of the entity along with its attributes:

Attribute Data Type Description
sensorID String sensorID attribute contains a unique ID of the particular sensor. ID will tell the user which sensor exactly has sent the data, it will be unique for each sensor on the system
sensorType String sensorType attribute contains the type of the sensor e.g. infrared(IR), RFID, etc.
measurementType String measurementType contains the information which tells user what has been measured exactly. Sensors of the same type may be used for measuring different types of information, hence the need to specify. For boolean data this should be set to boolean in the configuration file in order to avoid unit conversion conflicts
manufacturer String manufacturer contains the name of the manufacturer of the sensor
readings Array readings is an array with 1 attribute: reading. reading corresponds to a particular reading taken by sensor. reading is an attribute of this readings array because multiple reading attributes can be batched into the readings array when set by user.
modifiedTime String modifiedTime specifies the time when the reading was taken by sensor.
Attribute Data type Description
reading Number/Boolean/String/Array reading specified the actual measurement taken by sensor. It can be a numberic value, a boolean value or a string - it depends on the particular sensor. From this attribute the actual data is received

Above: Explanation of reading attribute

PLEASE NOTE! - the used time format is expected to be ISO8601

Orion Context Broker API to receive updates on SAN data

You can retrieve the SAN data off the Context Broker using 2 methods: either straight by using HTTP GET API command or by creating a subscription to a SAN entity.

Using HTTP GET

Use the following command to receive/GET the data:

unparsed raw output: curl http://orion:1026/v2/entities/sensorID -s -S -H 'Accept - application/json'

SAN-like output: curl http://orion:1026/v2/entities/sensorID -s -S -H 'Accept - application/json' | python -mjson.tool

The entities on the server, after receiving their first updates, would look like this for two separate sensors, when called with the SAN-like output GET command:

[
    {
        "id": "optical_sensor1",
        "type": "SensorAgent",
        "measurementType": {
            "type": "string",
            "value": "boolean",
            "metadata": {}
        },
        "modifiedTime": {
            "type": "string",
            "value": "2019-09-11T09:36:53Z",
            "metadata": {}
        },
        "readings": {
            "type": "array",
            "value": [
                {
                    "type": "SensorReading",
                    "value": {
                        "reading": {
                            "type": "boolean",
                            "value": false
                        }
                    }
                }
            ],
            "metadata": {}
        },
        "sanID": {
            "type": "string",
            "value": "SAN1",
            "metadata": {}
        },
        "sensorID": {
            "type": "string",
            "value": "optical_sensor1",
            "metadata": {}
        },
        "sensorManufacturer": {
            "type": "string",
            "value": "LLC",
            "metadata": {}
        },
        "sensorType": {
            "type": "string",
            "value": "ON_OFF_SENSOR",
            "metadata": {}
        },
        "units": {
            "type": "string",
            "value": "boolean",
            "metadata": {}
        }
    },
    {
        "id": "optical_sensor2",
        "type": "SensorAgent",
        "measurementType": {
            "type": "string",
            "value": "boolean",
            "metadata": {}
        },
        "modifiedTime": {
            "type": "string",
            "value": "2019-09-11T09:36:53Z",
            "metadata": {}
        },
        "readings": {
            "type": "array",
            "value": [
                {
                    "type": "SensorReading",
                    "value": {
                        "reading": {
                            "type": "boolean",
                            "value": false
                        }
                    }
                }
            ],
            "metadata": {}
        },
        "sanID": {
            "type": "string",
            "value": "SAN1",
            "metadata": {}
        },
        "sensorID": {
            "type": "string",
            "value": "optical_sensor2",
            "metadata": {}
        },
        "sensorManufacturer": {
            "type": "string",
            "value": "LLC",
            "metadata": {}
        },
        "sensorType": {
            "type": "string",
            "value": "ON_OFF_SENSOR",
            "metadata": {}
        },
        "units": {
            "type": "string",
            "value": "boolean",
            "metadata": {}
        }
    }
]

Output with only values (types are ignored in this output): curl http://orion:1026/v2/entities/sensorID?options=keyValues -s -S -H 'Accept - application/json' | python -mjson.tool

Above: Substitute orion with the IP address of your Orion Context Broker and sensorID with your sensor ID

Using subscription

Please check how subscriptions are made.

The example of a subscription POST operation can look like this:

curl -v http://orion:1026/v2/subscriptions -s -S -H 'Content-Type: application/json' -d @- <<EOF
{
    "description": "A subscription to get info about SAN",
    "subject": {
        "entities": [
            {
                "id": "SAN_demo",
                "type": "SensorAgent"
            }
        ],
        "condition": {
            "attrs": [
                "YOUR_ATTRIBUTE_HERE",
            ]
        }
    },
    "notification": {
        "http": {
            "url": "http://yoururl.com"
        },
        "attrs": [
            "YOUR_ATTRIBUTE_HERE",
        ]
    },
    "throttling": 2
}
EOF

Above: Instead of http://yoururl.com insert the endpoint you want to get data to and substitute orion with the IP address of your Orion Context Broker

Available attributes for the "attrs" field can be seen in the generic entity output above