Search

Heatzy - Manage your Heatzy Pilote devices under Linux

Contents[Hide]

dropcap linux 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.

At the time of this article, you find 2 generations of devices :

  • Heatzy (generation 1)
  • Pilote2 (generation 2)

 This article explains the main principles and usages of a bash script in charge of the complete management of Heatzy pilote devices (generation 1 & 2).

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'
{"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.

Heatzy devices (generation 1) will return :

  • \u505c\u6b62 for Off
  • \u8212\u9002 for Comfort
  • \u7ecf\u6d4e for Eco
  • \u89e3\u51bb for Frost free

Pilote2 devices (generation 2) will return :

  • stop for Off
  • cft for Comfort
  • eco for Eco
  • fro for Frost free

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 Heatzy devices (generation 1), 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

To set the state of Pilote2 devices (generation 2), you need to set the attrs / mode value accordingly :

  • stop for Off
  • cft for Comfort
  • eco for Eco
  • fro 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
  • list all available device states
  • get your Heatzy devices data (Alias & MAC address)
  • 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 and Pilote2 devices thru command line
Actions :
--list-state       List available states
--list-device      List devices DID
--update-device    Update and list devices DID
--get-state        Get device state ( off;Stopped comfort;Comfort eco;Economic freeze;Frost free )
--get-mac          Get device MAC address
--get-alias        Get device Alias
--get-product      Get device Product
--set-state        Set device state ( off eco comfort anti-freeze )
Options are :
--login            Heatzy account login
--password         Heatzy account password
--debug            Debug mode (display JSON)
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

[devices]
device1-did=device1-product;device1-mac;device1-alias
device2-did=device2-product;device2-mac;device2-alias
device3-did=device3-product;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-did
device2-did

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

You can now access your devices by using their did.

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

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

Terminal
# heatzy --get-state "device1-did"
off

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

Possible states are off, comfort, eco and freeze.

Terminal
# heatzy --set-state "device1-did" comfort

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 Accessories 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.

While loading configuration from Heatzy servers, you'll get a progress dialog :

heatzy progress

If you've not yet entered your credentials, you'll be prompted to do it :

heatzy login

Then, you'll get your devices state and you'll be able to change it :

heatzy gui

If any change is made, you'll get a Gnome notification.

You can now handle your Heatzy devices straight from your Linux desktop ...

 

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