About

smarther2mqtt is a Docker container that implements communication between a BTicino Smarther2 Wi-Fi thermostat and an MQTT broker like Mosquitto. My primary use case is monitoring and controlling the thermostat from openHAB using the MQTT binding.

Here is an overview of the assumed architecture, where ◄════► represents the data flow:

                         ┌────────────────────┐
                         │ Netatmo            │
   ┌────────────┐        │ Connect ┌───────┐  │      ╔═══════════════╗
   │ Smarther2  │        │  cloud  │Netatmo╞═◄╪════►═╣ smarther2mqtt ║
   │ thermostat ╞═◄════►═╡         │  API  │  │      ║  (this tool)  ║
   └────────────┘        │         └───────┘  │      ╚═══════╦═══════╝
                         └────────────────────┘              ▲
                                                             ║
                                                             ▼
                                                      ┌──────╨──────┐
                                                      │ MQTT broker │
                                                      └──────╥──────┘
                                                             ▲
                                                             ║
                                              ┌──────────────╫──────┐
                                              │ openHAB      ▼      │
    ┌──────┐                                  │          ┌───╨────┐ │
    │ User ╞═◄══════════════════════════════►═╡          │  MQTT  │ │
    └──────┘                                  │          │ add-on │ │
                                              │          └────────┘ │
                                              └─────────────────────┘

Setup

Let HOST_IPADDRESS be the IP address of the host on which smarther2mqtt will be executed (this it the IP address on your LAN). Also, let WEBSERVER_PORT be the TCP port on which a temporary web server will be launched to obtain an OAuth2 token when required at a later step (this is the host-side published port of the Docker container).

Take note of:

• HOST_IPADDRESS
• WEBSERVER_PORT

Setting up smarther2mqtt for exposing a Smarther2 thermostat in openHAB involves a few steps:

1. Register an app on the Netatmo Connect portal
2. Install an MQTT broker (or pick an existing one)
3. Configure smarther2mqtt
4. Run smarther2mqtt
5. Install the MQTT binding in openHAB
6. Configure things and items in openHAB

These steps are illustrated in detail below.

1. Register an app on the Netatmo Connect portal

• If required, sign up for a new account on the Netatmo Connect developer portal.
• Create a new app that will be used by smarther2mqtt to communicate with the thermostat. At this stage only generic information are requested, so there are no constraints about what to indicate.
• Once your new app has been approved, get back to the list of your apps.
• Take note of the Client ID and of the Client secret, as they will be required later on.
• Set http://HOST_IPADDRESS:WEBSERVER_PORT/token as Redirect URI. Be careful in respecting this exact syntax (e.g., do not put a final / in the URI), as this URI will be used as part of the OAuth2 authentication process.
• Make sure that the app status is Activated.
• Switch to the Netatmo Home + Control API documentation page, expand the homesdata section, click the Try It Out button and then the Execute /Homesdata button. From the resulting Server response, take note of the id of your home and of the room that contains the thermostat.

Take note of:

• Client ID
• Client secret
• id of your home
• id of the room with the thermostat

2. Set up the MQTT broker

An MQTT broker is a software that acts as an "exchange point" for messages in the MQTT protocol which subscriber applications receive from publisher applications. smarther2mqtt relies on an MQTT broker which it will use as a subscriber to receive thermostat commands (from openHAB) and as a publisher to expose readings from the thermostat (to openHAB).

In case you already have an MQTT broker running somewhere in your network, it is enough to point smarther2mqtt to this broker by editing the configuration file (see step 3 below). Otherwise, you will need to set up a new MQTT broker. In principle, it may even be possible to point smarther2mqtt to a free publicly available MQTT broker like HiveMQ, but this is strongly discouraged for obvious security reasons.

In practice, it is enough to install an open source MQTT broker like Mosquitto, which requires little to no configuration. Just make sure that:

