< Overview free@home cloud API

Content

Prerequisites for using the free@home cloud API

The free@home cloud API is capable accessing the free@home system access points of end users when they are connected to the cloud. For this, a few prerequisites have to be met, some for the end user that owns the smart home device(s) (e.g. the system access point, or “SysAP”) and some for the developer that is using the free@home cloud API.

End user

This API is currently only capable of accessing systems that are connected to the ABB myBUILDINGS cloud. Controlling a SysAP in the local network without internet is currently not supported.

Additionally the end user must enable the free@home API support* setting in the SysAP settings, found under Settings -> myBUILDINGS/myBUSCH-JAEGER -> Connection. Multiple SysAPs can be added to the same account.

The end user needs an ABB-free@home smart access point with version 2.2.4 or later.

Finally, once the free@home cloud API attempts to access the system access point, the end user has to grant access. The system access point frontend (i.e. when accessing the SysAP with a browser) will request that permission as-needed.

To sum up, the end user/system access point requirements are:

  • A system access point with at least version 2.2.4 must be available.

  • The end user must have a ABB myBUILDINGS/myBUSCH-JAEGER account.

  • The system access point must be connected to the myBUSCH/myBUSCH-JAEGER cloud with that account.
    This can be done by visiting Settings -> myBuildings/myBUSCH-JAEGER -> Connection on the system access point with a browser.

  • The system access point must enable the free@home API support setting under Settings -> myBUILDINGS/myBUSCH-JAEGER -> Connection.

  • Once the first connection attempt using the free@home cloud API is made, the end user must grant access to the system access point (logging into the system access point with a browser will display a message box asking for that permission).

Developer account

As a developer who wants to use the free@home cloud API to access one or more system access points, please visit https://developer.eu.mybuildings.abb.com and follow the instructions (listed on the main page) there. You can also find them at How to get started on the ABB Developer Portal. To sum up/repeat these instructions here for the specific free@home cloud API case:

  1. You first need to register for a developer account at https://developer.eu.mybuildings.abb.com (click the “Sign Up” button).
    Alternatively you can register a myBUILDINGS/myBUILDINGS-JAEGER account at the myBUILDINGS portal.

    If you already have such an account (e.g. due to the prerequisites from the end user section), then you can skip this step.

  2. Request developer access on https://developer.eu.mybuildings.abb.com (click the “Request” button).
    This provides you with access to the full https://developer.eu.mybuildings.abb.com site with the provided credentials.

  3. With these credentials, sign in to https://developer.eu.mybuildings.abb.com and subscribe to the free@home cloud API at https://developer.eu.mybuildings.abb.com.

Once finished, you can use the free@home cloud API. You can immediately use the basic API from the https://developer.eu.mybuildings.abb.com portal directly (navigate to “APIS” and select the free@home cloud API there. On the left side you can find the list of available requests. We suggest to start with the api/rest/configuration request.

Note however that when using the portal to execute the request (the “Try it” buttons), the free@home cloud API uses a special portal user to perform the requests on the SysAP. As a consequence, some advanced requests are not 100% supported, most notably subscribing to webhooks and websockets. To get full support, you need to use your own User-Id in your own OAuth2 implementation.

Developer OAuth2 implementation

In order to make full use of the free@home cloud API with your developer account, you first need perform an OAuth2 authentication. This will provide you with an OAuth2 access token that is required in all free@home cloud API requests. Note that this token has a limited lifetime and needs to be refreshed regularly.

In order to perform an OAuth2 authentication you need

  • A functional OAuth2 implementation. See the OAuth2 sample for a free@home cloud API specific example.

  • The User ID, User Secret and Redirect URL. You should have received these information when registering your developer account.

    Note that this User ID and User Secret is different from the credentials you use to login to https://developer.eu.mybuildings.abb.com and/or at https://eu.mybuildings.abb.com. This User ID and User Secret is required for OAuth2 only.

Please refer to OAuth2 Authentication Flow for details on the OAuth2 implementation of the myBUILDINGS portal. Also see OAuth2 sample for a hands-on example on how to obtain an OAuth2 access token.