Building Operations API¶
The Building Operations API enables you to read data from data points or issue commands to actuator points. Commanding enables you to e.g. change set-point values on a thermostat or open or close a valve.
The API is available for all Building X buildings that are connected with the Smart Edge services.
The Building Operations API is organized around the Device-, Point- and PointValue- resources. A device can host several points capable of either sensing information from the building such as temperature or air quality, or capable of receiving and processing commands. The data that is measured by data points is called point values and you can specify the time interval for which to fetch data.
Concepts & Glossary¶
| Term | Description |
|---|---|
| Device | A Device can be any electronic equipment with some computing ability that has a firmware or supports the installation of software. Examples are pumps, dampers, valves, sensors, detectors, limit switches, remote/local switches or automation devices. |
| Point | Points represent the interface to data in a system. Points are classifying data and give a semantic context to it. Examples for a Point are a Room Control for Temperature with a temperature set point. |
| PointValue | Object which represents a measurement or set value of a Point. |
| Event | An Event represents a non-normal (non-quiescent) state in building automation systems and is caused by an abnormal situation (technical: like fault, alarm, detector exclusion, range violation but also human: manually creating an alarm/task, request/call). |
| Location | A structure or part of a structure where a Device can be located |
A building typically contains multiple different Devices. The Devices host Points which can be of the following types: sensor, command or set-point. Points that are either sensors or set-points can have measured or aggregated time-series PointValues which can be filtered by time interval.
Devices¶
Some devices are connected directly to the Building X cloud and some make use of other devices to manage the connection. When a device relies on another device to connect to the cloud, it has a relationship called hasGateway defined, referring to the device it uses as a gateway to Building X.
Points¶
Any device may have points, regardless of whether the device is directly connected to the cloud or not.
System Attributes¶
In Building X some point properties are completely managed by the platform. In the Building Operations API those are defined in the API specification and include dataType and name. In addition, there are other properties contained in the systemAttributes-object.
The content of the systemAttributes is not marshaled by the Building Operations API and depends on the SW versions and configuration of devices and gateways connecting to Building X. As such, they may appear differently depending on the building and mentioned configurations. In addition, these properties may change outside of the API lifecycle, e.g., when updating firmware of the gateway device or software of the edge application.