various tidyups

packages/16a_ev_charging_controls.yaml

@@ -4,17 +4,60 @@
 # PACKAGE: 16A EV Charger Control
 ###############################################################################
 #
+# FILE:
+#   packages/16a_ev_charging_controls.yaml
+#
 # VERSION:
+#   V1.2 2026-07-20
+#     - Added structured mode, timing, and restart behavior documentation.
+#
 #   V1.1 2026-05-15
 #     - Reworked 1hr topup logic to use a hard deadline and watchdog.
 #     - Removed dependency on timer.finished event for relay shutoff.
 #     - Offpeak until charged now continues past offpeak end until charging stops.
-#     - 1hr topup now now rolls into Normal Offpeak if the hour ends during
+#     - 1hr topup now rolls into Normal Offpeak if the hour ends during
 #       the offpeak window, without switching the relay off and back on.
 #
 #   V1.0 2026-05-11
 #     - Initial package for 16A EV charger offpeak and charge-until-full control.
 #
+# PURPOSE:
+#   Controls the Leaf 16A charger relay using scheduled offpeak operation and
+#   user-selectable immediate or charge-until-full modes.
+#
+# DEPENDENCIES:
+#   - switch.garage_db_control_16a_wallcharger_operation controls charger power.
+#   - binary_sensor.garage_db_control_16a_wallcharger_charging reports whether
+#     the vehicle is actively charging.
+#
+# CHARGE MODES:
+#   - Normal (Offpeak) turns the relay on and off at the configured offpeak
+#     start and end times. Selecting this mode takes no immediate action.
+#   - Offpeak until charged starts at the offpeak time, or immediately if
+#     selected during offpeak, and may continue beyond offpeak end until the
+#     vehicle stops charging.
+#   - 1hr topup now turns the relay on immediately and records a hard deadline
+#     one hour ahead.
+#   - Charge now until full turns the relay on immediately and keeps it on until
+#     the vehicle stops charging.
+#   - Stop charging now turns the relay off immediately and returns the selector
+#     to Normal (Offpeak).
+#
+# TIMING AND COMPLETION:
+#   - Charge-until-full modes allow five minutes for charging to start. This
+#     also handles a vehicle that is already full.
+#   - Charging is considered complete after the charging sensor remains off for
+#     five minutes.
+#   - The one-hour topup deadline is stored in input_datetime and checked every
+#     minute and when Home Assistant starts.
+#   - If a topup ends during offpeak, the relay remains on and the mode returns
+#     to Normal (Offpeak), avoiding an off/on relay cycle.
+#   - Equal offpeak start and end times are interpreted as an all-day window.
+#
+# OPERATION NOTES:
+#   - Normal offpeak start and end use exact-time triggers.
+#   - There is no startup catch-up if Home Assistant is offline at either time.
+#
 # PACKAGE SETTINGS:
 #   Car display name:
 #     - Leaf