Install Homegear Docker Image using podman and Homegear LAN Gateway

Useful Homegear Container Links

TopicLink
Homegearhttps://homegear.eu/
Podmanhttps://podman.io/
Homegear / Dockerhttps://hub.docker.com/r/homegear/homegear/
Dockerhttps://www.docker.com/

Podman

This project uses podman instead of docker. First of all, due to recent docker licensing. Second, podman uses the same command set and is fully compatible with docker, while at the same time deamon-less, eliminating some single point of failures and daemon issues.

Install Podman

Here is a link to the installation of podman on various platforms : https://podman.io/getting-started/installation
I use Ubuntu for the project.

Homegear docker image using podman

Homegear user

Create a home directory /home/homegear
Create a group for homegear – in my case I use the group named „openhab“ because I also use OpenHAB.
Create a user „homegear“ for homegear with the group and home above, set password
Add homegear user to additional groups : tty, dialout, docker

Homegear Docker image

Get homegear docker image, create container and run it.

su - homegear
mkdir homegear-data

podman pull homegear/homegear

podman container create --stop-timeout 300 --restart always -v /home/homegear/homegear-data/etc:/etc/homegear:Z -v /home/homegear/homegear-data/lib:/var/lib/homegear:Z -v /home/homegear/homegear-data/log:/var/log/homegear:Z -e TZ=Europe/Berlin -e HOST_USER_ID=1201 -e HOST_USER_GID=1200 -p 2000-2004:2000-2004 --name homegear homegear/homegear

podman start homegear

Configure Homegear for Homegear RS485 LAN Gateway

Cleanup your families folder and configure only what you need.

In my case, I have only the LAN RS485 Gateway and the CCU.

Connect to homegear and search actors

podman exec -i homegear homegear -r

Use homegear interactive commands to search for actors and configure homegear.
Enter „help“ for help.

See homegear documentation in the links table at the top of this article.

Building a Raspberry Pi 3 b+ based homegear server using openSuse Kubic and Docker

Abstract

This article is about how to setup an homegear server for controlling Homematic wired homeautomation components, replacing or complementing a CCU2/3.

Results and conclusions first …

After running homegear with an non docker direct installation on Ubuntu for several years with good experience, but having sometimes a hard time with updates, I thought I do it differntly next.

I thought about using SuSE MicroOS for improving updates and stability.
Using Docker and the homegear docker image, to improve homegear updates as well, ease the installation and make it more flexible.

In the end, I managed to install it, and basically it works fine, updates going smoothly, automatic and snapshots and rollebacks on MicroOS are low maintenance.

HOWEVER ….
Using this setup, the MicroSD card inside the Raspberry Pi seems to be pretty stressed, and I got corrupted filesystems after 3-6 months now using my 3rd sd card, that just died again.
I mean, that was outlined already on the Web by several people, that this could be an issue, because the sd cards are not suitable for this type of workload.
But I didn’t think it was THAT bad …

To fix the issue, I would have to add some sort of a USB3 ssd, hdd or M2/USB drive. But this requires again some additional power, cost and space.

Therefore I decided to go another way, using a LAN RS485 gateway from Homematic instead, and moving homegear to my home server that also runs Openhab.
In addition, I added a Raspi based RaspberryMATIC installation as a CCU equivalent, but I will add my experience with that to another blog article here that follows soon.

Anyway, this was a nice project, with quite a few challenges and plenty of learnings.
Maybe the experience is helpful still for one or the other.

Let me know your feedback !

Here’s the story ….

Overview

The Hardware

  • Raspberry Pi 3 b+
  • LiIO Battery backup unit shield
  • RS485 module
  • DC/DC converter for a wide input power range
  • Housing and mounting equipment

Software

  • OpenSuse MicroOS Kubic based on Tumbleweed
  • Docker
  • Homegear Docker image
  • libgpio2
  • libgpio-tools
  • python3-gpiod

Prepare Hardware

  • Install BBU shield
  • Instll Raspi 3 + BBU shield in housing
  • Add RS485 module
  • Add DC/DC converter

OS installation : OpenSuSE MicroOS Kubic based on Tumbleweed

OpenSuSE MicroOS Kubic

This distribution is pretty new, based on Tumbleweed and should fit perfect for Edge devices, like the Homegear RasPi server.
The Kubic distribution includes a minimum OS and kubeadm, so it should be perfectly suited for running any container deployments on the Edge.

I actually expect to reduce the effort for maintaining and updating this edge server, and I hope many of the maintainance tasks run smoother and are less time consuming.

However, since this is pretty new, time and experience in the next months will tell, if my expectations are satisfied.

Useful links and information

TopicLink
OpenSuse Kubic Portalhttps://en.opensuse.org/Portal:Kubic
Using Combustion with MicroOS for first boot / setuphttps://en.opensuse.org/Portal:MicroOS/Combustion
Micro OS Portalhttps://en.opensuse.org/Portal:MicroOS
Manual Network setup / wicked – OpenSuSE
This is for Leap, but also applies to MicroOS
https://doc.opensuse.org/documentation/leap/reference/html/book-opensuse-reference/cha-network.html#sec-network-manconf
OpenSuSE Managing GPIOs with libgpiod and toolshttps://en.opensuse.org/openSUSE:GPIO#direction:_choose_input_or_output_pin

Installation

Download the required Version from Kubic Portal
Copy to a suitable MicroSD card, using the procedures outlined on the linked site.

Create USB stick with combustion/ignititon –> combustion script used

Get a USB stick, make sure it has sufficient space, a supported Filesystem (I used vfat but e.g. ext4 also works) and the filesystem has a label named „combustion“

Create the following folders and files :

/combustion
/combustion/script
/combustion/routes
/combustion/ifcfg-eth0

Content of the „script“ file :

#!/bin/bash
# combustion: network
# Redirect output to the console
exec > >(exec tee -a /dev/tty0) 2>&1
# Install network config files
cp ifcfg-eth0 routes /etc/sysconfig/network
chmod 644 /etc/sysconfig/network/ifcfg-eth0
chmod 644 /etc/sysconfig/network/routes
systemctl restart network
# Set a password for root, generate the hash with "openssl passwd -6"
echo  'root:SomeHashofPasswordHere' | chpasswd -e
systemctl enable sshd.service
# Install vim-small
zypper --non-interactive install vim-small
# Leave a marker
echo "Configured with combustion for Homegear" > /etc/issue.d/combustion

Content of „ifcfg-eth0“ file :

STARTMODE='auto'
BOOTPROTO='static'
IPADDR='192.168.2.222/24'

Content of „routes“ file – replace IP address with your gateway/router :

default 192.168.1.1 - eth0

You can add other first boot setup steps to the script, that you think are useful.

Additional Software installed using transactional-update

Packages : 
rpi-eeprom-config
libgpiod-utils
python3-gpiod
libgpiod2
openSUSE-release-appliance-docker
yast2-docker
zypper-docker
yast2

RS485 Module connection and config

– RS485 Module PinRasPi 3 b+
GPIO connector pin#
FunctionGPIO #
Homegear, raspi-gpio
UART tty device
RO10RxD1 alt=515ttyAMA0
RE-31OUTPUT pull=NONE6
DE29OUTPUT pull=NONE5
DI8TxD1 alt=514ttyAMA0
VCC4+5V
GND6GND
ANoneA – RS485
BNoneB – RS485
RS485 Module connection to Raspi GPIO pins

Adjust Memory Map permissions

A kernel parameter needs to be added to allow the software to memory map /dev/mem or some of the tools below won’t work and give an mmap error.

in /etc/default/grub change the following (comment original and copy and modify) :

