MAX! HOME AUTOMATION
version 1.6
by Dmitry A. Kazakov

(mailbox@dmitry-kazakov.de)
[Home]

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


MAX! home automation is a GTK+ application to manage ELV/eQ-3 MAX! cubes. A cube is a gateway to a network of radiator thermostats, shutter contacts etc.

      ARM Intel
Download MAX! home automation Platform:   v7 64- 32bit
Fedora packages fedora      precompiled and packaged using RPM     [Download page] [Download page] [Download page]
CentOS packages CentOS   precompiled and packaged using RPM       [Download page] [Download page]
Debian packages debian   precompiled and packaged for dpkg   [Download page] [Download page] [Download page]
Windows installer   max_home_automation_x86.msi.gz (installer + gzip, Windows users may use WinZip)   [Download]
Source distribution (any platform)   max_home_automation_1_6.tgz (tar + gzip, Windows users may use WinZip)   [Download]

Note: Some browsers have issues with downloading max_home_automation_x86.msi.gz file correctly. Chrome, MS Edge and older versions of Firefox are known for doing it wrong. When unpacking of the downloaded file fails to produce single installer file max_home_automation_86.msi, try to use another browser or else wget. Wget is a GNU command line program for reliable downloading available for Windows and Linux. Wget command to download is:

wget http://www.dmitry-kazakov.de/ada/max_home_automation_x86.msi.gz

See also the changes log.


[TOC][Next]

1. Use

When the application starts is scans the local area network (LAN) for connected MAX! cubes. Once a cube is found the radio network topology is shown on the overview pane:

1.1. Overview pane

 

Depending on the LAN configuration it could be impossible to find the cube. In that case the address of a MAX! cube can be entered manually after pressing the button . Note the bar near the cube address. It indicates the amount of 800 MHz radio traffic used by the cube. The traffic is limited. When the limit is exhausted the cube stops transmitting commands controlling the thermostats. The limit is reset each hour.

When a thermostat is selected its operating mode can be changed in the combo box:

Additional parameters like vacation end time and set temperature appear. The mode is changed by pressing the mode set button . Note that the cube performs mode change asynchronously. It could take a considerable time before the thermostat reacts to the change. While doing that the cube continues to report the previous operation mode. When the thermostat ultimately changes the mode and the cube becomes aware of that, the actual mode gets reflected on the overview panel.

1.2. Thermostat settings pane

The thermostat settings and time schedule is shown when the configure device button is clicked:

For each week day you can define thermostat temperatures, maximum up to 13 points per day. Each point defines the temperature and the time until the thermostat must keep that temperature. The time resolution is 5 minutes. The temperature resolution is 5 Centigrade.

The day schedule points are automatically sorted according to the time column. If you have to insert a new point enter it into any unused row. Multiple points can be copied. The whole week schedule can be taken from another thermostat when the copy from button is pressed:

A week thermostat schedule can be written into and read from a file. The file format is portable across supported operating systems.

1.3. Trace pane

The trace pane indicated the exchange with the cube:

1.4. Graphs pane

The graphs page contains one pane per room. A room's pane has stacked oscilloscopes one per thermostat indicating the measured temperature:

When the room contains a wall-mounted thermostat all radiator thermostats are managed by it. The graph pane of such managed room indicates only the temperature of the wall-mounted thermostat. When the room has only radiator thermostats their graphs are shown stacked.

1.5. Scanning temperatures measured by radiator thermostat

The application deploys a technique forcing radiator thermostats to report measured temperatures. A radiator thermostat installed in the room managed by a wall-mounted thermostat reports the temperature measured by the wall-mounted thermostat instead of its own temperature. When installed in an unmanaged room with no wall-mounted thermostats a radiator thermostat reports its own measured temperature but only when either its valve position is changed or its operating mode is. For such "unmanaged" thermostats the application temporarily alters the thermostat mode from automatic to manual or conversely, when there no recent measured temperature known. As soon as the thermostat refreshes the measured temperature it is switched back to the original mode.

The following parameters on the settings page control this scanning behavior:

1.6. Cube discovery

The application's setting pane controls the method cubes are discovered and connected.

1.7. Saving and restoring thermostat configurations

When a cube is selected configurations of all its radiator thermostats can be stored into and restored from a file. The items saved are:

Upon restoring configuration the following pane is shown:

