HomeAssistant Integration

After having installed RaspberryMatic either as a native Home Assistant Add-on or as a standalone CCU operating system Home Assistant (HA) can be additionally used as a third-party smarthome automation central by connecting it directly to a HomeMatic CCU including RaspberryMatic. This will then allow to control all your HomeMatic/homematicIP devices directly from Home Assistant and also use all the different automation possibilities Home Assistant provides.

The following documentation explains how to setup the HomeMatic/homematicIP Integration within Home Assistant as soon as you have RaspberryMatic correctly running either as a HA Add-on or as a standalone CCU system.

Home Assistant Community Store (HACS) Setup

To be able to bind/connect your Home Assistant installation to a CCU/RaspberryMatic system the so-called Home Assistant Community Store (HACS) has to be previously installed so that HomeMatic/homematicIP devices can be integrated into your HA installation. The following step will quickly guide you through the process of setting up HACS within your existing Home Assistant installation:

1. Enable 'Advanced Mode' in HA: As a first step, make sure you have the Advanced Mode enabled in your Home Assistant setup. This is required for the next coming step where you will have to install a SSH Add-on to install HACS afterwards. To do so, click your username in the bottom-left corner of the Home Assistant web interface, then scroll down until you find Advanced Mode:
2. Install 'SSH & Web Terminal' Add-on: To be able to install HACS you need a possibility to execute a command within the context of Home Assistant. For this you should have a SSH Terminal session Add-on installed. Preferably, you can install the SSH & Web Terminal Add-on from the Community Add-on section. To do so, go to Configuration -> Add-ons -> Add-on Store and search for 'SSH'. Then select the SSH & Web Terminal Add-on and install it accordingly:
3. Setup SSH Password: Once the SSH Add-on is installed make sure to switch to the Configuration tab of the Add-on and then setup either an authorized SSH key or dedicated password for being able to connect via SSH:
4. Open SSH Add-on Web UI: Afterwards make sure to start the new SSH Add-on and then open the Web UI of the Add-on so that you will be forwarded to a terminal session within Home Assistant:
5. Execute HACS Installation: Once the terminal session to your HA is established, you have to enter the following command-line and execute it to execute the HACS installation:

   wget -O - https://get.hacs.xyz | bash -

   
6. Restart Home Assistant: To finalize the HACS installation, make sure to reboot your Home Assistant installation, preferably by rebooting your whole Home Assistant host or just the core engine:
7. Add new 'HACS' integration: After the successful restart of Home Assistant make sure to change to Configuration -> Devices & Services and press + Add integration. In the integration list, make sure to search for HACS and then select it accordingly. Once you are going to install the new integration make sure to tick all checkboxes you may be asked so that you understand the deal when using HACS:
8. Install HACS integration: To be able to install and use the new HACS integration, make sure to authenticate it using your github.com account since the whole HACS functionality heavily relies on github to be used as a repository service:
9. Access HACS UI: After successful installation of the new HACS integration a new HACS top-level item in your HA menubar should appear, which means that HACS is now correctly installed:
10. Finalize HACS Setup: To finalize the HACS setup you will have to make sure to perform a final restart of Home Assistant by using Configuration -> Settings -> Check Configuration first and then press Restart afterwards to make sure that Home Assistant will be restarted a last time: Warning: After a fresh HACS installation/setup you will have to keep your Home Assistant running for about 10-15 minutes so that HACS can fetch all necessary third-party repository information from github. Depending on your connection speed and github use, this can take a long time until HACS has correctly fetched all necessary information in the background.

'Homematic(IP) Local' Integration Setup

After having correctly installed HACS as the base platform for third-party integration setups, you can now proceed with the installation of the Homematic(IP) Local integration (also called custom_homematic integration) by performing the following steps. This new integration will then allow you to connect your Home Assistant to any "HomeMatic/homematicIP CCU" device including RaspberryMatic installed as a native Home Assistant Add-on or as a standalone system:

1. Add custom repository to HACS: To be able to install the Homematic(IP) Local integration within HACS you have to add a custom repository path to HACS. To do so, go to HACS -> Integrations and then press the three vertical dots on the top-right corner. Then a drop-down menu should appear in which you should be able to select Custom repositories: Note: Please note, that in case the Custom repositories item is not selectable your HACS installation is still fetching additional information in the background. So please wait some minutes until this item can actually be selected and is NOT greyed out.
2. Add 'custom_homematic' as a repository: In the Custom repositories pop-up window, make sure to add the URL to the custom_homematic repository and select Integration as a category:

   https://github.com/danielperna84/custom_homematic
   

   
3. Add 'Homematic(IP) Local' repository: After adding the custom_homematic repository to HACS, you should be able to press the + Explore & Download Respositories button within HACS -> Integrations and then enter homematic as a search pattern to find and select the Homematic(IP) Local repository:
4. Download/Install latest version: In the next pop-up window make sure to select the latest version (not 0.38.2 like in the screenshot) of the respository and press Download to finally download+install the Homematic(IP) Local repository within HACS:
5. Collect RaspberryMatic hostname: In case you want to use the new Homematic(IP) Local integration to connect to a RaspberryMatic install within Home Assistant, make sure to change to Configuration -> Add-ons and then select RaspberryMatic CCU and make sure to write down the displayed hostname of the running add-on install. Also make sure that the add-on is actually running and working correctly:
6. Setup CCU Firewall: To allow the new 'Homematic(IP) Local' integration to access all necessary Homematic XML-RPC and Scripting APIs on your CCU/RaspberryMatic, you should make sure that you have the necessary firewall ports open in Settings -> Firewall configuration. Take special care that the XML-RPC and Scripting APIs are accessible from the HomeAssistant host you are installing the integration to.
7. Install 'Homematic(IP) Local' integration: Now that this new HACS installed integration is ready for you, change to Configuration -> Devices & Services and press + Add integration. In the following pop-up window make sure to enter homematic as a search pattern again and then select the Homematic(IP) Local integration for install:
8. 'Homematic(IP) Local' integration setup: In the pop-up window following the installation process of the new integration make sure to enter all necessary information to let the integration connect to your CCU device (including the CCU Username (case-sensitive) and CCU Password which have to correspond to a user within the CCU WebUI which has full admin privileges). Take special attention for the CCU Hostname/IP-Address which in case of a RaspberryMatic HA Add-on install should carry the HA internal hostname that you have previously written down:
9. Interface setup: In the next pop-up you will be prompted for selecting which communication interfaces (BidCos-RF, homematicIP, VirtualGroups, etc.) your CCU device provides. Make sure to select all the different interfaces your CCU has available. Do not select interfaces for devices you don't have, as this may result in errors during startup:
10. Finalize setup: After having entered the correct user credentials and homematic interface setup, the next pop-up should present you all the found HomeMatic/homematicIP devices within your CCU/RaspberryMatic. You can now either assign an Area for each devices within this popup or assign them later on and just press Finish to finalize the setup:
11. Verify functionality: To be able to verify a correct functionality of the new integration, you should now see the new Homematic(IP) Local integration listed in the Configuration -> Devices & Services list including the number of devices, services and entities that have been fetched from the RaspberryMatic CCU:
12. Display device parameters: To view any parameters of Homematic devices being identified you can now press on the number of devices display and then select any of the device to display diagnostic information. For example, here you can see the DutyCycle Level and Carrier Sense Level being display for a HmIP-RFUSB used within the queried RaspberryMatic:

Following these installation steps and setups you should then be able to see and use all your HomeMatic/homematicIP devices within Home Assistant and add them to any automation or Lovelace display card just as you do for any other devices added through other integrations.

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" (🇩🇪)