Search

Linux - Manage your Heatzy pilote devices

Contents[Hide]

dropcap heatzy

Heatzy is a french startup which manufactures some nice IOT devices. I recently got some Heatzy pilote wifi devices that you connect to any electrical heater thru a French technology called 'fil pilote'. Once connected to your wifi network, these devices allow you to control your electrical heaters over internet from any smartphone (IOS or Android) with their proprietary app.

A nice thing about Heatzy is that they lately made their devices manageable thru some public API called Gizwits Open API.

Based on these API, I decided to write two Linux tools to control these devices :

  • a small bash script to control Heatzy pilote devices from command line
  • a simple GUI to illustrate usage of this script

Why a bash script ? First because bash programming is fun. Next, and most important, because a bash script can be used by any type of application : a GUI, a cron task, a web server, a domotic solution, … This opens some simple yet powerful interconnection capabilities.

This article explains the main principles and usages of a bash script in charge of the complete management of some Heatzy pilote devices. It has been tested with Debian and Ubuntu workstations.

If you are not interested with the technical explanations and you just want to control your Heatzy pilote devices from your Linux workstation, you can jump to the paragraph Complete installation procedure.

1. API usage basics

This section explains the main Heatzy pilote management commands available thru Heatzy API.

These commands are the one used by the management script explained later in this article.

To control your Heatzy pilote devices, you first need to create your Heatzy account.

This account can be created from Heatzy smartphone app or from Heatzy web site.

You'll be identified with an email and a password, which are needed by the API.

1.1. Generate a token

Every command you issue to Heatzy API are using a 7 days validity token.

If a token is not provided or if your token is invalid, here is the result you'll get :

Terminal
{"error_message":"token invalid!","error_code":9004,"detail_message":null}

Here is the command you need to issue to get a valid token where you need to provide :

  • your Heatzy account login
  • your Heatzy account password
  • Heatzy application id (c70a66ff039d41b4a220e198b0fcc8b3)

Terminal
# curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Gizwits-Application-Id: c70a66ff039d41b4a220e198b0fcc8b3' -d '{ "username": "This email address is being protected from spambots. You need JavaScript enabled to view it.", "password": "your-password", "lang": "en" }' 'https://euapi.gizwits.com/app/login'
{"token": "53ce2780419841e7b9e038658ac3e218", "uid": "6c7abae3141541f6bb46b8b7e58d030f", "expire_at": 1524388319}

1.2. List your devices

Once you've got your account token, you can list all devices associated with your Heatzy account.

Terminal
# curl -X GET --header 'Accept: application/json' --header 'X-Gizwits-User-token: token-generated-earlier' --header 'X-Gizwits-Application-Id: c70a66ff039d41b4a220e198b0fcc8b3' 'https://euapi.gizwits.com/app/bindings?limit=20&skip=0'
{"devices": [{"protoc": 3, "ws_port": 8080, "port_s": 8883, "is_disabled": false, "gw_did": null, "wifi_soft_version": "04020017", "dev_alias": "device1-alias", "mesh_id": null, "is_online": false, "host": "eum2m.gizwits.com", "dev_label": [], "port": 1883, "remark": "range=5|isdelete=1|gid=0|groupname=|grouprange=0", "did": "device1-did", "mac": "device1-mac", "product_key": "device1-productkey", "wss_port": 8880, "role": "special", "is_sandbox": false, "passcode": "device1-passcode", "type": "normal", "product_name": "Heatzy"}, {"protoc": 3, "ws_port": 8080, "port_s": 8883, "is_disabled": false, "gw_did": null, "wifi_soft_version": "04020017", "dev_alias": "device2-alias", "mesh_id": null, "is_online": false, "host": "eum2m.gizwits.com", "dev_label": [], "port": 1883, "remark": "range=3|isdelete=1|gid=0|groupname=|grouprange=0", "did": "device2-did", "mac": "device2-mac", "product_key": "device2-productkey", "wss_port": 8880, "role": "special", "is_sandbox": false, "passcode": "device2-passcode", "type": "normal", "product_name": "Heatzy"}]}

1.3. Get device detail with DID

You can also get a single device description by providing the device-did within the URL.

Terminal
# curl -X GET --header 'Accept: application/json' --header 'X-Gizwits-User-token: your-token' --header 'X-Gizwits-Application-Id: c70a66ff039d41b4a220e198b0fcc8b3' 'https://euapi.gizwits.com/app/devices/device1-did'
{"ws_port": 8080, "port_s": 8883, "is_disabled": false, "mac": "device1-mac", "is_online": true, "wss_port": 8880, "remark": "range=2|isdelete=1|gid=0|groupname=|grouprange=0", "did": "device1-did", "host": "eum2m.gizwits.com", "product_key": "device1-productkey", "port": 1883, "role": "special", "passcode": "device1-passcode"}

If device is not found you'll get this error message :

Terminal
{"error_message":"device not bound!","error_code":9017,"detail_message":null}

1.4. Get device state

This call will give you the actual state of a Heatzy pilote. Device is targeted with its did.

According to the returned mode you get the device state :

  • \u505c\u6b62 for Off
  • \u8212\u9002 for Comfort
  • \u7ecf\u6d4e for Eco
  • \u89e3\u51bb for Anti-Freeze

Terminal
# curl -X GET --header 'Accept: application/json' --header 'X-Gizwits-Application-Id: c70a66ff039d41b4a220e198b0fcc8b3' 'https://euapi.gizwits.com/app/devdata/device-did/latest'
{"did":"device-did","updated_at":1523792708,"attr":{"mode":"\u505c\u6b62"}}

1.5. Set device state

This call will allow you to set the actual state of a Heatzy pilote device. Device is again targeted with its did.

As you control the device, you'll need to provide a valid token.

To set the state of device, you need to set the raw value accordingly :

  • [1,1,3] for Off
  • [1,1,0] for Comfort
  • [1,1,1] for Eco
  • [1,1,2] for Anti-Freeze

Terminal
# curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Gizwits-User-token: your-token' --header 'X-Gizwits-Application-Id: c70a66ff039d41b4a220e198b0fcc8b3' -d '{"raw": [1,1,0]} ' 'https://euapi.gizwits.com/app/control/device-did'

2. Complete installation procedure

All scripts and ressources explained later in this article can be installed very easily on any modern Debian or Ubuntu workstation.

If you plan to use the GUI, just make sure to install yad from your repositories.

Installation script is provided on my GitHub account.

Terminal
# wget https://raw.githubusercontent.com/NicolasBernaerts/debian-scripts/master/heatzy/heatzy-install.sh
# chmod +x ./heatzy-install.sh
# ./heatzy-install.sh

You can now control your Heatzy pilote devices from command line or from a desktop GUI.

3. Heatzy Pilote Script

I wrote this Heatzy management script to handle few things :

  • log to your Heatzy account
  • generate or refresh an access token (valid for 7 days)
  • list all devices associated with your account
  • access your Heatzy pilote devices thru their alias, MAC address or device identifier (did)
  • get your devices state
  • set your devices state

This command line script opens lots of possibilities :

  • management thru a GUI
  • interface with domotic apps (like domoticz)
  • planification thru cron scripts
  • command thru a web interface

heatzy script provides an embedded help.

Terminal
# heatzy
Tool to manage Heatzy devices thru Web API
Actions are :
--update Update devices list
--get Get device state ( off comfort eco freeze )
--set Set device state ( off comfort eco freeze )
Options are :
--did Select device by did
--mac Select device by mac address
--alias Select device by alias (remove any space)
--silent Silent mode (no display)
--login Set heatzy account login
--password Set heatzy account password
Configuration file is /home/your-account/.config/heatzy.conf

3.1. Configuration

By default, configuration file is stored under $HOME/.config/heatzy.conf

It can of course be placed anywhere on your server. You'll just need to adjust new location in heatzy main script.

$HOME/.config/heatzy.conf
[user]
login=This email address is being protected from spambots. You need JavaScript enabled to view it.
password=your-password

[application]
appid=c70a66ff039d4444a220e198888cc8b3
token=your-token
expiry=toyen-expiry-date

[devices]
device1-did=device1-mac;device1-alias
device2-did=device2-mac;device2-alias
device3-did=device3-mac;device3-alias

The account which will run heatzy Bash script should have read and write access to this configuration file.

For example, if you plan to run the bash script from any page served by Apache web server, it should be readable and writable by www-data.

All parameters handled by the heatzy script will be stored in this file :

  • Your account login and password
  • Heatzy appid identifier
  • Your latest access token
  • Your Heazy devices information (did identifiers, mad address and alias)

File will be populated after your first heatzy script call.

Once populated, this configuration file will make next calls much easier as :

  • you won't have to provide your login & password anymore
  • your valid token will be used automatically
  • you can target your devices by their did, mac address or alias

3.2. Script Usage

heatzy script should be first called to list your Heatzy devices.

This is the only time you'll need to provide your Heatzy account login and password.

Terminal
# heatzy --login "This email address is being protected from spambots. You need JavaScript enabled to view it." --password "your-heazy-password" --update
Device device1-alias
    Did : device1-did
    Mac : device1-mac
    Version : 04020017
    Online : true
Device device2-alias
    Did : device2-did
    Mac : device2-mac
    Version : 04020017
    Online : true
Token expires on xxxxxxx, hh:mm:ss (UTC+0100)

If everything runs fine you should get a list of Heatzy devices registered with your account.

You can now access your devices by using either their did, mac address or alias (name given to the device in the smartphone app).

You can now read your device state with the --get parameter.

Available states are off, comfort, eco, anti-freeze and offline.

Terminal
# heatzy --alias "device1-alias" --get
off
# heatzy --did "device2-did" --get
comfort
# heatzy --mac "device3-mac" --get
eco

You also set your device state with the --set parameter.

Possible states are off, comfort, eco and anti-freeze.

Terminal
# heatzy --alias "device1-alias" --set comfort
# heatzy --did "device2-did" --set eco
# heatzy --mac "device3-mac" --set anti-freeze

You can now control your electrical heaters from a simple bash script !

4. Heatzy management GUI

Once installed from my GitHub account, Heatzy pilote management GUI is available from the utilities menu.

It allows you to manage very easily your Heatzy pilote devices straight from your desktop.

It uses Heatzy pilote management script and yad to allow you to :

  • Enter your Heatzy login and password
  • Display your devices state
  • Set your devices state

Application integration whithin Gnome Shell desktop is done with the help of heatzy.desktop.

heatzy login

heatzy gui

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