Integración domótica MAX! Cube, gratuita y de código abierto

Unofficial: eQ-3 MAX! Cube on your network: radiator and wall thermostats, window contacts.

• Publicado por LM1LC3N7
• Dispositivos
• Versión 0.1.2
• Requiere Gladys >=5.1.0
• ★ 0

Ver en GitHubTodas las integraciones

info

La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.

Your eQ-3 MAX! heating system in Gladys, through the local port of the MAX! Cube (TCP 62910) on your network, without any cloud:

• radiator thermostats (MAX! Heating Thermostat and Thermostat+): room temperature (when the Cube gives one), setpoint, mode (auto, heating, off), MAX! mode (auto, manual, vacation, boost), heating state and valve opening (%), battery low, radio link error;
• wall thermostats (MAX! Wall Thermostat): temperature, setpoint, mode, MAX! mode, battery, link;
• window contacts (MAX! Shutter Contact): open / closed, battery, link;
• the Cube itself: radio duty cycle (%) and free command slots.

This integration has never been tested with a real Cube. This first version was written from the protocol description (Bouni/max-cube-protocol) and the python-maxcube-api library (the one of Home Assistant), and tested only against a fake Cube. Say on the Gladys forum what works and what does not.

Unofficial integration, not affiliated with eQ-3. The MAX! hardware is no longer made, but it remains widely installed; the eQ-3 portal is not used.

What you need

• A MAX! Cube (the LAN gateway) on your network, with its devices already paired and sorted by room in the MAX! software (the names of the rooms and devices come from there). Push buttons (MAX! Eco Switch) are ignored.
• A Cube accepts one client at a time. By default, Gladys keeps its connection open: the MAX! software cannot connect meanwhile. Untick Keep the connection open so that Gladys only opens a connection for the time of a read or a command; the MAX! software can then connect between two reads.

Configuration

• Cube address: its IP address on your network (192.168.1.40), shown by your router or the MAX! software; a port may follow (62910 by default). Prefer the IP address: a .local name (mDNS) does not resolve inside the container of the integration. Give the Cube a fixed address in your router; if it changes, type the new one: the devices and their history are kept (they are known by their serial numbers). No password: the Cube asks for none on its local port.
• Allow the setpoint commands and Allow the mode commands: off by default (see Commands).
• Keep the connection open: ticked by default (see above).
• Language of the devices: French (default) or English.

Then open the Discover tab and create the devices to follow. The devices are named Room - Name after the MAX! software. The Test the connection button reads the Cube and lists what it shows; it never reads the Cube again less than a minute after the previous read (it then shows the last read), but it does not wait for the retry pause after a failure.

Readings

• The Cube is read every minute (its own memory, no radio traffic: the MAX! devices report to the Cube at their own pace, and the Cube keeps their last values). With the connection kept open, a device that reports to the Cube is shown at once. Only the values that change are sent to Gladys (and each one at least every 10 minutes).
• The temperature of a radiator thermostat is only given by the Cube now and then (when the valve moves, in auto or manual mode); the one of a wall thermostat is at each read (per the protocol description). A device the Cube has not heard yet (no values) shows as unreachable and the status says so.
• The mode follows the modes of Gladys: auto (3) when the thermostat follows its weekly programme, heating (1) in manual, boost or vacation, off (0) when the setpoint is 4.5 °C (valve closed). The MAX! mode (text: auto, manual, vacation, boost) gives the detail.
• The window contact is 1 closed, 0 open (the opening sensor of Gladys).
• Only the values the Cube marks valid are shown: a device whose entry is not valid or not initialized, or that reports a radio link error, only shows its flags (battery low, link error), shows as unreachable, and the status says so. The radio budget of the Cube is only shown when less than 10 minutes old (the Cube resets it every hour).
• A message of the Cube that cannot be read for one device (its configuration, an entry too short) does not stop the reading of the others. Two devices on the same radio address are left out (the log gives their number).
• The names of the rooms and devices are read again at each new connection (every 6 hours at the latest with the connection kept).

Commands

By default, Gladys only reads, and can stop a thermostat (the stop needs no option). Once an option is ticked, the dashboard, the scenes, the voice assistants (Siri / HomeKit, Alexa, Google Home) and the Thermostat service of Gladys can also set the setpoint or switch to heating or auto. As the MAX! software does, each command is sent to the whole room of the thermostat (the thermostats of a room are linked).

Off (mode 0)

Off puts the thermostat in manual at 4.5 °C, the "off" setpoint of MAX! (valve closed). It needs no option, no bounds and no values of the device: only the device in the list of the Cube. It is sent even when the device seems off already. It goes before the other commands:

• the commands of the same room asked before it and not sent yet are cancelled ("cancelled: a stop was asked");
• a read of the Cube without answer for 1 s, or a connection whose greeting has been silent for 1 s (not a byte), is cut (a younger read is waited for: the Cube answers it in a few milliseconds);
• it only waits for the answer to a command already sent (2 s at most);
• after a connection is closed, it waits for the Cube to free its slot (it accepts one client), then opens again; whatever keeps it from leaving (a connection refused or closed, a greeting that does not come, a previous command without answer) is tried again every 250 ms, within the 3.5 s that follow the command.

The thermostat applies its own frost protection as described by eQ-3: check the manual of your device before leaving a radiator off in winter.

An off command that could not leave within these 3.5 s is not dropped: Gladys answers "not sent yet", the status of the integration says so, and it leaves at the next read of the Cube (5 s later), 3 tries at most. Off is refused only when: the address of the Cube is not set or the configuration is not loaded yet; the configuration changes during the command; the device is no longer paired with the Cube. Once sent, it can be discarded by the Cube (radio budget of the hour used up, or no free slot) or queued by it; Gladys says so.

It is then checked: the Cube is read again 5 s, 30 s, 1 min and 2 min after it. When the thermostat does not show it 1 min after the send, it is sent again, 3 times at most (not while the fresh radio budget of the Cube is at 90 % or more); when it is still not applied 2 min after the last send (radio budget included), the logs and the status of the integration say so ("the stop was not applied by ..."), until the device shows it. A newer command accepted for the same room (setpoint, heating, auto), sent or already so, replaces the stop: it is then no longer sent, nor sent again.

Setpoint, heating, auto

• Allow the setpoint commands: the setpoint of a radiator or wall thermostat, 5 to 30 °C, rounded to the half degree (the resolution of the thermostat), within the bounds set on every thermostat of the room (the Cube gives them); a value outside is refused, never brought back into the bounds. In auto mode, the setpoint holds until the next switch point of the weekly programme; otherwise it puts the thermostat in manual (a boost or a vacation under way ends).
• Allow the mode commands (auto, heating):
  • auto (3): back to the weekly programme of the device;
  • heating (1): manual at the current setpoint, or at the comfort temperature set on the device when the valve was closed;
  • cooling (2): refused, a MAX! thermostat does not cool.
• Just before acting, Gladys asks the Cube for its live values and decides on that read only. One of these commands is not sent when:
  • the option is unticked (checked when the command arrives and again just before sending), or the configuration is not loaded yet;
  • the value is not a number from 5 to 30 °C, or the mode is not 1 or 3;
  • the thermostat is off and only the setpoint is allowed (a setpoint would start it again: "switch it to heating or auto");
  • the device is no longer paired; the Cube has no values for it; its values are marked not valid or it reports a radio link error;
  • the bounds of the thermostats of the room leave no value; heating needs the comfort temperature and the Cube does not give it;
  • the radio budget of the Cube (given less than 10 min ago) reaches 90 % or it has no free slot (the command would wait up to an hour);
  • the read fails or does not end in time, the configuration changes, or a stop of the same room is asked meanwhile;
  • the value asked is already the one of every thermostat of the room (nothing to do, the command is acknowledged).
• These commands run one after the other (one Cube, one connection).
• A command not seen on the device 2 min after its send is said in the logs (not sent again).

Delays

The delays are measured on the monotonic clock of the container (a change of the time of day does not change them). When a command cannot be sent within the 3.5 s that follow its arrival, nothing is sent and Gladys shows a failure. Once sent, Gladys gets an answer at most 4.3 s after the command arrived: "accepted by the Cube" when the Cube answered that it passes it over the radio, "sent, without confirmation" when it has not answered yet, "queued" or "discarded" after its answer. The Cube does not confirm that the thermostat applied the command: it is checked on the follow-up reads (see above); the value shown is always the one the Cube gives, never the one asked.

The weekly programme, the boost, the vacation mode, the comfort and eco temperatures, the temperature offset and the pairing stay in the MAX! software.

Connection problems

• Cube unreachable or not answering: every device shows as unreachable; new try after 1 min, then less and less often up to every 10 min (never faster than the normal read). The most common cause: another client (the MAX! software, another integration) holds the connection of the Cube.
• This address does not answer like a MAX! Cube: the address or the port (62910) is wrong, or another service answers.
• After a restart of the integration, the reading loop does not read the Cube again less than a minute after the previous read (the time of the last read is kept in /data); a command reads it just before acting, and the reads that follow a command take place 5 s, 30 s, 1 min and 2 min after it.
• The logs hold nothing of what the Cube sends (no serial numbers, names or values): only our own words, the kind of device ("thermostat", "wall") and numbers (no connection, no answer in time...). The status of the integration names the devices (room and name) whose stop was not applied.

Limits

• One Cube per integration.
• No boost, vacation mode, weekly programme, comfort / eco temperatures, pairing or removal of devices from Gladys.
• Push buttons (Eco Switch) are not published.
• Never tested with a real Cube.

Parámetros de configuración

Estos son los parámetros que MAX! Cube te pide en su pantalla de configuración en Gladys.

Parámetro	Tipo	Obligatorio	Descripción
How it works	section	No	Unofficial integration, not affiliated with eQ-3. Gladys reads your MAX! Cube through its local port (62910), on your network, without any cloud: every minute, the temperature, the setpoint, the mode, the valve opening and the battery of the radiator thermostats, the temperature and setpoint of the wall thermostats, the open / closed state of the window contacts. The setpoint and the mode can be commanded, each behind an option off by default. A Cube accepts one client at a time: close the MAX! software while Gladys uses it, or untick "Keep the connection open". Never tested with a real Cube: see the documentation.
Cube address	string	Sí	The IP address (or name) of the MAX! Cube on your network, shown by your router or the MAX! software. Give it a fixed address in your router: the devices and their history are kept if it changes (they are known by their serial numbers). A port may follow (62910 by default). No password: the Cube asks for none on its local port.
Commands	section	No	By default Gladys only reads, and stops: the off mode (the valve closed) needs no option. Once an option is ticked, the dashboard, the scenes, the voice assistants (Siri / HomeKit, Alexa, Google Home) and the Thermostat service of Gladys can also set the setpoint or switch to heating or auto. Each of these commands asks the Cube for its live values just before acting. A command goes to the whole room of the thermostat, as the MAX! software does. The weekly programme, the boost and the vacation mode stay in the MAX! software.
Allow the setpoint commands	boolean	No	The setpoint of a radiator or wall thermostat: 5 to 30 °C by half degrees, within the bounds set on every thermostat of the room. A value outside is refused, never brought back into the bounds. On a thermostat that is off, a setpoint also needs the mode commands.
Allow the mode commands (auto, heating)	boolean	No	Auto (the weekly programme of the device) and heating (a fixed setpoint). Off (the valve closed: the setpoint 4.5 °C of MAX!) needs no option: it is accepted with this option unticked. The thermostat applies its own frost protection as described by eQ-3: check the manual of your device before leaving a radiator off in winter.
Keep the connection open	boolean	No	Ticked: one connection to the Cube is kept, and a device that reports is shown at once; the MAX! software cannot connect meanwhile (a Cube accepts one client). Unticked: a connection is opened and closed for each read and each command, so the MAX! software can connect in between.
Language of the devices	select	No	Names of the devices and features.

Cómo instalar MAX! Cube en Gladys

1. En Gladys, abre Integraciones: MAX! Cube aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/lm1lc3n7/gladys-maxcube:0.1.2), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-maxcube.

MAX! Cube requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.

¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.

Sobre las integraciones externas

MAX! Cube es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.

• Explorar todas las integraciones, nativas y de la comunidad
• Crear y publicar tu propia integración externa
• Código fuente en GitHub — fuente de esta documentación

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