How to get started on the ABB Developer Portal


How to create an account for the ABB Developer Portal

To create an account you simply have to click the "Sign up" button on the start page of the developer portal. Additionally you are also able to use your already existing myBuildings Portal account to log in. To create an account just browse here.


Why is a myBuildings Portal account required to log in to the ABB Developer Portal?

The myBuildings portal is the central point for our customers to register and manage all Internet-enabled devices for Smart Home and Smart Building. In order to give you the most user-friendly handling possible, we offer you login on both portals with only one pair of user credentials.


How to activate the myBuildings Portal account for the ABB Developer Portal

To activate your myBuildings Portal account for the ABB Developer Portal please simply use the request button on the start page. After successful review of our API Team you get an approval as developer. Afterwards you are able to log into the portal with your credentials and enter all required areas..


How to get access to different APIs on the developer portal

To get access to different APIs you simply have to click the Product area and subscribe to the APIs you want to start development with.



How to use the free@home cloud API to access and control your smart home


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",
            "type": "BEED0064",
            "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.


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 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 his different outputs in different rooms. The floor and room attributes may be missing then the user has not set a location in the free@home configuration.

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.

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 other possible values, see the reference documentation for a complete list:

functionID name
0000 Switch sensor
0001 Dimming sensor
0003 Blind sensor
0007 Switch actuator
0009 Shutter actuator
000a Room temperature controller master with fan
000b Room temperature controller slave
0012 Dimming actuator
0023 Room temperature controller master without fan
0025 LED Brightness sensor
0061 Blind actuator
0062 Attic window actuator
0063 Awning actuator
4000 Light group
4001 Blind group
4a00 Timer program switch actuator

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.

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

pairingID in/out name value
1 in Switch On/Off 0 - Off
1 - On
17 in Absolute control of the set value percent from 0 to 100
32 in Move sunblind up / down 0 - up
1 - down
33 in Stops the sunblind and to step it up/down 0
35 in Moves the sunblinds into a specified position position from 0 to 100 percent
51 out Defines the displayed set point temperature of the system temperature in °C
54 out states: on/off; heating/cooling; eco/comfort; frost/not frost bitmask:
0x01 - comfort mode
0x02 - standby
0x04 - eco mode
0x08 - building protect
0x10 - dew alarm
0x20 - heat (set) / cool (unset)
0x40 - no heating/cooling (set)
0x80 - frost alarm
56 out Switches controller on or off. Off means protection mode 0 - off (Protection mode)
1 - on (Comfort mode or Eco mode)
58 in Switches eco mode on or off 0 - off
1 - on
66 in Request for switching controller on or off. Off means protection mode 0 - off (Protection mode)
1 - on (Comfort mode or Eco mode)
256 out Info On/Off 0 - Off
1 - On
272 out Info Actual dimming value brightness from 0 to 100 percent
288 out indicate the move up/down and stop state 0 - not moving
2 - moves up
3 - moves down
289 out Indicate the current position of the sunblinds in percentage position from 0 to 100 percent
320 in Absolute set point temperature input for timer temperature in °C

See the reference for a complete list.


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.

After connecting to the websocket all events in the free@home smart home system will be send on the websocket as JSON objects.

A event looks like this:

{
  "1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1": {
    "configDirty":"false",
    "datapoints":{
      "ABB70000098B/ch0000/odp0000":"1",
      "ABB70000098B/ch0006/idp0000":"1"
    },
    "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.


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. 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 will be default to 180 seconds. To disable TTL expiration by the SysAP you can specify a TTL value of -1. 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 request object 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 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:

Device Type
BinarySensor
WindowSensor
CeilingFanActuator
DimActuator
ShutterActuator
SwitchingActuator
RTC
CODetector
FireDetector
Weather-BrightnessSensor
Weather-RainSensor
Weather-TemperatureSensor
Weather-WindSensor
WeatherStation

See below for an example.


Examples

Note that all endpoints need a valid OAuth2 access token for authorization. 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.


Query the configuration

With the following command you can fetch a data model.

curl -X GET \
  https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/configuration \
  -H 'authorization: Bearer OAUTH2_ACCESS_TOKEN'

Your response would be JSON like the example given above.


Query a datapoint

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

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 \
  https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/BEED2CD50001.ch0000.idp0000 \
  -H 'authorization: Bearer OAUTH2_ACCESS_TOKEN' \
  -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) 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). 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:

functionID name
0007 Switch actuator

For datapoints:

