Update OctoLight Home Assistant listing for v0.3.0

_plugins/octolightHA.md

@@ -3,87 +3,126 @@ layout: plugin
 
 id: octolightHA
 title: OctoLight Home Assistant
-description: Adds a button to the navbar, toggling a Home Assistant controlled light. Forked off of OctoLight by Žiga Kralj
+description: Control Home Assistant lights and switches from OctoPrint, with brightness, colour, print status lighting and delayed shutoff.
 authors:
 - Mark Bloom
-#- second autor name
-license: AGPLv3
-
-# today's date in format YYYY-MM-DD, e.g.
+- idontwantfame
+license: AGPL-3.0-or-later
 date: 2023-07-04
 
 homepage: https://github.com/mark-bloom/OctoLight_Home-Assistant
 source: https://github.com/mark-bloom/OctoLight_Home-Assistant
 archive: https://github.com/mark-bloom/OctoLight_Home-Assistant/archive/master.zip
 
-# Set this to true if your plugin uses the dependency_links setup parameter to include
-# library versions not yet published on pypi. SHOULD ONLY BE USED IF THERE IS NO OTHER OPTION!
-#follow_dependency_links: false
-
 tags:
 - raspberry pi
 - home assistant
 - lights
+- switch
+- automation
+- gcode
 
 screenshots:
-- url: /assets/img/plugins/octolightHA/screenshot.png 
-
-featuredimage: /assets/img/plugins/octolightHA/screenshot.png
-
-# You only need the following if your plugin requires specific OctoPrint versions or
-# specific operating systems to function - you can safely remove the whole
-# "compatibility" block if this is not the case.
+- url: /assets/img/plugins/octolightHA/controls.png
+  alt: OctoLight Home Assistant navbar controls for brightness and colour
+  caption: Toggle configured entities and adjust supported lights from the OctoPrint navbar.
+- url: /assets/img/plugins/octolightHA/settings.png
+  alt: OctoLight Home Assistant connection settings and entity discovery
+  caption: Connect to Home Assistant, search for entities and test access before saving.
+- url: /assets/img/plugins/octolightHA/automation.png
+  alt: OctoLight Home Assistant print automation and light appearance settings
+  caption: Configure delayed shutoff, host commands, brightness defaults and print status colours.
+
+featuredimage: /assets/img/plugins/octolightHA/controls.png
 
 compatibility:
-
-  # List of compatible versions
-  #
-  # A single version number will be interpretated as a minimum version requirement,
-  # e.g. "1.3.1" will show the plugin as compatible to OctoPrint versions 1.3.1 and up.
-  # More sophisticated version requirements can be modelled too by using PEP440
-  # compatible version specifiers.
-  #
-  # You can also remove the whole "octoprint" block. Removing it will default to all
-  # OctoPrint versions being supported.
-
   octoprint:
-  - 0.0.1
-
-  # List of compatible operating systems
-  #
-  # Possible values:
-  #
-  # - windows
-  # - linux
-  # - macos
-  # - freebsd
-  #
-  # There are also two OS groups defined that get expanded on usage:
-  #
-  # - posix: linux, macos and freebsd
-  # - nix: linux and freebsd
-  #
-  # You can also remove the whole "os" block. Removing it will default to all
-  # operating systems being supported.
-
+  - ">=1.8.0,<3"
   os:
   - linux
+  python: ">=3.9,<4"
 
-  # Compatible Python version
-  #
-  # Plugins should aim for compatibility for Python 2 and 3 for now, in which case the value should be ">=2.7,<4".
-  #
-  # Plugins that only wish to support Python 3 should set it to ">=3,<4".
-  #
-  # If your plugin only supports Python 2 (worst case, not recommended for newly developed plugins since Python 2
-  # is EOL), leave at ">=2.7,<3"
-
-  python: ">=2.7,<4"
-
+attributes:
+- ai-developed
 ---
 
-Adds a button to the navbar, toggling a Home Assistant controlled light. Forked off of OctoLight by Žiga Kralj
-
-
-![screenshot](/assets/img/plugins/octolightHA/settings1.png)
+Control your printer enclosure lighting and other Home Assistant lights or switches
+from OctoPrint. Search for entities in settings, toggle them from the navbar, and
+adjust brightness or RGB colour on supported lights. Optional automation follows
+print events and switches lights off after a configurable delay.
+
+Maintained by Mark Bloom and idontwantfame, originally based on
+[OctoLight by Žiga Kralj](https://github.com/gigibu5/OctoLight).
+
+## Features
+
+- Search Home Assistant by friendly name or entity ID and test access before saving.
+- Control multiple entities independently, with individual navbar icons, print
+  automation settings and shutoff timers.
+- Adjust brightness and RGB colour from navbar menus or configure turn-on defaults.
+- Refresh state from Home Assistant, including changes made in other apps.
+  Unavailable entities are distinguished from lights that are off.
+- Optionally apply configurable colours for printing, pause, completion, cancellation
+  and errors, plus a native short error flash on supported lights.
+- Turn lights on at print start and off after completion, failure or cancellation.
+  New prints and manual controls cancel pending completion shutoff timers.
+- Control configured entities using opt-in `@OCTOLIGHT` host commands or an
+  authenticated HTTP API.
+
+Brightness, RGB colour and native flashes depend on each light's capabilities.
+`switch` and `input_boolean` entities provide on/off control.
+
+## Requirements and setup
+
+Requires Python **>=3.9,<4**, OctoPrint **>=1.8.0,<3** on Linux, and a Home
+Assistant instance reachable from the OctoPrint host. Create a Home Assistant
+long-lived access token with access to the entities you want to control.
+
+1. Install the plugin and restart OctoPrint.
+2. Open **Settings → OctoLight Home Assistant**.
+3. Enter your Home Assistant URL and long-lived access token.
+4. Select **Search Home Assistant**, then choose a light, switch or input boolean.
+5. Select **Test connection and entity**, save, and configure optional automation.
+
+Tested with OctoPrint **1.8.0 / Python 3.9**, **1.11.8 / Python 3.9 and 3.10**,
+and **2.0.0rc7 / Python 3.12**. OctoPrint 2 testing covers this release candidate.
+Automated checks use Linux and a simulated Home Assistant; physical devices,
+Windows and macOS have not been verified.
+
+## G-code and API
+
+Enable **@OCTOLIGHT host commands** in settings to control configured entities from
+OctoPrint's Terminal, G-code scripts, streamed G-code files or OctoDash actions:
+
+```gcode
+@OCTOLIGHT on
+@OCTOLIGHT set brightness=75 color=#ff8000
+@OCTOLIGHT set light.printer color=#ff0000 flash=short
+@OCTOLIGHT off
+```
+
+Commands run asynchronously and target configured entities only. Printing directly
+from a printer's SD card does not process these host commands.
+
+The API is `/api/plugin/octolightHA`. GET reads cached state; authenticated JSON
+POST requests operate lights. See the
+[API documentation](https://github.com/mark-bloom/OctoLight_Home-Assistant#http-api)
+for commands and permission requirements.
+
+## Connections and credentials
+
+The plugin sends authenticated REST requests to the Home Assistant address you
+configure. Home Assistant can run locally; no vendor cloud account is required.
+Network requests use timeouts and run outside OctoPrint's event and serial command
+dispatch threads.
+
+New configurations verify HTTPS certificates by default; existing preferences are
+preserved on upgrade. Local HTTP addresses are also supported. The access token
+stays server-side, is masked in settings and is not logged. Credentials require
+Settings permission, light controls require Control permission, and state access
+requires Status permission.
+
+For configuration details, troubleshooting and release notes, see the
+[project README](https://github.com/mark-bloom/OctoLight_Home-Assistant)
+and [releases](https://github.com/mark-bloom/OctoLight_Home-Assistant/releases).