# ABB free\@home

## ABB Free\@home

#### Eliona App for ABB Free\@home Integration

> Simply smart. ABB-free\@home® turns the house or apartment into an intelligent home. Whether blinds, lighting, heating, air conditioning, door communication, or scenes. Easily remote-controlled via a wall switch, with a laptop, or with a smartphone. Very convenient. Extremely comfortable. Very energy efficient. Especially attractive: compared with conventional electrical installations, only minimal costs are incurred.

This app enables access to ABB Free\@home systems directly in Eliona via the ABB ProService Portal. The user can monitor values, browse statistics, control Free\@home devices, and, above all, link ABB devices with systems from other manufacturers.

### Installation

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

### Assets

The ABB Free\@home app automatically creates all necessary assets and asset types.

#### Structure Assets

The following asset types are created only to establish 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 that controls 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 the 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 actual functionality:

* *Switch*: A normal light switch.

| Attribute     | Description  | Subtype |
| ------------- | ------------ | ------- |
| `SwitchState` | Switch state | Input   |
| `Switch`      | Switch       | Output  |

* *Dimmer*: A channel for controlling lighting intensity.

| Attribute     | Description  | Subtype |
| ------------- | ------------ | ------- |
| `SwitchState` | Switch state | Input   |
| `DimmerState` | Dimmer State | Input   |
| `Switch`      | Switch       | Output  |
| `Dimmer`      | Dimmer       | Output  |

* *HueActuator*: A channel for controlling colored lighting.

| Attribute               | Description              | Subtype |
| ----------------------- | ------------------------ | ------- |
| `SwitchState`           | Switch state             | Input   |
| `DimmerState`           | Dimmer state             | Input   |
| `HSVState`              | HSV state                | Input   |
| `ColorModeState`        | Color mode status        | Input   |
| `ColorTemperatureState` | Color temperature status | 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 device.

| Attribute      | Description   | Subtype |
| -------------- | ------------- | ------- |
| `InfoFlow`     | Info Flow     | Input   |
| `ActuatorFlow` | Actuator Flow | input   |

* *WindowSensor*: Sensor for detecting the window position.

| Attribute  | Description | Subtype |
| ---------- | ----------- | ------- |
| `Position` | Position    | Input   |

* *DoorSensor*: Sensor for detecting the door position.

| Attribute  | Description | Subtype |
| ---------- | ----------- | ------- |
| `Position` | Position    | Input   |

* *MovementSensor*: Sensor for detecting movement.

| Attribute | Description | Subtype |
| --------- | ----------- | ------- |
| `Motion`  | Motion      | Input   |

* *Scene*: Represents a scene.

| Attribute     | Description  | Subtype |
| ------------- | ------------ | ------- |
| `SwitchState` | Switch state | Input   |

### Configuration

{% hint style="info" %}
More information on configuring apps can be found [↗ here](https://doc.eliona.io/collection/dokumentation/einstellungen/apps).
{% endhint %}

The ABB Free\@home app is configured by defining one or more authentication credentials. The following data is required for each configuration:

| Attribute           | Description                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `abbConnectionType` | Type of connection. Currently only “ProService” is supported.                                                                              |
| `apiKey`            | API key provided by ABB                                                                                                                    |
| `orgUUID`           | UUID of the ProService organization                                                                                                        |
| `enable`            | Flag to enable or disable retrieval from this API                                                                                          |
| `refreshInterval`   | Interval in seconds for device discovery. This is an expensive operation and should not be less than 3600 s                                |
| `requestTimeout`    | API query timeout in seconds                                                                                                               |
| `assetFilter`       | Filter for asset creation; further details can be found in the 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. |

Configuration is done using 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 in Eliona with this structure under `Apps > ABB Free@home > Settings` . To do so, select the /configs endpoint with the POST method.

After configuration is complete, the app starts continuous asset creation. When all discovered devices have been created, the user is informed via Eliona's notification system.

### After configuration

After the application is configured, it searches for systems connected to the configured ProService account. On all these systems, a user named “eliona\_ProService” is automatically created, which is later used to control the devices. This account must be activated locally on these systems.

To activate the account, log in to the SysAPs, look under “User settings” for a user named “eliona\_ProService”. Activate this user and make sure that it has the correct access rights to control the devices.

### Troubleshooting

#### Error message “Defective device

Some devices have an error that causes the system to classify the device as “defective” when it writes datapoints. The system then no longer sends data to these devices and makes them uncontrollable.

However, the devices are not defective; the sysAP just needs to be restarted and the devices will respond again.

ABB is aware of this error and is working on a way to fix it. If you repeatedly encounter this problem, please let us know so we can resolve it.

#### Troubleshooting with GraphQL

> ABB has a GraphQL playground for its Smart Home API: <https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphiql>

You can log into the playground either with your MyBuildings account or with 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 check what relationship you have to the systems, you can use this query:

```
{
  UserDevice {dtId} # the dtId should appear here - if the user is the owner of the sysap
  CustomerDevice {dtId} # the dtId should appear here - if the user is the installer who invited the user as a customer
}
```

Please note that ABB currently does not recommend using the same user account for ProService and MyBuildings portals. This leads to some issues that can be worked around, but are not desirable.

#### Optimizing requests

ABB has implemented a way to analyze resource consumption by the current user:

```
{
  ServerDescriptionService
  {
    consumedRequestCosts # returns the sum of the costs caused by this user (should be reset to 0 overnight)
    requestCosts # returns the cost of this query (in your case mainly affected by 1 per loaded object + 1 per DataPointRequest)
  }
# ... add the rest/normal query here
}
```

We have put a lot of effort into reducing resource consumption. Nevertheless, querying the app for new devices is a very resource-intensive process that can be further optimized if there is a need for it.