Upon reading the file application tries to match addresses or names of the saved thermostats with the addresses and names of existing thermostats. The match is shown in the column get from. The column contains combo-boxes where another source thermostat or no thermostat can be selected. When no thermostat address is selected in the combo box, the existing thermostat's configuration is not touched. Additionally the items to restore can be selected in the check boxes below.

Note that restoring configurations of many thermostats requires much of radio traffic. When the exhausted the cube will stop accepting commands. The bar at the cube address will show 100% and an exclamation sign will appear. After that an hour is required to wait until restoring can be continued. Successfully restored thermostat configurations are skipped. The retry button starts failed configuration over again.


[Back][TOC][Next]

2. HTTP automation

The application has an integrated HTTP server than can be used to control the connected cubes. The server is disabled by default. It can be enabled through the settings pane. The HTTP server port can be set to a value different from the standard 80, when it is already used. The server supports the HTTP GET requests described below:

2.1. Querying a device status

http://<max-home-automation>/get-status?cube=<address>&device=<address>

Here <max-home-automation> is the name or IP-address of the server. <address> is the RF address (hexadecimal) of the cube and the device correspondingly. For example, assuming accessing the server at the localhost:

http://127.0.0.1/get-status?cube=0BB8F0&device=10A40C

The server response describes the current device status in textual format. Its components depend on the device type. When device address is absent the response lists statuses of all devices controlled by the cube. Individual parts of the status can be queried by the following queries

http://<max-home-automation>/get-status-json?cube=<address>&device=<address>

This query is analogous to get-status except that it reports the status of a device or of all available devices in the JSON's parse format.

http://<max-home-automation>/get-battery?cube=<address>&device=<address>

This query is responded with the current battery level of a device. The returned value is high or low.

http://<max-home-automation>/get-link?cube=<address>&device=<address>

This query is responded with the radio link of a device. The returned value is error or ok.

http://<max-home-automation>/get-mode?cube=<address>&device=<address>

This query is responded with the current mode of a thermostat. The returned values are automatic, manual, boots, vacation.

http://<max-home-automation>/get-temperature?cube=<address>&device=<address>

This query is responded with the current temperature measured by a wall-mounted thermostat in Centigrade.

http://<max-home-automation>/get-set-temperature?cube=<address>&device=<address>

This query is responded with the current set temperature of a thermostat in Centigrade.

http://<max-home-automation>/get-summer-time?cube=<address>&device=<address>

This query is responded with the device summer time settings. The returned value is yes or no.

http://<max-home-automation>/get-valve?cube=<address>&device=<address>

This query is responded with the current valve position of a radiator thermostat 0-100%. The value 100% corresponds to the fully opened valve.

2.2. Setting a thermostat into automatic mode

http://<max-home-automation>/set-automatic?cube=<address>&device=<address>

For example:

http://127.0.0.1/set-automatic?cube=0BB8F0&device=10A40C

2.3. Setting a thermostat into boost mode

http://<max-home-automation>/set-boost?cube=<address>&device=<address>

For example:

http://127.0.0.1/set-boost?cube=0BB8F0&device=10A40C

2.4. Setting a thermostat into manual mode

http://<max-home-automation>/set-manual?cube=<address>&device=<address>&temperature[+|-]=<value>

The temperature is specified by the parameter <value>. It can be a relative or absolute value. For example an absolute temperature specification:

http://127.0.0.1/set-manual?cube=0BB8F0&device=10A40C&temperature=18.5

Here the thermostat 10A40C is set to keep 18.5 Centigrade. The following is a example of setting the temperature relative to the current one:

http://127.0.0.1/set-manual?cube=0BB8F0&device=10A40C&temperature+=0.5

In this example  the temperature is incremented by 0.5 Centigrade.

2.5. Setting a thermostat into vacation mode

http://<max-home-automation>/set-vacation?cube=<address>&device=<address>&temperature[+|-]=<value>&{weeks|days|hours|minutes}=<count>

For the vacation mode again the temperature can be specified relative or absolute. The vacation end time is given as a number <count> of weeks, days, hours or minutes. For example:

http://127.0.0.1/set-vacation?cube=0BB8F0&device=10A40C&temperature=16&days=2

Here the thermostat 10A40C is set to keep 16 Centigrade for two days. After that it will switch back into its previous mode.


