RaspberryMatic

The RaspberryMatic project is a collaborate effort to provide a lightweight, Linux/buildroot-based HomeMatic compatible distribution for embedded devices like the RaspberryPi or Tinkerboard. It is based on the Open-Central-Control-Unit-SDK (OCCU) provided by eQ-3 as part of the HomeMatic home automation platform. The RaspberryMatic distribution is provided as a full operating system image that can be flashed and then used in a RaspberryPi/Tinkerboard as the main operating system for controlling all HomeMatic compatible devices with full compatibility to a CCU device directly sold by eQ-3.

🍪 Features

• 100% HomeMatic CCU2/CCU3 system compliant using latest OCCU software environment
• Fully BidCos-RF (HomeMatic), Wired (HomeMatic-Wired) and HmIP-RF (HomeMaticIP) compatible
• Integrated WebUI-based firmware update mechanism and Recovery System to perform maintenance operations such as system restore.
• Enabled Preemptive kernel support (PREEMPT) to minimize latencies and improve CCU operation properties
• Read-only root file system to minimize write operations on SD card
• Includes embedded JAVA8 runtime environment (1.8.0_172-8.30.0.106)
• Full IPv6 support and default HTTPS enabled WebUI support
• Auto-resizing /usr/local partition to utilize the full capacity of the SD card or USB stick
• Hardware WatchDog support automatically rebooting the system upon severe hardware/lockup problems
• Direct CloudMatic (meine-homematic.de) support

🍰 Exclusive Features (not available in CCU2/CCU3 firmware)

• Fully compatible to all available RaspberryPi and ASUS Tinkerboard hardware models on the market.
• Integration of latest community version of ReGaHss comming with latest features and bugfixes in logic engine.
• Integration of third-party patches for an improved WebUI experience.
• Support to be used as a pure HomeMatic LAN Gateway (HM-LGW-O-TW-W-EU) only
• Support to be used without GPIO RF module just connecting to a HomeMatic LAN Gateway (HM-LGW-O-TW-W-EU)
• Self-contained disk image targeted for lightweight embedded devices (e.g. RaspberryPi, ASUS Tinkerboard)
• Based on latest Buildroot 2018.05 lightweight Linux operating system
• Latest Linux kernel (RaspberryPi: 4.14.50, Tinkerboard: 4.14.53) with hard-float (ARMv7) support
• Support to boot system using an external USB memory stick or hard disk (RaspberryPi3 only) or from internal eMMC storage (ASUS Tinkerboard S)
• Supports onboard WiFi of RaspberryPi3, Raspberry Pi Zero W or ASUS Tinkerboard as well as various third-party USB WiFi sticks
• Supports onboard Bluetooth of RaspberryPi3, Raspberry Pi Zero W or ASUS Tinkerboard as well as various third-party USB Bluetooth sticks
• Supports Network UPS Tools (NUT) setups including USB connection to uninterruptible power supply (UPS) as well as remote NUT server use (e.g. via Synology NAS Network UPS functionality)
• Support to query status information of the underlying Linux system using SNMP requests
• Support for the following third-party Hardware Attached on Top (HAT) boards:
  • S.USV – UPS including alarm notification upon power loss and automatic system shutdown.
  • PiUSV+ – UPS including alarm notification upon power loss and automatic system shutdown.
  • PiModules UPS PIco – UPS including automatic system shutdown.
  • StromPi2 – UPS including alarm notification upon power loss.
  • PiDesktop – Addon HAT with power button and dedicated RTC clock (PCF8563).
• Integrated support for various RTC clock modules:
  • PiFace Shim RTC
  • DS3231
  • DS1307
  • RX8130CE
  • PCF8563
  • onboard Tinkerboard RTC
• Dedicated Build Environment using a cross compiler (arm-linux-gcc) to compile third-party applications

🔥 Limitations

• No web-based configuration for setting up WiFi or Bluetooth support (work in progress)
• No web-based configuration for enabling/disabling the LAN-Gateway mode (work in progress)
• No web-based configuration for configuring NUT (UPS) support (work in progress)

💻 Requirements

• Any of the following embedded hardware boards:
  • RaspberryPi3 Model B+
  • RaspberryPi3 Model B
  • RaspberryPi2 Model B
  • RaspberryPi Compute Module 3
  • RaspberryPi Compute Module 3 lite
  • RaspberryPi Zero W
  • RaspberryPi Zero
  • RaspberryPi Compute Module 1
  • RaspberryPi1 Model B+ or Model B, 512MB
  • RaspberryPi1 Model A+ or Model A, 256MB
  • Tinker Board S
  • Tinker Board
• One or more of the following HomeMatic/HomeMatic-Wired/HomeMaticIP capabale devices:
  • HomeMatic + HomeMaticIP:
    • GPIO Radio Module HAT – RPI-RF-MOD
    • GPIO Radio Module HAT – HM-MOD-RPI-PCB (Installation)
  • HomeMaticIP only:
    • USB Stick – HmIP-RFUSB
  • HomeMatic only:
    • LAN Gateway – HM-LGW-O-TW-W-EU
    • USB Config Adapter – HM-CFG-USB-2
  • HomeMatic-Wired only:
    • LAN Wired Gateway – HMW-LGW-O-DR-GS-EU
• 4 GB minimum sized microSD card or USB memory stick / hard disk (RaspberryPi3 only)

🔭 Compatible Third-Party CCU Addons