#GRUB_CMDLINE_LINUX_DEFAULT="quiet systemd.show_status=yes console=ttyS0,115200n8 console=tty0 net.ifnames=0 \$ignition_firstboot ignition.platform.id=metal"
GRUB_CMDLINE_LINUX_DEFAULT="quiet systemd.show_status=yes console=tty0 net.ifnames=0 iomem=relaxed"

The important part is the added „iomem=relaxed“ and notice that we removed ttyS0 as serial console, which is also important to avoid later issues with the serial UART.

On Kubic, you need to call transactional update for the kernel command line changes to apply :

transactional-update grub.cfg

Note : If you do multiple updates and changes at once, you might need the option –continue

Raspi 3 b+ GPIO pins and UART / serial devices

Raspberry Pi 3 b+ has 2 serial devices.
There is a PL011 and a mini UART. The later has only reduced capabilities.
Unfortunately, compared to the Raspi 2, these 2 devices are switched primary / secondary.
Furthermore, Blootooth is by default occuppying the PL011 UART, which is another cause of issues.
In some cases, by default, only the mini UART is available on GPIO Pins 8 and 10.
The mini UART does not work properly for the RS485 module.
Therefore, the GPIO settings have to be changed so that the PL011 UART uses the GPIO pins and the best is to disable BT.

Additional details can be found here

UART configuration RasPi : https://www.raspberrypi.org/documentation/configuration/uart.md

RasPi GPIO Howto : http://raspberrypiguide.de/howtos/raspberry-pi-gpio-how-to/

Diable any getty on ttyS0

To avoid later issues, any getty running on ttyS0 or ttyAMA* needs to be disabled.

chkconfig | grep getty

Typically with Kubic, there is a getty running on ttyS0 but not ttyAMA*

systemctl disable serial-getty@ttyS0.service
systemctl stop serial-getty@ttyS0.service

Make sure, you don’t accidentally disable the getty on tty1, or otherwise you won’t be able to login from the console.

Optional, I have added another getty to tty0 to have a second login on the virtual console.

For this, you need to do a few teps on Kubic, using the transactiona update :

transactional-update shell
cd /usr/lib/systemd/system
cp -a getty@tty1.service.d getty@tty0.service.d
exit
systemctl start getty@tty0
systemctl enable getty@tty0

Now reboot to update the snapshot.

Compile raspi-gpio from sources for Micro-OS

Install raspi-gpio from github sources : https://github.com/RPi-Distro/raspi-gpio.git

I have not found a similar tool to manage device alternate functions.
Since I did not find that tool as a rpm package, I had to compile the latest revision from sources.

If you do opt out to install this tool, it will make it more difficult to troubleshoot any GPIO / UART related issues.

Dependencies : git, make, automake, gcc, …

cd #Change to Root Home
git clone https://github.com/RPi-Distro/raspi-gpio
cd raspi-gpio
./configure #fails if you did not change the kernel parameters above
make
#make install #installed binary manual in /usr/local/bin
mv raspi-gpio /usr/local/bin
#Remove raspi-gpio source and build files for cleanup

Normally, on a Raspi 3, the serial0 is on GPIOs 32 and 33 while serial1 is on GPIOs 14 and 15.

raspi-gpio get #check the output for GPIO 32,33,14 and 15

Here is the compiled file for convenience, might not run on your version and you might need to compile it yourself, using the above procedure.

Modify RasPi configuration for GPIOs,UARTs and Serial devices

Set as needed for our homegear setup.

Change the UART usage in config.txt

Modifications to config.txt are required to fix the UART configuration for homegear.

On OpenSuSE MicroOS it is recommended to use extraconfig.txt for any custom changes to be save for updates.

transactional-update shell
vi /boot/vc/extraconfig.txt 


Edit the extraconfig.txt file (should be empty normally) and add the following lines :

#Make sure UART is enable 
enable_uart=1 

[pi3]

# Use miniUART for BT/WiFi and free the UART for RS485 module 
#dtoverlay=pi3-miniuart-bt 
dtoverlay=disable-bt 

[all]

