homematic-community / hm_pdetect

:iphone: A HomeMatic CCU-Addon to regularly query AVM FRITZ!-devices for registered WiFi/LAN devices and deduce general user presence from this information
GNU Lesser General Public License v3.0
74 stars 6 forks source link
ccu homematic homematic-ip

FRITZ!-based Presence Detection for HomeMatic - hm_pdetect

Release Downloads Issues License Donate

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

Supported CCU models

Supported FRITZ! models

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: