Developer Portal for Smart Buildings

Free@home cloud API samples

This page provides a collection of sample requests to the free@home cloud API.

Not that all endpoints require the following custom HTTP headers in the request:

• Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY: Your subscription for the Smart Home API. You can find your subscription key in the products section.
  If you do not yet have a subscription to the Smart Home API, please follow the instructions on https://developer.eu.mybuildings.abb.com to request access.
  Substitute the SUBSCRIPTION_KEYwith your key in the Ocp-Apim-Substitute-Key header.
• Authorization: Bearer OAUTH2_ACCESS_TOKEN: A valid OAuth2 access token for authorization. See [the documentation on OAuth2]({{ relref “oauth2_authentication_flow” }}) for details.
  Substitute the OAUTH2_ACCESS_TOKEN in the Authorization header with your current access token.
  Please note that the access token has only a limited lifetime.

The following examples use the curl command line tool for convenience.

Obtaining an OAuth2 token

All requests on this page require a valid OAuth2 token. In some cases you can use the developer portal for this, either by using the “Try it” button found along with the requests (remember to fill in the “Authorization” headers - the portal will obtain a valid token for you), or by copying to Authorization header/token from the request that the portal outputs.

However some requests - most notably webhooks and websockets - require a valid OAuth2 token with the current User ID: The developer portal uses a different User ID (it does not know your OAuth2 credentials), therefore you must perform an OAuth2 authentication yourself to perform these requests.

Please refer to the OAuth2 sample for an example in a common use-case on how to obtain the token.

Query the configuration

With the following command you can fetch a data model.

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/configuration

The response body is a JSON object similar to this:

{
  "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
    "sysapName": "my little SysAP",
    "devices": {
      "BEED2CD50001": {
        "displayName": "Dimmable lamp",
        "floor": "04",
        "room" : "01",
        "channels": {
          "ch0000": {
            "displayName": "Dimmable lamp",
            "floor": "04",
            "room" : "01",
            "functionID": "0012",
            "inputs": {
              "idp0000": { "pairingID": 1,  "value": "1" },
              "idp0001": { "pairingID": 16, "value": "50" }
            }
            "outputs": {
              "odp0000": { "pairingID": 256, "value": "0" },
              "odp0001": { "pairingID": 272, "value": "0" }
            }
          }
        }
      }
    }
    "floorplan": {
      "floors": {
        "04": {
          "name":"First floor",
          "rooms": {
            "01": {
              "name":"Office"
            },
            "02": {
              "name":"Kitchen"
            }
          }
        }
      }
    }
  }
}

In this shortened example you see that there is a single SysAP sending its data model. That model consists of devices (here only one) that consists of channels that are made of input and output datapoints.

Query a datapoint

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/FFFF40000001.ch0000.idp0000

The response looks like this:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "values": [
         "1"
        ]
      }
    }

The current value for the first input datapoint on channel 0 for device FFFF40000001 is "1".

Set a datapoint

To set a datapoint to the value “1” call:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/BEED2CD50001.ch0000.idp0000 \
      -d 1

The response body is:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "result": "OK"
      }
    }

How to control devices

Switch actuator

To operate an Switch actuator you first need to fetch the configuration and search for a device and channel that has a value of "0007" (Switch actuator, see the reference for a list of all valid function ids) as functionID.
Note that for example the Switch actuator sensor, 2/2gang from ABB has multiple channels and two with the functionID == "0007" because it has two outputs that can be controlled.

In the selected channel you need to check for an input datapoint with the pairingID == 1 (Switch On/Off, see the reference for a list of all valid pairing ids). This input datapoint can be used to send a Switch Off command by setting the value to "0" and the value of "1" sends a Switch On command.

The output datapoint with the pairingID == 256 (Info On/Off) shows the current state of the switch.

Relevant IDs and values

For channels:

For datapoints:

See also the reference for a list of all valid IDs.

Example

Switch output on:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/60007F6A06A7.ch0000.idp0000 \
      -d 1

Check current state:

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/60007F6A06A7.ch0000.odp0000

Returns the following, meaning the output is switched off:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "values":["0"]
      }
    }

Dimming actuator

For a dimming actuator you have to search for a device and channel with the functionID == "0012" (Dimming actuator, see the reference for a list of all valid function ids).

In the selected channel you need to search for an input datapoint with the pairingID == 17 (Absolute control of the set value) to set the brightness. The brightness is given in percent from "0" to "100" as decimal string.

The input datapoint with pairingID == 1 (Switch On/Off, see the reference works like the switch actuator.
Setting this datapoint to "0" switches the dimmer off. Setting it to "1" switches it on and restores the last brightness setting.

When setting a new brightness level it is not necessary to explicitly send a "1" to the Switch On/Off datapoint. But to switch off a "0" should be send to the Switch On/Off datapoint.

Note: A really low brightness level may be too dark to be visible and therefore does not activate the dimming lamp.

The output datapoints with the pairingIDs 272 (Info actual dimming value) and 256 (Info On/Off) use the same data representations like their input counterparts.

Relevant IDs and values

For channels:

For datapoints:

See also the reference for a list of all valid IDs.

Example

Set the brightness to 75%:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/BEED2CD50001.ch0000.idp0002 \
      -d 75

Switch off:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/BEED2CD50001.ch0000.idp0000 \
      -d 0

Check current/last brightness:

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/BEED2CD50001.ch0000.odp0001

Returns the brightness as 75% (approximately):

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1":
      {
        "values":["75.1969"]
      }
    }

