This article is about using Homematic and Homematic IP on a Raspberry Pi running with Raspbian Stretch and integrate it into OpenHab 2. For better reading I will just say Homematic in the article but this is valid for both: Homematic and Homematic IP. For the connection to Homematic the radio module HM-MOD-RPI-PCB is used and piVCCU is used to host the “server” of Homematic. OpenHab and piVCCU are running on the same Raspberry Pi. As every time: Everything will run completely offline in the final setup.

I will add several Smoke Detectors based on Homematic IP in this article. You can use other devices and just skip the part that is about that integration. This smoke detectors are the test winner of the biggest and most important testing institute “Stiftung Warentest” in Germany for connected Smoke Detectors. There are also many other smoke detectors for almost the same price, but they are not “smart” (i.e. Hekatron), not “smart” enough (closed ecosystem i.e. Innogy Smoke Detectors) for the same price, do not fulfill the German Smoke Detector law (DIN 14676/EN 14604) or much to expensive (Bosch TwinGuard, Nest Smoke Detectors, …). Additionally the Homematic IP dectectors are “smart” and able to alarm other smoke detectors even if the base (our Raspberry) is not reachable (i.e. power outage).

Remark:
The HM-MOD-RPI-PCB is a kit. It is NOT ready-to-use! You have to solder two banks of pins to the board before you can use it! In any case of questions, feel free to write me a message.

Requirements

HM-MOD-RPI-PCB

The Radio Module for Homematic

ELV Elektronik
Amazon*

Raspberry Pi3b+ or Raspberry Pi Zero

As the base for the Homematic Radio Module. In this article I use a Raspberry Pi3b+

Amazon*
BuyZero
Reichelt

 

Homematic IP HmIP-SWSD

Homematic IP Smoke Detector with 10 years of lifetime

Amazon*
ELV Elektronik

 

Homematic IP HmIP-SWSD (3-pack)

Homematic IP Smoke Detector with 10 years of lifetime
Set of three Smoke Detecotors

Amazon*
ELV Elektronik

 

Mount the HM-MOD-RPI-PCB

First we need to solder the two banks of the HM-MOD-RPI-PCB. In the box that contains the HM-MOD-RPI-PCB is a detailed instruction how to do it. Additionally there is a video at the product page of ELV Elektronik where you can see what you need to do: https://www.elv.de/homematic-funkmodul-fuer-raspberry-pi-bausatz.html

When you are done, you can shotdown and unplug the Raspberry Pi and attach the HM-MOD-RPI-PCB to the GPIO pins 1-12 on the Raspberry. That finally looks like this:

 

Installation of CCU3 based on piVCCU

Credits to most of this part are going to the piVCCU team.
Most parts are copied from https://github.com/alexreinert/piVCCU/blob/master/docs/setup/raspberrypi.md

  1. Before we start, create a full backup of your SD card
  2. Connect to the Raspberry Pi via SSH
  3. Add the public key of the repository
    wget -q -O - https://www.pivccu.de/piVCCU/public.key | sudo apt-key add -
  4. Add the package repository
    sudo bash -c 'echo "deb https://www.pivccu.de/piVCCU stable main" > /etc/apt/sources.list.d/pivccu.list'
    sudo apt update
  5. Install the necessary kernel modules
    sudo apt install raspberrypi-kernel-headers pivccu-modules-dkms
  6. Install the necessary device tree patches
    sudo apt install pivccu-modules-raspberrypi
  7. Enable UART GPIO pins (only on Raspberry Pi 3)
    • Option 1: Disable bluetooth (preferred)
      sudo bash -c 'cat << EOT >> /boot/config.txt
      dtoverlay=pi3-disable-bt
      EOT'
      sudo systemctl disable hciuart.service
    • Option 2: Bluetooth attached to mini uart
      sudo bash -c 'cat << EOT >> /boot/config.txt
      dtoverlay=pi3-miniuart-bt
      enable_uart=1
      force_turbo=1
      EOT'
  8. Disable serial console in command line
    sudo sed -i /boot/cmdline.txt -e "s/console=serial0,[0-9]\+ //"
    sudo sed -i /boot/cmdline.txt -e "s/console=ttyAMA0,[0-9]\+ //"
  9. Add network bridge (for wired connection, for Wifi connection see step 10!)
    • Verify, that eth0 is the name of your primary network interface:
      sudo ip link show | cut -d' ' -f2 | cut -d: -f1 | grep -e '^e.*'
    • If using DHCP execute this (Replace eth0 if necessary)
      sudo apt remove dhcpcd5

      After that:

      sudo apt install bridge-utils
      sudo bash -c 'cat << EOT > /etc/network/interfaces
      source-directory /etc/network/interfaces.d
      
      auto lo
      iface lo inet loopback
      
      iface eth0 inet manual
      
      auto br0
      iface br0 inet dhcp
        bridge_ports eth0
      EOT'
    • You can use an static IP address, too. Replace the address, netmask, gateway, dns1 and dns2 and use this instead:
      sudo apt remove dhcpcd5

      After that:

      sudo apt install bridge-utils
      
      sudo bash -c 'cat << EOT > /etc/network/interfaces
      
      source-directory /etc/network/interfaces.d
      
      auto lo
      iface lo inet loopback
      
      iface eth0 inet manual
      
      auto br0
      iface br0 inet static
       bridge_ports eth0
       address <address>
       netmask <netmask>
       gateway <gateway>
       dns-nameservers <dns1> <dns2>
      EOT'
  10. Skip this step if you are using wired Ethernet connection. To use Wireless LAN, please click => here <=.
  11. Reboot the system
    sudo reboot
  12. Install CCU3 container
    sudo apt install pivccu3

    When the installation is almost done, you are asked about the radio module. Select “HM-MOD-RPI-PCB or RPI-RF-MOD (only on supported platforms)” and press enter.

  13. Start using your new virtualized CCU, you can get the IP of the container using
    sudo pivccu-info

    The piVCCU installs a virtual machine on the Raspberry. That machine has it’s own IP address. You see the IP in the output of the command above.

 

