various tidyups

packages/firewall_control.yaml

@@ -1,3 +1,50 @@
+#:########################################################################################:#
+# Firewall Internet Control Package                                                     #
+#:########################################################################################:#
+#
+# TITLE:
+#   Firewall Internet Control
+#
+# FILE:
+#   packages/firewall_control.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured MQTT and external-firewall documentation.
+#
+#   V1.0
+#     - Initial persistent and temporary internet-blocking controls.
+#
+# PURPOSE:
+#   Provides Home Assistant controls for persistent and temporary internet
+#   blocking of Mollie's devices through an external MQTT firewall service.
+#
+# PERSISTENT CONTROL:
+#   - Blocked enables persistent internet blocking.
+#   - Unblocked disables persistent internet blocking.
+#   - The switch state is reported by the external firewall service.
+#
+# TEMPORARY CONTROLS:
+#   - One-hour block publishes Blocked to the temporary-block topic.
+#   - 15-minute unblock publishes Unblocked to the temporary-unblock topic.
+#   - One-hour unblock publishes Unblocked to its one-hour topic.
+#
+# EXTERNAL DEPENDENCY:
+#   - Home Assistant only publishes command requests.
+#   - The external firewall service implements temporary durations, restores the
+#     appropriate state afterward, and publishes persistent switch feedback.
+#
+# MQTT NOTES:
+#   - All commands are non-retained.
+#   - No availability topic is configured for these entities.
+#   - The persistent status topic retains the legacy device label
+#     block-unblock-mollie-iphone8.
+#
+#:########################################################################################:#
+
 mqtt:
   switch:
     - unique_id: mollies.internet