Developer Portal for Smart Buildings

Free@home cloud API concepts

free@home cloud API model

The ABB-free@home smart home systems connect to the ABB-cloud and send all state changes to the cloud. The free@home API provides endpoints to request the current configuration or data model. Additional endpoints allow to get and set datapoints which represent the current state of the devices in your smart home.

With a WebSocket connection or using a WebHook the application can be informed about changes to the model or datapoints without polling.

Then there is a endpoint to register virtual devices on the ABB-free@home smart home system that represent 3rd-party hardware.

Data model

The data model consists of the different ABB-free@home smart home systems (also called SysAP) that are registered for the same ABB-myBuildings Account. The SysAPs are identified by their UUID or Site ID. Most endpoints return a JSON-Object where the SysAP-UUID is the key for the response object from this SysAP.

A simplified response from the configuration endpoint looks like 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:

• There is a single SysAP sending its data model.
• That model consists of devices (here only one). A device in the data model matches a real hardware device that is connected to the SysAP either via cable or via radio (with the special-case of virtual devices for advanced use-cases, as discussed further below), for example a light switch/actuator device.
• The device consists of channels. A channel represents some kind of function of the device, such as “switch” and “light”, that can be controlled separately. Some devices have multiple channels which may be mutually exclusive, depending on the device.
  See the section on Devices and Channels for details.
• Each channel is made of input and output datapoints. A datapoint represents some kind of data that can be sent to the device (input datapoint), such as “switch on/off”, or that can be read from the device (output datapoint), such as “light is currently on/off”.
  See the section on Input and output datapoints for details.

Devices and Channels

The channels in the devices are used to establish specific applications like switching and dimming etc. A device with multiple functions has multiple channels.
Both devices and channels have attributes like displayName, floor and room that often, but not always have the same values. In most cases you should use the values from the channel. For example a 4-channel switching actuator may have its different outputs in different rooms.

Note that the floor and room attributes may be missing when the user has not set a location in the free@home configuration (device/channel is not “placed”).

Devices are identified by their ID or serial, in the example above: BEED2CD50001. Channel IDs are numbered with a prefix of ch. Both IDs are used as keys in the hashmaps under devices and channels. Note that the Channel ID is actually a hex number, not a decimal number, i.e. a value of ch000a is valid.

The meaning of a channel is given by the attribute functionID that is given as a 4-digit hexadecimal number.

In the example the device BEED2CD50001 has only one channel (ch0000) with the functionID of "0012" which represents a Dimming actuator. Here are some commonly used possibly values:

Please refer to the reference documentation for a complete list.

Input and output datapoints

The datapoints represent the internal state of the devices. Input and output is meant from the perspective of the device: Setting new values to an input datapoint will change the state and will be represented by changed output datapoint values. Input datapoints are used to control the device and output datapoints are the feedback datapoints that show the current condition in which the device is. The input and output datapoints can be distinguished by their prefix idp and odp. Please note that the number after idp and odp in the datapoint ID is a hexadecimal number, i.e. a value of ipd000a is valid.

You can use the pairingID to determine the semantic for a datapoint. This pairingID also define values or value types you can write to a datapoint. For reading and writing datapoints the value is always encoded as string.

In the example above the first input datapoint (idp0000) has a pairingID of 1, which specifies a On/Off switch. Here are some commonly used values for pairing IDs:

Please refer to the reference documentation for a complete list.

Scenes

A SysAP supports configuration of scenes as a way to set multiple datapoints to a configured value by activating a single switch. Common use-cases are “all lights off”, or e.g. “dim living room lights to 50%” etc.

A scene in the datamodel of the SysAP is represented as a device with a channel with function ID “4800” (0x4800).

However while these special scene devices may be included in the datamodel, they can currently not be controlled directly by the free@home cloud API: The configuration of scenes is handled completely by the SysAP. The intended way to activate a scene using the free@home cloud API is to pair the scene with a switch in the SysAP configuration and then activate the switch.

Note that using a virtual device instead of a hardware device is possible, however setting up a virtual device is an advanced concept and may be overkill for this use-case.

Websocket

The free@home cloud API provides a websocket endpoint to enable the API user to get immediately informed about changes to datapoints or the configuration without polling.

In order to open a websocket, you require a websocket implementation that:

• Supports providing headers to the connection request.
• Supports HTTP redirect responses (NOTE: Take special care of this. Not all implementations support this out of the box, sometime is must be enabled in the configuration, sometimes it is not supported at all).