• the broker is not accessible from the Internet by setting up proper firewall rules
• smarther2mqtt is pointed to the correct broker, as no authentication is enforced
• the broker is reachable by the Docker container that runs smarther2mqtt (by default, some default Mosquitto installations listen on 127.0.0.1 only)

3. Configure smarther2mqtt

Copy file smarther2mqtt_settings-template.yml to smarther2mqtt_settings.yml and edit its contents to suit your setup.

Comments inside the provided template configuration file should be fairly self-explanatory about the semantic of each parameter. Most of the paramaters that you have taken note of will be required at this stage.

4. Run smarther2mqtt

Execute the following sequence of commands to build the container image, create a container and execute it.

Note about network mode - The correct network mode to be used depends on your system settings:

• bridge ensures isolation, hence is deemed more safe (smarther2mqtt will be able to reach your whole network but prevented from exposing unintended services). It is fine to use as long as the MQTT broker listens on the host IP address (i.e., not just 127.0.0.1) or is executed on a different host
• host, used in this example, is slightly less safe (smarther2mqtt does not normally expose any services anyway) but allows to reach a host-side MQTT broker listening on 127.0.0.1 only

sudo docker build --tag smarther2mqtt .
sudo docker container create --name smarther2mqtt --hostname smarther2mqtt --network host --mount type=bind,source=$PWD/smarther2mqtt_settings.yml,target=/smarther2mqtt_settings.yml --restart unless-stopped smarther2mqtt
sudo docker start smarther2mqtt

At the time of first execution, or if the OAuth2 token has somehow been invalidated, it is required to authorize access to the Netatmo Connect API. For this purpose, smarther2mqtt requires the user to access a specific URL from a web browser that can reach HOST_IPADDRESS and WEBSERVER_PORT. The need to perform this action, as well as the URL to contact are notified in the container log and, optionally (if set in the configuration file) through a Telegram bot. To check the container log:

sudo docker logs smarther2mqtt

The message that invites to contact the URL is similar to the following:

[2023/04/14 19:26:53] INFO:smarther2mqtt:publish:34 - The *Netatmo Smarther2* tool requires authorization. Please grant it by accessing this web page: http://192.168.10.150:9090/authorize

Just access the URL, authenticate yourself on the Netatmo Connect cloud, grant the requested access and you are done.

5. Install the MQTT binding in openHAB

From the Add-on Store menu of openHAB, install the MQTT binding.

6. Configure things and items in openHAB

Configure things and item as follows:

• Add a new mqtt:broker thing (bridge) and configure it to point to the IP address (and, if required, port) of your MQTT broker. Review and tune the other parameters to make sure that the thing status is Online. Unless explicitly required, it should be perfectly fine to use QoS 0 here, especially if the MQTT broker is running on the same host.
• Add another Generic MQTT thing (mqtt:topic) and configure it to use the MQTT broker added above as bridge.
• Edit the freshly added Generic MQTT thing and open its Channels tab (see also the applicable section of the MQTT Things and Channels Binding guide). For each topic in the smarther2mqtt configuration file (both publish_topics and subscribe_topics) add a new Channel, picking its parameters as follows:
  • identifiers and labels can be arbitrary, but pick ones that will be easy to recognize later on
  • channel types should be quite obvious: temperature and humidity topics will use numbers; mode will use strings; setpoint end time will use date/time
  • for each of the temperature, humidity and setpoint end time topics just indicate the corresponding publish_topic from the smarther2mqtt configuration file as status topic in each channel's settings
  • for each of the temperature setpoint and mode topics indicate the corresponding pair of publish_topic and subscribe_topic from the smarther2mqtt configuration file as status and command topics, respectively, in each channel's settings: for example, create a single channel to represent the temperature setpoint where you set smarther2/thermostat1/sensors/temperature_setpoint as status topic and smarther2/thermostat1/commands/temperature_setpoint as command topic
  • optionally, for the channel that represents the thermostat's operational mode you can indicate the following list of Allowed states in the Advanced options section: AUTO,MANUAL,BOOST,OFF. This will allow to easily set the state from the openHAB GUI
  • always indicate the full topic path (e.g., smarther2/thermostat1/sensors/temperature) in each channel
  • it is perfectly fine not to set any qos value for the channel, thus letting the default one from the broker thing be applied
  • do not set the retained flag on any of the created channels: it is pointless for channels used to get readings from the thermostat, and it may have adverse effects for channels used to send commands to the thermostat (see Synchronization Logic below)