[Back][TOC][Next]

3. MQTT automation

The integrated MQTT server allows access and control of the cubes through the Message Queueing Telemetry Transport (MQTT). MQTT is an ISO standard (ISO/IEC PRF 20922) messaging protocol. By default the MQTT server is disabled. It is enabled through the settings pane.

3.1. Published topics

The server publishes data received from the cube as retained topics:

Topic Contents
/<cube-address>/shutter contact/<device-address>/battery low, high
/<cube-address>/shutter contact/<device-address>/status open, close
/<cube-address>/radiator thermostat/<device-address>/battery low, high
/<cube-address>/radiator thermostat/<device-address>/mode automatic, manual, boost, vacation
/<cube-address>/radiator thermostat/<device-address>/set temperature 19.0
/<cube-address>/radiator thermostat/<device-address>/temperature 19.5
/<cube-address>/radiator thermostat/<device-address>/valve 30
/<cube-address>/wall thermostat/<device-address>/battery low, high
/<cube-address>/wall thermostat/<device-address>/mode automatic, manual, boost, vacation
/<cube-address>/wall thermostat/<device-address>/set temperature 19.0
/<cube-address>/wall thermostat/<device-address>/temperature 19.5

Here <cube-address> is the RF address (hexadecimal) of the cube. <device-address> is the RF address of the device. All topics are retained, that means a client may subscribe to them at any time and get the latest values of.

3.2. Controlling thermostats

A thermostat can be controlled by publishing a special topics on the server. The server does not propagate or retain these topics.

Topic Contents
/<cube-address>/set/<address>/automatic -
/<cube-address>/set/<address>/boost -
/<cube-address>/set/<address>/manual [+|-]<temperature>
/<cube-address>/set/<address>/vacation [+|-]<temperature> <count>{weeks|days|hours|minutes}

Here <cube-address> is the RF address (hexadecimal) of the cube. <device-address> is the RF address of the device, which must be a thermostat. <temperature> is the temperature to set. When a sign is used the temperature is relative to the actual set value. <count> is the number of weeks, days, hours, minutes as specified.


[Back][TOC][Next]

4. Running headless and other issues

4.1. Headless

In order to run the application headless under Linux use the following command (bash):

>xvfb-run -a max_home_automation

Here Xvfb is X virtual frame buffer, an X11 server that uses memory instead of a physical display. You might need to install it on your system if the package xvfb is not there.

4.2. Running remotely

Before running the application headless you might wish to change some settings or monitor how things work in general. You can run it remotely using the PC's X11 local server as the display for the remotely running program.

Linux. Under Linux you use SSH with X11 forwarding. The command line looks like follows:

>ssh -X -v <user>@<host> max_home_automation

Here <user> is the user you want to log in and <host> is the address or name of the machine where you want to run it, e.g. on your headless Raspberry PI. On the other side you must have the SSH daemon running.

Windows. Under Windows you need a X11 server and SSH client. There is a software that combines both: MobaXterm. Under MobaXterm you can configure an SSH session with X11 forwarding.

4.3. Permission denied

When you get error 13 permission denied upon HTTP start, that is because you lack permissions to bind the socket to the port 80. Usually only root can use ports with numbers below 1024 while the default HTTP port is 80. You may use another port or else run the software as root.


[Back][TOC][Next]

5. Building from sources

The program uses Simple Components for Ada, GtkAda contributions which are distributed with it. In order to compile it, GtkAda must be installed first. Then with GNAT compiler it can be build using the following command:

>gprbuild -XDevelopment=Release -p -P max_home_automation.gpr

issued in the directory containing the sources. You can also use the max_home_automation.gpr project with the GPS and compile it from there.


[Back][TOC][Next]

6. Changes log

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (21 November 2016) to the version 1.5:

Changes (25 July 2016) to the version 1.4:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (31 May 2016) to the version 1.3:

The following versions were tested with the compilers:

and the GtkAda versions:

Changes (13 April 2016) to the version 1.2:

Changes (5 March 2016) to the version 1.1:

Changes (18 October 2015) to the version 1.0:

Version 1.0 released (24 August 2015).


[Back][TOC]

7. Table of Contents

1. Use
2. HTTP automation
3. MQTT automation
4. Runnung headless and other issues
5. Building from sources
6. Changes log
7. Table of Contents