Developer Portal for Smart Buildings

Free@home local API concepts

free@home local API model

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

{
  "00000000-0000-0000-0000-000000000000": {
    "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 local API: The configuration of scenes is handled completely by the SysAP. The intended way to activate a scene using the free@home local 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 local 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:

When these requirements are ensured, simply open a websocket with the correct authentication headers. on the websocket url (using the usual websocket schema wss:// instead of https://):

    wss://{IP-Address of the Sysap}/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.

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:

    {
      "00000000-0000-0000-0000-000000000000": {
        "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.

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.

    {
      "00000000-0000-0000-0000-000000000000" : {
        "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.