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 Home Assistant 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.

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.

Known limitations

• Due to a limitation in the abilities to use multicast UDP network routing in HomeAssistant (https://github.com/home-assistant/plugin-multicast/issues/17), it is currently not possible to teach-in / use a HmIPW-DRAP gateway to control homematicIP-Wired devices (cf. https://github.com/jens-maus/RaspberryMatic/issues/1373) or use a HmIP-HAP as a range extender for homematicIP.

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), 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

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 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://www.pivccu.de/piVCCU/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/pivccu-archive-keyring.gpg >/dev/null
   sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/pivccu-archive-keyring.gpg] https://www.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):
   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

Warning: 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 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"

This will then allow the supervisor to correctly setup the cgroup permissions even if cgroup v2 is used. Please note, that in case your host system for the Home Assistant Supervised installation is using a RaspberryPi you can also add the systemd.unified_cgroup_hierarchy=false kernel command line option to /boot/cmdline.txt to get the kernel to have the right cgroup permissions.

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.