pairingID in/out name value
1 in Switch On/Off 0 - Off
1 - On
256 out Info On/Off see above

Example

Switch output on:

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

Check current state:

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

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).

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

functionID name
0012 Dimming actuator

For datapoints:

pairingID in/out name value
1 in Switch On/Off 0 - Off
1 - On
17 in Absolute control of the set value brightness from 0 to 100 percent
256 out Info On/Off 0 - Off
1 - On
272 out Info Actual dimming value brightness from 0 to 100 percent

Example

Set the brightness to 75%:

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

Switch off:

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

Check current/last brightness:

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

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 \
   https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/BEED2CD50001.ch0000.odp0000 \
  -H 'authorization: Bearer OAUTH2_ACCESS_TOKEN' \

{
  "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), "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). 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:

functionID name
0009 Shutter actuator
0061 Blind actuator
0062 Attic window actuator
0063 Awning actuator

For datapoints:

pairingID in/out name value
32 in Move sunblind up / down 0 - up
1 - down
33 in Stops the sunblind and to step it up/down
35 in Moves the sunblinds into a specified position position from 0 to 100 percent
288 out indicate the move up/down and stop state 0 - not moving
2 - moves up
3 - moves down
289 out Indicate the current position of the sunblinds in percentage position from 0 to 100 percent

Example

Move the blind to 50%:

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

Move the blind up:

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

Stop moving:

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

Query for current moving state:

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

May return that its moving down:

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

Query for current position:

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

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) or "0023" (Room temperature controller master without fan).

On this channel are many input datapoints, search for pairingID == 320 (Absolute set point temperature input). 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:

functionID name
000a Room temperature controller master with fan
000b Room temperature controller slave
0023 Room temperature controller master without fan

For datapoints:

pairingID in/out name value
51 out Defines the displayed set point temperature of the system temperature in °C
54 out states: on/off; heating/cooling; eco/comfort; frost/not frost bitmask:
0x01 - comfort mode
0x02 - standby
0x04 - eco mode
0x08 - building protect
0x10 - dew alarm
0x20 - heat (set) / cool (unset)
0x40 - no heating/cooling (set)
0x80 - frost alarm
56 out Switches controller on or off. Off means protection mode 0 - off (Protection mode)
1 - on (Comfort mode or Eco mode)
58 in Switches eco mode on or off 0 - off
1 - on
66 in Request for switching controller on or off. Off means protection mode 0 - off (Protection mode)
1 - on (Comfort mode or Eco mode)
304 out Indicates the actual measured temperature temperature in °C
320 in Absolute set point temperature input for timer temperature in °C

Example

Set the temperature to 20.5°C:

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

Activate the eco mode:

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

Query target temperature:

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

Returns 17.5 °C because of the active ECO mode:

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

Query measured temperature:

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

Returns the temperature measured by the RTC:

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


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 \
   https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
  -H 'authorization: Bearer OAUTH2_ACCESS_TOKEN' \
  -d '{"type": "SwitchingActuator", "properties": {"ttl": "180","displayname":"Virtual switch"}}'

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

curl -X PUT \
   https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
  -H 'authorization: Bearer OAUTH2_ACCESS_TOKEN' \
  -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 \
   https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
  -H 'authorization: Bearer OAUTH2_ACCESS_TOKEN' \
  -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 \
   https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/virtualdevice/1f07d9e0-a9fd-4696-8b2d-1bf2ccabd3a1/abcdefgh0123456789 \
  -H 'authorization: Bearer OAUTH2_ACCESS_TOKEN' \
  -d '{"properties": {"ttl": "-1"}}'


How to get started with the KNX i-bus® IoT Dashboard API


How to get the rights to use the local REST API on a KNX i-bus® IoT Dashboard Server

Create a user account via the IoT Dashboard Tool who has the right to access the API and upload the project to the device.


How to authorize to the local REST API on a KNX i-bus® IoT Dashboard Server

You can access the API of a physical device in the same network via different tools, e.g. via Postman. In the following example we are showing the access using the Swagger on the box:


1. Open http://ipadress:port/swagger/ in your webbrowser to see the Swagger Interface


2. Open the call "api/user/login/" from the list and press "try out". Edit user/password according to your IoT Dashboard Account


3. Then click the execute button


4. Copy the token received as a response (only the value as selected below)


5. Then unblock API via the "Authorize" button in the right upper corner of the Swagger window.


6. Please type “Bearer” and paste the token after one space and the press "authorize".


Now you are authorized to the device and can start using all the other API calls shown at Swagger.