Note in particular that opening from a browser in javascript is therefore not possible with default javascript websocket implementations.

When these requirements are ensured, simply open a websocket with the correct authentication headers (see the samples for details), including a valid OAuth2 token on the websocket url (using the usual websocket schema wss:// instead of https://):

    wss://apim.eu.mybuildings.abb.com/fhapi/v1/api/ws

After this, you can receive websocket events on the opened websocket connection. Note that sending commands over the websocket is not possible, simply use the normal REST API instead.

See the samples for an example.

Note that a full OAuth2 token for your User ID and User Secret is required for websockets. Opening a websocket with an OAuth2 token as generated from the developer portal (either by using the “Try it” button or by copying the generated token from the headers) will not work, as the portal does not possess your credentials.

HTTP redirect

When opening a websocket on wss://apim.eu.mybuildings.abb.com/fhapi/v1/api/ws, the free@home cloud will respond with a status code 301, indicating a HTTP redirect. The websocket implementation is expected to follow this redirect, i.e. repeat the request (including the headers) on the URL provided in the Location header of the response.

You should ensure that your websocket implementation supports HTTP redirect, as not all implementations do so. If needed, check if the websocket implementation requires to provide an additional parameter of configuration in order to activate redirects.

If your implementation does not support redirects, you can instead use the following approach:

1. Make a HTTP GET request on the websocket URL (using https:// instead of wss://). Make sure Redirects are disabled. You can ignore the response body. (HTTP HEAD will not work)
2. Obtain the Redirect location from the response (the value Location: header). The location should start with wss://.
3. Open a websocket on that url.

The following call will print the redirect location (without newline and without response body):

    curl \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      -s -o /dev/null \
      -w '%{redirect_url}' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/api/ws

Websocket events

After connecting to the websocket, all events in the free@home smart home system will be sent on the websocket as JSON objects. Each websocket frame will contain one JSON object.

An event looks like this:

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
        "configDirty":"false",
        "datapoints":{
          "ABB70000098B/ch0000/odp0000":"1",
          "ABB70000098B/ch0006/idp0000":"1"
        },
        "scenesTriggered": {},
        "devices":{},
        "devicesAdded":[],
        "devicesRemoved":[],
        "timestamp":"2019-09-05T12:54:14.992Z"
      }
    }

In this event two datapoints were changed and their new values are notified. Changing attributes of devices and/or adding/removing devices will be notified in the devices, devicesAdded and devicesRemoved attributes. The latter two attributes only contain the device serials. But the devices attribute contains the whole configuration for the new/modified device like in JSON returned by the configuration endpoint.

Websockets will always send all events from the SysAP. The whitelist for webhooks is not applied. Depending on the devices that are connected to the SysAP(s), this may be a lot of data, consider using webhooks instead.

Webhooks

Webhooks are a way to receive events from a SysAP via the cloud. A webhook is simply a web page on your server that the free@home cloud will call when the SysAP sends an event. On receival of that event, you can then perform custom actions. This can be seen as a “callback” mechanism.

In order to use webhooks in the free@home cloud API, you have to

1. Have a webhook redirect URL available that the free@home cloud can reach.
   For example a simple PHP page would suffice.
2. Register this URL with the free@home cloud.
   Please note: There is no self-service right now to use webhooks for the free@home API. Please contact us at DE-SmarterHomeDeveloper@abb.com and send us your webhook redirect URL.
3. Subscribe to events using the REST API. This triggers the free@home cloud to call the webhook URL with the events.
4. Whitelist the datapoints that you want to receive. The free@home cloud will send datapoint updates for whitelisted events only. The whitelist is empty by default.

Subscribing to webhook events

The following call can be used to subscribe the webhook for a specific user:

    curl -X POST \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \
      -H 'Content-Type: application/json' \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/events/subscription \
      -d '{}'

On success, this endpoint will respond with a HTTP 200 (success) response and no HTTP body. This means that the webhook has been activated.

In advanced use-cases, if the webhook itself (not the free@home cloud API calls, but rather the webhook implementation) uses OAuth2 as well, the /events/subscription call may contain an authCode parameter:

      -d '{ "authCode": "xxxxxxx-User-Scoped-Secret-xxxxxxx" }'

This authCode parameter can be used for that authentication. This is however not required and the parameter is not used by the free@home cloud itself.

NOTE: You also must set a whitelist, otherwise no datapoint updates will be sent by the free@home cloud.

Whitelisting datapoints for webhook events

