Installation HomeAssistant

RaspberryMatic can be installed as a Home Assistant Add-on. By doing so, it will run as a virtual appliance (based on Docker) within the Home Assistant's own operating system called Home Assistant OS or within a "HomeAssistant Supervised" installation. Similar to the installation of RaspberryMatic on real hardware, the HomeAssistant OS can be installed on a wide variety of systems, starting from e.g. a RaspberryPi to intelNUC systems or also as a pure virtual OVA-based appliance under, e.g. Proxmox VE, vmWare ESXi, etc.

By directly installing RaspberryMatic as a Home Assistant Add-on, rather than installing it exclusively on an own hardware or separate virtual appliance, the full functionality of RaspberryMatic is directly embedded into the standard Home Assistant user interface and thus can run in parallel with other Home Assistant provided IoT integrations like Philips HUE, SONOS, etc. This provides some superior features including the standard snapshotting functionality of Home Assistant OS.

Please note: If you have an already working RaspberryMatic installation on a dedicated device or environment and you are just interested in getting your HomeMatic/homematicIP devices to be integrated into the Home Assistant UI, please follow the Home Assistant Integration section of this documentation instead.

Known limitations

Important

Due to current limitations in the abilities to use multicast UDP network routing within HomeAssistant add-ons, it is currently NOT possible to teach-in / use a HmIPW-DRAP gateway to control homematicIP-Wired devices or a HmIP-HAP as a range extender for homematicIP when running RaspberryMatic as a HomeAssistant Addon (cf. https://github.com/jens-maus/RaspberryMatic/issues/1373). However, if support for a HmIP-HAP or HmIPW-DRAP is mandatory, there currently exists a manual patch procedure outline in the HmIP-HAP/HmIPW-DRAP Support Patch section below.

Pre-Installation Steps

Depending on the actual use-case of the Home Assistant RaspberryMatic Add-on you might have to perform certain pre-installation steps so that the Add-on can work correctly on your selected platform.

Using HomeAssistant OS:

1. Installation of HomeAssistant OS: To make sure that the Add-on works correctly within Home Assistant OS, it is necessary that you make sure that you are using HomeAssistant OS version 7.3 or higher. To do so, please make sure to download+install HAos version 7.3+ from https://github.com/home-assistant/operating-system/releases
2. Enable GPIO bus support in HAos: If you use a RaspberryPi, Tinkerboard or ODROID as a host hardware and you want to use a RPI-RF-MOD or HM-MOD-RPI-PCB directly connected to the GPIO bus (not required if you use a HB-RF-USB, HB-RF-USB-2, HB-RF-ETH or HmIP-RFUSB/HmIP-RFUSB-TK), make sure to...

   • either mount the flashed sd card / eMMC locally to be able to access the config.txt/haos-config.txt file located on the /mnt/boot boot partition.

   • or use a SSH Login later on to log in via SSH remotely (see also SSH port 22222 configurator)

   • or connect a HDMI Monitor+keyboard and login in the console

   • On RaspberryPi: edit the /mnt/boot/config.txt file and uncomment the following lines at the bottom:

     # Uncomment this to enable GPIO support for RPI-RF-MOD/HM-MOD-RPI-PCB
     enable_uart=1
     dtparam=i2c_arm=on
     dtoverlay=miniuart-bt
     dtoverlay=rpi-rf-mod

     (if you are not very familiar with Linux you can also plug in the sd card or ssd drive into your PC and edit the config.txt file with your favorite editor)

   • On Tinkerboard or ODROID: edit the /mnt/boot/haos-config.txt file and uncomment the following lines at the bottom:

     # Uncomment this to enable GPIO support for RPI-RF-MOD/HM-MOD-RPI-PCB
     overlays=rpi-rf-mod

   • Make sure that you completely reboot your Home Assistant host machine before you proceed with the add-on installation.

Using HomeAssistant Supervised

Important

Please note, that due to technical dependencies/complications regarding a Supervised driven installation of HomeAssistant and direct hardware access from within docker containers, only experienced users should consider installation of the RaspberryMatic HA add-on within a HA supervised installation.

If you are using a Home Assistant Supervised installation, thus not a full HomeAssistant OS for running HomeAssistant but directly the HA supervisor on an existing Linux system you have to perform the following minimal steps to support the use of a RPI-RF-MOD, HM-MOD-RPI-PCB or HmIP-RFUSB/HmIP-RFUSB-TK rf module and the HB-RF-USB, HB-RF-USB-2 or HB-RF-ETH adapters:

1. Install pivccu-modules-dkms kernel modules:

   sudo apt install wget ca-certificates build-essential bison flex libssl-dev gpg
   wget -qO - https://apt.pivccu.de/piVCCU/public.key | sudo gpg --dearmor -o /usr/share/keyrings/pivccu-archive-keyring.gpg
   sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/pivccu-archive-keyring.gpg] https://apt.pivccu.de/piVCCU stable main" >/etc/apt/sources.list.d/pivccu.list'
   sudo apt update
   sudo apt install build-essential bison flex libssl-dev
   sudo apt install raspberrypi-kernel-headers pivccu-modules-dkms

