HomeMatic CCU add-on retirement/migration path (#2352)

* added first version of createBackup.sh for homematic addon

* move bin directory to opt/hm

* debug

* debug

* minor cleanup change.

* added a patched version of cp_security.cgi to support direct WebUI based
backup creation+download.

* minor fix

* minor fix

* version bump and removal of subsystem=tty filter for device spec

* added changed to CHANGELOG.md

* Added retirement notification

* Update README.md

* Update DOCS.md

* Update CHANGELOG.md

* fixed shellcheck errors.

* Update homematic/CHANGELOG.md

* Update homematic/config.yaml

Co-authored-by: Pascal Vizeli <pascal.vizeli@syshack.ch>

homematic/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+#### :warning: This add-on is considered to be obsolete/retired in favor of the much more advanced third-party [RaspberryMatic CCU](https://github.com/jens-maus/RaspberryMatic/tree/master/home-assistant-addon) add-on for running a HomeMatic/homematicIP smart home central within HomeAssistant. If you want to migrate to the new add-on, please make sure to update to the latest version of this old "HomeMatic CCU" add-on first and then use the WebUI-based backup routines to export a `*.sbk` config backup file which you can then restore in the new "RaspberryMatic CCU" add-on afterwards (cf. [RaspberryMatic Documentation](https://github.com/jens-maus/RaspberryMatic/wiki/Installation-HomeAssistant)) :warning:
+
+## 99.0.0
+
+- added a notification to the main add-on README that this add-on
+  is now considered obsolete/retired in favor of using the
+  "RaspberryMatic CCU" HomeAssistant add-on instead.
+- implemented a config backup routine which will allow to export
+  the current HomeMatic configuration in a somewhat compatible
+  file format (.sbk) to be able to directly import it into a
+  real CCU or the successor "RaspberryMatic" add-on.
+- modified config.yaml to allow to specify arbitrary devices and
+  not just tty devices. This should allow to specify the new
+  raw-uart device which will be required with upcoming HAos updates
+  supporting dualcopro mode for HmIP-RFUSB.
+
 ## 11.3.0
 
 - Update OCCU to 3.59.6

homematic/DOCS.md

@@ -1,5 +1,7 @@
 # Home Assistant Add-on: HomeMatic
 
+#### :warning: This add-on is considered to be obsolete/retired in favor of the much more advanced third-party [RaspberryMatic CCU](https://github.com/jens-maus/RaspberryMatic/tree/master/home-assistant-addon) add-on for running a HomeMatic/homematicIP smart home central within HomeAssistant. If you want to migrate to the new add-on, please make sure to update to the latest version of this old "HomeMatic CCU" add-on first and then use the WebUI-based backup routines to export a `*.sbk` config backup file which you can then restore in the new "RaspberryMatic CCU" add-on afterwards (cf. [RaspberryMatic Documentation](https://github.com/jens-maus/RaspberryMatic/wiki/Installation-HomeAssistant)) :warning:
+
 ## Installation
 
 Follow these steps to get the add-on installed on your system:

homematic/README.md

@@ -1,5 +1,7 @@
 # Home Assistant Add-on: HomeMatic
 
+#### :warning: This add-on is considered to be obsolete/retired in favor of the much more advanced third-party [RaspberryMatic CCU](https://github.com/jens-maus/RaspberryMatic/tree/master/home-assistant-addon) add-on for running a HomeMatic/homematicIP smart home central within HomeAssistant. If you want to migrate to the new add-on, please make sure to update to the latest version of this old "HomeMatic CCU" add-on first and then use the WebUI-based backup routines to export a `*.sbk` config backup file which you can then restore in the new "RaspberryMatic CCU" add-on afterwards (cf. [RaspberryMatic Documentation](https://github.com/jens-maus/RaspberryMatic/wiki/Installation-HomeAssistant)) :warning:
+
 HomeMatic central based on OCCU.
 
 ![Supports aarch64 Architecture][aarch64-shield] ![Supports amd64 Architecture][amd64-shield] ![Supports armhf Architecture][armhf-shield] ![Supports armv7 Architecture][armv7-shield] ![Supports i386 Architecture][i386-shield]

homematic/config.yaml

@@ -1,4 +1,4 @@
-version: 11.3.0
+version: 99.0.0
 slug: homematic
 name: HomeMatic CCU
 description: HomeMatic central based on OCCU
@@ -33,12 +33,12 @@ ports_description:
   80/tcp: ReGaHss Webinterface (Not required for Ingress)
 schema:
   hmip:
-    - device: device(subsystem=tty)
+    - device: device
       type: match(HMIP_CCU2)
   hmip_enable: bool
   regahss_reset: bool?
   rf:
-    - device: device(subsystem=tty)
+    - device: device
       reset: bool?
       type: match(CCU2)
   rf_enable: bool

homematic/rootfs/opt/hm/bin/createBackup.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+# shellcheck source=/dev/null
+#
+# simple backup script to create a CCU compatible .sbk type
+# backup out of the core-homematic HomeAssistant add-on
+#
+# Copyright (c) 2022 Jens Maus <mail@jens-maus.de>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Usage:
+# createBackup.sh <directory/file>
+#
+
+# Stop on error
+set -e
+
+# default backup destination directory
+BACKUPDIR=/tmp
+
+# let caller overwrite the backup path
+if [[ -n "${1}" ]]; then
+  BACKUPPATH="${1}"
+else
+  echo "ERROR: no backup path specified"
+fi
+
+# get running firmware version
+. /VERSION 2>/dev/null
+
+# check if specified path is a directory or file
+if [[ -d "${BACKUPPATH}" ]]; then
+  # a directory path was specified, lets construct the complete filepath
+  BACKUPDIR="$(realpath "${BACKUPPATH}")"
+  BACKUPFILE="$(hostname)-${VERSION}-$(date +%Y-%m-%d-%H%M).sbk"
+else
+  # a file was specified with a directory path
+  BACKUPDIR="$(realpath "$(dirname "${BACKUPPATH}")")"
+  BACKUPFILE="$(basename "${BACKUPPATH}")"
+fi
+
+# use the backupdir as base directory for creating
+# a temporary directory to create the backup stuff in there.
+TMPDIR=$(mktemp -d -p "${BACKUPDIR}")
+if [[ -d "${TMPDIR}" ]]; then
+  # make sure TMPDIR is removed under all circumstances
+  # shellcheck disable=SC2064
+
+  # make sure ReGaHSS saves its current settings
+  echo 'load tclrega.so; rega system.Save()' | /opt/hm/bin/tclsh >/dev/null 2>&1
+
+  # create a CCU conform copy of /usr/local
+  mkdir -p "${TMPDIR}/usr/local"
+  mkdir -p "${TMPDIR}/usr/local/etc/config"
+  cp -a /opt/hm/etc/config/* "${TMPDIR}/usr/local/etc/config/"
+  rm -f "${TMPDIR}/usr/local/etc/config/groups.gson" "${TMPDIR}/usr/local/etc/config/userprofiles"
+  cp -a /data/* "${TMPDIR}/usr/local/etc/config/"
+
+  # cleanup
+  rm -f "${TMPDIR}/usr/local/etc/config/options.json"
+  rm -f "${TMPDIR}/usr/local/etc/config/groups.json"
+  rm -f "${TMPDIR}/usr/local/etc/config/HMServer.conf"
+  rm -f "${TMPDIR}/usr/local/etc/config/hmip_user.conf"
+  rm -f "${TMPDIR}/usr/local/etc/config/log4j.xml"
+  rm -f "${TMPDIR}/usr/local/etc/config/rega.conf"
+  rm -f "${TMPDIR}/usr/local/etc/config/rega_user.conf"
+
+  # create a gzipped tar of /usr/local
+  set +e # disable abort on error
+  /bin/tar -C "${TMPDIR}" --owner=root --group=root --exclude=usr/local/tmp --exclude=usr/local/lost+found --exclude="${BACKUPDIR}" --exclude-tag=.nobackup --ignore-failed-read --warning=no-file-changed -czf "${TMPDIR}/usr_local.tar.gz" usr/local 2>/dev/null
+  if [[ $? -eq 2 ]]; then
+    exit 2
+  fi
+  set -e # re-enable abort on error
+
+  # remove the temp usr dir again
+  rm -rf "${TMPDIR:?}/usr"
+
+  # sign the configuration with the current key
+  /opt/hm/bin/crypttool -s -t 1 <"${TMPDIR}/usr_local.tar.gz" >"${TMPDIR}/signature"
+
+  # store the current key index
+  /opt/hm/bin/crypttool -g -t 1 >"${TMPDIR}/key_index"
+
+  # store the firmware VERSION
+  echo "VERSION=${VERSION}" >"${TMPDIR}/firmware_version"
+
+  # create sha256 checksum of all files
+  (cd "${TMPDIR}" && /usr/bin/sha256sum ./* >signature.sha256)
+
+  # create sbk file
+  /bin/tar -C "${TMPDIR}" --owner=root --group=root -cf "${BACKUPDIR}/${BACKUPFILE}" usr_local.tar.gz signature signature.sha256 key_index firmware_version 2>/dev/null
+
+  exit 0
+else
+  exit 1
+fi