In this tutorial we want to control and read the first free@home device. For this, the status of a room temperature controller is to be requested and the operating mode switched between OFF and Eco.

Preconditions:

* You have succesfully completed Tutorial 1.

* Deactivate "SSL certificate validation" in the settings of Postman

1. Before we send the first requests, we have to add the personal subscription key in the header for each call inside Postman. You can find this in the Developer Portal in your profile:

2. After successfully completing Tutorial 1, we can now focus on querying and controlling the free @ home facility. First we ask the API endpoint "Request the configuration of your SysAP" -> https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/configuration

Since we receive an answer when the command is executed, but this does not show any building structure and equipment, an intermediate step is necessary:

2.1 As an intermediate step, we must once accept the request for rights in the local web interface of the System Access Point, so that we get access to the system. Switch to the local web interface via the IP address of the SysAP in your browser (eg 192.168.1.32) and log in with the local user data. You see the following picture:

Confirm this popup with all checkboxes active. You now have access to the system.

If we send the previous call "Request the configuration of your SysAP" again, we now get back the list of the building with the building structure and all installed devices, and no longer an "empty" answer. This answers delivers a full view of the whole environment will als Rooms, devices, channels and functions.

2. If you first want to get a clearer view, you can also first only query the device list instead of the full configuration.

The numbers returned correspond to the serial numbers of the physical free @ home devices (sensors and actuators). For comparison, we also find these in the local web interface of free @ home via the IP address in the browser:

3. With the device number, we now ask the specifically desired device, in this case a room temperature controller. To do this, we add the appropriate SiteID and Device ID to the call address of the API endpoint "Get device" at the end of the address. We get the required information from the answer from the previous call from point 7 "Request all devices".

As an answer, as in the picture above, we get back a series of channels, pairing IDs and values. The meaning of these can be found in the free @ home API description. Channel 6 in the red frame above shows us a value of 22. After checking the documentation, this means that the room temperature has currently set a target temperature of 22 ° C.

4. If we want to read a specific data point value, we use the API endpoint: https://apim.eu.mybuildings.abb.com/fhapi/v1/api/rest/datapoint/{siteid}/{device.id}.{channelid}.{inputid o. output.id}. We get this information from previous requests to the API. We get back an answer with values:

5. As a last step, we change a value on the room temperature controller via API call. For this we use the API endpoint "Write a datapoint value"

This is the same API endpoint,but request as PUT instead of GET. The value that we want to send to the data point is entered as a RAW value in the Body tab. If the value was set successfully, we get back "OK" in response:

Attention: Not all data points are writable. Thus, input data points (idp000X) differ from output data points (odp000X). Please follow the regular documentation of the free @ home API documentation for a detailed description of the identifier and data point types.