Check whether the dimming actuator is switched on or off:

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/BEED2CD50001.ch0000.odp0000

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1":
      {
        "values":["1"]
      }
    }

Blind actuator

For a blind/shutter actuator you need to search for a device with a channel that has a functionID with a value of "0009" (Shutter actuator, see the reference for a list of all valid function ids), "0061" (Blind actuator), "0062" (Attic window actuator) or "0063" (Awning actuator) depending on the device configuration.

On the selected channel search for an input datapoint with pairingID == 35 (Moves the sunblinds into a specified position, see the reference for a list of all valid pairing ids). To this datapoint you send a percent value to control the position of the blind.

The other method is to send command to move the blind up or down and send a stop command when done. The pairingId == 32 (Move sunblind up / down) input datapoint gets the value "0" to move up or "1" to move down. When the blind is in the desired position send "0" to the input datapoint with pairingID == 33 (Stops the sunblinds and to step it up/down) to stop it.

There is an output datapoint with pairingID == 288 (indicate the move up/down and stop state) shows the current movement, see in the table below for possible values. Another output datapoint (289 Indicate the current position of the sunblinds in percentage) represents the current position in percent. But note, that its not necessarly updated during the movement.

Relevant IDs and values

For channels:

For datapoints:

See also the reference for a list of all valid IDs.

Example

Move the blind to 50%:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C886B5.ch0003.idp0002
      -d 50

Move the blind up:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C886B5.ch0003.idp0000 \
      -d 0

Stop moving:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C886B5.ch0003.idp0001 \
      -d 0

Query for current moving state:

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C886B5.ch0003.odp0000

May return that its moving down:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "values":["3"]
      }
    }

Query for current position:

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C886B5.ch0003.odp0001

Returns 0% as position:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "values":["0"]
      }
    }

Thermostat

Depending on the device configuration (room temperature controller with or without fan) you have to search for a device with channel that has a functionID of "000a" (Room temperature controller master with fan, see the reference for a list of all valid function ids) or "0023" (Room temperature controller master without fan).

On this channel are many input datapoints, search for pairingID == 320 (Absolute set point temperature input, see the reference for a list of all valid pairing ids). There you can write the new temperature in degree Celsius with a precession of 0.5 degree.

There are other input datapoints to switch the controller on/off (66 Request for switching controller on or off) and activating the Eco mode (58 Switches eco mode on or off). Both use "0" to switch off and "1" to switch on their mode.

You can query for the modes by reading the values from the output datapoints with values 56 and 54. The first is a normal boolean values ("0" or "1"), the other is an integer bitwise-ORed with the mask values given below.

You can read the current target temperature with output datapoint for pairingID == 51. Also interesting is the temperature measured by the thermostat, that you can read from the output datapoint with pairingID == 304.

Relevant IDs and values

For channels:

For datapoints:

See also the reference for a list of all valid IDs.

Example

Set the temperature to 20.5°C:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C878FA.ch0000.idp0016 \
      -d 20.5

Activate the eco mode:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C878FA.ch0000.idp0011 \
      -d 1

Query target temperature:

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C878FA.ch0000.odp0006

Returns 17.5 °C because of the active ECO mode:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "values":["17.5"]
      }
    }

Query measured temperature:

    curl -X GET \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/ABB700C878FA.ch0000.odp0010

Returns the temperature measured by the RTC:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "values":["25.98"]
      }
    }

Open a websocket connection

As discussed in the websocket documentation, in order to open a websocket, you require a websocket implementation that:

• Supports providing headers to the connection request.
• Supports HTTP redirect responses.

Here we provide a short example using python and the websockets library (use pip install websockets to install it):

import asyncio
import websockets

oauth2_token = ''  # Set this to your OAUTH2_ACCESS_TOKEN
subscription_key = ''  # Set this to you SUBSCRIPTION_KEY

async def ws_main():
    headers = {
            "Authorization": f"Bearer {oauth2_token}",
            "Ocp-Apim-Subscription-Key": subscription_key
            }
    async with websockets.connect('wss://apim.eu.mybuildings.abb.com/fhapi/v1/api/ws', extra_headers=headers) as ws:
        print("Websocket has been opened.")
        while True:
            data = await ws.recv()
            print("Received event:")
            print(data)  # You can use json.loads(data) to parse the json object

asyncio.get_event_loop().run_until_complete(ws_main())

How to register a virtual device

Registering for the first time with a friendly name and a TTL value of 3 minutes:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
      -d '{"type": "SwitchingActuator", "properties": {"ttl": "180","displayname":"Virtual switch"}}'

You get a return value like this:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "devices": {
          "abcdefgh0123456789": {
            "serial":"60007F6A06A7"
          }
        }
      }
    }

This means the virtual device with the Native ID of abcdefgh0123456789 will use the serial 60007F6A06A7. Instead of processing the result of this API endpoint you will find the serial in the output of the configuration endpoint and you get notified about the new virtual device via websockets or webhooks.

Later it is enough to send a new lifesign with only a TTL value:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
      -d '{"properties": {"ttl": "60"}}'

To mark a virtual device as unresponsive (or ready for removal), reregister the device with a TTL value of zero:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
      -d '{"properties": {"ttl": "0"}}'

To avoid re-registering the virtual device at regular intervals, the API user can specify a TTL value of -1:

    curl -X PUT \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
      -d '{"properties": {"ttl": "-1"}}'