The CCU platform allows to enhance the functionality of a CCU by installing so-called CCU Addon packages. For RaspberryMatic, standard CCU Addon packages won't work because included binaries have to be recompiled for the hard-float buildroot environment RaspberryMatic uses. Here is a list of well-known already compatible Addon packages (please note that this list might be incomplete):

• CUxD
• XML-API
• hm_pdetect
• Email-Addon
• CUxD-Highcharts
• HQ-WebUI
• DB-Access
• QuickAccess
• Script-Parser
• WebMatic
• Sonos Player
• hm2mqtt
• CCU-Historian
• Watchdog
• homeputer CL Studio
• Print / ProgrammeDrucken
• HomeMatic Check_MK
• hm-tools
• HB-UW-Sen-THPL Universalsensor
• RedMatic
• Mosquitto
• Redis

☁️ Installation

The installation of RaspberryMatic is quite straight forward as it is delivered as a full SD card image that can be directly flashed onto a microSD card and put into the corresponding RaspberryPi. As such the installation consists of the following basic steps:

1. Download latest release archive (RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.zip) for the hardware platform you are using:
   • wget https://github.com/jens-maus/RaspberryMatic/releases/download/X.XX.XX.YYYYMMDD/RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.zip
2. Unarchive zip file resulting in an SD card image (RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img), e.g.:
   • unzip RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.zip
3. Check sha256 checksum to check integrity of SD card image, e.g.:
   • sha256sum -c RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img.sha256
4. Use the image flasher tool "Etcher" (https://etcher.io) to flash the *.img file to your SD card or USB drive. As an alternative you can also use the following command-line calls to manually flash it on Unix-based operating systems:
   • Linux: sudo dd if=RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img of=/dev/mmcblk0 bs=1M conv=fsync
   • macOS: sudo dd if=RaspberryMatic-X.XX.XX.YYYYMMDD-XXX.img of=/dev/rdiskX bs=1m
5. For HM-MOD-RPI-PCB use only: Make sure you have the HM-MOD-RPI-PCB radio module installed on the GPIO
6. Install microSD in your RaspberryPi and connect power
7. Wait until bootup process is finished and use a web browser to connect to http://homematic-raspi/

📝 Documentation

Documentation (e.g. how to port your HomeMatic configuration from a CCU2 to RaspberryMatic) and installation support is currently limited to using a mostly german language speaking fora with the following links pointing to the relevant sections of the fora where you can find documentation and help about RaspberryMatic:

• RaspberryMatic - Installation Guide 🇩🇪
• RaspberryMatic - Forum 🇩🇪
• HM-MOD-RPI-PCB - Installation Video 🇩🇪

📺 Presentations (German 🇩🇪 – YouTube)

😋 How to contribute

As the RaspberryMatic project is an open source based project everyone is invited to contribute to this project. Please note, however, that functionality within the corresponding eQ-3 OCCU binaries can not be modified as the main HomeMatic services (rfd, ReGaHSS, HMServer, etc.) are provided in binary format by the OCCU project and not compiled from sources. Nevertheless, if you are a talented developer and want to contribute to the success of RaspberryMatic feel free to send over pull requests or report issues / enhancement requests.

💰 Donations

Even for those that don't have the technical knowhow to help developing on RaspberryMatic there are ways to support our development. Please consider sending us a donation to not only help us to compensate for expenses regarding RaspberryMatic, but also to keep our general development motivation on a high level. So if you want to donate some money please feel free to send us money via PayPal. And if you are running a business which might integrate RaspberryMatic in one of your products please contact us for a regular donation plan which could not only show that you do care about open source development, but also could secure your product by ensuring that development on RaspberryMatic continues in future.

🚧 Development

Building your own RaspberryMatic SD card image is a very straight forward process using this build environment – given that you have sufficient Linux/Unix knowledge and you know what you are actually doing. But if you know what you are doing and which host tools are required to actually be able to run a RaspberryMatic build, it should be as simple as:

$ git clone https://github.com/jens-maus/RaspberryMatic
$ cd RaspberryMatic
$ make dist
[wait up to 1h]
$ make install of=/dev/sdX

🔖 Using the generated cross compiler

After a successfull build of RaspberryMatic a dedicated cross compiler (arm-linux-gcc) should be available within the build-raspberrypi3 path. You can use this GCC-based cross compiler to compile all kind of third party applications which can then be run within RaspberryMatic:

$ cd HelloWorld
$ <path-to-RaspberryMatic-build>/build-raspmatic_rpi3/host/usr/bin/arm-linux-gcc -o HelloWorld HelloWorld.c

A valid alternative for building RaspberryMatic ARM-hardfloat compatible binaries is to use the linaro based Linux cross compiler suite supplied here.

📜 License

The RaspberryMatic build environment itself – the files found in this git repository – as well as the RaspberryMatic sd card images are licensed under the conditions of the Apache License 2.0. Please note, however, that the buildroot distribution RaspberryMatic is using is licensed under the GPLv2 license instead. Furthermore, the eQ-3 OCCU software RaspberryMatic is using to provide HomeMatic-based services is licensed under the (HMSL).

👏 Acknowledgments

As this project is a collaborative effort also indirectly using several third-party solutions we would like to thank the following authors for their valueable contributions:

• Alexander Reinert – for his generic_raw_uart kernel module enabling HomeMaticIP support with the ASUS Tinkerboard.

👪 Authors

See Contributors for a complete list of people that have directly contributed to this project.