[PACKAGE]: ../../raw/master/mkp/fritzbox_smarthome-0.9.1-20240617.mkp "fritzbox_smarthome-0.9.1-20240617.mkp"
# 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)](#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:

<details><summary>FRITZ!DECT Repeater 100</summary>

- Device Status
- Temperature

</details>
<details><summary>FRITZ!DECT 200/210</summary>

- App lock
- Device lock
- Device status
- Energy
- Power
- Power socket
- Switch
- Temperature
- Voltage

</details>

<details><summary>FRITZ!DECT 301/302</summary>

- App lock
- Battery
- Device Lock
- Device status
- Temperature
- Thermostat

</details> 

<details><summary>FRITZ!DECT 350</summary>

- Battery
- Device status
- Sensor

</details> 

<details><summary>FRITZ!DECT 440</summary>

- Battery
- Button
- Device status
- Humidity
- Temperature

</details> 

So if you want the package to be extended to support your sensors as well, see [Want to Contribute?](CONTRIBUTING.md).

---
### Acknowledgments

This packages is based on the werk by [MaximilianClemens](https://github.com/MaximilianClemens) see [checkmk_fritzbox on GitHub](https://github.com/MaximilianClemens/checkmk_fritzbox)

---
### Packages contents

<details><summary>This package contains the follwing plugins</summary>


| 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          |

</details>

There is also a basic dashboard for AVM devices included.

---
### Usage

<details><summary>How to configure the agent</summary>
<br>

**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.

</details>

<details><summary>Command Line help</summary>
<br>

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)
```

</details>

---
### Download
* [Download latest mkp file][PACKAGE]

**Note**: before you update to a newer version, always check the [CHANGELOG](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](CONTRIBUTING.md "Contributing")

---
### Check Info

<details><summary>Device status</summary>
<br>
The plugin creates the services "Device status" for each discovered device. In non pigyback mode the device ID is used as item.
<br>
<br>
Monitoring states

| State | condition | WATO | 
| ------ | ------ | ------ |
| WARN/CRIT | if the device is offline | yes |


<br>
Perfdata

This plugin has no perfdata.

<br>
WATO 

| Section | Rule name |
| ------ | ------ |
| Applications, Processes & Services | Fritz!Box Smarthome Devices |

| Option | Defailt value |
| ------ | ------ |
| Monitoring state for offline devices | WARN |

</details>

<details><summary>App lock</summary>
<br>
The plugin creates the service "APP lock" for each discovered device. In non pigyback mode the device ID is used as item.
<br>
<br>
Monitoring states

| State | condition | WATO | 
| ------ | ------ | ------ |
| WARN/CRIT | if App lock is activated/deactivated | yes |

<br>
Perfdata

This plugin has no perfdata.

<br>
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 |


</details>

<details><summary>Battery</summary>
<br>
The plugin creates the service "Battery" for each discovered battery. In non pigyback mode the device ID is used as item.
<br>
<br>
Monitoring states

| State | condition | WATO | 
| ------ | ------ | ------ |
| WARN/CRIT | if the battery is low | yes |

<br>
Perfdata

This plugin has no perfdata.

<br>
WATO 

| Section | Rule name |
| ------ | ------ |
| Applications, Processes & Services | Fritz!Box Smarthome Battery |

| Option | Defailt value |
| ------ | ------ |
| Monitoring state on low battery | CRIT |


</details>

<details><summary>Device lock</summary>
<br>
The plugin creates the service "Device lock" for each discovered device. In non pigyback mode the device ID is used as item.
<br>
<br>
Monitoring states

| State | condition | WATO | 
| ------ | ------ | ------ |
| WARN/CRIT | if the bdevice lock is activated/deactivated | yes |

<br>
Perfdata

This plugin has no perfdata.

<br>
WATO 

| Section | Rule name |
| ------ | ------ |
| Applications, Processes & Services | Fritz!Box Smarthome Device Lock |

| Option | Defailt value |
| ------ | ------ |
| Button lock on the device | Activated -> OK |

</details>

<details><summary>Energy, Power and Voltage</summary>
<br>
The plugin creates the services "Energy", "Power" and "Voltage" for each discovered device. In non pigyback mode the device ID is used as item.
<br>
<br>
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 |

<br>
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 |

<br>
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)

</details>


<details><summary>Power socket</summary>
<br>
The plugin creates the service "Power Socket" for each discovered device. In non pigyback mode the device ID is used as item.
<br>
<br>
Monitoring states

| State | condition | WATO | 
| ------ | ------ | ------ |
| WARN/CRIT | if state on/off | yes |
| WARN/CRIT | if mode manuell/automatic | yes |

<br>
Perfdata

This plugin has no perfdata.

<br>
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 |

</details>


<details><summary>Temperature</summary>
<br>
The plugin creates the service "Temperature" for each discovered temperature sensor. In non pigyback mode the device ID is used as item.
<br>
<br>
Monitoring states

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

<br>
Perfdata

Temperature in °C

<br>
WATO 

This plugin uses the build-in Temperature rule set.


</details>


<details><summary>Thermostat</summary>
<br>
The plugin creates the service "Thermostat" for each discovered device with thermostat function. In non pigyback mode the device ID is used as item.
<br>
<br>
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 |

<br>
Perfdata

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

<br>
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 |

</details>

---
### WATO
<details><summary>Service monitoring rules</summary>

see Check Info

</details> 

<details><summary>Special agent rule</summary>

-> 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 |

</details> 

<details><summary>Discovery rule</summary>
There is on discovery rule.
</details> 

<details><summary>HW/SW inventory rules</summary>
The inventory plugin is not configurable.
</details> 

---
### Sample Output

Sample output

![sample output](img/sample.png?raw=true "sample output")

Sample output details

![sample output details](img/sample-details.png?raw=true "sample output details")

Sample inventory

![sampleinventory](img/sample_inventory.png?raw=true "sample inventory")