various tidyups

packages/waste_collection.yaml

@@ -1,8 +1,61 @@
+#:########################################################################################:#
+# Auckland Council Waste Collection Package                                             #
+#:########################################################################################:#
+#
+# TITLE:
+#   Auckland Council Waste Collection
+#
+# FILE:
+#   packages/waste_collection.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added source setup, schedule, MQTT, and maintenance documentation.
+#
+#   V1.0
+#     - Initial Auckland Council schedules and MQTT bin-status sensors.
+#
+# PURPOSE:
+#   Provides Auckland Council rubbish, recycling, and food-waste collection
+#   schedules, plus independent MQTT sensors indicating whether bins are out.
+#
+# DEPENDENCY:
+#   Requires the Waste Collection Schedule custom integration and its
+#   aucklandcouncil_govt_nz source.
+#
+# AREA NUMBER SETUP:
+#   - Open the Auckland Council rubbish and recycling collection-day finder.
+#   - Select the property address.
+#   - Use the displayed assessment number as area_number below.
+#   - Source documentation:
+#     https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/aucklandcouncil_govt_nz.md
+#
+# SCHEDULE SENSORS:
+#   - Types are rubbish, recycle, and food-waste.
+#   - Each sensor returns one upcoming collection with a one-day lead time.
+#   - details_format is upcoming and add_days_to adds relative-day text.
+#
+# MQTT BIN-OUT SENSORS:
+#   - These sensors are independent of the council collection schedules.
+#   - An external publisher must send status to the configured MQTT topics.
+#   - Payloads remain raw sensor strings such as "true"; these are not binary
+#     sensor entities and no boolean conversion is performed here.
+#
+# CURRENT STATUS:
+#   - As of 2026-07-20, the rubbish schedule resolves correctly.
+#   - Recycling and food-waste report unknown; review the source type names when
+#     investigating those schedules.
+#
+#:########################################################################################:#
+
 waste_collection_schedule:
   sources:
     - name: aucklandcouncil_govt_nz
       args:
-        area_number: 12344403722 # see 'How to get the source argument below'
+        area_number: 12344403722 # Auckland Council assessment number.
 
 sensor:
   - platform: waste_collection_schedule