2. If you are using a RaspberryPi and want to use a RPI-RF-MOD or HM-MOD-RPI-PCB directly connected to GPIO (not necessary if you use a HB-RF-USB, HB-RF-USB-2, HB-RF-ETH or HmIP-RFUSB/HmIP-RFUSB-TK):
   1. Install the necessary device tree patches:

      sudo apt install pivccu-modules-raspberrypi

   2. Disable bluetooth:

      sudo bash -c 'cat <<EOT >>/boot/config.txt
      dtoverlay=pi3-disable-bt
      EOT'
      systemctl is-active --quiet hciuart.service && sudo systemctl disable hciuart.service

   3. Disable serial console

      sudo sed -i /boot/cmdline.txt -e "s/console=\(serial0\|ttyAMA0\),[0-9]\+ //"

3. Install eq3_char_loop kernel module to automatic module load section:

   sudo sh -c 'echo eq3_char_loop >/etc/modules-load.d/eq3_char_loop.conf'

4. Start+Load all necessary kernel modules on host:

   sudo service pivccu-dkms start
   sudo modprobe eq3_char_loop

Important

In case of a "Supervised" HomeAssistant installation, it can happen that due to newer cgroup v2 being used in the host operating system an error Can't set cgroup permission on the host for addon_XXXX_raspberrymatic are shown in the HA supervisor logs because HomeAssistant supervisor only supports cgroup v1 at the moment. To workaround this issue, thought, the following line - in case your host system is using the grub bootload - can be put into the /etc/default/grub configuration file on the host operating system:

GRUB_CMDLINE_LINUX_DEFAULT="quiet systemd.unified_cgroup_hierarchy=false"

and execute the update-grub command. Afterwards the HA supervisor should be able to correctly setup the cgroup permissions even if cgroup v2 is used in the host system. Please note, that in case your host system for the Home Assistant Supervised installation is using a RaspberryPi you can add the corresponding systemd.unified_cgroup_hierarchy=false kernel option to /boot/cmdline.txt instead to get the kernel to have the right cgroup permissions. For other systems, like a Tinkerboard or ODROID, you will have to put that kernel option to the respective bootloader config.

On a kernel compiled with CONFIG_RT_GROUP_SCHED=y (like Armbian), Home Assistant does not assign any real-time execution time to addons. This prevents multimacd from working properly and renders the addon non-functional. One can disable the limit altogether by changing a kernel parameter with sudo sysctl -w kernel.sched_rt_runtime_us=-1 or echo "kernel.sched_rt_runtime_us = -1" | sudo tee /etc/sysctl.d/10-disable-rt-group-limit.conf to make it permanent.

Add-on Installation Steps

The basic Home Assistant Add-on installation of RaspberryMatic requires that a standard Home Assistant OS or HomeAssistant Supervised installation has already been preinstalled on the platform that the Add-on should be installed. If this requirement is already fulfilled the following steps can be performed for the basic Add-on installation:

1. Uninstall "Homematic CCU" Addon: Make sure you have uninstalled the legacy "Homematic CCU" HomeAssistant Add-on, which is provided by the standard Add-on store of HomeAssistant. The old legacy "Homematic CCU" Addon is NOT meant to be installed/used in parallel to the "RaspberryMatic CCU" Addo-n you are going to install here. Also note, that the functionality the "RaspberryMatic CCU" Add-on provides is superior to the old "Homematic CCU" Addon and that there is almost no reason to use it anymore.
2. Open Add-on Repository setup: For the Add-on to appear in the Home Assistant web interface, log into your preinstalled Home Assistant (e.g. http://homeassistant.local:8123/) with your favorite web browser. Then navigate to Configuration -> Addons, Backups & Supervisor -> Add-on Store and press the three vertical ⋮ (dots) at the top right corner. Then select Repositories:
3. Add 'RaspberryMatic' Add-on repository: Add the https://github.com/jens-maus/RaspberryMatic url as an additional Home Assistant Add-on repository:
4. Navigate to the RaspberryMatic Add-on configuration: Close the "Manage add-on repositories" window and close down to the newly added "Home Assistant RaspberryMatic Add-on" section (you have to scroll-down to the bottom of the add-on section). Then select the "RaspberryMatic CCU" add-on:
5. Install the Add-on: Press INSTALL to permanently install the RaspberryMatic Add-on in your Home Assistent system:
6. Install to sidebar and start Add-on: As soon as the add-on is installed, buttons will appear in the Add-on info page. Click on Show in sidebar to be able to directly access the RaspberryMatic WebUI from the Home Assistant web interface. Afterwards, press START to start RaspberryMatic. After starting, you can view the progress of the startup in the Log tab of the Add-on info page. After startup you can see the hostname, current CPU usage and RAM usage.
7. Configure additional API ports: If you would like to configure network access to the standard API network ports RaspberryMatic provides to access and query configures HomeMatic/homematicIP devices you can do so by switching to the Configuration tab on the add-on info page:
8. Access to CCU WebUI: After startup of the RaspberryMatic add-on you can press on the RaspberryMatic entry in the sidebar of the Home Assistant user interface to access the standard CCU WebUI:

After having performed the above steps you can now add or configure your HomeMatic/homematicIP devices in a similar way like you would do with a real RaspberryMatic system. Thus, you should be able to import and existing configuration, start to teach-in HomeMatic/homematicIP devices (depending on the RF/Wired hardware you are using), etc.

Home Assistant Integration Setup

After the RaspberryMatic Add-on has been correctly installed and your embedded RaspberryMatic WebUI shows existing HomeMatic/homematicIP devices, you still have to setup an 'integration' within Home Assistant for the HomeMatic/homematicIP devices to appear as any other smart home device from other vendors. To do so, please walk through the dedicated integration setup installation process documented in the Home Assistant Integration section.

HmIP-HAP/HmIPW-DRAP Support Patch

Due to current limitations in the docker networking support in HomeAssistant the RaspberryMatic HA Add-on can usually not communicate with a HmIP-HAP used as a range extender or a HmIPW-DRAP homematicIP-Wired gateway (cf. https://github.com/jens-maus/RaspberryMatic/issues/1373). However, if support for a HmIP-HAP or HmIPW-DRAP is mandatory in your environment there is currently a manual workaround to let the Add-on connect to your local network like a normal RaspberryMatic system using the following procedure:

1. Identify a static ip address from your local network which the add-on container can use and which is NOT part of your DHCP supplied range (<IP-ADDRESS>).

2. For conveniently applying the patch, make sure to have the "Advanced SSH & Web Terminal" Add-on (https://github.com/hassio-addons/addon-ssh) installed in HomeAssistant so that you are able to use a Web Terminal to access the HomeAssistant command-line. Make sure to disable the protection mode of this add-on so that docker commands can be executed in the Web Terminal.

3. Make sure the RaspberryMatic Add-on is up and running when applying the patch and Watchdog of RaspberryMatic Add-on is disabled. Write down the internal hostname under which the RaspberryMatic add-on (NOT your HomeAssistant host!) is reachable (e.g. 5422eb72-raspberrymatic) because you will require it in the next step.

4. Connect to the HomeAssistant command-line via the Web Terminal and execute the following command to apply the patch:

   wget -qO - https://raw.githubusercontent.com/jens-maus/RaspberryMatic/master/scripts/patch-ha-addon-macvlan.sh | bash -

   On execution, this script will try to identify the main network interface, the subnet and the default gateway ip of your HA instance and ask for verification. Then it will create a macvlan docker network and ask for the hostname of your running RaspberryMatic HA add-on (e.g. 5422eb72-raspberrymatic) and also for the dedicated ip address the addon will exclusively use (<IP-ADDRESS>).

   LIMITATION: Note, that applying this patch is unfortunately not persistent upon HomeAssistant reboots or restarts of the RaspberryMatic add-on. Thus, upon reboot of HomeAssistant or any restart of the RaspberryMatic add-on you will have to re-apply this patch so that the add-on can be re-assigned to communicate through the dedicated macvlan docker network bridge allowing to communicate with your HmIP-HAP/HmIPW-DRAP. Thought, in a future HomeAssistant version direct support will be added so that the add-on will be able to setup and use a macvlan bridge network itself without requiring to manually patch the docker environment like outlined here.

5. After being able to access the add-on via the new static ip address (e.g. via http://<IP-ADDRESS>/) make sure to tune/setup the internal RaspberryMatic firewall to your needs, since with the macvlan bridge it is directly connected to your home network independently of the virtual network bridge HomeAssistant usually uses for its add-ons. Thus, to limit access to certain ports, make sure to setup the RaspberryMatic firewall from within its WebUI accordingly. Also note, that once the macvlan solution is working the dedicated port settings in the add-on configuration section are not effective anymore since the add-on is directly connected to your LAN now.

After having applied the patch, the WebUI of the RaspberryMatic add-on should be directly reachable via the statically assigned ip address (http://<IP-ADDRESS>/). In addition, if the HmIP-HAP or HmIPW-DRAP is connected to the same subnet like the assigned add-on ip address communication to both devices should finally work and you should be able to teach-in these devices and use them within RaspberryMatic. Keep in mind: As soon as you restart HomeAssistant or the add-on you will have to re-apply the patch (execute the shell script again!).

Additional Resources

If you need more assistance on the topic of HomeAssistant Add-on installation, please have a look at the following external resources:

YouTube-Video on "RaspberryMatic AddOn auf Home Assistant installieren und einrichten 2022" (🇩🇪)