The free@home system access point manages a lot of datapoint updates, especially when many devices are connected. For example when dimming single a dimmable light, many updates will be sent (at least one per dimming step). However most systems don’t care about most updates and sending all of them to the webhook would be a huge waste of bandwidth and performance.

Therefore, in order to receive datapoint updates, you must install a whitelist first. Only datapoint updates for datapoints that are in the whitelist are ever sent.

An HTTP PUT call to events/whitelist sets a filter which determines which information is of interest. Setting an empty whitelist causes the delivery of no updates.

The call takes a JSON object as request body:

{
    "<sysap-uuid>/<dpSerial1>": {
        "custom data": "needed for recognizing the type of the datapoint",
        "some more data": "not interpreted by free@home cloud"
    },
    "<sysap-uuid>/<dpSerial2>": {
        "custom data": "needed for recognizing the type of the datapoint"
    }
}

For example:

    curl -X PUT \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/events/whitelist \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN'
      -H 'Content-Type: application/json' \
      -d '{ "86f10d2c-ea8c-11e9-920a-68f728dbd933/FFFFFFFFFFFF/chFFFF/odpFFFF": { "mydeviceid": "afa55e08-ea8c-11e9-86c2-68f728dbd933", "type": "toaster" } }'

Each entry of the whitelist is a key/value pair. The key is a datapoint serial, the value is a JSON object. Note that any JSON object is valid as value, including an empty object “{}”.

The datapoint serial uses the format <SysAP UUID>/<Device ID>/<Channel ID>/<Datapoint ID>. All values can be obtained from a /api/rest/configuration call. Note that the <Channel ID> always starts with ch and the <Datapoint ID> always starts with odp (input datapoints make little sense in webhook events).

See also the API documentation on this call.

Custom data in whitelist values

The JSON object in in each key/value pair of the whitelist may contain your own custom data that helps you to identify the meaning of this datapoint. If your webhook implementation does not need additional data, simply use an empty object (“{}”). In the example above, the whitelist indicates that the device FFFFFFFFFFFF refers to a “toaster” with your (custom) deviceid afa55e08-ea8c-11e9-86c2-68f728dbd933.

The whitelist is sent along with all webhook events that are sent by the free@home cloud, therefore these custom JSON objects may help the webhook to process the data.

Webhook events

A typical webhook call to your host cloud.example.com is an HTTP POST call with the following POST body:

{
    "updates": {
        "2144f07d-1db5-42bb-adec-6da0211b1666": {
            "datapoints": {
                "FFFFFFFFFFFF/chFFFF/odpFFFF": "0"
            },
            "timestamp": "2019-08-01T12:07:50.465Z"
        }
    },
    "whitelist": {
        "2144f07d-1db5-42bb-adec-6da0211b1666/FFFFFFFFFFFF/chFFFF/odpFFFF": {
            "mydeviceid": "afa55e08-ea8c-11e9-86c2-68f728dbd933",
            "type": "toaster"
        }
    }
}

In this example you can see

• The updated datapoints (FFFFFFFFFFFF/chFFFF/odpFFFF) for every SysAP (2144f07d-1db5-42bb-adec-6da0211b1666) with the new values.
• The whitelist that was set by your /events/whitelist request.

Note that the free@home cloud sends updates for the datapoints that are included in the whitelist only. The whitelist is included in the webhook calls for your convenience: If you added additional data to a datapoint, you can use it here to obtain information for this event. In this example, the custom JSON object that was set for the datapoint

{
    "mydeviceid": "afa55e08-ea8c-11e9-86c2-68f728dbd933",
    "type": "toaster"
}

The whitelist that is included in the events lets you determine that the device is a toaster and that your custom deviceid is afa55e08-ea8c-11e9-86c2-68f728dbd933. These values are merely meant as an example and don’t make actual sense: You can use whatever data is convenient to you when receiving the webhook call.

Deleting a webhook subscription

With this call, the webhook subscription is deleted:

    curl -X DELETE \
      https://apim.eu.mybuildings.abb.com/fhapi/v1/events/subscription \
      -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \
      -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN'

After this, you should not longer receive any calls to the webhook. You can activate the subscription again at any time.

Virtual devices

There is a REST endpoint to register a virtual device in the free@home smart home automation system. The API user can use this to create a proxy device in free@home for a hardware device operated outside of the free@home smart home system. For example you can register a garage door opener in your home automation system as virtual device to control and monitor it from there.

