FRITZ!-based Presence Detection for HomeMatic - hm_pdetect

This CCU-Addon allows to implement a general home presence detection system within a eQ3 HomeMatic homeautomation system. It regularly queries the WiFi/LAN status of user devices (e.g. Smartphones) logging in/out of AVM FRITZ! WiFi routers (e.g. FRITZ!Box, FRITZ!Repeater). Upon manually configured MAC and IP addresses of user devices this addon is able to set the general home presence status of that user in terms of setting CCU-based system variables. These variables can then be evaluated within the general HomeMatic home automation system. In addition, any device that is not recognized as a configured user devices or known device will otherwise be considered a guest device and a separate system variable set accordingly. This allows to identify any guests being present at the house so that e.g. the heating system of a guest room could be switched on/off accordingly.

Features

• Querying of several FRITZ!-devices (FRITZ!Box/Repeater) in one run
• User-definable interval for querying FRITZ!-devices regularly
• Support for manually triggering execution via CUxD SystemExec calls.
• Support for FRITZ!Box/Repeater local network login with and without password
• Possibility to remotely query FRITZ!-devices via https
• Support for querying a dedicated guest-WiFi network
• User device definition based on MAC and/or IP address
• Possibility to define multiple devices per user
• Automatically generates all necessary CCU system variables
• Additional String and Enum system variable to easily display the general presence status at home
• Guest detection based on unknown devices being identified in a dedicated Guest-WiFi
• Guest detection can be applied to the whole WiFi/LAN environment
• Web based configuration pages accessible via CCU-WebUI

Supported CCU models

• HomeMatic CCU3 / RaspberryMatic
• HomeMatic CCU2
• HomeMatic CCU1

Supported FRITZ! models

• All models of FRITZ!Box and FRITZ!Repeater running with FRITZ!OS 6 or newer

Configuration FRITZ! device

1. Open the web configuration of the individual FRITZ!-device (e.g. http://fritz.box/)
2. Create a new dedicated user via System->FRITZ!Box-User->Add User
   • Restrict access rights of user to FRITZ!Box Settings only
3. Open the Homenetwork-Login configuration at System->FRITZ!Box-User->Login to Homenetwork
   • Modify login setting to Login with FRITZ!Box-Username and Password

Installation as CCU Addon

1. Download of recent Addon-Release from Github
2. Installation of Addon archive (hm_pdetect-X.X.tar.gz) via WebUI interface of CCU device
3. Configuration of FRITZ!Box/Repeater (see next section)
4. Configuration of Addon using the WebUI accessible config pages

Manual Installation as stand-alone script (e.g. on RaspberryPi)

1. Create a new directory for hm_pdetect:

   mkdir /opt/hm_pdetect

2. Change to new directory:

   cd /opt/hm_pdetect

3. Download latest hm_pdetect.sh:

   wget https://github.com/homematic-community/hm_pdetect/raw/master/hm_pdetect.sh

4. Download of sample config:

   wget https://github.com/homematic-community/hm_pdetect/raw/master/hm_pdetect.conf.sample

5. Rename sample config to active one:

   mv hm_pdetect.conf.sample hm_pdetect.conf

6. Modify configuration according to comments in config file:

   vim hm_pdetect.conf

7. Execute hm_pdetect manually:

   /opt/hm_pdetect/hm_pdetect.sh

8. If you want to automatically start hm_pdetect on system startup a startup script

Using 'system.Exec()'

Instead of automatically calling hm_pdetect on a predefined interval one can also trigger its execution using the system.Exec() command within HomeMatic scripts on the CCU following the following syntax:

    system.Exec("/usr/local/addons/hm_pdetect/run.sh <iterations> <waittime> &");

Please note the <iterations> and <waittime> which allows to additionally specify how many times hm_pdetect should be executed with a certain amount of wait time in between. One example of such an execution can be:

    system.Exec("/usr/local/addons/hm_pdetect/run.sh 5 2 &");

This will execute hm_pdetect for a total amount of 5 times with a waittime of 2 seconds between each execution.

Support

In case of problems/bugs or if you have any feature requests please feel free to open a new ticket at the Github project pages. To seek for help for configuring/using this Addon please use the following german language based fora thread: hm_pdetect.

License

The use and development of this addon is based on version 3 of the LGPL open source license.

Authors

Copyright (c) 2015-2023 Jens Maus <mail@jens-maus.de>

Notice

This Addon uses KnowHow that was developed throughout the following projects:

• https://github.com/jollyjinx/homematic
• https://github.com/max2play/webinterface