various tidyups

packages/raspberry_pi_monitor.yaml

@@ -1,3 +1,67 @@
+#:########################################################################################:#
+# Raspberry Pi CCTV Monitor Package                                                      #
+#:########################################################################################:#
+#
+# TITLE:
+#   Raspberry Pi CCTV Monitor
+#
+# FILE:
+#   packages/raspberry_pi_monitor.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured documentation for MQTT, availability, and controls.
+#
+#   V1.0
+#     - Initial monitoring and remote-control configuration.
+#
+# PURPOSE:
+#   Monitors the cctvquad1 and cctvquad2 Raspberry Pi hosts and provides remote
+#   reboot and shutdown controls through MQTT.
+#
+# EXTERNAL DEPENDENCY:
+#   - Each Raspberry Pi requires an external process that publishes telemetry
+#     and state, consumes command topics, and performs the requested actions.
+#   - This package does not install or manage that external process.
+#
+# MQTT STATUS:
+#   Topic pattern:
+#     viewroad-status/rpis/<host>/<field>
+#
+#   Fields:
+#     cpu-temp, cpu-use, ram-use, disk-use, uptime, last-seen, ipv4-address,
+#     reboot, and shutdown.
+#
+#   The last-seen payload must be a timestamp that Home Assistant can parse with
+#   as_timestamp().
+#
+# MQTT COMMANDS:
+#   Topic pattern:
+#     viewroad-commands/rpis/<host>/reboot/set
+#     viewroad-commands/rpis/<host>/shutdown/set
+#
+#   Commands use the default MQTT switch ON/OFF payloads, QoS 1, and are not
+#   retained. The external process must publish matching switch state feedback.
+#
+# AVAILABILITY:
+#   - A host is considered available when its last-seen timestamp is valid and
+#     no more than 180 seconds old.
+#   - The template uses now(), so Home Assistant periodically re-evaluates age.
+#
+# GROUPS:
+#   - group.pi_cctvquad1_on collects Quad1 telemetry and controls.
+#   - group.pi_cctvquad2_on collects Quad2 telemetry and controls.
+#
+# SAFETY:
+#   - Reboot and shutdown interrupt CCTV services and host availability.
+#   - Shutdown may require physical access to power the host back on.
+#   - Dashboard controls should require confirmation before sending commands.
+#
+#:########################################################################################:#
+
 mqtt:
   sensor:
     - unique_id: cctvquad1_cpu_temp