Heatzy - Setup a Heatzy Pilote to MQTT Gateway under Linux


dropcap linux heatzy

One year back, I started to use some Heatzy pilote devices. Heatzy is a french startup which manufactures IOT devices.

Heatzy pilote devices are connected to your wifi network and allow you to control your electrical heaters over internet from any smartphone (IOS or Android) with Heatzy proprietary app.

A nice thing about Heatzy is that they also publish some API called Gizwits Open API to manage their devices.

I've written a first article explaining how to manage your Heatzy devices from Command line under Linux.

To open wider management possibilities, I decided to write a simple Heatzy to MQTT Gateway. This gateway goal is to allow you to set and to get your Heatzy pilote state thru a simple MQTT broker like Mosquitto. It is a complete bridge between Heatzy server and your MQTT clients.

It should greatly simplify the declaration of your Heatzy pilote devices in most home automation software solutions (OpenHab, Domoticz, Jeedom, …).

This article explains how to setup a Heatzy to MQTT gateway for Heatzy Pilote devices generation 1 and 2.
Gateway will work as a systemd service.

Article also provides an integration example in OpenHab home automation software.

It has been developped under Debian 9.0 but it should work on most modern Linux distros.

1. Pre-requisite

To use this Heatzy Pilote ↔ MQTT Gateway your need 2 pre-requisites :

  • An Heazy account where your devices are declared
  • an operational MQTT broker where your Heatzy devices state will be published

All informations about your Heatzy account and your MQTT broker service should be fully configured in the Configuration section of the gateway script.

2. Gateway Principle

Heatzy pilote ↔ MQTT gateway will be in charge of 4 main actions :

  • periodically query your Heatzy account to enquire about your Heatzy devices state
  • publish your devices state and alias on a MQTT topic
  • publish your devices DID list
  • listen to some MQTT commands to forward them to Heatzy server

As all Heatzy devices are identified by their DID, the gateway will periodically publish the list of your Heazy devices DID on a specific MQTT topic :

/your/heatzy/topic/list : list of your devices DID separated by ';'

In case Heatzy server is not available, the list will be set to none.

The gateway will also periodically publish 2 informations for every known Heatzy device :

/your/heatzy/topic/{DID}/state : current state of the device
/your/heatzy/topic/{DID}/name : current name (alias) of the device

All states are identified by numerical values :

  • 0 : offline
  • 1 : off
  • 2 : comfort
  • 3 : economy
  • 4 : frost

At the same time, the gateway will subscribe to a topic pattern to catch and handle all publications for state change :

/your/heatzy/topic/{DID}/command : new state to set (numerical value)

Every state published on this topic will be handled by the gateway and command sent to Heatzy server.

The gateway is using a FIFO to handle all MQTT requests (commands and state update).

As it is supposed to run as a daemon, the gateway script takes 2 parameters :

--start : starts the service
--stop : kills running service if any

3. Installation

The Heatzy to MQTT Gateway is made of :

  • a simple Bash script to run the gateway service
  • a configuration file to declare the systemd service

Both files are available from my Github repository.

An complete installation script is available to download, install, enable and start theHeatzy to MQTT Gateway.

You just need to run the following commands :

# wget
# chmod +x ./
# ./

If you install the gateway service on an Ubuntu server, make sure to add sudo before running the installation script.

Once the gateway service is installed, you need to edit the main script to configure it and declare your Heatzy account and your MQTT server.

# nano /usr/local/sbin/heatzy2mqtt

# -----------------------
# User configuration
# -----------------------

# Heatzy state refresh cycle (in seconds)

# Heatzy account

# MQTT account

You can now enable & start the systemd service and check its status :

