This page is part of archived documentation for openHAB 3.0. Go to the current stable version
# BTicinoSmarther Binding
The BTicino Smarther binding implements a bridge to the Legrand/BTicino Smarther v2.0 API and allows you to control your BTicino Smarther chronothermostat units with openHAB, making it possible to discover Smarther units connected to your Legrand/BTicino Smarther account.
Smarther chronothermostat is produced by BTicino (opens new window), has its own API set and does not support the OpenWebNet protocol.
# Supported Things
All BTicino Smarther Chronothermostat device models should be discoverable through this binding:
- Flush mounting installation item (X8000)
- Wall installation item (X8000W)
If you can control them from BTicino Thermostat mobile app on your iPhone/Android you should be able to add it as a thing.
# Discovery
As long as BTicino Smarther Chronothermostat devices are available in the locations registered on the user account configured with the bridge they should show up whenever you initiate discovery of things.
If no devices are showing up, try to connect to the device(s) from your smartphone to make sure the device(s) are in use by your user account.
The discovery of devices in the Smarther API is based on what is known by Legrand. There is difference between e.g. smartphones and computers which can discover devices on the local network and the Smarther API which is not able to do so; it only knows about a device if your account is currently associated with the device.
# Thing Configuration
Each Bridge item requires you to register an Application with Legrand Developer portal (opens new window). This will get you a set of Client ID and Client Secret parameters to be used in the Bridge Configuration phase.
Optionally, if you want to later receive push notifications on the status of your units, consider to make your openHAB installation reachable in https from a public IP or domain (see Note on notifications).
The following configuration options are available on the BTicino Smarther Bridge thing:
| Parameter | Description | Condition |
|---|---|---|
| subscriptionKey | This is the Primary Key provided by Legrand when you create a new Account and subscribe to a product | Required |
| clientId | This is the Client ID provided by Legrand when you add a new Application for openHAB to your Legrand account | Required |
| clientSecret | This is the Client Secret provided by Legrand when you add a new Application for openHAB to your Legrand account | Required |
| useNotifications | ON = the bridge subscribes to receive push notifications on devices status change; OFF = status updates are requested (pull) on a periodical basis | |
| statusRefreshPeriod | This is the frequency of the polling requests to the Smarther API to update the bridge status (in minutes) |
The following configuration options are available on the BTicino Smarther Chronothermostat thing:
| Parameter | Description | Condition |
|---|---|---|
| plantId | This is the Plant Id of the location the Chronothermostat module is installed in, provided by Smarther API | Read-only |
| moduleId | This is the Module Id of the Chronothermostat module, provided by Smarther API | Read-only |
| settingsAutoupdate | ON = the thermostat settings are aligned with current status whenever it changes; OFF = settings are aligned to status only upon initialization | |
| programsRefreshPeriod | This is the frequency the Smarther API gateway is called to refresh Programs list used in "automatic" mode (in hours) | |
| numberOfEndDays | This is the number of days to be displayed in module settings, as options list for "End Date" field in "manual" mode | |
| statusRefreshPeriod | This is the frequency of the polling requests to the Smarther API to update the module status and sensor data (in minutes) |
# Account Creation
Follow the instructions in the tutorial here (opens new window), under:
- Step 1 : Create an account
- Step 2 : Subscribe to a product and get subscription key
There's also a Step 3 in this tutorial, you can skip it as not needed to complete this process. Simply write down your "Primary Key" as it will be needed later on in the bridge configuration phase.
# Application Creation
Follow the instructions in the tutorial here (opens new window), under:
- Step 1 : Register your application
- Step 2 : Check scopes
- Step 3 : Getting application details
When registering your new Legrand Application for openHAB BTicino Smarther Bridge you have to specify the allowed Reply URL, aka white-listed address. Here you have to specify the URL to the Bridge Authorization page on your server.
For example if you run your openHAB server on http://openhabianpi:8080 (opens new window) you should set http://openhabianpi:8080/bticinosmarther/connectsmarther as the "First Reply URL" required field in Step 1.
Other Reply URLs (second, third, etc.) you can leave them blank.
This is very important since the authorize process with Legrand takes place using your client web browser and Legrand will have to know the right URL to your openHAB server for the authorization to be completed.
When you have authorized with Legrand, this Redirect URI is where authorization tokens for your openHAB BTicino Smarther Brigde will be sent and they have to be received by the servlet on /bticinosmarther/connectsmarther.
On Step 2, please make sure to select both comfort.read and comfort.write scopes, as they're mandatory for the bridge to manage its chronothermostat devices.
Usually, Step 3 is then completed by Legrand within 1-2 days and you'll receive an email containing your application's Client ID and Client Secret.
# Note On Notifications
If you want to later receive push notifications (device status) from Legrand for this application, you must have your openHAB server reachable from a public IP/address and use the related public IP/address and public port when filling-in the "Reply URL" field in Step 1.
# Bridge Configuration
- Install the binding and make sure the BTicino Smarther Binding is listed on your server, if you have not already done so.
- Complete the Account Creation and Application Creation steps, if you have not already done so.
- Make sure you have your Legrand account Primary Key and your Legrand application Client ID and Client Secret identities available.
- Go to your preferred openHAB admin UI and add a new Thing - select the "BTicino Smarther Bridge".
- Choose new Id for the bridge, unless you like the generated one.
- Put in your Primary Key (in Subscription Key field), Client ID and Cliend Secret in their respective fields of the bridge configuration.
- Set Use Notifications to
ONif your openHAB server is reachable from a public https URL (see Note on notifications), setOFFotherwise. - You can leave the Bridge Status Refresh Period as is.
- Save the bridge.
- The bridge thing will stay in state INITIALIZING and eventually go OFFLINE - this is fine, as you now have to authorize this bridge with Legrand.
- Go to the authorization page of your server (see Application Creation)
http://<your openHAB address>:<your openHAB port>/bticinosmarther/connectsmarther; your newly added bridge should be listed there (along with the available locations). - Press the "Authorize Bridge" button; this will take you either to the login page of Legrand portal or directly to the authorization screen.
- Login and/or authorize the application; if the Reply URL is correct you will be returned and the entry should show your bridge is authorized with your Client ID; otherwise, go back to your application configuration on Legrand portal and ensure you have set the right Reply URL (see Troubleshooting below).
- The bridge will be updated with a refresh token and go ONLINE (the refresh token is used to re-authorize the bridge with Legrand Smarther API whenever required).
Now that you have got your bridge ONLINE it is time to discover your devices! Go to Inbox in the UI and search for "BTicino Smarther Chronothermostat" things. Any BTicino Smarther Chronothermostat device currently available on your account should show up immediately.
If no devices show up you may have to trigger the openHAB discovery several times as bridge will only find active devices known by the Smarther API at the time the discovery is triggered.
Should the bridge configuration be broken for any reason, the authorization procedure can be reinitiated from step 11 whenever required.
You can force reinitialization by authorizing again on the /bticinosmarther/connectsmarther page, even if the page shows it as already authorized. This will reset the refresh token.
# Troubleshooting
When configuring the bridge (see step 13 here), you can receive the following error from Legrand portal:
{
"error": "invalid_request",
"error_description": "The reply url host xxxxx doesn't match with the ones configured on the application"
}
This means you've either opened the /bticinosmarther/connectsmarther page from the wrong address or set the wrong "Reply URL" attribute in your application (see step 1 here).
Please remember these two strings must match for authentication process to work.
To solve the issue, either:
- Correct the address you're accessing the
/bticinosmarther/connectsmartherpage from, to match the "Reply URL" attribute registered in your application, or - Should you have specified a wrong "Reply URL" attribute in your application, go to the Legrand portal and correct it accordingly then resubmit the application for approval.
# Channels
# Bridge
The channels on the bridge are the ones used to get details of current communication with Smarther API on the Legrand account associated with the bridge.
Status Channels:
The following channels represent the current operational status of the bridge and must all be referenced with the status# prefix.
| Channel Type ID | Item Type | Read/Write | Description | Type |
|---|---|---|---|---|
| apiCallsHandled | Number | Read-only | The total number of API calls handled by the bridge | Common |
| notifsReceived | Number | Read-only | The total number of push notifications received by the bridge | Common |
| notifsRejected | Number | Read-only | The total number of push notifications rejected by the bridge (part of the received ones) | Common |
Configuration Channels:
The following channels represent convenience configuration channels for the bridge and must all be referenced with the config# prefix.
| Channel Type ID | Item Type | Read/Write | Description | Type |
|---|---|---|---|---|
| fetchLocations | Switch | Read-write | Trigger to manually fetch the updated client locations list from Smarther API | Advanced |
# Devices
Measures Channels:
The following channels represent the measures taken from the module on-board sensors and must all be referenced with the measures# prefix.
| Channel Type ID | Item Type | Read/Write | Description | Type |
|---|---|---|---|---|
| temperature | Number:Temperature | Read-only | Indoor temperature as measured by the sensor (precision of 1/10 degree Celsius) | Common |
| humidity | Number:Dimensionless | Read-only | Indoor humidity as measured by the sensor (in percentage) | Common |
Status Channels:
The following channels represent the current operational status of the module and must all be referenced with the status# prefix.
| Channel Type ID | Item Type | Read/Write | Description | Type |
|---|---|---|---|---|
| state | Switch | Read-only | Current operational state of the module | Common |
| function | String | Read-only | Current operational function set on the module (HEATING, COOLING) | Advanced |
| mode | String | Read-only | Current operational mode set on the module (AUTOMATIC, MANUAL, BOOST, OFF, PROTECTION) | Common |
| temperature | Number:Temperature | Read-only | Current operational target temperature set on the module (precision of 1/10 degree Celsius) | Common |
| program | String | Read-only | Current operational program set on the module (valid only for "Automatic" mode) | Common |
| endTime | String | Read-only | Current operational end time set on the module | Common |
| temperatureFormat | String | Read-only | Current operational temperature format of the module | Advanced |
Settings Channels:
The following channels represent the new operational settings to be applied to the module and must all be referenced with the settings# prefix.
| Channel Type ID | Item Type | Read/Write | Description | Type |
|---|---|---|---|---|
| mode | String | Read-write | New operational mode to be set (AUTOMATIC, MANUAL, BOOST, OFF, PROTECTION) | Common |
| temperature | Number:Temperature | Read-write | New operational set-point temperature to be set (valid only for "Manual" mode, precision of 1/10 degree Celsius) | Common |
| program | Number | Read-write | New operational program to be set (valid only for "Automatic" mode) | Common |
| boostTime | Number | Read-write | New operational boost time to be set (valid only for "Boost" mode) | Common |
| endDate | String | Read-write | New operational end date to be set (valid only for "Manual" mode) | Common |
| endHour | Number | Read-write | New operational end hour to be set (valid only for "Manual" mode) | Common |
| endMinute | Number | Read-write | New operational end minute to be set (valid only for "Manual" mode) | Common |
| power | Switch | Read-write | Power on, send new operational settings to the module | Common |
Note: The program and endDate channels are Selection channels.
They are dynamically populated, respectively with the module specific set programs and the next N days (starting from "Today", N driven by the numberOfEndDays device configuration option).
Configuration Channels:
The following channels represent convenience configuration channels for the module and must all be referenced with the config# prefix.
| Channel Type ID | Item Type | Read/Write | Description | Type |
|---|---|---|---|---|
| fetchPrograms | Switch | Read-write | Trigger to manually fetch the updated module programs list from Smarther API | Advanced |
# Full Example
In this example there is a bridge configured with Thing ID mybridge:
bticinosmarther.things:
Bridge bticinosmarther:bridge:mybridge "BTicino Smarther Bridge" [subscriptionKey="<your primary key>" clientId="<your client id>", clientSecret="<your client secret>"] {
Thing module thermo1 "Thermo 1" [plantId="<location plant id>" moduleId="<chronothermostat module id>"]
Thing module thermo2 "Thermo 2" [plantId="<location plant id>" moduleId="<chronothermostat module id>"]
}
bticinosmarther.items:
// Measures items
Number:Temperature smaTemperature "In Temperature [%.1f %unit%]" { channel="bticinosmarther:module:mybridge:thermo1:measures#temperature" }
Number:Dimensionless smaHumidity "In Humidity [%.1f %unit%]" { channel="bticinosmarther:module:mybridge:thermo1:measures#humidity" }
// Status items
Switch smaCurState "Cur State [%s]" { channel="bticinosmarther:module:mybridge:thermo1:status#state" }
String smaCurMode "Cur Mode [%s]" { channel="bticinosmarther:module:mybridge:thermo1:status#mode" }
Number:Temperature smaCurPoint "Cur Temperature [%.1f %unit%]" { channel="bticinosmarther:module:mybridge:thermo1:status#temperature" }
String smaCurProgram "Cur Program [%s]" { channel="bticinosmarther:module:mybridge:thermo1:status#program" }
String smaCurTime "Cur Timer [%s]" { channel="bticinosmarther:module:mybridge:thermo1:status#endTime" }
// Settings items
String smaSetMode "Set Mode [%s]" { channel="bticinosmarther:module:mybridge:thermo1:settings#mode" }
Number:Temperature smaSetPoint "Set Temperature [%.0f %unit%]" { channel="bticinosmarther:module:mybridge:thermo1:settings#temperature" }
Number smaSetProgram "Set Program [%s]" { channel="bticinosmarther:module:mybridge:thermo1:settings#program" }
Number smaSetBoost "Set Boost Time []" { channel="bticinosmarther:module:mybridge:thermo1:settings#boostTime" }
String smaSetDate "Set End Date [%s]" { channel="bticinosmarther:module:mybridge:thermo1:settings#endDate" }
Number smaSetHour "Set End Hour [%02d:00]" { channel="bticinosmarther:module:mybridge:thermo1:settings#endHour" }
Number smaSetMinute "Set End Minute [hh:%02d]" { channel="bticinosmarther:module:mybridge:thermo1:settings#endMinute" }
Switch smaSetPower "Apply Changes" { channel="bticinosmarther:module:mybridge:thermo1:settings#power" }
// Convenience items
Switch smaDisplayTime
bticinosmarther.sitemap:
sitemap bticinosmarther label="BTicino Smarther Sitemap" {
Frame label="Smarther Measures" {
Text item=smaTemperature
Text item=smaHumidity
}
Frame label="Smarther Status" {
Text item=smaCurState
Text item=smaCurMode
Text item=smaCurPoint
Text item=smaCurProgram
Text item=smaCurTime
}
Frame label="Smarther Settings" {
Selection item=smaSetMode
Selection item=smaSetProgram visibility=[smaSetMode=="AUTOMATIC"]
Setpoint item=smaSetPoint minValue=7 maxValue=24 step=1 visibility=[smaSetMode=="MANUAL"]
Selection item=smaSetDate visibility=[smaSetMode=="MANUAL"]
Setpoint item=smaSetHour minValue=0 maxValue=23 step=1 visibility=[smaDisplayTime==ON]
Setpoint item=smaSetMinute minValue=0 maxValue=45 step=15 visibility=[smaDisplayTime==ON]
Switch item=smaSetBoost mappings=[30="30'", 60="60'", 90="90'"] visibility=[smaSetMode=="BOOST"]
Switch item=smaSetPower mappings=["ON"="Start"]
}
}
bticinosmarther.rules:
rule "BTicino Smarther - Set time visibility flag"
when
Item smaSetMode received update or Item smaSetDate received update
then
if (smaSetMode.state == "MANUAL" && smaSetDate.state != "") {
smaDisplayTime.sendCommand(ON)
}
else {
smaDisplayTime.sendCommand(OFF)
}
end
# Binding Model And Smarther API
The model of the binding is such that the bridge takes care of all the remote communications with the Smarther API in the context of a specific user. All devices (chronothermostats modules) currently associated with the user account are available to control.
Legrand/BTicino Smarther topology considers the following dimensions:
- topology : is the whole network of devices associated with a user account
- plant : is the location where a module is installed (0..N plants per topology)
- module : is the chronothermostat installed in a location (0..N modules per location)
You can add multiple bridges to allow controlling devices in the context of multiple Legrand user accounts.
Legrand manages the push notifications on device status via MS Azure C2C queues. Each bridge registers itself to the queue, takes care of incoming notifications on behalf of its managed devices and dispatches each payload to the related device.
The binding uses the Smarther API v2.0 (opens new window). The main gap between the API and Smarther mobile app is that the latter also allows you to create new programs.
← BSB-LAN Buienradar →