# ABB free\@home

## ABB Free\@home

#### BuildingPro Suites App for the ABB Free\@home Integration

> Simply smart. ABB-free\@home® turns a house or apartment into a smart home. Whether it's blinds, lights, heating, air conditioning, door communication, or scenes. Easily remote-controlled via a switch on the wall, with a laptop, or with a smartphone. Very convenient. Extremely comfortable. Very energy-efficient. Particularly attractive: the costs are minimal compared to conventional electrical installations.

This app allows access to ABB Free\@home systems directly in BuildingPro Suites via the ABB ProService Portal. The user can monitor values, browse statistics, control the Free\@home devices, and, most importantly, network ABB devices with systems from other manufacturers.

### Installation

The ABB Free\@home App is installed via the App Store in BuildingPro Suites.

### Assets

The ABB Free\@home App independently creates all necessary assets and asset types.

#### Asset Structure

The following asset types are created only to create a structure in BuildingPro Suites:

* *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 BuildingPro Suites 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 light 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 unit.

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

* *WindowSensor*: Sensor for detecting window position.

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

* *DoorSensor*: Sensor for detecting door position.

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

* *MovementSensor*: Sensor for detecting movement.

| Attribute  | Description | Subtype |
| ---------- | ----------- | ------- |
| `Movement` | Movement    | Input   |

* *Scene*: Represents a scene.

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

#### Configuration

{% hint style="info" %}
You can find more information on app configuration [↗ here](https://doc.eliona.io/collection/documentation/settings/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 activate or deactivate the retrieval from this API                                                                                                       |
| `refreshInterval`   | Interval in seconds for device detection. This is an expensive operation and should not be less than 3600 s                                                      |
| `requestTimeout`    | API query timeout in seconds                                                                                                                                     |
| `assetFilter`       | Filter for asset creation, more details can be found in the app's README                                                                                         |
| `tenantIDs`         | List of BuildingPro Suites tenant IDs for which this device should collect data. For each tenant ID, all assets are automatically created in BuildingPro Suites. |

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

```json
{
  „abbConnectionType“: „ProService“,
  „apiKey“: „api.key“,
  „orgUUID“: „org-uuid“,
  „enable“: wahr,
  „refreshInterval“: 3600,
  „requestTimeout“: 120,
  „assetFilter“: [],
  „tenantIDs“: [
    „10“
  ]
}
```

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

After completing the configuration, the app starts the continuous asset creation. When all detected devices are created, the user is informed about it via BuildingPro Suites's notification system.

#### After Configuration

After the application is configured, it searches for systems connected to the configured ProService account. On all of these systems, a user named "BuildingPro Suites\_ProService" is automatically created, who 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, search for a user named "BuildingPro Suites\_ProService" under "User settings." Activate this user and make sure that they have the correct access rights to control the devices.

## Troubleshooting

### Error Message "Defective Device"

Some devices have a bug that causes the system to classify the device as "defective" when it writes data points. The system then no longer sends data to these devices and makes them uncontrollable.

However, the devices are not defective; the sysAP only 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 fix 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 in to the playground with either your MyBuildings account or your ProService account.

```json
{
  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 - in case the user is the owner of the sysap
  CustomerDevice {dtId} #the dtId should appear here - in case 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 problems that can be circumvented but are not desirable.

### Optimizing Requests

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

```json
{
  ServerDescriptionService
  {
    consumedRequestCosts # returns the sum of the costs caused by this user (should be reset to 0 at night)
    requestCosts # returns the costs for this query (in your case, mainly affected by 1 per loaded object + 1 per DataPointRequest)
  }

# ... add the rest/the normal query here
}
```

We have made great efforts to reduce resource consumption. Nevertheless, the app's querying for new devices is a very resource-intensive process that can be further optimized if there is a need for it.