POC event handler

HOWTO.md

@@ -350,13 +350,13 @@ python3 -m venv .venv
 .venv/bin/pip install -r requirements.txt
 ```
 
-Edit the supplied `config.yaml`. MQTT settings, collection timing, storage
+Edit the supplied `sensors.yaml`. MQTT settings, collection timing, storage
 paths, logging, all six sensors, RRD archives, and graph presentation are
 configured in this one file. Replace all five `CHANGE_ME` topics with the
 friendly names shown by Zigbee2MQTT:
 
 ```bash
-nano config.yaml
+nano sensors.yaml
 ```
 
 Sensor entries whose `name` begins with `CHANGE_ME` are placeholders and are
@@ -377,7 +377,7 @@ sudo install -d -o "$USER" -g "$USER" /var/lib/rrd
 sudo install -d -o "$USER" -g "$USER" /var/www/html/sensors
 ```
 
-Both paths can be changed under `storage` in `config.yaml`:
+Both paths can be changed under `storage` in `sensors.yaml`:
 
 ```yaml
 storage:
@@ -388,7 +388,7 @@ storage:
 Test one collection cycle:
 
 ```bash
-.venv/bin/python read_temperature.py --once
+.venv/bin/python zigbee_sensors.py --once
 ```
 
 The script creates one RRD file per sensor in the configured data directory and
@@ -404,7 +404,7 @@ samples existed before the RRD was created.
 
 Temperature uses the left axis with a default range of 0–30°C. Humidity and
 battery use the right axis with a default range of 0–100%. These ranges and
-labels can be changed in `config.yaml` under `graph.axes`. Temperature grid
+labels can be changed in `sensors.yaml` under `graph.axes`. Temperature grid
 labels default to five-degree intervals, and both axes display integers. Since
 RRDtool ties the right axis to the left, the corresponding percentage labels
 are rounded to integers. Light-grey reference lines are drawn at 15, 20, and
@@ -422,7 +422,7 @@ With a web server serving `/var/www/html`, open:
 http://RASPBERRY_PI_IP/sensors/
 ```
 
-The page settings are configurable in `config.yaml`:
+The page settings are configurable in `sensors.yaml`:
 
 ```yaml
 html:
@@ -440,7 +440,7 @@ a replacement.
 Run the ten-minute collection loop in the foreground with:
 
 ```bash
-.venv/bin/python read_temperature.py
+.venv/bin/python zigbee_sensors.py
 ```
 
 To run it automatically as a user service, copy the supplied service file. It
@@ -462,10 +462,76 @@ journalctl --user -u zigbee-rrd.service -f
 Graphs can be regenerated without collecting a new MQTT reading:
 
 ```bash
-.venv/bin/python read_temperature.py --graph-only
+.venv/bin/python zigbee_sensors.py --graph-only
 ```
 
 References:
 
 - [RRDtool database creation](https://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html)
+
+## 9. Log button and remote-control events
+
+`zigbee_events.py` runs continuously and logs Zigbee2MQTT messages that contain
+the configured event field. Edit `events.yaml` and set the MQTT broker's LAN IP,
+credentials if required, and the exact `zigbee2mqtt/<friendly_name>` topic for
+each device. Between one and five entries may be enabled.
+
+Validate the configuration without connecting to MQTT:
+
+```bash
+.venv/bin/python zigbee_events.py --check-config
+```
+
+For a foreground test, start the listener and then press a configured button:
+
+```bash
+.venv/bin/python zigbee_events.py
+tail -f zigbee-events.log
+```
+
+Ordinary state messages, such as battery or link-quality reports, are ignored
+unless they also contain the device's `event_field`. For the SONOFF SNZB-01M
+Orb, leave that field set to `action`.
+
+Each device's `events` mapping connects an event value to an allow-listed
+function. Unmapped events are logged but do not call a function:
+
+```yaml
+events:
+  single_button_1: denon.on
+  single_button_2: denon.off
+  single_button_3: denon.previous
+  single_button_4: denon.next
+```
+
+Volume actions are also available as `denon.volume_up` and
+`denon.volume_down`. Each call sends five volume steps to the receiver.
+
+The Denon receiver connection is also configured in `events.yaml`. Power
+actions use Denon's HTTP control endpoint; set **Settings → Network → Network
+Control** to **Always On** on the receiver so it remains reachable in standby:
+
+```yaml
+denon:
+  host: 192.168.178.177
+  port: 8080
+  timeout_seconds: 3
+  verify_tls: true
+```
+
+The supplied system service assumes the project is installed at
+`/opt/service_zigbee`:
+
+```bash
+sudo cp zigbee-events.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now zigbee-events.service
+sudo systemctl status zigbee-events.service
+```
+
+After changing `events.yaml`, restart the listener:
+
+```bash
+sudo systemctl restart zigbee-events.service
+```
 - [RRDtool graph elements](https://oss.oetiker.ch/rrdtool/doc/rrdgraph_graph.en.html)