• Create a new item for each of the channels created above. For convenience, it is possible to use the Create Points from Thing button to accomplish this. Item types should be selected according to the corresponding channels (for example, temperature setpoint must be a setpoint, while mode must be a string).

Synchronization logic

Once this setup stage is reached, the Smarther2 thermostat can be controlled and its status be monitored through 3 different interfaces:

1. the Legrand/Netatmo/BTicino Home + Control mobile app
2. Apple HomeKit (or, possibly, Google Home)
3. the MQTT topics exposed by smarther2mqtt

While interfaces 1 and 2 are natively paired, it is natural to wonder how smarther2mqtt is expected to interact with them.

Status Readings

All thermostat readings are made available through all the three aforementioned interfaces: they should all return the same readings at any time, regardless of which one is queried.
As a minor exception, status information published by smarther2mqtt via MQTT may be refreshed with a slight delay due to the setting of its internal parameter netatmo/polling_interval.

Commands

As a general rule, the latest requested (temperature/mode) change is always applied, regardless of the interface it was received through.
However, a couple of additional mechanisms should be considered:

• Messages published on the MQTT topics used to receive temperature/mode commands (subscribe_topics) need not and should never have the retained flag set; channels of the openHAB thing should be configured accordingly.
  In fact, if a retained message is published on any of the subscribe_topics, this message becomes "sticky" and is sent to any new subscribers, even if they connect to the MQTT broker after the message has been sent. Although in principle this is not harmful, the retained message would be fetched by smarther2mqtt every time it starts up (for example, in the event of a reboot of the device that smarther2mqtt is executed on), causing unintentional overrides of the current thermostat operational mode.
  Checking whether a retained message exists can be accomplished by simply subscribing to a topic with an appropriate filter: if a message is immediately received, then that message was set to be retained. For example:

  mosquitto_sub --retained-only -t smarther2/thermostat1/commands/temperature_setpoint
  13.5 <===== retained message
  

  In case a retained message has been mistakenly sent to one of the subscribe_topics, it can be cleared by using a command similar to the following:

  mosquitto_pub -n -r -t smarther2/thermostat1/commands/TOPIC_TO_BE_CLEARED
  

• Similarly to environmental readings, also the last issued command is always synchronized among the 3 aforementioned interfaces. Therefore, changes requested via the Home + Control app are also reflected in the temperature setpoint item in openHAB.
  Also in this case, the refresh may take a short time due to the polling_interval setting.

Testing and troubleshooting

Assuming that the Mosquitto MQTT broker is being used, it is possible to verify which messages are exchanged by smarther2mqtt by installing the mosquitto-clients package and running commands similar to the following:

# To verify information published by smarther2mqtt (i.e., thermostat sensor readings)
for SENSOR in temperature humidity temperature_setpoint mode setpoint_endtime; do echo -n "-t smarther2/thermostat1/sensors/$SENSOR "; done | xargs mosquitto_sub

# To verify commands issued by smarther2mqtt
echo auto | mosquitto_pub -t smarther2/thermostat1/commands/mode -l
echo 18   | mosquitto_pub -t smarther2/thermostat1/commands/temperature_setpoint -l

---

Background

BTicino S.p.A. is a renowned italian manufacturer of electrical components for home and industry use. Its product range includes a family of thermostats called Smarther that can drive heating or cooling home systems: they have a built-in Wi-Fi connection for being managed from the cloud and support being controlled by the user from a mobile app.

