Skip to content

Operations API

The 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 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

overview

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 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 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.

For more information about the systemAttributes that are specific to your edge application, refer to the next chapter, Edge Application Specific Information.

Edge Application Specific Information

This chapter details properties and behaviors that are specific for a certain Edge Application or a specific version of an application.

Building Operator Discovery (BOD) v3.0.25

The information in this section is applicable for setups with the following characteristics:

  • Gateway: X300/4.11.X
  • Edge Application: BOD/3.0.25
  • Network Protocol: BACnet

Custom System Attributes

A subset of the most relevant properties contained in the systemAttributes are listed below:

Property Data type Example Description
enum String Off,Stage 1,Stage 2,Stage 3,Stage 4,Stage 5,Stage 6,Stage 7,Stage 8,Stage 9,Stage 10,Stage 11,Stage 12,Stage 13,Stage 14,Stage 15, Off,On A string of comma separated values representing the possible values this point can be set to or measure.
kind String (enum) One of Bool, Str and Number Describing the data type.
unit String °C, pascals, degrees_celsius, degrees_kelvin ,percent The unit of the values set or measured by the point.
sensor String (marker) m: Point is a sensor. Mutually exclusive with sp and cmd.
sp String (marker) m: Point is a 'set point'. Mutually exclusive with sensor and cmd.
cmd String (marker) m: Point is a command. Mutually exclusive with sp and sensor.
writable String (marker) m: Indicates that the point value can be updated (commanded or set).
writeLevel String (with number) 17 Current priority level for writeVal as number between 1 and 17. The value 17 indicates the relinquish default value.
minValue String 0 Inclusive minimum for a numeric value.
maxValue String 100 Inclusive maximum for a numeric value.

The presence and content of the listed, and other, properties depend on the configuration of the BOD application. Please refer to the BOD documentation for detailed information.

Example of a Point model with custom systemAttributes specific to BOD 3.0.25:

{
  "data": {
    "type": "Point",
    "id": "2d55baf8-b5af-4fd1-8af6-187e67f527f9",
    "attributes": {
      "dataType": "number",
      "systemAttributes": {
        "cmd": "m:",
        "cur": "m:",
        "kind": "Number",
        "maxVal": "90",
        "minVal": "10",
        "unit": "%",
        "writable": "m:"
      },
      "name": "point 123"
    },
    "meta": {
      "createdAt": "2022-07-05T11:59:45.884Z",
      "updatedAt": "2022-07-05T11:59:45.884Z"
    },
    "relationships": {
      "hostedBy": {
        "data": {
          "id": "1bcaafc3-d4d3-43e1-ab64-89d8518d5951",
          "type": "Device"
        }
      }
    }
  }
}

Commanding a point

To successfully update a point value several conditions need to be fulfilled:

  1. The point must have the following properties writable and either cmd or sp.
  2. The chosen value must be a valid value for the point. If there is an enum the value must either be defined in it or a transform of it (e.g. 0,1,2,3 etc). If there is a minVal and maxVal defined the value must be in the range. Also, note that not all resolutions are applicable, typically integers or decimals of 0.1 or 0.5 are valid.
  3. Note that, manual overrides or automation applications may be running at higher priorities, and these may block the command issues via the API call from taking effect.

As an example, for a point that has the tags writable, sp and unit=degrees_celsius the following will request payload will set the value to 23.2:

{
  "data": {
    "type": "Point",
    "id": "2d55baf8-b5af-4fd1-8af6-187e67f527f9",
    "attributes": {
      "pointValue": {
        "value": "23.2"
      }
    }
  }
}

Release Point

To reset a previously updated point it's possible to release the point by setting the null value in the command request, e.g.

{
  "data": {
    "type": "Point",
    "id": "2d55baf8-b5af-4fd1-8af6-187e67f527f9",
    "attributes": {
      "pointValue": {
        "value": null
      }
    }
  }
}

Usage of APIs is subject to an agreement between customer and Siemens. To the extent nothing specific is agreed, the Siemens terms and conditions agreed in the Siemens subscription manager shall apply.