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 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 |
| Workorder | A Workorder represents a task or job that needs to be carried out within the building operations, such as maintenance, repair, or inspection activities. Workorders can be created, updated, retrieved, and assigned to specific teams or individuals. They provide a structured way to manage operational activities and ensure proper tracking of work progress. |
| Fault | A Fault represents a detected abnormal condition or malfunction within a building system. Faults can be monitored, updated, and analyzed to understand their occurrences and overall impact on the building’s performance. |
| Team | A Team represents a group of people responsible for performing tasks or managing specific areas of the building operations. Teams can be created, updated, retrieved, and managed to ensure collaboration and assignment of responsibilities. |
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.
A building system can generate Faults that highlight abnormal conditions, which in turn lead to Workorders documenting the required activities, and these Workorders are assigned to Teams that ensure the issues are resolved effectively.
Workorders¶
Workorders are used to manage tasks and operational activities in the building environment. They enable a structured approach to handling different kinds of work, ensuring proper planning, execution, and tracking. A workorder can be created to document a maintenance activity, an inspection, or a repair. Once created, it can be updated with additional details such as its description, priority, or due date. Workorders can then be assigned to individuals or teams so that responsibilities are clear, and their progress can be tracked throughout the lifecycle of the task. They serve as a reliable tool for monitoring the status of ongoing activities, keeping a history of what has been completed, and ensuring that all work within the building operations is properly documented and followed through until completion.
Faults¶
Faults represent abnormal conditions or malfunctions in building systems and play an important role in monitoring operational health. They allow building operators to identify and analyze issues that may affect performance or safety. Faults can be retrieved to get an overview of all the problems detected in a partition or for a specific fault identifier. The state of a fault can be updated as its condition evolves, for instance when it is acknowledged or resolved. Each fault can also be examined in detail by looking at its occurrences, which provide insights into how frequently the issue arises and under what circumstances. Additionally, aggregated statistics about faults in a building can be accessed to better understand their overall impact, supporting both reactive and preventive maintenance strategies. In this way, the management of faults ensures that technical issues are not only detected but also documented, analyzed, and addressed effectively.
Teams¶
Teams represent groups of people that are responsible for carrying out tasks or managing specific aspects of building operations. They can be created for a customer with a defined name, description, and domain, and can be linked to certain locations or buildings. Once created, a team can be updated to reflect changes in its responsibilities or organizational context. Teams can also be retrieved to view details such as their members, scope, and associated locations. Members can be added to or managed within a team, ensuring that the right individuals are assigned to the right groups. This structure supports collaboration, accountability, and clear allocation of work across the building operations. Teams therefore serve as a foundation for organizing human resources, enabling efficient execution of workorders, and ensuring smooth communication and responsibility management within the building environment.
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.