Configure the Homematic CCU

After the CCU is installed, we can try to access the CCU. Open http://<Ip of your piVCCU> in your browser. i.e. http://192.168.0.162.>

You will be asked about the password in the first step. Enter a password of your choice and click “next”.

In the next step select custom setting.

Now configure the following settings to allow OpenHab to access the Homematic API:

  • Set “Homematic XML-RPC API” to “Restricted access”
  • Set “Remote Homematic script API” to “Restricted access”
  • Set “Port opening” to “2000;2001;2010;8701;9292;”
  • Add the IP address of the OpenHab Raspberry to the list “IP addresses for restricted access”. Do not forget the semi-colon (;) in the line above!

Now read the security warnings and check “I have read the above warning” and click “Next”.

Now the setup of the CCU is completed. We are ready to pair devices.

Add Homematic IP device to CCU

In this section I will describe the connection for the smoke detector. Other Homematic devices may be connected slightly different.
To add the smoke detector follow these steps:

  1. Read the manual of the device how to set the device in pairing mode. Do not start pairing at this point.
  2. Click on “Teach-In devices” at the to right of the Homematic CCU Website.

  3. In the next window we want to connect the Homematic IP device without a internet connection. Because of this we have to enter the key and the sgtin into the two text fields. At my smoke detector there was a sticker with a QR-code and this two strings in the first page of the manual. After you entered this strings, click on “Teach-in HmIP device (local)”.
  4. Immediatly after click on the button, start the pairing of your device. My smoke detectors need to be mounted to the frame to be turned on and start pairing. After some seconds in the Inbox at the lower left will be “Inbox (1)”. That means, that the smoke detector was paired with the CCU that is running on our Raspberry Pi.

  5. When you click on the “Inbox” button, you will see the device in the inbox.
  6. Click on the “Done”-Button in the last column of the inbox row.
  7. To check if everything was successful, click on the “Status and control”-button at the top left and select “Devices”

  8. You will see a list of devices. The first two devices are the CCU. The third one is the smoke detector.

  9. Now the Homematic CCU knows your devices and we can teach OpenHab to use the CCU we just installed.

Configure OpenHab

Now let’s integrate the CCU and all it’s devices to OpenHab.

  1. Start the PaperUI of OpenHab.
  2. Go to “Add-ons” (1) and select the “Bindings”-Tab (2). Enter “homematic” in the search box (3) and in the result list click on install (4).
  3. After the installation is done go into the inbox (1) and click the checkbox in front of the CCU3 item. Choose a name for your CCU (i.e. “Homematic CCU3”).

  4. After you finished, the CCU is now part of your configuration as a bridge and discovers all of your connected devices automatically. In my environment it looks like this:

  5. Add all of the Items by click on the blue check-bubble in front of the device and enter the name of the device. Finally click “Add as Thing”.

  6. After that you will find the devices as a “Thing” at “Configuration” => “Things”.
  7. After that you can click on the gray bubble in front of the thing. Here you have to configure the channels. For my smoke detectors there is a “Show More”-Text at the right that hides most of the features the smoke detectors have. I believe that the default view should show the “most used” channels.

  8. To configure a channel, click on the blue bubble in front of the channel name. A popup will be shown. In the upper box leave “Default” and in the lower box select “Create new Item”.
  9. Another popup will appear. Just confirm the settings by click on “Link” at the lower right. Both popups will disappear but the inner part of the bubble in front of the channel name will now be filled.

  10. If you switch to the “Control”-Element in the navigation bar, you will see the configured thing with the configured channel.

 

We can now send us a notification when a smoke detector starts to alarm. i.e. by

  • Mail
  • Telegram

 

 

Remarks:
Product links marked with * are affiliate links. That means I get some percent of the money you will spend when you are using this links. I’m not trying to influence you. In most cases there are also other sellers for the products where I don’t get money for. I am not trying to influence you to spend more money than you need. If you are using this links, you don’t have to pay anything extra. It is the same price as if you enter the shop on your own.