Collection of CheckMK checks (see https://checkmk.com/). All checks and plugins are provided as is. Absolutely no warranty. Send any comments to thl-cmk[at]outlook[dot]com

Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • 2.2.x
2 results
Blame Permalink
README.md 14.63 KiB

AVM Fritz!Box Smarthome

This repository contains a additional check_MK Fritz!Box Agent which can gather informations over the AVM AHA HTTP Interface about SmartHome Devices connected to an Fritz!Box.

This package is based on the work of Maximilian Clemens (see Acknowledgements). I have rewritten this package for use with CMK 2.2.0x. As I do not have access to all Smarthome devices, I have only implemented the checks for the following devices:

FRITZ!DECT Repeater 100
  • Device Status
  • Temperature
FRITZ!DECT 200/210
  • App lock
  • Device lock
  • Device status
  • Energy
  • Power
  • Power socket
  • Switch
  • Temperature
  • Voltage
FRITZ!DECT 301/302
  • App lock
  • Battery
  • Device Lock
  • Device status
  • Temperature
  • Thermostat
FRITZ!DECT 350
  • Battery
  • Device status
  • Sensor
FRITZ!DECT 440
  • Battery
  • Button
  • Device status
  • Humidity
  • Temperature

So if you want the package to be extended to support your sensors as well, see Want to Contribute?.

Acknowledgments

This packages is based on the werk by MaximilianClemens see checkmk_fritzbox on GitHub

Packages contents

This package contains the follwing plugins
Service File Description
N/A agent_fritzbox_smarthome.py the actual agent
Device status fritzbox_smarthome.py the base check plugin
App lock fritzbox_smarthome_app_lock.py shows if the device can be accessed by App, Phone or UI
Battery fritzbox_smarthome_battery.py shows the the battery state
Button fritzbox_smarthome_button.py shows when a button was last pressed
Device Lock fritzbox_smarthome_device_lock.py shows if the buttons on the device are locked or not
Energy, Power, Voltage fritzbox_smarthome_power_meter.py shows electrical energy, electrical power and voltage
Humidity fritzbox_smarthome_humidity.py shows the relative humidity
Power Socket fritzbox_smarthome_power_socket.py shows the status of a switchable power socket
Sensor fritzbox_smarthome_sensor.py shows the status of a sensor (open/closed)
Switch fritzbox_smarthome_switch.py shows the status of a simple switch (on/off)
Temperature fritzbox_smarthome_temperature.py shows the temperature and offset of a temperature sensor
Thermostat fritzbox_smarthome_thermostat.py shows the working states of a thermostat (radiator controller)
N/A inv_fritzbox_smarthome.py adds the smarthome devices to the CMK HW/SW inventory

There is also a basic dashboard for AVM devices included.

Usage

How to configure the agent

Note: Before using this agent, please make sure that the names of your smart home devices are compatible with CMK. CMK only allows .-_a-zA-Z0-9. If your devices do not follow this pattern, the agent replaces (space) with _ and removes all other non-allowed characters from the host names.

After installing the package, create a new WATO rule Setup -> Other integrations -> Fritz!Box Smarthome devices. Here you need at least the user name and password to log in to your Fritz!Box For the password, I recommend using the CMK password store. The agent uses HTTPS on port TCP/443 by default and checks the certificate of your Fritz!Box, so if you do not have a good certificate, activate the option Ignore SSL errors. Don't forget to use your Fritz!Box as a condition with Explicit hosts.

Note: If you are also using the Fritz!Box agent with your Fritz1Box, you need to change in the CMK host settings of your Fritz!Box for Checkmk agent / API integrations to Configured API integrations, no Checkmk agent

By default, the agent uses the CMK piggyback mechanism for the Smarthome devices. Depending on your CMK edition, you therefore have two options for adding these hosts. In the RAW edition, you create them like any other host object (by hand, CSV, API). Set the following fields:

  • IP address family -> No IP
  • Checkmk agent / API integrations -> No API integration, no Checkmk agent
  • SNMP -> no SNMP
  • Piggyback -> Always use and expect piggyback data

In all othe editions you can use the Dynamic host management (DCD) to do this job for you. See Setup -> Dynamic host management.

Now you are ready to let CMK find your Smarthomne devices.

Command Line help

This is the Help txt from the agent.

OMD[build]:~$ ~/local/share/check_mk/agents/special/agent_fritzbox_smarthome --help
usage: agent_fritzbox_smarthome [-h] [--debug] [--ignore_ssl] [--no-piggyback] [--password [PASSWORD]]
                                [--username [USERNAME]] [--port [PORT]] [--prefix [PREFIX]]
                                [--protocol [{http,https}]] [--testing]
                                host

Check_MK Fritz!Box Smarthome Agent
This is an additional check_MK Fritz!Box Agent which can gather information's over the 
AVM AHA HTTP Interface about SmartHome Devices connected to an Fritz!Box.

positional arguments:
  host                  Host name or IP address of your Fritz!Box

options:
  -h, --help            show this help message and exit
  --debug               Debug mode: let Python exceptions come through
  --ignore_ssl          Tha agent will ignores SSL errors
  --no-piggyback        By default the agent generates the output as piggyback data for each
                        Samrthome device. If you want to attach all your Smarthome devices directly
                         to your Fritz!Box use this option.
  --password [PASSWORD]
                        The password to logon the Fritz!Box
  --username [USERNAME]
                        The username to logon to the Fritz!Box
  --port [PORT]         The TCP port on witch to access the Fritz!Box
  --prefix [PREFIX]     The prefix is used to group all the Smarthome devices from one Fritz!Box in CMK.
  --protocol [{http,https}]
                        The protocol used to access the Fritz!Box
  --testing             Development usage only (might be ignored)

Download

Note: before you update to a newer version, always check the CHANGELOG. There might be incompatible changes.

Installation

You can install the package by uploading it to your CheckMK site and as site user run

mkp add PAKAGE_NAME.mkp
mkp enable PAKAGE_NAME VERSION

In the Enterprise/Free/Cloud edition of CheckMK you can use the GUI to install the package (Setup -> Extension Packages -> Upload package)

Want to Contribute?

Nice ;-) Have a look at the contribution guidelines

Check Info

Device status
The plugin creates the services "Device status" for each discovered device. In non pigyback mode the device ID is used as item.

Monitoring states
State condition WATO
WARN/CRIT if the device is offline yes

Perfdata

This plugin has no perfdata.


WATO
Section Rule name
Applications, Processes & Services Fritz!Box Smarthome Devices
Option Defailt value
Monitoring state for offline devices WARN
App lock
The plugin creates the service "APP lock" for each discovered device. In non pigyback mode the device ID is used as item.

Monitoring states
State condition WATO
WARN/CRIT if App lock is activated/deactivated yes

Perfdata

This plugin has no perfdata.


WATO
Section Rule name
Applications, Processes & Services Fritz!Box Smarthome App Lock
Option Defailt value
Manual access for phone, app or user interface Activated -> OK
Battery
The plugin creates the service "Battery" for each discovered battery. In non pigyback mode the device ID is used as item.

Monitoring states
State condition WATO
WARN/CRIT if the battery is low yes

Perfdata

This plugin has no perfdata.


WATO
Section Rule name
Applications, Processes & Services Fritz!Box Smarthome Battery
Option Defailt value
Monitoring state on low battery CRIT
Device lock
The plugin creates the service "Device lock" for each discovered device. In non pigyback mode the device ID is used as item.

Monitoring states
State condition WATO
WARN/CRIT if the bdevice lock is activated/deactivated yes

Perfdata

This plugin has no perfdata.


WATO
Section Rule name
Applications, Processes & Services Fritz!Box Smarthome Device Lock
Option Defailt value
Button lock on the device Activated -> OK
Energy, Power and Voltage
The plugin creates the services "Energy", "Power" and "Voltage" for each discovered device. In non pigyback mode the device ID is used as item.

Monitoring states
State condition WATO
WARN/CRIT if energy outside upper/lower levels yes
WARN/CRIT if power above upper levels yes
WARN/CRIT if voltage outside upper/lower levels yes

Perfdata
Metric Unit Perfometer
Cost this day ¤ yes
Cost this hour ¤ yes
Cost this month ¤ yes
Cost this year ¤ yes
Energy since last Wh yes
Energy Total Wh no
Time between readings s no
Power W yes
Voltage V yes

WATO
Section Rule name
Applications, Processes & Services Electrical Energy
Option Defailt value
Upper levels for electrical energy no defaults
Lower levels for electrical energy no defaults
Cost per kWh 030€

Note: Power and Voltage uses the build-in WATO rulsets (Electrical Power for Devices with only one phase / Voltage Sensor)

Power socket
The plugin creates the service "Power Socket" for each discovered device. In non pigyback mode the device ID is used as item.

Monitoring states
State condition WATO
WARN/CRIT if state on/off yes
WARN/CRIT if mode manuell/automatic yes

Perfdata

This plugin has no perfdata.


WATO
Section Rule name
Applications, Processes & Services Fritz!Box Smarthome Power socket
Option Defailt value
Power Socket state Switched on -> OK
Power Socket switching mode Manuell -> OK
Temperature
The plugin creates the service "Temperature" for each discovered temperature sensor. In non pigyback mode the device ID is used as item.

Monitoring states

This plugin uses the build-in Temperature WARN/CRIT levels.


Perfdata

Temperature in °C


WATO

This plugin uses the build-in Temperature rule set.

Thermostat
The plugin creates the service "Thermostat" for each discovered device with thermostat function. In non pigyback mode the device ID is used as item.

Monitoring states
State condition WATO
WARN/CRIT if temperature deviates from target yes
WARN/CRIT if thermostat is off yes
WARN/CRIT on error yes

Perfdata
Metric Unit Perfometer
Temperature current °C yes
Temperature target °C yes
Temperature comfort °C no
Temperature economic °C no

WATO
Section Rule name
Applications, Processes & Services Fritz!Box Smarthome Thermostat
Option Defailt value
Deviation from target temperature 2°C/5°C
Monitoring state if thermostat is off OK
Monitoring state on error WARN

WATO

Service monitoring rules

see Check Info

Special agent rule

-> Setup -> Agents -> Other integrations

Section Rule name
Hardware Fritz!Box Smarthome Devices
Option Description Defailt value
Username no default Username to logon to the FritzBox
Password no default Password for the user to log on
Port 443 The TCP Port used to connect to the Fritz!Box
Protocol HTTPS The Protocol used to connect to the Fritz!Box
Ignore SSL errors don't ignire errors Tha agent will ignores SSL errors
Add Prefix don't add prefx The prefix is used to group all the Smarthome devices from one Fritz!Box in CMK
Disable piggyback use piggyback If you want to attach all your Smarthome devices directly to your Fritz!Box use this option
Add test data disabled only for development, will be removed
Discovery rule There is on discovery rule.
HW/SW inventory rules The inventory plugin is not configurable.

Sample Output

Sample output

sample output

Sample output details

sample output details

Sample inventory

sampleinventory

Collection of CheckMK checks (see https://checkmk.com/). All checks and plugins are provided as is. Absolutely no warranty. Send any comments to thl-cmk[at]outlook[dot]com