There exist two generations of such thermostats:

• the earlier Smarther, which can be controlled using the companion BTicino Thermostat app (Apple App Store, Google Play Store), relies on the Works with Legrand cloud platform, implements the Smarther legacy v2.0 API specification and is fully supported by the BTicinoSmarther openHAB binding
• the later Smarther2, which can be controlled using the companion Legrand/Netatmo/BTicino Home + Control app (Apple App Store, Google Play Store) as well as through the Apple Homekit framework (Apple Home), relies on the Netatmo Connect cloud platform, implements the Netatmo Home+Control API specification and, although a Netatmo binding exists in openHAB, as of April 2023 is not among the device types it supports

Here is a summary of the picture:

Generation	Cloud Platform	Mobile App	Apple Homekit	Implemented API	openHAB Binding
Smarther	Works with Legrand	BTicino Thermostat Apple App Store Google Play Store	No	Smarther legacy v2.0	BTicinoSmarther
Smarther2	Netatmo Connect	Legrand/Netatmo/BTicino Home + Control Apple App Store Google Play Store	Yes	Netatmo Connect Home+Control	Netatmo

To the best of my knowledge, each thermostat generation is meant to work with the control chain (cloud platform, app, API) it was designed for, therefore the two openHAB bindings are not interchangeable. smarther2mqtt specifically addresses the Smarther2 generation, and implements a simple a link between the Netatmo Connect cloud and openHAB, in a way that does not require any integrations to openHAB itself.

Additional notes

Features

• The following functions of the Smarther2 thermostat are supported:
  • Room temperature reading
  • Room humidity reading
  • Temperature setpoint reading
  • Current operational mode reading (AUTO/MANUAL/BOOST/OFF)
  • Temperature setpoint setting
  • Operational mode setting (AUTO/MANUAL/BOOST/OFF)
    • Changing the temperature setpoint automatically switches the operational mode of the thermostat to MANUAL
• smarther2mqtt includes an implementation of the Netatmo Connect API Authorization code grant type. For this purpose, it temporarily runs a web server that is used to serve a callback URL where the authorization token is received. This service never needs to be exposed on the Internet and terminates as soon as the grant is obtained.
• Temperature setpoints and operational modes changed via smarther2mqtt (by sending commands to the MQTT subscribe_topics) can be set to expire after a configurable timespan:
  • an established timespan specified in the smarther2mqtt configuration file, or
  • the default duration of manual settings that has been configured in the Home + Control app, or
  • never (persistent setting)

Requirements

• Excerpts from the Smarther2 FAQ claim that the Smarther2 thermostat can be controlled from the local Wi-Fi network even in the absence of a working Internet connection. In practice, the native Legrand/Netatmo/BTicino Home + Control app refuses to start or fails to reach any thermostats without an Internet connection. The "local" operational mode, which may therefore only be supported via Apple Home (again, I don't know about Google Home) is anyway out of the scope of this tool: smarther2mqtt requires an Internet connection and always relies on it to control a thermostat by leveraging the API from the Netatmo Connect cloud.

Scope and limitations

• This tool is not meant to replace the companion Legrand/Netatmo/BTicino Home + Control app, which remains the only tool for first-time setup of a thermostat and for accessing its full feature set.
• This tool is also not meant to enable exposing the Smarther2 thermostat on the Apple Homekit system via the openHAB Homekit add-on: in fact, the unit is already supposed to be natively added in Apple Home at the time of first setup. A similar point may apply to Google Home.
• This tool only supports a single instance of a Smarther2 thermostat. However, in principle it should be possible to run multiple instances of the container, provided that each uses a different configuration file and a different WEBSERVER_PORT.
• Thermostat readings are queried by periodical polling: there is no support for proactive event (status change) notifications from the Netatmo Connect cloud via a webhook URI.