Developer Portal for Smart Buildings

Free@home local API samples

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

Not that all endpoints require the following HTTP basic auth header in the request:

• Authorization: Basic {BASE64_USERNAME_COLON_PASSWORD}: The generation of the header is documented in rfc7617.

For the examples to work, you need to connect to your System Access Point 2.0 in access point mode. To activate the Access Point mode, press the button on the System Access Point. A blue LED light signals the access point mode.

Alternatively, you can change the url in the following examples to match the IP-address of your local System Access Point.

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

Get the login username

The generated username for a specific user account can be found in the free@home next app on the settings page for the local API (More -> free@home Settings -> Local API).

Query the configuration

With the following command you can fetch a data model.

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/configuration

The response body is a JSON object similar to 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 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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/FFFF40000001.ch0000.idp0000

The response looks like this:

    {
      "00000000-0000-0000-0000-000000000000": {
        "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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/BEED2CD50001.ch0000.idp0000 \
      -d 1

The response body is:

    {
      "00000000-0000-0000-0000-000000000000": {
        "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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/60007F6A06A7.ch0000.idp0000 \
      -d 1

Check current state:

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/60007F6A06A7.ch0000.odp0000

Returns the following, meaning the output is switched off:

    {
      "00000000-0000-0000-0000-000000000000": {
        "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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/BEED2CD50001.ch0000.idp0002 \
      -d 75

Switch off:

    curl -X PUT \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/BEED2CD50001.ch0000.idp0000 \
      -d 0

Check current/last brightness:

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/BEED2CD50001.ch0000.odp0001

Returns the brightness as 75% (approximately):

    {
      "00000000-0000-0000-0000-000000000000":
      {
        "values":["75.1969"]
      }
    }

Check whether the dimming actuator is switched on or off:

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/BEED2CD50001.ch0000.odp0000

    {
      "00000000-0000-0000-0000-000000000000":
      {
        "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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C886B5.ch0003.idp0002
      -d 50

Move the blind up:

    curl -X PUT \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C886B5.ch0003.idp0000 \
      -d 0

Stop moving:

    curl -X PUT \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C886B5.ch0003.idp0001 \
      -d 0

Query for current moving state:

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C886B5.ch0003.odp0000

May return that its moving down:

    {
      "00000000-0000-0000-0000-000000000000": {
        "values":["3"]
      }
    }

Query for current position:

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C886B5.ch0003.odp0001

Returns 0% as position:

    {
      "00000000-0000-0000-0000-000000000000": {
        "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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C878FA.ch0000.idp0016 \
      -d 20.5

Activate the eco mode:

    curl -X PUT \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C878FA.ch0000.idp0011 \
      -d 1

Query target temperature:

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C878FA.ch0000.odp0006

Returns 17.5 °C because of the active ECO mode:

    {
      "00000000-0000-0000-0000-000000000000": {
        "values":["17.5"]
      }
    }

Query measured temperature:

    curl -X GET \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/datapoint/00000000-0000-0000-0000-000000000000/ABB700C878FA.ch0000.odp0010

Returns the temperature measured by the RTC:

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

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

import asyncio
import websockets
from base64 import b64encode

username = ''  # Set this to your username
password = ''  # Set this to you password
sysap_ip = '192.168.2.1' # Set this to the IP address of your Sysap

basic_auth = b64encode((username + ":" + password).encode()).decode("ascii")

async def ws_main():
    headers = {
            "Authorization": f"Basic {basic_auth}",
            }
    async with websockets.connect('ws://' + sysap_ip + '/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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/virtualdevice/00000000-0000-0000-0000-000000000000/abcdefgh0123456789 \
      -d '{"type": "SwitchingActuator", "properties": {"ttl": "180","displayname":"Virtual switch"}}'

You get a return value like this:

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

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

    curl -X PUT \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/virtualdevice/00000000-0000-0000-0000-000000000000/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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/virtualdevice/00000000-0000-0000-0000-000000000000/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 \
      --user USERNAME:PASSWORD \
      https://192.168.2.1/fhapi/v1/api/rest/virtualdevice/00000000-0000-0000-0000-000000000000/abcdefgh0123456789 \
      -d '{"properties": {"ttl": "-1"}}'