Quick Start¶

Getting started with using Building Operations APIs involves the following steps:

1. Create an account and a machine user.
2. Create a JSON Web Token (JWT) by using the machine user credentials.
3. Make API requests using the JWT.

Create an account and a machine user¶

The Getting Started page documents the required steps to get a hold of the clientId, clientSecret and partitionId.

Create a token¶

Use the values described in the Authorization- section to construct the Create Token request.

Example request¶

export CLIENT_ID=<YOUR_CLIENT_ID>
export CLIENT_SECRET=<YOUR_CLIENT_SECRET>

curl https://siemens-bt-015.eu.auth0.com/oauth/token \
  -H 'content-type: application/json' \
  -d "{
            \"client_id\":\"$CLIENT_ID\",
            \"client_secret\":\"$CLIENT_SECRET\",
            \"audience\":\"https://horizon.siemens.com\",
            \"grant_type\":\"client_credentials\"
      }"

To run this example yourself, set the CLIENT_ID and CLIENT_SECRET first.

Example response¶

{
  "access_token": "eyJ0eXAiOiUSJ9.eyJpc3MiOiJdGlhbHMifQ.MJpcxLfyOt",
  "token_type": "Bearer",
  "expires_in": 86400
}

The token, or JWT (JSON Web Token), is the value of the access_token-property in the response. You can now use it by passing it in the Authorization-header of any subsequent API requests. The expires_in-property represents the number of seconds your token is valid, usually, the value corresponds to 24 hours. When this time has elapsed you will need to create a new token.

Now you have all you need to start using the API. As a last step of preparation set the token and partitionId as environmental variables.

export PARTITION=<YOUR_PARTITION_ID>
export TOKEN=<YOUR_TOKEN>

Make API requests¶

This guide will take you through the steps you need to perform to read values, e.g. temperature measurements, from a Point. We will assume you don't yet know the id of the Point, meaning that before you can get the temperature data for the Point you must discover the Point by listing Locations, Devices and Points.

List Locations¶

The first step to perform is to list the buildings in your partition. This you can do by performing the List Locations operation. Below we specify the include -parameter to include the address of each building in the included section of the response.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/locations?filter[type]=Building&include=hasPostalAddress"

The response contains all buildings in your partition. If you have a large number of buildings you may need to retrieve multiple pages, see Pagination.

Select the id property of one of the locations in the response and set it in an environmental variable. E.g. if the id is 8db4216d-61c5-4e79-8558-164aa179bfe9 then set it using the following command:

    export LOCATION=8db4216d-61c5-4e79-8558-164aa179bfe9

List Devices¶

The next step is to list the devices available in your building. This is achieved by using the List Devices operation. In this example also the optional include -parameter is specified, it's useful to retrieve the name and connectivity status of the devices.

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/devices?filter[hasLocation.data.id]=$LOCATION&include=hasFeatures.DeviceInfo,hasFeatures.Connectivity"

The response contains a list of all devices with their location defined as the building you specified. To also get the devices that are potentially behind the first set of devices we must use the List devices behind a gateway operation.

This must be done for each device retrieved above. Imagine we have retrieved one device with id 7d4293a7-5c61-47e2-b010-9ba913c016e4, then we can get the devices behind it by performing the following operation:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/devices/7d4293a7-5c61-47e2-b010-9ba913c016e4/devices&include=hasFeatures.DeviceInfo,hasFeatures.Connectivity"

Once you have performed the second request for each of the devices in the first set you have all the devices in your building.

Any of these devices may host points. That means that to be certain to retrieve all points in your building you must perform the List Points operation, explained in the next section, for each of the devices. If your use case is well defined and you have a well-known hierarchy in your setup you can of course use that knowledge, e.g. by using the modelName or DeviceInfo to only query some devices for points.

List Points for Device¶

The List Points operation retrieve point for a certain device. By specifying the optional field-parameter, also the latest known value will be present in the response. Assuming the DEVICE environmental variable contains the id of the device you are interested in you can perform the following request:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/devices/$DEVICE/points?field[Point]=pointValue"

The response contains a list of all points for the device. Select the id property and store in the POINT-variable. E.g.

export POINT=a850ec9a-daf6-4630-9c22-af680e82b3a4

List Values¶

To get the time series data or PointValues you can use the List Values operation. To use this operation you will need to specify the query parameter filter[timestamp][from] with a valid date-time in the RFC3339 (UTC) format. The recommended value for trying is to specify the current time minus one hour. E.g. 2021-10-25T23:00:00.000Z

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/points/$POINT/values?filter[timestamp][from]=2021-10-25T23:00:00.000Z"

In the response, you will find the latest values, e.g. temperature or air quality readings for the point.

Commanding Points¶

You can change the value of a point by using the Update Point operation. The following example will set the value of the point to 2.

<!-- markdownlint-disable MD013 -->
curl -X PATCH  "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/points/$POINT" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Bearer $TOKEN" \
-d "{
  \"data\": {
    \"type\": \"Point\",
    \"id\": \"$POINT\",
    \"attributes\": {
      \"pointValue\": {
        \"value\": \"2\"
      }
    }
  }
}"  

List Events¶

To get current and past events and alarms for a device, the List Events operation can be used:

curl -H "Authorization: Bearer $TOKEN" \
    "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/devices/$DEVICE/events"

Create Device¶

To create a new device, the Create Device operation can be used:

curl -X 'POST' \
  "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/devices" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
  \"data\": {
    \"type\": \"Device\",
    \"attributes\": {
      \"modelName\": \"string\",
      \"serialNumber\": \"string\"
    }
  }
}"

In the response, you will find the device is created for the given modelName & serialNumber.

Add point values¶

To add point values, the Post values operation can be used.

Push 1 to 100 values for given point in a batch.

Only one pointValue per millisecond will be stored. pointValues are dropped if there are timestamp conflicts, i.e. if a pointValue with the same timestamp already exists. Example with following pointValues:

• 2022-07-11T11:11:30.333
• 2022-07-11T11:11:30.222
• 2022-07-11T11:11:30.333
• 2022-07-11T11:11:30.444

The first is accepted (it's the first for time "30.333"). The second is also accepted. The third is dropped because it's the same timestamp as the first. The fourth is accepted again. The indices of dropped pointValues are listed in the response (0-based), in this example there is one conflict with index "2".

If there is no conflict status 204 is returned instead of 202.

Note: Use query parameter overwrite=true to force overwriting of conflicting values.

curl -X 'POST' \
<!-- markdownlint-disable MD013 -->
  "https://api.bpcloud.siemens.com/operations/partitions/$PARTITION/points/$POINTID/values" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d "{
  \"data\": [
    {
      \"type\": \"PointValue\",
      \"attributes\": {
        \"timestamp\": \"2000-05-11T10:32:54.964Z\",
        \"value\": \"12.66\"
      }
    }
  ]
}"

In the response, you will find the values added for the pointId.