To register a virtual device to a sysap you need the SysAP ID to identify the SysAP where you will register the virtual device. As second parameter a Native ID to uniquely identify the device in this and subsequent calls. Additional parameters are given as JSON in the request body. This object may look like:

    {
        "type": "SwitchingActuator",
        "properties": {
            "ttl": "180",
            "displayname": "Virtual switch"
        }
    }

In this request object you can give a type to specify the device type of the new virtual device. Check the table below for possible device types.

The value of displayname is the friendly name shown to the user.

The value of ttl is a decimal string that specifies the Time to live in seconds. Valid values are from 180 to 86400 seconds, i.e. 3 min to 24 hours. After this time you need to re-register the virtual device. If you fail to re-register the virtual device before the TTL expires the device is marked as unresponsive in the free@home smart home automation system. This is retracted when a new lifesign is send by calling the endpoint to register a virtual device again. If you omit the ttl parameter it defaults to 180 seconds. A TTL value of 0 immediately marks the device as unresponsive.

As the return value the endpoint will return the serial used by the free@home automation system to identify the virtual device. Note that this serial ID is different from the native ID. You will find the nativeId in the data model as attribute on virtual devices. Another attribute to identify virtual device in the data model is the interface attribute whose value have a prefix of "vdev:".

After the registration you will be informed via the WebSocket of the new device and it will be returned by the configuration endpoint. The available channels and input and output datapoints will depend on the specified device type. Please remember that input and output datapoints are named from the perspective of the device. This means that the API user has to write to the output datapoints that are the feedback datapoints to show the current state of the virtual device. The input datapoints for a virtual device are used to control it and change its current state. The owner of the virtual device has to monitor the input datapoints for its virtual devices to react to these changes and use it to control the hardware device.

Life-cycle of a virtual device

The virtual device is created via the first call to the api/rest/virtualdevice endpoint. The JSON object in the request body is required to contain the type value and can contain the other properties like ttl and displayname.

Then before the TTL from the previous call is expired the api user needs to call the endpoint again. But in this case you can omit all parameters with the exception of the two path parameters (SysAP ID and Native ID). The TTL value will be the default (3 minutes) in this case.

To mark a virtual device as unresponsive in the free@home automation system re-register it with a TTL value of 0. An unresponsive device can be removed by the enduser.

Device type

The type parameter in the request object can be one of the following values:

See here for an example.

Scene support for virtual devices

As all devices in ABB-free@home smart home system the virtual devices created by calling the virtualdevice endpoint can be configured and used with scenes. This means the enduser is able to trigger a scene (using the frontend, a switch, …) and the SysAP will inform all configured devices for the scene to switch to a specified state.

For virtual devices the API user can implement this feature using the events received via WebSocket or WebHook. They contain a scenesTriggered subobject for each SysAP. In this object you find the information you need to activate the scene on your virtual device. It is send once per scene activation and only for virtual devices created by your API user. The contents of these objects are a subset of the devices objects returned from the configuration endpoint. It contains only the output datapoints for the channels of the virtual device. For each output datapoint the value and pairingID is transmitted.

The following JSON is an example for an event with a non empty scenesTriggered object.

    {
      "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1" : {
        "configDirty": "false",
        "datapoints" : {
          "BEED2CD50001/ch0000/idp0004" : "1",
          "ABB70000098B/ch0006/idp0005" : "1"
        },
        "scenesTriggered" : {
          "BEED2CD50001" : {
            "channels" : {
              "ch0000" : {
                "outputs" : {
                  "odp0000" : {"value" : "1",   "pairingID" : 256},
                  "odp0001" : {"value" : "100", "pairingID" : 272}
                }
              }
            }
          },
          "ABB70000098B" : {
            "channels" : {
              "ch0006" : {
                "outputs" : {
                  "odp0001" : {"pairingID" : 272, "value" : "100"}
                }
              }
            }
          }
        },
        "scenesTriggered": {},
        "devices":{},
        "devicesAdded":[],
        "devicesRemoved":[],
        "timestamp":"2019-09-05T13:54:14.992Z"
      }
    }

Note: In this example you can also see the input datapoints set to the scene number (here: 1). These datapoints have a pairingID of 4 (Scene Control) and are used internally.

The main difference of triggered scenes and normal datapoint changes is that datapoint changes for your device always affect only input datapoints. But scenes are configured in the SysAP by saving the output datapoints for the devices. When the scene is activated the device has to restore the state to have the same output datapoint values as the scenesTriggered object specifies.