diff --git a/_plugins/octolightHA.md b/_plugins/octolightHA.md index 67d3473373e5..6a96eedcd0ff 100644 --- a/_plugins/octolightHA.md +++ b/_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). diff --git a/assets/img/plugins/octolightHA/automation.png b/assets/img/plugins/octolightHA/automation.png new file mode 100644 index 000000000000..a09758ba640d Binary files /dev/null and b/assets/img/plugins/octolightHA/automation.png differ diff --git a/assets/img/plugins/octolightHA/controls.png b/assets/img/plugins/octolightHA/controls.png new file mode 100644 index 000000000000..fe4cc682e247 Binary files /dev/null and b/assets/img/plugins/octolightHA/controls.png differ diff --git a/assets/img/plugins/octolightHA/screenshot.png b/assets/img/plugins/octolightHA/screenshot.png deleted file mode 100644 index 87f1a70e2b2f..000000000000 Binary files a/assets/img/plugins/octolightHA/screenshot.png and /dev/null differ diff --git a/assets/img/plugins/octolightHA/settings.png b/assets/img/plugins/octolightHA/settings.png new file mode 100644 index 000000000000..6afe9e8304fb Binary files /dev/null and b/assets/img/plugins/octolightHA/settings.png differ diff --git a/assets/img/plugins/octolightHA/settings1.png b/assets/img/plugins/octolightHA/settings1.png deleted file mode 100644 index 4b749fa44ac6..000000000000 Binary files a/assets/img/plugins/octolightHA/settings1.png and /dev/null differ