document shutdown report on systemctl/hostname/preparing-for-shutdown

CHANGELOG.md

@@ -8,7 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - forward logind's [PreparingForShutdown](https://www.freedesktop.org/wiki/Software/systemd/inhibit/)
   to `systemctl/hostname/preparing-for-shutdown`
-- log shutdown [inhibitor locks](https://www.freedesktop.org/wiki/Software/systemd/inhibit/)
+- log [inhibitor locks](https://www.freedesktop.org/wiki/Software/systemd/inhibit/)
+  when scheduling a shutdown
 
 ### Fixed
 - explicit timestamp type specification to avoid

README.md

@@ -6,7 +6,7 @@
 [![Last Release](https://img.shields.io/pypi/v/systemctl-mqtt.svg)](https://pypi.org/project/systemctl-mqtt/#history)
 [![Compatible Python Versions](https://img.shields.io/pypi/pyversions/systemctl-mqtt.svg)](https://pypi.org/project/systemctl-mqtt/)
 
-MQTT client triggering shutdown on [systemd](https://freedesktop.org/wiki/Software/systemd/)-based systems
+MQTT client triggering & reporting shutdown on [systemd](https://freedesktop.org/wiki/Software/systemd/)-based systems
 
 ## Setup
 
@@ -26,10 +26,18 @@ Schedule poweroff by sending a MQTT message to topic `systemctl/hostname/powerof
 $ mosquitto_pub -h MQTT_BROKER -t systemctl/hostname/poweroff -n
 ```
 
+### Shutdown Report
+
+`systemctl-mqtt` subscribes to [logind](https://freedesktop.org/wiki/Software/systemd/logind/)'s `PrepareForShutdown` signal.
+
+`systemctl halt|poweroff|reboot` triggers a message with payload `true` on topic `systemctl/hostname/preparing-for-shutdown`.
+
 ## Home Assistant 🏡
 
 ### Sample Setup
 
+#### Send Poweroff Command
+
 ```yaml
 # https://www.home-assistant.io/docs/mqtt/broker/#configuration-variables
 mqtt:
@@ -50,6 +58,19 @@ homeassistant:
       icon: mdi:power
 ```
 
+#### Trigger Automation on Shutdown
+
+```yaml
+automation:
+- trigger:
+    platform: mqtt
+    topic: systemctl/raspberrypi/preparing-for-shutdown
+    payload: 'true'
+  action:
+    service: switch.turn_off
+    entity_id: switch.desk_lamp
+```
+
 ## Docker 🐳
 
 1. Clone this repository.

docker-apparmor-profile

@@ -1,4 +1,4 @@
-# systemctl-mqtt - MQTT client triggering shutdown on systemd-based systems
+# systemctl-mqtt - MQTT client triggering & reporting shutdown on systemd-based systems
 #
 # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
 #

setup.py

@@ -1,4 +1,4 @@
-# systemctl-mqtt - MQTT client triggering shutdown on systemd-based systems
+# systemctl-mqtt - MQTT client triggering & reporting shutdown on systemd-based systems
 #
 # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
 #
@@ -29,7 +29,7 @@ setuptools.setup(
         "git_describe_command": "git describe --dirty --tags --long --match v*",
     },
     packages=setuptools.find_packages(),
-    description="MQTT client triggering shutdown on systemd-based systems",
+    description="MQTT client triggering & reporting shutdown on systemd-based systems",
     long_description=pathlib.Path(__file__).parent.joinpath("README.md").read_text(),
     long_description_content_type="text/markdown",
     author="Fabian Peter Hammerle",

systemctl_mqtt/__init__.py

@@ -1,4 +1,4 @@
-# systemctl-mqtt - MQTT client triggering shutdown on systemd-based systems
+# systemctl-mqtt - MQTT client triggering & reporting shutdown on systemd-based systems
 #
 # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
 #
@@ -286,7 +286,7 @@ def _main() -> None:
         datefmt="%Y-%m-%dT%H:%M:%S%z",
     )
     argparser = argparse.ArgumentParser(
-        description="MQTT client triggering shutdown on systemd-based systems",
+        description="MQTT client triggering & reporting shutdown on systemd-based systems",
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
     argparser.add_argument("--mqtt-host", type=str, required=True)

tests/test_cli.py

@@ -1,4 +1,4 @@
-# systemctl-mqtt - MQTT client triggering shutdown on systemd-based systems
+# systemctl-mqtt - MQTT client triggering & reporting shutdown on systemd-based systems
 #
 # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
 #

tests/test_dbus.py

@@ -1,4 +1,4 @@
-# systemctl-mqtt - MQTT client triggering shutdown on systemd-based systems
+# systemctl-mqtt - MQTT client triggering & reporting shutdown on systemd-based systems
 #
 # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
 #

tests/test_mqtt.py

@@ -1,4 +1,4 @@
-# systemctl-mqtt - MQTT client triggering shutdown on systemd-based systems
+# systemctl-mqtt - MQTT client triggering & reporting shutdown on systemd-based systems
 #
 # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
 #

tests/test_state_dbus.py

@@ -1,4 +1,4 @@
-# systemctl-mqtt - MQTT client triggering shutdown on systemd-based systems
+# systemctl-mqtt - MQTT client triggering & reporting shutdown on systemd-based systems
 #
 # Copyright (C) 2020 Fabian Peter Hammerle <fabian@hammerle.me>
 #