various tidyups

packages/moonraker_3dprinter.yaml

@@ -1,4 +1,72 @@
-# === Add friendly names, icons, and area for printer controls ===
+#:########################################################################################:#
+# Moonraker 3D Printer Package                                                           #
+#:########################################################################################:#
+#
+# TITLE:
+#   Moonraker 3D Printer
+#
+# FILE:
+#   packages/moonraker_3dprinter.yaml
+#
+# VERSION:
+#   V1.1 2026-07-20
+#
+# VERSION HISTORY:
+#   V1.1 2026-07-20
+#     - Added structured documentation for setup, polling, outputs, and safety.
+#     - Recorded that the Creality printer is not currently connected.
+#
+#   V1.0
+#     - Initial Moonraker REST sensors, commands, and customizations.
+#
+# PURPOSE:
+#   Reads Klipper and Moonraker printer data and provides Home Assistant REST
+#   commands for controlling a Creality K1C 3D printer.
+#
+# CURRENT STATUS:
+#   - As of 2026-07-20, this configuration no longer connects to the printer.
+#   - It is retained as a reference for future reconnection work.
+#   - Before reconnecting, verify the printer address, Moonraker availability,
+#     queried Klipper object names, and companion template entities.
+#
+# DEPENDENCIES:
+#   - A reachable Moonraker server for the Klipper printer.
+#   - Current configured endpoint: http://192.168.2.31:7125
+#   - Companion templates: templates/moonraker_3dprinter.yaml
+#   - The queried sensors and object names must match the Klipper configuration.
+#
+# POLLING:
+#   - Full printer status, printer info, and server data poll every second.
+#   - Current print file metadata polls every five seconds.
+#
+# RAW REST OUTPUTS:
+#   - sensor.printer_3d_sensor provides printer object status attributes.
+#   - sensor.printer_3d_info provides printer state and state message.
+#   - sensor.printer_3d_server provides Mainsail server configuration data.
+#   - sensor.printer_3d_file_metadata provides current-file metadata.
+#   - Companion templates derive user-facing sensors from these raw entities.
+#
+# CONTROLS:
+#   - Emergency stop immediately halts the printer.
+#   - Firmware restart restarts the Klipper firmware process.
+#   - Cancel stops the current print; pause and resume control print progress.
+#
+# SAFETY AND NETWORK:
+#   - Emergency stop, firmware restart, and cancel are disruptive actions and
+#     should only be exposed through dashboard controls with confirmation.
+#   - The configured endpoint uses unencrypted HTTP without authentication and
+#     assumes Moonraker is available only on a trusted local network.
+#
+# USER CONFIGURATION:
+#   - If the printer address changes, update every Moonraker URL in this file.
+#   - Confirm the filament and chamber sensor object names before reconnecting.
+#
+#:########################################################################################:#
+
+#:########################################################################################:#
+# Home Assistant Customizations                                                          #
+#:########################################################################################:#
+
 homeassistant:
   customize:
     rest_command.3d_printer_emergency_stop: