Converting a MAX! Cube to CUL/CUN to use with Home Assistant

swifty · October 20, 2018, 1:00pm

I have recently managed to successfully flash my Max! EQ3 Cube with a a-culfw firmware.
Once running the new firmware, I expose my EQ3 radiator thermostats to Home Assistant via homegear and the built in component.

This guide will talk through the steps involved - but please heed the warnings, I take no responsibility if you break your kit!

Note that flashing the Max Cube is a one way deal, there isn’t currently any way to restore the default firmware.
Having said that, my cube forgot its configuration often (a common issue) - so it was mostly paper weight anyway.
The firmware I link to on Google Drive is an edited version of the latest a-culfw and compiled by me to remove the credit restrictions.
If you are uncomfortable with this, simply use the prebuilt firmware from the official github page: https://github.com/heliflieger/a-culfw (the Mediafire link in the readme)
Otherwise - the firmware with no credits is here; https://drive.google.com/file/d/1y1L2Tt1iHgdyodw9M-Yxvy0niRtOXEQ2/view?usp=sharing
As I note in the guide, pairing with HomeGear will fail if the device was not unpaired before flashing the cube.
The fix is to factory reset the device, but save yourself some hassle and unpair everything before proceeding

Ok - so on to the good stuff

First, download and install ATMEL SAM-BA 2.x (I used 2.18) from here:- http://ww1.microchip.com/downloads/en/DeviceDoc/SAM-BA%20v2.18%20for%20Windows.exe
Next, either grab the creditless firmware or use the offical firmware with credit restrictions mentioned above.
Lastly, grab Tera Term and install it on your PC: https://osdn.net/projects/ttssh2/releases/

Now, pop open your Cube - this should be fairly easy, just prise a small screwdriver at the notches in the bottom and it should pop right off.
Next you want to take a look at the board and find the two contacts on the board marked J1 - you need to use a paper-clip, or a small bit of wire to short these contacts together.
With the contacts shorted, plug in the USB for the Cube and apply power - count to 5 and remove the power again.

Your cube has now lost it’s mind (literally) - the firmware is gone, and it’s ready to accept a new one.
Remove whatever you used to short the J1 contacts, so that they are no longer connected.

Connect the USB cable back to the cube, and hook it up to your PC that has SAM-BA installed.
If using Windows, wait a moment for it to install the newly detected device - you should see a new COM port in device manager.

Now, start the SAM-BA software and pick your newly added COM port.
Pick your chip type - at91sam7x256-ek
Press the connect button, then click on the ‘Flash’ tab.
Find the section 'Send File Name' and point it at the bootloader_CUBE.bin file.
Press Send File, and wait with excitement…

Once completed, you’ll be prompted with a question asking if you want to lock the flash - Answer ‘No’ to this.

In the scripts drop down, ensure you have 'Boot from Flash (GPNVM2)' selected, and press execute.
Close the ATMEL software and disconnect the USB.

At this point you have the new bootloader flashed to your Cube and it should be ready to accept the a-culfw firmware.

Flashing the a-culfw Firmware

The bootloader is activated by pressing the button located on the bottom of the cube while applying power.

So, press the button and insert the USB cable again - now release the button.
The D1 LED on the cube should be flashing 4x a second if the Cube successfully entered the bootloader, and you should see another new device appear in device manager.

Start Tera Term and pick File -> New Connection -> Serial - Pick the COM port labelled 'AT91 USB to Serial Converter', and press OK.
Select File -> Transfer -> XMODEM -> Send and pick the CUBE_BL.bin file.

It should take less than a minute to flash the firmware - once completed the Cube will reboot and the light flashes 1x per second.

Well done - you now have a CUL/CUN device

The unit can be used via USB (I’ve not tested this) as a CUL, or in the same fashion as the original cube (using the network connection) acting as a CUN device.

HomeGear

Home Gear will act as a layer between the Cube and HomeMatic component for Home Assistant, and will be used to setup the devices you add to the cube.

You have a number of options here :-
A) There is an official image on dockerhub https://hub.docker.com/r/homegear/homegear/
I had a quick play with this, but couldn’t get homegear to load any of the modules - there seemed to be a permission issue inside the container, but I’m no docker expert so I gave up on that and just installed directly.
B) Install on a Linux machine natively (this is what I did as I have a Linux server running 24x7)
Follow the guidance at www.homegear.eu on how to install.

C) @AndrejDelany has kindly put together a preview Hassio add-on for Raspberry Pi - see Converting a MAX! Cube to CUL/CUN to use with Home Assistant

Once you have Home Gear installed you will need to configure it to talk to the cube - to do this, inspect your router/DHCP server and find out what IP has been issued to your Cube.

When you have determined the Cube IP go to your HomeGear install and edit the file /etc/homegear/families/max.conf

Add the following to the config (or uncomment the sample data and edit appropriately)

[CUNX]
id = Max-CUNX
default = true
deviceType = cunx
host = <CUBE_IP_ADDRESS>
port = 2323
responseDelay = 40

This is the config I use for connecting the the Cube via the network connection, if you are going down the USB route, you should use the CUL sample instead - but as previously mentioned, I haven’t tested this option.

Now restart HomeGear so that the new configuration takes effect.

We can use the homegear cli to add a user for HomeAssistant - execute ‘homegear -r’ on your homegear server.
Type: users create <USERNAME> "<PASSWORD>" "1"
(Include those quotes around password and 1…)

At this point it is worth hitting http://<HOMEGEAR_IP>:2001 to make sure you are greeted by the HomeGear RPC Server page, if you are then carry on

Now you need to link your devices to the Cube using homegear - for this I used HomeMatic Manager (https://github.com/hobbyquaker/homematic-manager/releases)
So I’ll talk through the process for using that, but there are a number of clients you can use to manage HomeGear.
Unfortunately the HomeMatic Manager software is in German, and I couldn’t see any way to switch to English, so i’ll include exact steps for the english speakers.

Start up HomeMatic Manager - you should be greeted with a connection screen - input your HomeGear server IP in to the 'CCU Adresse' field and press 'Speichern und Neustarten'.
Note - you may get an error message when the app restarts (I did) but if it shows the IP of HomeGear with a green tick next to the row of tabs, then it should work OK.

Now we need to add the devices you own so they are paired to the cube - to do this, on the ‘Gerate’ tab press the ‘+’ at the bottom of the window.
Next press 'Aniermodus Aktivieren' - this enables pairing mode on the cube, now go to your Max! device and put it to pairing mode as well.
I use the Max! Radiator thermostats, which are put into pairing mode by pressing the adjustment wheel for a few seconds.
After a few seconds of being in pairing mode, your device you show as detected in HomeMatic Manager.

I found it helps to dismiss the pairing screen once a device is paired and right click it on the list, then choose ‘Umbenennen’ then enter a name for the device and press ‘Speichern’.
Now repeat the process for all of your devices…

TIP! - If your device doesn’t appear to be pairing, it is worth taking a look at the HomeGear log - if the device already thinks it is paired, then the log will tell you and reject pairing with the device.
The Max devices can be factory reset using a combination of button presses which should allow it to re-pair - check the manual for your specific device.

Home Assistant Configuration

Now all your devices are added in HomeGear, we can finally get them into HomeAssistant - you should also see them listed if you hit the HomeGear server again at http://<HOMEGEAR_IP>:2001

Add the following to your Home Assistant configuration.yaml:-

homematic:
  local_ip: <HOME_ASSISTANT_IP>
  local_port: 36845
  interfaces:
    wireless:
      host: <HOMEGEAR_IP>
      port: 2001
      callback_ip: <HOME_ASSISTANT_IP>
      callback_port: 36845
      resolvenames: json
      username: <HOMEGEAR_USER>
      password: <HOMEGEAR_PASS>

Restart Home Assistant once added - you should now magically see a bunch of homematic devices appear which correlate with your HomeGear devices.

Note, my device friendly names didn’t pull through from HomeGear to HA - I’ve not looked into this yet, but I simply used the serial numbers to determine which device was which (since the serial is displayed next to the friendly name I assigned in HomeMatic Manager).
Then I added a friendly name using the UI in Home Assistant.

I hope this guide helps someone, please let me know if this works for you, or if I’ve missed anything from the guide!

badgerhome · October 20, 2018, 1:21pm

I’m not familiar with EQ-3 but I’ve been looking for a radiator TRV solution for my home. I’ve been tempted by the Tado valves bit they have mixed reviews.

Does this flashing of firmware on the cube expose both sensors and a method to control / set the temperature of the radiator valves from home assistant?

Well done of the comprehensive write up! I’d be more than happy to give this a go if I can finally control my radiators from HA!

Thanks

swifty · October 20, 2018, 2:14pm

I only use the Max! TRVs but they also make door/window sensors, wall thermostats and few other things, all of which work with HomeGear.

With the setup above I can read the current settings and send new ones (eg new target temperature) to the TRVs from Home Assistant.

badgerhome · October 20, 2018, 2:21pm

Awesome thank you.

I notice there’s two different TRVs which ones do you use? I’m not too sure what the differences are between them but my radiators are all veritcal mount valves

AndrejDelany · October 20, 2018, 2:37pm

Great, thank for the tutorial! Do you think there is an easy way to install HomeGear on HassIO to avoid using another machine?

swifty · October 20, 2018, 2:39pm

I use the Max EQ-3 basic (https://m.reichelt.com/gb/en/max-basic-heating-controller-max-ht-basic-p161419.html?CTYPE=0&MWSTFREE=0&PROVID=2788&gclid=CjwKCAjwpKveBRAwEiwAo4Pqm7ZvZp7X6UJ2aIClTAE5T9AZXT79ocFQZlKLFkhWT0RdbVWOp3gBxxoCgskQAvD_BwE&&r=1)

Be careful when searching around, as I believe they do one that looks very similar but uses Bluetooth (no cube connection).

I think the larger squarish looking one has built in scheduling on the TRV itself, but this isn’t required if using Cube / Home Assistant, since you can create schedules there…

swifty · October 20, 2018, 2:42pm

The only hassio add-on I could find for HomeGear appeared to be for Raspberry Pi - but I think its no longer maintained.
I use Hassio in a VM so that was no good for me anyway.

If you are using RPi I guess it should work OK though : Homegear Add-on for Hassio

AndrejDelany · October 21, 2018, 2:37pm

I started to install homegear before flashing the cube, just to make sure, my installation works. Seems like Homematic Manager connects correctly to Homegear and after adding the homematic configuration to the configuration.yaml I get no error in HomeAssistant as well.

But when opening homegear:2001 in a browser, i get a server response, but an error. Is this correct, or should there be an UI? Error

You say: “At this point it is worth hitting http://<HOMEGEAR_IP>:2001 to make sure you are greeted by the HomeGear RPC Server page”. Is this page what you meant with that?

Another problem: HomeAssistant doesn’t care, if the provided homegear credentials in the configuration.yaml are valid or not. In homegear, I’m always getting the following log when starting home assistant. Is this the same output you get?

10/21/18 14:56:21.306 Info: Client with IP ::ffff:192.168.178.106 is calling "init".
10/21/18 14:56:21.306 Info: Adding server "http://192.168.178.106".
10/21/18 14:56:21.307 Info: Calling init methods on server "http://192.168.178.106".

(Please note, both home assistant as homegear run on the same IP)

swifty · October 21, 2018, 9:51pm

I’m not sure why you get URL not found… it certainly looks like it’s Homegear that is listening on that port and responding by looking at the page footer…

I get this when I browse to port 2001 on my Homegear server:-

I wonder if the page is only alive when you have at least 1 backend (CUL/CUN etc…) configured / connected ?

As for the username/password - I believe these are only actually needed when using the json method of retrieving friendly names for the devices in Homegear.
I included it as this is what I have in my config, but as I note the friendly names don’t retrieve for me (I just set them in HA instead).
I’ve not had time yet to take a look at why this isn’t working - but it’s low priority for me as everything works ok otherwise

mornsen · October 22, 2018, 3:30pm

Hello,
great write up!
One question though - what is the advantage of using the Cube as CUL/CUN device ?
Is it just to remove the send limits or are there further benefits?

swifty · October 22, 2018, 4:03pm

For me, I was having issues with the cube forgetting the configuration when paired with HA (this seems to be a common issue with it related to frequent polling).

With the new firmware this issue shouldn’t be present anymore - I believe it also allows the Cube to pair with other extra devices (that use the correct frequency) but I’ve not looked into this much.
I mainly just wanted a stable heating system that didn’t forget all its settings every week

Klagio · October 22, 2018, 5:42pm

Hi, I am trying to do as you advice but need some help.

Irun HASSIO 0.80.3 and added this addon

Homegear.

But it does not install (clicking on install does nothing).

Trying now to follow your instructions: first file name is “Dockerfile”, correct?

And where shall I save the 2 files, not sure how to access HASSIO addon folders (I just have config, share, ssl, addons, backup)

Below the log

18-10-22 17:35:22 INFO (MainThread) [hassio.addons.addon] Create Home Assistant add-on data folder /data/addons/data/89330960_rpi-homegear 18-10-22 17:35:22 INFO (SyncWorker_1) [hassio.docker.addon] Start build 89330960/amd64-addon-rpi-homegear:0.2 18-10-22 17:35:40 ERROR (SyncWorker_1) [hassio.docker.addon] Can't build 89330960/amd64-addon-rpi-homegear:0.2: The command '/bin/sh -c apt-get update &amp;&amp; apt-get -y install apt-transport-https wget ca-certificates apt-utils gnupg' returned a non-zero code: 1 18-10-22 17:36:12 INFO (SyncWorker_16) [hassio.docker.addon] Start build 89330960/amd64-addon-rpi-homegear:0.2 18-10-22 17:36:14 ERROR (SyncWorker_16) [hassio.docker.addon] Can't build 89330960/amd64-addon-rpi-homegear:0.2: The command '/bin/sh -c apt-get update &amp;&amp; apt-get -y install apt-transport-https wget ca-certificates apt-utils gnupg' returned a non-zero code: 1 18-10-22 17:43:44 INFO (SyncWorker_11) [hassio.docker.addon] Start build 89330960/amd64-addon-rpi-homegear:0.2 18-10-22 17:43:47 ERROR (SyncWorker_11) [hassio.docker.addon] Can't build 89330960/amd64-addon-rpi-homegear:0.2: The command '/bin/sh -c apt-get update &amp;&amp; apt-get -y install apt-transport-https wget ca-certificates apt-utils gnupg' returned a non-zero code: 1 18-10-22 17:45:02 INFO (SyncWorker_4) [hassio.docker.addon] Start build 89330960/amd64-addon-rpi-homegear:0.2 18-10-22 17:45:04 ERROR (SyncWorker_4) [hassio.docker.addon] Can't build 89330960/amd64-addon-rpi-homegear:0.2: The command '/bin/sh -c apt-get update &amp;&amp; apt-get -y install apt-transport-https wget ca-certificates apt-utils gnupg' returned a non-zero code: 1 18-10-22 17:47:02 INFO (SyncWorker_2) [hassio.docker.addon] Start build 89330960/amd64-addon-rpi-homegear:0.2 18-10-22 17:47:05 ERROR (SyncWorker_2) [hassio.docker.addon] Can't build 89330960/amd64-addon-rpi-homegear:0.2: The command '/bin/sh -c apt-get update &amp;&amp; apt-get -y install apt-transport-https wget ca-certificates apt-utils gnupg' returned a non-zero code: 1

Klagio · October 22, 2018, 5:59pm

Did you make some test? Since is irreversible firmware flash wish to see others experiences

AndrejDelany · October 22, 2018, 6:00pm

Yes, exactly this error message I got when I tried to install the HassIO HomeGear addon from the repo you mentioned. Unfortunately there are some minor problems with my solution from above, e.g. the HTTP server does not start correctly.

But I am working on a new version of the HassIO HomeGear addon. If I’ve got everything working, I will post a tutorial here.

swifty · October 22, 2018, 6:30pm

I’ve been running the flashed cube for a few weeks now connected to HA.
Many restarts of HA and everything is still working OK - that’s more than I ever got with the original firmware.

The configuration loss seems to be a bug in the original firmware, so should no longer be present with a-culfw AFAIK.

Klagio · October 22, 2018, 6:54pm

yes I sort of fixed it changing the poll interval to 600 seconds, so far it works,

Klagio · October 22, 2018, 6:55pm

how does the pairing process work? From HASS you click something?

swifty · October 22, 2018, 7:39pm

See in the guide above - pairing happens via HomeGear, there are a number of apps that can be used to control HomeGear, I used Homematic manager.
The homematic manager app tells HomeGear to put the cube to pairing mode, the actual pairing process then works the same as the original firmware.

AndrejDelany · October 23, 2018, 2:21pm

~~So, I finally managed to setup HomeGear as HassIO Addon. Before publishing it in a repo for easy installation, I would like to give a preview for testing:~~

~~Zippyshare.com - [now defunct] Free File Hosting~~

Please create a Directory “Homegear” in your HassIO’s addons share and copy the 5 files in there. Afterwards you can install from the “Add-on Store” inside HassIO (see https://developers.home-assistant.io/docs/en/hassio_addon_tutorial.html).

~~If it works for you or not, please give me feedback.~~

Please see here for new instructions on how to run HomeGear on HassOS on RaspberryPi:

Coedy · October 23, 2018, 2:56pm

Watching this closely.

I’m currently looking at incorporating TRV control into HA and am torn between this, Thermal Actuators controlled by Sonoffs (with automation to close them off when a room temp is hit) or EnerGenies…