From 4b7a5b664406bd81e1e6d8a85e36e770645954df Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 3 May 2026 08:41:38 +0000 Subject: [PATCH 1/2] docs: 2025.x version coverage, requirements marker, 2025.2 upgrade notes, ConfigUiValues callbacks - quick-start.md: expand version reference table (paths, Python, Runtime API) to cover 2025.2 / 2025.1 / 2023.2 and clarify ServerApiVersion is a minimum - common-issues.md + quick-start.md: document version-keyed pip success marker (3.13-pip-install-log-success.txt on 2025.2) - common-issues.md: add "Upgrading to Indigo 2025.2 / Python 3.13" section covering telnetlib removal, websockets v14+ rename, matplotlib legendHandles and plot_date deprecations - plugin-lifecycle.md: add ConfigUI pre-population callbacks reference covering all five get*ConfigUiValues callbacks (incl. previously undocumented getMenuActionConfigUiValues and getActionConfigUiValues), with menu-item date-default and device-token examples - cross-link new reference from menu-items.md, actions.md, devices.md, configui.md, events.md, plugin-preferences.md - bump plugin.json + marketplace.json to 1.9.0 Closes #32, #33, #34, #35 https://claude.ai/code/session_01PBR2a67rzj9NsZ8Vpmat6H --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- docs/plugin-dev/concepts/actions.md | 2 + docs/plugin-dev/concepts/configui.md | 4 ++ docs/plugin-dev/concepts/devices.md | 2 + docs/plugin-dev/concepts/events.md | 2 + docs/plugin-dev/concepts/menu-items.md | 2 + docs/plugin-dev/concepts/plugin-lifecycle.md | 43 ++++++++++++++++ .../plugin-dev/concepts/plugin-preferences.md | 2 + docs/plugin-dev/quick-start.md | 30 +++++++---- .../troubleshooting/common-issues.md | 51 ++++++++++++++++++- 11 files changed, 127 insertions(+), 15 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6f8d390..ccba5f3 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ "name": "indigo", "source": "./", "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building", - "version": "1.8.0", + "version": "1.9.0", "repository": "https://github.com/simons-plugins/indigo-claude-plugin", "license": "MIT", "keywords": [ diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ad2b3c5..405903b 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "indigo", - "version": "1.8.0", + "version": "1.9.0", "description": "Indigo home automation development toolkit \u2014 plugin development, API integration, and control page building", "repository": "https://github.com/simons-plugins/indigo-claude-plugin" } diff --git a/docs/plugin-dev/concepts/actions.md b/docs/plugin-dev/concepts/actions.md index 1c60b1f..b2056aa 100644 --- a/docs/plugin-dev/concepts/actions.md +++ b/docs/plugin-dev/concepts/actions.md @@ -35,6 +35,8 @@ Define custom plugin actions in `Actions.xml`. Users configure and trigger these ``` +To pre-populate fields with computed or live values when the dialog opens (e.g. seed `brightness` from the device's current state), override `getActionConfigUiValues(self, plugin_props, type_id, dev_id)` — see [`plugin-lifecycle.md`](plugin-lifecycle.md#configui-pre-population-callbacks). + ### Action Targeting All Devices ```xml diff --git a/docs/plugin-dev/concepts/configui.md b/docs/plugin-dev/concepts/configui.md index ec898e2..74e0674 100644 --- a/docs/plugin-dev/concepts/configui.md +++ b/docs/plugin-dev/concepts/configui.md @@ -326,6 +326,10 @@ def get_device_list(self, filter="", values_dict=None, type_id="", target_id=0): **Return**: List of `(value_string, display_string)` tuples. +## Pre-population Callbacks + +To seed fields with computed values when a dialog opens (today's date, the latest sensor reading, a freshly minted token), override the matching `get*ConfigUiValues` callback. Static `defaultValue` only fires once and dynamic lists do not auto-select their first item — the callback is the supported way to set values that may change between opens. See [`plugin-lifecycle.md`](plugin-lifecycle.md#configui-pre-population-callbacks) for the full reference table covering all five callbacks (`getPrefsConfigUiValues`, `getDeviceConfigUiValues`, `getEventConfigUiValues`, `getMenuActionConfigUiValues`, `getActionConfigUiValues`). + ## Validation ### Validation Callbacks diff --git a/docs/plugin-dev/concepts/devices.md b/docs/plugin-dev/concepts/devices.md index e00de7b..522bef7 100644 --- a/docs/plugin-dev/concepts/devices.md +++ b/docs/plugin-dev/concepts/devices.md @@ -106,6 +106,8 @@ States store device data and can trigger events: **Field Types**: `textfield`, `textarea`, `checkbox`, `menu`, `list`, `button`, `label`, `separator` +To pre-populate fields when the device dialog opens (e.g. seed a fresh API token, load the current sensor reading), override `getDeviceConfigUiValues(self, plugin_props, type_id, dev_id)` — see [`plugin-lifecycle.md`](plugin-lifecycle.md#configui-pre-population-callbacks). + ## Device Factory Pattern A Device Factory creates and manages a group of child devices from a single dialog. Use this when a hub or controller discovers multiple sub-devices (e.g., a bridge with relays, dimmers, and sensors). diff --git a/docs/plugin-dev/concepts/events.md b/docs/plugin-dev/concepts/events.md index 7852d07..e43f944 100644 --- a/docs/plugin-dev/concepts/events.md +++ b/docs/plugin-dev/concepts/events.md @@ -145,6 +145,8 @@ def getEventConfigUiValues(self, pluginProps, typeId, triggerId): return valuesDict ``` +This is one of five `get*ConfigUiValues` callbacks — see [`plugin-lifecycle.md`](plugin-lifecycle.md#configui-pre-population-callbacks) for the full reference (device, action, menu item, and plugin prefs dialogs). + ### closedEventConfigUi Called after event config is saved: diff --git a/docs/plugin-dev/concepts/menu-items.md b/docs/plugin-dev/concepts/menu-items.md index ddc7043..cf70e99 100644 --- a/docs/plugin-dev/concepts/menu-items.md +++ b/docs/plugin-dev/concepts/menu-items.md @@ -78,6 +78,8 @@ def send_custom_command(self, values_dict, menu_item_id): self.logger.info(f"Sending command: {command}") ``` +**Pre-populating fields when the dialog opens.** Override `getMenuActionConfigUiValues(self, menu_id)` to seed fields with computed values (today's date, the latest reading, etc.) before the dialog is shown. Static `defaultValue` only fires once and dynamic lists do not auto-select their first item — see [`plugin-lifecycle.md`](plugin-lifecycle.md#configui-pre-population-callbacks) for the full reference. + ## Common Patterns ### Debug Toggle diff --git a/docs/plugin-dev/concepts/plugin-lifecycle.md b/docs/plugin-dev/concepts/plugin-lifecycle.md index af291d1..af3d130 100644 --- a/docs/plugin-dev/concepts/plugin-lifecycle.md +++ b/docs/plugin-dev/concepts/plugin-lifecycle.md @@ -351,6 +351,49 @@ def deviceDeleted(self, dev): self._cleanup_device_data(dev.id) ``` +## ConfigUI Pre-population Callbacks + +Override any of these to seed dialog fields with computed or live values **before** the dialog opens. They run on every dialog open, so the values can change from one open to the next (e.g. defaulting a date dropdown to today). All return `(values_dict, errors_dict)` as `indigo.Dict()` instances. + +| Callback | Dialog | Signature | +|--------------------------------|-----------------|-------------------------------------------------| +| `getPrefsConfigUiValues` | Plugin prefs | `(self)` | +| `getDeviceConfigUiValues` | Device config | `(self, plugin_props, type_id, dev_id)` | +| `getEventConfigUiValues` | Event / trigger | `(self, plugin_props, type_id, event_id)` | +| `getMenuActionConfigUiValues` | Menu item | `(self, menu_id)` | +| `getActionConfigUiValues` | Action config | `(self, plugin_props, type_id, dev_id)` | + +All five exist in `plugin_base.py` on every supported Indigo version (2023.2, 2025.1, 2025.2). The Indigo SDK examples leave most of them off, which has historically made them easy to miss. + +**Static `defaultValue` vs. dynamic lists.** A `` only seeds the field on first open — and dynamic lists (``) do **not** auto-select their first item if no `defaultValue` matches. If you want a value computed at open-time (today's date, the latest sensor reading, the user's last choice), use the callback above for that dialog type. + +### Example — default a menu item's date dropdowns to today + +```python +from datetime import date + +def getMenuActionConfigUiValues(self, menu_id): + values_dict = indigo.Dict() + errors_dict = indigo.Dict() + if menu_id == "dailyReport": + today = date.today() + values_dict["rpt_day"] = f"{today.day:02d}" + values_dict["rpt_month"] = f"{today.month:02d}" + values_dict["rpt_year"] = str(today.year) + return (values_dict, errors_dict) +``` + +### Example — seed a device dialog with a fresh API token + +```python +def getDeviceConfigUiValues(self, plugin_props, type_id, dev_id): + values_dict = indigo.Dict(plugin_props) + errors_dict = indigo.Dict() + if not values_dict.get("api_token"): + values_dict["api_token"] = self._mint_token() + return (values_dict, errors_dict) +``` + ## Common Patterns ### Deferred Initialization diff --git a/docs/plugin-dev/concepts/plugin-preferences.md b/docs/plugin-dev/concepts/plugin-preferences.md index cd5250f..672f049 100644 --- a/docs/plugin-dev/concepts/plugin-preferences.md +++ b/docs/plugin-dev/concepts/plugin-preferences.md @@ -60,6 +60,8 @@ def startup(self): debug = self.pluginPrefs.get("showDebugInfo", False) ``` +To seed fields with computed values when the prefs dialog opens, override `getPrefsConfigUiValues(self)` — see [`plugin-lifecycle.md`](plugin-lifecycle.md#configui-pre-population-callbacks). + ## Hidden Preferences Store values not shown in the config UI: diff --git a/docs/plugin-dev/quick-start.md b/docs/plugin-dev/quick-start.md index 709ebfb..a1aed82 100644 --- a/docs/plugin-dev/quick-start.md +++ b/docs/plugin-dev/quick-start.md @@ -5,8 +5,8 @@ Your comprehensive guide to creating your first Indigo plugin in minutes. ## Prerequisites - **macOS**: Indigo runs only on macOS -- **Indigo 2023.2+**: Home automation server installed and running -- **Python 3.10+**: Comes with macOS, used by Indigo +- **Indigo 2023.2+** (2025.x recommended): Home automation server installed and running +- **Python 3.10–3.13**: Comes bundled with Indigo (see version table below) - **Text Editor**: VS Code, PyCharm, or any code editor - **Basic Python**: Understanding of Python and object-oriented programming @@ -241,9 +241,11 @@ import paho.mqtt.client as mqtt **How it works:** - Indigo runs `pip install` into `Contents/Packages/` automatically on first load -- Indigo tracks installation via `pip-install-log-success.txt` in `Packages/` -- Subsequent restarts skip installation if the success marker exists -- If you change `requirements.txt`, delete the success marker to force reinstall +- Indigo writes a success marker in `Packages/` — filename is version-keyed: + - **2025.2**: `3.13-pip-install-log-success.txt` + - **2025.1 and older**: `pip-install-log-success.txt` +- Subsequent restarts skip installation if the marker exists +- If you change `requirements.txt`, delete the marker to force reinstall **Important:** - Do NOT commit `Contents/Packages/` to git — add it to `.gitignore` @@ -298,17 +300,23 @@ Place `.py` files here to make them importable by any plugin. After adding or up **Solutions**: - Add a `requirements.txt` in `Contents/Server Plugin/` listing your dependencies -- Delete `Contents/Packages/pip-install-log-success.txt` to force Indigo to reinstall +- To force Indigo to reinstall, delete the success marker in `Contents/Packages/` (`3.13-pip-install-log-success.txt` on 2025.2, `pip-install-log-success.txt` on older versions) - If you see `dlopen` errors with architecture mismatches, remove any manually bundled `.so` files from `Contents/Packages/` and let Indigo reinstall via `requirements.txt` - Use Python 3 syntax (not Python 2) - Check package compatibility with Python 3.10+ -## Python Version Reference +## Version Reference -| Indigo Version | Python Version | Notes | -|----------------|----------------|-------| -| 2023.2+ | Python 3.10+ | Current, recommended | -| 2022.x | Python 2.7 | Legacy, end-of-life | +| Indigo | Python | Plugin install path | Runtime API | +|--------|--------|----------------------------------------------------|-------------| +| 2025.2 | 3.13.9 | `.../Perceptive Automation/Indigo 2025.2/Plugins/` | 3.8 | +| 2025.1 | 3.11.6 | `.../Perceptive Automation/Indigo 2025.1/Plugins/` | 3.7 | +| 2023.2 | 3.10+ | `.../Perceptive Automation/Indigo 2023.2/Plugins/` | (see docs) | +| 2022.x | 2.7 | Legacy, end-of-life | n/a | + +`ServerApiVersion` in `Info.plist` declares the **minimum** API your plugin requires. `3.0` continues to work on all 2023.2+ versions — there is no need to bump it just because you're on a newer Indigo release. The path examples elsewhere in this guide use 2023.2; substitute the row above that matches your installation. + +**Upgrading to 2025.2?** Python 3.13 has several library breaking changes — see [`troubleshooting/common-issues.md`](troubleshooting/common-issues.md#upgrading-to-indigo-20252--python-313). **For Python 3 migration**, see: [`reference/Python3-Migration-Guide.md`](../../reference/Python3-Migration-Guide.md) diff --git a/docs/plugin-dev/troubleshooting/common-issues.md b/docs/plugin-dev/troubleshooting/common-issues.md index da9bdc9..06a49d1 100644 --- a/docs/plugin-dev/troubleshooting/common-issues.md +++ b/docs/plugin-dev/troubleshooting/common-issues.md @@ -289,13 +289,22 @@ zeroconf==0.148.0 **How Indigo handles it:** 1. On plugin load, Indigo checks for `requirements.txt` 2. Runs `pip install` into `Contents/Packages/` using Indigo's Python -3. Creates `Contents/Packages/pip-install-log-success.txt` as a marker +3. Creates a success marker in `Contents/Packages/` (filename varies — see below) 4. On subsequent restarts, skips installation if the marker exists +The marker filename is version-keyed: + +| Indigo | Success file (in `Contents/Packages/`) | +|----------------|-----------------------------------------------| +| 2025.2 | `3.13-pip-install-log-success.txt` | +| 2025.1 / older | `pip-install-log-success.txt` | + +Never `pip install` into the system Python — those packages disappear on any Python upgrade. `requirements.txt` is the only supported path on every Indigo version. + ### Force Reinstall If you change `requirements.txt` or packages are corrupted: -1. Delete `Contents/Packages/pip-install-log-success.txt` +1. Delete the success marker (see filename table above) 2. Restart the plugin 3. Indigo will re-run `pip install` @@ -332,6 +341,44 @@ import requests - Files built for Python 3.11 won't load on Python 3.10 - `__file__` is not defined in Indigo's plugin environment, breaking `os.path.dirname(__file__)` patterns +## Upgrading to Indigo 2025.2 / Python 3.13 + +*Applies to 2025.2 only — earlier Indigo versions ship Python 3.10 or 3.11.* + +Indigo 2025.2 ships Python 3.13.9. Several stdlib and popular-library changes between 3.11 and 3.13 break plugins that worked on 2025.1. + +### `telnetlib` removed from the Python 3.13 stdlib + +``` +ModuleNotFoundError: No module named 'telnetlib' +``` + +**Fix**: add `telnetlib-313-and-up` to your `requirements.txt`. The shim restores the same import path so existing code keeps working. + +### `websockets` v14+ — `extra_headers` renamed + +``` +TypeError: connect() got unexpected keyword argument 'extra_headers' +``` + +**Fix**: rename `extra_headers=` to `additional_headers=` in `websockets.connect()`. This is a `websockets` library change (v14+), not Python 3.13 itself — pinning `websockets<14` in `requirements.txt` is the alternative. + +### `matplotlib` — `legendHandles` removed + +``` +AttributeError: 'Legend' object has no attribute 'legendHandles' +``` + +**Fix**: use `legend_handles` (snake_case) instead — e.g. `ax.legend().legend_handles`. + +### `matplotlib` — `plot_date` deprecated + +``` +MatplotlibDeprecationWarning: plot_date was deprecated in 3.9 and will be removed in 3.11. Use plot() instead. +``` + +**Fix**: replace `ax.plot_date(...)` with `ax.plot(...)`. Matplotlib auto-formats date axes on `plot()` — no extra setup needed. + ## Python 3 Issues ### Common Migration Errors From 3caa6f18cb47fc386989c184b138e41e7e68aa40 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 3 May 2026 08:53:37 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20follow-up=20audit=20fixes=20?= =?UTF-8?q?=E2=80=94=20version=20staleness,=20broken=20links?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes 6 of 7 findings in #36; deferred item is the menu-item validation/closed ConfigUI callbacks pending plugin_base.py verification. - snippets/plugin-base-template.py: docstring now reflects 3.10–3.13 range - docs/plugin-dev/concepts/scripting-shell.md: switch CLI path examples to Indigo 2025.2 with a substitute-your-version note linking the version table - skills/dev/SKILL.md: replace "bundle in Contents/Packages/" with the requirements.txt-based guidance, and update the Python version line - docs/api/README.md: fix broken link to indigo-object-model.md (correct path is plugin-dev/api/), and fix two adjacent broken links to concepts/ and examples/ that pointed to non-existent repo-root paths - docs/api/overview.md: same indigo-object-model.md path fix - docs/plugin-dev/concepts/README.md: replace dead link to non-existent CONTRIBUTING.md with a pointer to the GitHub repo https://claude.ai/code/session_01PBR2a67rzj9NsZ8Vpmat6H --- docs/api/README.md | 6 +++--- docs/api/overview.md | 2 +- docs/plugin-dev/concepts/README.md | 2 +- docs/plugin-dev/concepts/scripting-shell.md | 8 +++++--- skills/dev/SKILL.md | 4 ++-- snippets/plugin-base-template.py | 4 ++-- 6 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index 7c4bed4..2ffddcb 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -89,9 +89,9 @@ Indigo provides two primary integration APIs: ## Related Documentation -- **[Indigo Object Model](../indigo-object-model.md)** - Understanding device/variable objects -- **[Plugin Development](../../concepts/)** - Building Indigo plugins (server-side) -- **[Examples](../../examples/)** - SDK examples for plugin development +- **[Indigo Object Model](../plugin-dev/api/indigo-object-model.md)** - Understanding device/variable objects +- **[Plugin Development](../plugin-dev/concepts/)** - Building Indigo plugins (server-side) +- **[Examples](../plugin-dev/examples/)** - SDK examples for plugin development ## For Claude (Context Optimization) diff --git a/docs/api/overview.md b/docs/api/overview.md index 3d6e5e7..5a87823 100644 --- a/docs/api/overview.md +++ b/docs/api/overview.md @@ -189,4 +189,4 @@ While both APIs provide access to core Indigo functionality (devices, variables, - **[HTTP API Reference](http-api.md)** - Complete HTTP documentation - **[Authentication Guide](authentication.md)** - Setup and security - **[Device Commands](device-commands.md)** - All available commands -- **[Indigo Object Model](../indigo-object-model.md)** - Understanding device objects +- **[Indigo Object Model](../plugin-dev/api/indigo-object-model.md)** - Understanding device objects diff --git a/docs/plugin-dev/concepts/README.md b/docs/plugin-dev/concepts/README.md index ac1f2ae..ee3963b 100644 --- a/docs/plugin-dev/concepts/README.md +++ b/docs/plugin-dev/concepts/README.md @@ -70,7 +70,7 @@ Documentation planned for this section: ## Contributing -Want to add documentation to this section? See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines. +Want to add documentation to this section? Open a PR or issue on the [GitHub repo](https://github.com/simons-plugins/indigo-claude-plugin). **Valuable topics include**: - State update performance patterns diff --git a/docs/plugin-dev/concepts/scripting-shell.md b/docs/plugin-dev/concepts/scripting-shell.md index 2744cfd..f1910f6 100644 --- a/docs/plugin-dev/concepts/scripting-shell.md +++ b/docs/plugin-dev/concepts/scripting-shell.md @@ -25,16 +25,18 @@ Useful for: ## Command-Line Interface +> Path examples below use `Indigo 2025.2`. Substitute your installed version (`2025.1`, `2023.2`, etc.) — see the [version reference table](../quick-start.md#version-reference). + ### Run a Script File ```bash -/Library/Application\ Support/Perceptive\ Automation/Indigo\ 2023.2/IndigoPluginHost.app/Contents/MacOS/IndigoPluginHost -x /path/to/script.py +/Library/Application\ Support/Perceptive\ Automation/Indigo\ 2025.2/IndigoPluginHost.app/Contents/MacOS/IndigoPluginHost -x /path/to/script.py ``` ### Run Inline Code ```bash -/Library/Application\ Support/Perceptive\ Automation/Indigo\ 2023.2/IndigoPluginHost.app/Contents/MacOS/IndigoPluginHost -e 'indigo.device.turnOn("Hallway Light")' +/Library/Application\ Support/Perceptive\ Automation/Indigo\ 2025.2/IndigoPluginHost.app/Contents/MacOS/IndigoPluginHost -e 'indigo.device.turnOn("Hallway Light")' ``` ### SSH Remote Access @@ -42,7 +44,7 @@ Useful for: You can run Indigo scripts remotely via SSH: ```bash -ssh user@indigo-mac '/Library/Application\ Support/Perceptive\ Automation/Indigo\ 2023.2/IndigoPluginHost.app/Contents/MacOS/IndigoPluginHost -e "indigo.server.log(\"Hello from SSH\")"' +ssh user@indigo-mac '/Library/Application\ Support/Perceptive\ Automation/Indigo\ 2025.2/IndigoPluginHost.app/Contents/MacOS/IndigoPluginHost -e "indigo.server.log(\"Hello from SSH\")"' ``` ## Notes diff --git a/skills/dev/SKILL.md b/skills/dev/SKILL.md index f73ee84..5c7435c 100644 --- a/skills/dev/SKILL.md +++ b/skills/dev/SKILL.md @@ -71,8 +71,8 @@ class Plugin(indigo.PluginBase): - Use `self.sleep()` not `time.sleep()` in concurrent threads - Handle `self.StopThread` in `runConcurrentThread` - Log with `self.logger.debug/info/warning/error/exception()` -- Python 3.10+ (Indigo 2023+) -- Bundle dependencies in `Contents/Packages/` (not system pip) +- Python 3.10–3.13 (see version table in `docs/plugin-dev/quick-start.md`) +- Use `requirements.txt` in `Contents/Server Plugin/` — Indigo auto-installs into `Contents/Packages/`. Never `pip install` into system Python. - `CFBundleIdentifier` in Info.plist must be globally unique ## Device Types (Devices.xml) diff --git a/snippets/plugin-base-template.py b/snippets/plugin-base-template.py index 8782555..187e12c 100644 --- a/snippets/plugin-base-template.py +++ b/snippets/plugin-base-template.py @@ -10,8 +10,8 @@ 4. Implement your plugin logic in the appropriate methods Requirements: - - Indigo 2023.2+ (Python 3.10+) - - ServerApiVersion 3.0 in Info.plist + - Indigo 2023.2+ (Python 3.10–3.13; 2025.2 recommended) + - ServerApiVersion 3.0 in Info.plist (declares minimum API; works on all 2023.2+) """ import indigo