ABB Free@Home

Eliona App for ABB Free@home integration

Simply smart. ABB-free@home® transforms the house or the apartment into an intelligent home. Whether blinds, lights, heating, air conditioning, door communication or scenes. Easy to remote control via a switch on the wall, with the laptop or with the smartphone. Very convenient. Extremely comfortable. Very energy efficient. Especially attractive: Only minimal costs are involved when compared with conventional electrical installations.

This app allows accessing ABB Free@home systems directly in Eliona using the ABB ProService portal. Users can monitor values, browse through statistics, control the Free@home devices and, most importantly, interconnect ABB devices with systems from other manufacturers.

Installation

The ABB Free@home App is installed via the App Store in Eliona.

Assets

The ABB Free@home App automatically creates all the necessary asset types and assets.

Structure assets

The following asset types are created just to create a structure in Eliona:

• Floor: Represents a specific level in a building.

Attribute	Description
Id	Floor Identifier
Name	Floor Name
Level	Floor Level

• Room: Represents a specific room on a floor.

Attribute	Description
Id	Room Identifier
Name	Room Name

• System: Represents a central system controlling multiple devices.

Attribute	Description	Filterable
ID	System ID	x
GAI	GAI	x
Name	System Name	x

• Device: Represents a specific device in the system. Devices are linked to their respective systems and locations in Eliona asset tree.

Attribute	Description	Filterable
ID	Device Identifier	x
GAI	GAI
Name	Device Name	x
Location	Device Location

Channels

Channels are linked to devices. These channels provide the real functionality:

• Switch: A regular light switch .

Attribute	Description	Subtype
SwitchState	Switch State	input
Switch	Switch	output

• Dimmer: A channel to control lighting intensity.

Attribute	Description	Subtype
SwitchState	Switch State	input
DimmerState	Dimmer State	input
Switch	Switch	output
Dimmer	Dimmer	output

• HueActuator: A channel to control colored lighting.

Attribute	Description	Subtype
SwitchState	Switch State	input
DimmerState	Dimmer State	input
HSVState	HSV State	input
ColorModeState	Color Mode State	input
ColorTemperatureState	Color Temperature State	input
Switch	Switch	output
Dimmer	Dimmer	output
HSVHue	HSV Hue	output
HSVSaturation	HSV Saturation	output
HSVValue	HSV Value	output
ColorTemperature	Color Temperature	output

• RTC: Room Temperature Controller.

Attribute	Description	Subtype
SwitchState	Switch State	input
CurrentTemp	Current Temperature	input
SetTempState	Set Temperature State	input
Switch	Switch	output
SetTemp	Set Temperature	output

• RadiatorThermostat: Thermostat for a radiator.

Attribute	Description	Subtype
SwitchState	Switch State	input
CurrentTemp	Current Temperature	input
SetTempState	Set Temperature State	input
StatusIndication	Status Indication	input
HeatingActive	Heating Active	input
HeatingValue	Heating Value	input
Switch	Switch	output
SetTemp	Set Temperature	output

• HeatingActuator: Heating control unit.

Attribute	Description	Subtype
InfoFlow	Info Flow	input
ActuatorFlow	Actuator Flow	input

• WindowSensor: Sensor to detect window position.

Attribute	Description	Subtype
Position	Position	input

• DoorSensor: Sensor to detect door position.

Attribute	Description	Subtype
Position	Position	input

• MovementSensor: Sensor to detect movement.

Attribute	Description	Subtype
Movement	Movement	input

• Scene: Represents a scene.

Attribute	Description	Subtype
SwitchState	Switch State	input

Configuration

For a detailed guide to configuring apps, follow the manual.

The ABB Free@home App is configured by defining one or more authentication credentials. Each configuration requires the following data:

Attribute	Description
abbConnectionType	Type of connection. Only "ProService" is currently supported.
apiKey	API key provided by ABB
orgUUID	UUID of the ProService organization
enable	Flag to enable or disable fetching from this API
refreshInterval	Interval in seconds for device discovery. This is an expensive operation, should be no lower than 3600 s
requestTimeout	API query timeout in seconds
assetFilter	Filter for asset creation, more details can be found in app's README
projectIDs	List of Eliona project ids for which this device should collect data. For each project id, all assets are automatically created in Eliona.

The configuration is done via a corresponding JSON structure. As an example, the following JSON structure can be used to define an endpoint for app permissions:

{
  "abbConnectionType": "ProService",
  "apiKey": "api.key",
  "orgUUID": "org-uuid",
  "enable": true,
  "refreshInterval": 3600,
  "requestTimeout": 120,
  "assetFilter": [],
  "projectIDs": [
    "10"
  ]
}

Configurations can be created using this structure in Eliona under Apps > ABB Free@home > Settings. To do this, select the /configs endpoint with the POST method.

After completing configuration, the app starts Continuous Asset Creation. When all discovered devices are created, user is notified about that in Eliona's notification system.

After configuration

After the application is configured, it looks up systems connected to the configured ProService account. On all of these systems, it automatically creates a user called "eliona_ProService" that would later be used when controlling the devices. This account has to be enabled locally on these systems.

To enable the account, log in to the SysAPs, find "User settings" and find a user called "eliona_ProService". Enable this user and ensure it has the correct access rights to control the devices.

Troubleshooting

Defective Device error message

There is an error with some devices, that some datapoint writes cause the system to consider the device "defective". The system then stops sending data to these devices, making them uncontrollable.

The devices are not defective though, the sysAP just needs to be restarted and the devices respond again.

ABB is aware of that error and on a way to fix it. If you run into this issue repeatedly, please let us know about it for a fix.

Troubleshooting using GraphQL

ABB has a GraphQL playground for it's Smart Home API: https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphiql

You can log in to the playground either using your MyBuildings account or your ProService account.

{
  PSOrganization{dtId} # should not work for a normal user
}
{
  User{userName} # should return the username of the user who created the token
}

To verify which relation you have to the systems, you can use this query:

{
  UserDevice  {dtId} #the dtId should appear here - in case the user is the owner of the sysap
  CustomerDevice {dtId} #the dtId should appear here - in case the user is the installer that invited the user as customer
}

Please note that ABB currently does not recommend using the same user account for ProService and MyBuildings portals. It causes some problems that can be worked around, but are not desired.

Requests optimization

ABB implemented a way to analyze resource usage by current user:

{
  ServerDescriptionService
  {
    consumedRequestCosts # returns the sum of costs produced by this user (should be turned back to 0 in the night)
    requestCosts #returns the costs by this query (in your case mainly affected by 1 per object loaded + 1 per DataPointRequest)
  }
# … add here the rest/normal query
}

We took a lot of effort to bring resource usage down. Still, the app polling for new devices is a very resource-intensive process that can be further optimized if there is a demand for it.