# systemctl enable heatzy2mqtt.service
# systemctl start heatzy2mqtt.service
# systemctl status heatzy2mqtt.service
● heatzy2mqtt.service - MQTT gateway for Heatzy pilot devices
Loaded: loaded (/etc/systemd/system/heatzy2mqtt.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2019-02-21 23:46:42 CET; 19s ago
Main PID: 13712 (heatzy2mqtt)
Tasks: 4 (limit: 4915)
CGroup: /system.slice/heatzy2mqtt.service
├─13712 /bin/bash /usr/local/sbin/heatzy2mqtt --start
├─13713 mosquitto_sub --host --port 883 --qos 1 --username your-mqtt-login --pw your-mqtt-password --verbose --topic your/heatzy/topic/+/command
├─13715 /bin/bash /usr/local/sbin/heatzy2mqtt --start
└─13716 sleep 120

4. Usage

4.1. MQTT Subscription

You can now use a MQTT subscriber client like mosquitto_sub  to listen to your/heatzy/topic topic from your broker.

You'll receive :

  • a complete update of your Heatzy heaters after every refresh cycle duration (as set in your configuration section)
  • an update after every change state command

# mosquitto_sub --verbose --host --port 883 --username your-mqtt-login --pw your-mqtt-password --topic your/heatzy/topic/#
your/heatzy/topic/6uKAAAAAAAAGyEA6NbNVaC/state 3
your/heatzy/topic/6uKAAAAAAAAGyEA6NbNVaC/name First heater
your/heatzy/topic/TR6AAAAAAAAizDJ3fvsLe/state 2
your/heatzy/topic/TR6AAAAAAAAizDJ3fvsLe/name Second heater
your/heatzy/topic/list 6uKAAAAAAAAGyEA6NbNVaC;TR6AAAAAAAAizDJ3fvsLe
your/heatzy/topic/6uKAAAAAAAAGyEA6NbNVaC/command 1
your/heatzy/topic/6uKAAAAAAAAGyEA6NbNVaC/state 1

4.2. MQTT publising

The last 2 lines are the result of a MQTT state publishing done with publisher client mosquitto_pub in another console :

# mosquitto_pub --host --port 883 --username your-mqtt-login --pw your-mqtt-password --topic your/heatzy/topic/6uKAAAAAAAAGyEA6NbNVaC/command --message 1

You've just switched off your Heatzy heater by sending a message to your MQTT broker.

You should see the state change on your electrical heater or on your Heatzy official client.

heatzy smartphone client

5. OpenHab Integration

Once your Heatzy to MQTT gateway is up and running, you can declare your Heatzy heaters as MQTT devices in any OpenHab server.

These devices will have 5 different states identified by numerical values :

  • 0 : Offline
  • 1 : Switched off
  • 2 : Comfort
  • 3 : Economy
  • 4 : Frost

First step is to declare one MQTT thing per Heatzy heater, with separate state and command topics.

Every heater is declared using its own DID in the topic path.

Bridge mqtt:broker:mosquitto [ host="", secure=false, username="your-mqtt-login", password="your-mqtt-password" ]
   Thing topic yourfirstheatzy "Your first Heatzy" {
       Type number : power "Power" [ stateTopic="your/heatzy/topic/6uKAAAAAAAAGyEA6NbNVaC/state", commandTopic="your/heatzy/topic/6uKAAAAAAAAGyEA6NbNVaC/command" ]
   Thing topic yoursecondheatzy "Your second Heatzy" {
       Type number : power "Power" [ stateTopic="your/heatzy/topic/TR6AAAAAAAAizDJ3fvsLe/state", commandTopic="your/heatzy/topic/TR6AAAAAAAAizDJ3fvsLe/command" ]

Second step is to declare heaters as items thru their respective MQTT channel :

// Heatzy heaters
Number First_Heatzy_Heater "First heater" {channel="mqtt:topic:mosquitto:yourfirstheatzy:power"}
Number Second_Heatzy_Heater "Second heater" {channel="mqtt:topic:mosquitto:yoursecondheatzy:power"}

Final step is to integrate Heatzy items in a sitemap to display them :

sitemap heatzy label="Heaters" {
  Frame label="Heaters" {
    Selection item=First_Heatzy_Heater mappings=[0="Offline",1="Off",2="Comfort",3="Economy",4="Frost"]
    Selection item=Second_Heatzy_Heater mappings=[0="Offline",1="Off",2="Comfort",3="Economy",4="Frost"]

You can now control your Heatzy heaters from OpenHab with the help of the Heatzy to MQTT gateway.

heatzy mqtt openhab


Hope it helps.

Signature Technoblog

This article is published "as is", without any warranty that it will work for your specific need.
If you think this article needs some complement, or simply if you think it saved you lots of time & trouble,
just let me know at This email address is being protected from spambots. You need JavaScript enabled to view it.. Cheers !

icon linux icon debian icon apache icon mysql icon php icon piwik icon googleplus