dtparam=spi=on 
dtparam=i2c_arm=on

Remark :
I had issues with using „pi3-miniuart-bt“, which occationally worked, providing ttyAMA1 (!!) as devicefile for the PL011 UART.
However, suddenly this stopped working and I had no ttyAMA* at all anymore. The ttyAMA1 disapeared suddenly at a reboot after an update. A rollback did not bring it back, so I have no idea what caused this. Maybe some Raspi Firmware update that can not be rolled back with transactional-update.
The only way making this consistently work, was using „disable-bt“, which is not a big issue, because BlueTooth shouldn’t be used used anyway.
Disabling BT brings back the PL011 UART, but now as ttyAMA0, which I am using further in this article.

Copy file :

cp /boot/vc/extraconfig.txt /boot/efi/extraconfig.txt

Exit the transactional update shell and complete the changes with a reboot

exit

Please reboot your machine to activate the changes and avoid data loss. 
New default snapshot is #13 (/.snapshots/13/snapshot). 
transactional-update finished

reboot
Set the DE/RE pins for the RS485 module
raspi-gpio set 5 op pn dh
raspi-gpio set 6 op pn dl

Homegear Docker Image installation

Useful Homegear Links
TopicLink
Homegearhttps://homegear.eu/
Dockerhttps://www.docker.com/
Homegear / Dockerhttps://hub.docker.com/r/homegear/homegear/
Homegear user

Create a home directory /srv/homegear
Create a group for homegear
Create a user „homegear“ for homegear with the group and home above, set password
Add homegear user to additional groups : tty, dialout, docker

Configure systemd docker service

Change the timeout for the docker service, because startup might take some time.

transactional-update run vi /usr/lib/systemd/system/docker.service

Add the following timeout to the [Service] section.

TimeoutSec=900
Docker image

Get homegear docker image, create container and run it.

su - homegear
mkdir homegear-data

docker pull homegear/homegear

docker container create --privileged --stop-timeout 300 --restart always -v /srv/homegear/homegear-data/etc:/etc/homegear:Z -v /srv/homegear/homegear-data/lib:/var/lib/homegear:Z -v /srv/homegear/homegear-data/log:/var/log/homegear:Z -e TZ=Europe/Berlin -e HOST_USER_ID=1201 -e HOST_USER_GID=1200 -p 2001:2001 -p 2002:2002 -p 2003:2003 -p 2004:2004 --device=/dev/ttyAMA0 --name homegear homegear/homegear

docker start homegear

Copy raspi-gpio :

cp /usr/local/bin/raspi-gpio /srv/homegear/homegear-data/etc

Modify /srv/homegear/homegear-data/etc/homegear-start.sh
… add the lines for adding tty group for tty permissions for homegear
… add the lines for modifying gpio ports

Code of homegear-start.sh.sh with modifications, remember the directory mappings : /srv/homegear/homegear-data/etc:/etc/homegear – so, raspi-gpio is to be found there !

#!/bin/bash

# This script is executed before Homegear starts.

#Add group tty to homegear user, to access tty device
usermod -G tty,dialout homegear

#Modify GPIO settings to use proper tty on RasPi3
#Set the GPIOs 32 and 33 as Input and remove the serial functionality
/etc/homegear/raspi-gpio set 32 ip pn
/etc/homegear/raspi-gpio set 33 ip pn
#Change GPIO 14 and 15 from serial1 to serial0 (to use advanced PL011)
/etc/homegear/raspi-gpio set 14 a0 pn
/etc/homegear/raspi-gpio set 15 a0 pn

# Set permissions on interfaces and directories, export GPIOs.
/usr/bin/homegear -u homegear -g homegear -p /var/run/homegear/homegear.pid -pre

Restart docker image

docker restart homegear

Connect to homegear and search actors

docker exec -i homegear homegear -r

Use homegear interactive commands to search for actors and configure homegear.
Enter „help“ for help.

See homegear documentation in the links table at the top of this article.