From 5135ae1d16e9503aa12b837c073fb7666757c277 Mon Sep 17 00:00:00 2001 From: Simon Clark Date: Fri, 10 Jul 2026 07:54:00 +0100 Subject: [PATCH 1/3] feat(canonical): vendor the user guide + bundled-plugin docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Widen refresh_canonical.py's INCLUDE_PREFIXES to also emit the `user` and `plugins` trees, so general "how does Indigo work" questions (Z-Wave/Insteon/X10 interfaces, control-page/trigger/schedule concepts, reflectors & remote access, Apple Shortcuts, and the bundled plugins) have canonical grounding. Regenerated: 68 -> 127 pages. Existing pages are byte-identical (only INDEX.md and VERSION change); +59 new pages under user/ and plugins/. Standing cost is just a larger INDEX — pages still load individually on demand. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01Arj5R66d73tc3PMPvHS65Z --- reference/canonical/INDEX.md | 60 ++ reference/canonical/VERSION | 4 +- reference/canonical/plugins.md | 27 + reference/canonical/plugins/airfoilpro.md | 683 ++++++++++++++++++ reference/canonical/plugins/alexa.md | 16 + .../canonical/plugins/alexa/custom-skill.md | 82 +++ .../canonical/plugins/alexa/migrating.md | 31 + .../canonical/plugins/alexa/operations.md | 79 ++ .../plugins/alexa/smart-home-skill.md | 161 +++++ .../plugins/alexa/troubleshooting.md | 104 +++ reference/canonical/plugins/easydaq_1.md | 216 ++++++ reference/canonical/plugins/email.md | 279 +++++++ .../plugins/globalpropertymanager.md | 78 ++ reference/canonical/plugins/noaaweather.md | 133 ++++ reference/canonical/plugins/sql_logger.md | 149 ++++ .../canonical/plugins/timersandpesters.md | 192 +++++ reference/canonical/user.md | 31 + .../user/automation/apple-shortcuts.md | 335 +++++++++ .../canonical/user/automation/event-data.md | 139 ++++ .../user/automation/get-contents-of-url.md | 62 ++ .../user/automation/substitutions.md | 66 ++ reference/canonical/user/concepts.md | 25 + reference/canonical/user/concepts/actions.md | 434 +++++++++++ .../canonical/user/concepts/conditions.md | 91 +++ .../canonical/user/concepts/control-pages.md | 146 ++++ .../user/concepts/deletion-dependencies.md | 21 + reference/canonical/user/concepts/devices.md | 39 + reference/canonical/user/concepts/plugins.md | 129 ++++ .../canonical/user/concepts/schedules.md | 49 ++ reference/canonical/user/concepts/triggers.md | 116 +++ .../canonical/user/concepts/variables.md | 18 + reference/canonical/user/getting-started.md | 75 ++ .../user/getting-started/installation.md | 154 ++++ .../user/getting-started/interfaces.md | 21 + .../user/getting-started/remote-access.md | 99 +++ reference/canonical/user/glossary.md | 42 ++ .../canonical/user/interfaces/insteon.md | 328 +++++++++ .../interfaces/insteon/advanced-powerlinc.md | 18 + .../insteon/fanlinc_and_keypadlinc.md | 69 ++ .../user/interfaces/insteon/insteon_links.md | 33 + .../interfaces/insteon/powerlinc-2413s.md | 14 + .../user/interfaces/virtual-devices.md | 174 +++++ reference/canonical/user/interfaces/x10.md | 32 + .../user/interfaces/x10/rf-options.md | 12 + reference/canonical/user/interfaces/z-wave.md | 268 +++++++ .../canonical/user/interfaces/z-wave/about.md | 76 ++ .../user/interfaces/z-wave/associations.md | 17 + reference/canonical/user/mac-client.md | 21 + .../canonical/user/mac-client/event-log.md | 9 + .../canonical/user/mac-client/home-window.md | 239 ++++++ reference/canonical/user/mac-client/menus.md | 69 ++ .../user/maintenance/license-transfer.md | 13 + .../canonical/user/maintenance/moving.md | 36 + .../user/maintenance/uninstalling.md | 96 +++ .../canonical/user/maintenance/upgrading.md | 221 ++++++ .../canonical/user/remote-access/reflector.md | 125 ++++ .../user/remote-access/ssl-certificates.md | 41 ++ .../user/remote-access/touch-for-web.md | 143 ++++ .../user/remote-access/web-server.md | 210 ++++++ .../powerline-signal-troubleshooting.md | 77 ++ .../user/troubleshooting/python-conflicts.md | 62 ++ tools/refresh_canonical.py | 6 +- 62 files changed, 6791 insertions(+), 4 deletions(-) create mode 100644 reference/canonical/plugins.md create mode 100644 reference/canonical/plugins/airfoilpro.md create mode 100644 reference/canonical/plugins/alexa.md create mode 100644 reference/canonical/plugins/alexa/custom-skill.md create mode 100644 reference/canonical/plugins/alexa/migrating.md create mode 100644 reference/canonical/plugins/alexa/operations.md create mode 100644 reference/canonical/plugins/alexa/smart-home-skill.md create mode 100644 reference/canonical/plugins/alexa/troubleshooting.md create mode 100644 reference/canonical/plugins/easydaq_1.md create mode 100644 reference/canonical/plugins/email.md create mode 100644 reference/canonical/plugins/globalpropertymanager.md create mode 100644 reference/canonical/plugins/noaaweather.md create mode 100644 reference/canonical/plugins/sql_logger.md create mode 100644 reference/canonical/plugins/timersandpesters.md create mode 100644 reference/canonical/user.md create mode 100644 reference/canonical/user/automation/apple-shortcuts.md create mode 100644 reference/canonical/user/automation/event-data.md create mode 100644 reference/canonical/user/automation/get-contents-of-url.md create mode 100644 reference/canonical/user/automation/substitutions.md create mode 100644 reference/canonical/user/concepts.md create mode 100644 reference/canonical/user/concepts/actions.md create mode 100644 reference/canonical/user/concepts/conditions.md create mode 100644 reference/canonical/user/concepts/control-pages.md create mode 100644 reference/canonical/user/concepts/deletion-dependencies.md create mode 100644 reference/canonical/user/concepts/devices.md create mode 100644 reference/canonical/user/concepts/plugins.md create mode 100644 reference/canonical/user/concepts/schedules.md create mode 100644 reference/canonical/user/concepts/triggers.md create mode 100644 reference/canonical/user/concepts/variables.md create mode 100644 reference/canonical/user/getting-started.md create mode 100644 reference/canonical/user/getting-started/installation.md create mode 100644 reference/canonical/user/getting-started/interfaces.md create mode 100644 reference/canonical/user/getting-started/remote-access.md create mode 100644 reference/canonical/user/glossary.md create mode 100644 reference/canonical/user/interfaces/insteon.md create mode 100644 reference/canonical/user/interfaces/insteon/advanced-powerlinc.md create mode 100644 reference/canonical/user/interfaces/insteon/fanlinc_and_keypadlinc.md create mode 100644 reference/canonical/user/interfaces/insteon/insteon_links.md create mode 100644 reference/canonical/user/interfaces/insteon/powerlinc-2413s.md create mode 100644 reference/canonical/user/interfaces/virtual-devices.md create mode 100644 reference/canonical/user/interfaces/x10.md create mode 100644 reference/canonical/user/interfaces/x10/rf-options.md create mode 100644 reference/canonical/user/interfaces/z-wave.md create mode 100644 reference/canonical/user/interfaces/z-wave/about.md create mode 100644 reference/canonical/user/interfaces/z-wave/associations.md create mode 100644 reference/canonical/user/mac-client.md create mode 100644 reference/canonical/user/mac-client/event-log.md create mode 100644 reference/canonical/user/mac-client/home-window.md create mode 100644 reference/canonical/user/mac-client/menus.md create mode 100644 reference/canonical/user/maintenance/license-transfer.md create mode 100644 reference/canonical/user/maintenance/moving.md create mode 100644 reference/canonical/user/maintenance/uninstalling.md create mode 100644 reference/canonical/user/maintenance/upgrading.md create mode 100644 reference/canonical/user/remote-access/reflector.md create mode 100644 reference/canonical/user/remote-access/ssl-certificates.md create mode 100644 reference/canonical/user/remote-access/touch-for-web.md create mode 100644 reference/canonical/user/remote-access/web-server.md create mode 100644 reference/canonical/user/troubleshooting/powerline-signal-troubleshooting.md create mode 100644 reference/canonical/user/troubleshooting/python-conflicts.md diff --git a/reference/canonical/INDEX.md b/reference/canonical/INDEX.md index 6dc3b3e..67e0d71 100644 --- a/reference/canonical/INDEX.md +++ b/reference/canonical/INDEX.md @@ -54,6 +54,20 @@ Each entry points at a local vendored file — load only the page you need. ## Bundled Plugins +- **Bundled Plugins** — Documentation for the plugins that ship with Indigo: Airfoil Pro, Alexa, EasyDAQ, Email+, Global Property Manager, NOAA Weather, SQL Logger, and Timers and Pesters. → `reference/canonical/plugins.md` +- **Airfoil Pro** — Documentation for the Airfoil Pro bundled plugin: controlling Airfoil audio routing from Indigo actions and scripts. → `reference/canonical/plugins/airfoilpro.md` +- **EasyDAQ Relay Card** — Documentation for the EasyDAQ Relay Card plugin: controlling EasyDAQ USB relay boards from Indigo. → `reference/canonical/plugins/easydaq_1.md` +- **Email+** — Documentation for the Email+ bundled plugin: sending and receiving email from Indigo actions. → `reference/canonical/plugins/email.md` +- **Global Property Manager** — Documentation for the Global Property Manager bundled plugin: storing and retrieving persistent key-value data shared across plugins. → `reference/canonical/plugins/globalpropertymanager.md` +- **NOAA Weather** — Documentation for the NOAA Weather bundled plugin: fetching weather conditions and forecasts into Indigo variables. → `reference/canonical/plugins/noaaweather.md` +- **SQL Logger** — Documentation for the SQL Logger bundled plugin: logging device state changes and variable updates to a SQLite database. → `reference/canonical/plugins/sql_logger.md` +- **Timers and Pesters** — Documentation for the Timers and Pesters bundled plugin: countdown timers, repeating actions, and scheduled one-shot events. → `reference/canonical/plugins/timersandpesters.md` +- **Alexa** — Documentation for the Alexa bundled plugin: linking Indigo devices to Amazon Alexa for voice control. → `reference/canonical/plugins/alexa.md` +- **Custom Indigo Skill** — How to execute Indigo action groups and read variable values by voice with the Custom Indigo Alexa Skill. → `reference/canonical/plugins/alexa/custom-skill.md` +- **Migrating from Alexa-Hue Bridge** — How to migrate from the legacy Alexa-Hue Bridge plugin to the current Alexa plugin. → `reference/canonical/plugins/alexa/migrating.md` +- **Plugin Operations** — Day-to-day operation of the Alexa plugin: publishing devices, managing the device list, and discovery. → `reference/canonical/plugins/alexa/operations.md` +- **Smart Home Skill** — How to control Indigo devices with Alexa using the Indigo Smart Home Skill. → `reference/canonical/plugins/alexa/smart-home-skill.md` +- **Troubleshooting** — Troubleshooting the Alexa plugin: discovery failures, naming, and skill-linking problems. → `reference/canonical/plugins/alexa/troubleshooting.md` ## Scripting @@ -86,5 +100,51 @@ Each entry points at a local vendored file — load only the page you need. ## User Guide +- **Indigo User Guide** — The Indigo User Guide: getting started, core concepts, the Mac client, hardware interfaces, remote access, automation techniques, and maintenance. → `reference/canonical/user.md` +- **Glossary** — Definitions of key Indigo terms: devices, triggers, action groups, variables, control pages, and more. → `reference/canonical/user/glossary.md` +- **Apple Shortcuts** — How to use Apple Shortcuts with Indigo to trigger actions, control devices, and query status from iOS and macOS. → `reference/canonical/user/automation/apple-shortcuts.md` +- **Event Data Passing** — How to pass data from the event that triggered an action — device state changes, variable values, and trigger metadata. → `reference/canonical/user/automation/event-data.md` +- **Get Contents of URL** — How to use the Get Contents of URL action to fetch data from HTTP endpoints and store responses in Indigo variables. → `reference/canonical/user/automation/get-contents-of-url.md` +- **Substitutions** — How to use Indigo substitution syntax to embed dynamic device state, variable values, and date/time data in action parameters. → `reference/canonical/user/automation/substitutions.md` +- **Core Concepts** — Overview of Indigo's building blocks: devices, triggers, schedules, actions and action groups, variables, control pages, conditions, and plugins. → `reference/canonical/user/concepts.md` +- **Actions & Action Groups** — What Indigo actions and action groups are: the full catalog of device, server, variable, notification, Z-Wave, and Insteon actions, and grouping them for reuse. → `reference/canonical/user/concepts/actions.md` +- **Conditions** — What Indigo conditions are: restricting when triggers and schedules execute, including condition scripts. → `reference/canonical/user/concepts/conditions.md` +- **Control Pages** — What Indigo control pages are: building custom touch/browser interfaces with the Control Page editor. → `reference/canonical/user/concepts/control-pages.md` +- **Devices** — What Indigo devices are: representing Z-Wave, Insteon, X10, virtual, and plugin hardware, device options, and multi-personality devices. → `reference/canonical/user/concepts/devices.md` +- **Managing Plugins** — What Indigo plugins are and how to manage them: installing and updating from the Plugin Store, the Plugins menu, preferences, and uninstalling. → `reference/canonical/user/concepts/plugins.md` +- **Schedules** — What Indigo schedules are: time and date options for running actions on a schedule, including sunrise/sunset and randomization. → `reference/canonical/user/concepts/schedules.md` +- **Triggers** — What Indigo triggers are: every trigger event type, from device state changes and variable changes to email, interface, and plugin events. → `reference/canonical/user/concepts/triggers.md` +- **Variables** — What Indigo variables are: storing state and data for use in triggers, conditions, and substitutions. → `reference/canonical/user/concepts/variables.md` +- **Getting Started Guide** — Step-by-step guide to installing Indigo, configuring interfaces, adding devices, and setting up your first automations. → `reference/canonical/user/getting-started.md` +- **Installation & Server Setup** — Installing Indigo, starting and configuring the Indigo Server, general preferences, location settings, and keeping the Mac awake for continuous operation. → `reference/canonical/user/getting-started/installation.md` +- **Managing the Built-in Interfaces** — Enabling, disabling, and configuring Indigo's four built-in interfaces: Z-Wave, Insteon, X10, and Virtual Devices. → `reference/canonical/user/getting-started/interfaces.md` +- **Accessing Indigo Remotely** — Reaching the Indigo Server from other Macs, Indigo Touch, and web browsers — firewall settings, server discovery, and reflector activation. → `reference/canonical/user/getting-started/remote-access.md` +- **Virtual Devices** — How to create and use Virtual Devices in Indigo to represent non-physical devices or aggregate states. → `reference/canonical/user/interfaces/virtual-devices.md` +- **Managing Insteon Devices** — How to add, configure, link, and troubleshoot Insteon devices in Indigo using the Mac client. → `reference/canonical/user/interfaces/insteon.md` +- **Advanced PowerLinc Options** — Advanced configuration options for the PowerLinc 2413U/2413S Insteon interface, including LED brightness and signal timing. → `reference/canonical/user/interfaces/insteon/advanced-powerlinc.md` +- **FanLinc and KeypadLinc** — Configure a 6-button KeypadLinc as a radio group to control a FanLinc: setting auto-off button groups, non-toggle mode, creating the links, and keeping button LEDs in sync from Indigo. → `reference/canonical/user/interfaces/insteon/fanlinc_and_keypadlinc.md` +- **Insteon Links (Scenes)** — How Insteon device links (scenes) work, how they compare to Indigo triggers, and when to use each — or both together. → `reference/canonical/user/interfaces/insteon/insteon_links.md` +- **PowerLinc 2413S** — Setup and configuration guide for the PowerLinc 2413S serial Insteon interface. → `reference/canonical/user/interfaces/insteon/powerlinc-2413s.md` +- **Connecting X10 Interfaces** — How to add and control X10 devices in Indigo, including configuring the X10 RF interface and assigning house/unit codes. → `reference/canonical/user/interfaces/x10.md` +- **X10 RF Options** — Configuration options for the X10 RF receiver interface, including supported hardware and frequency settings. → `reference/canonical/user/interfaces/x10/rf-options.md` +- **Managing Z-Wave Devices** — How to add, interview, configure, and troubleshoot Z-Wave devices in Indigo, including secure inclusion and network repair. → `reference/canonical/user/interfaces/z-wave.md` +- **Z-Wave Technology Overview** — A general-terms overview of Z-Wave technology: the wireless mesh network, primary and secondary controllers, including and excluding devices, associations, network healing, and a glossary of Z-Wave terms. → `reference/canonical/user/interfaces/z-wave/about.md` +- **Association Management** — How to view and manage Z-Wave device associations in Indigo, including adding, removing, and troubleshooting association groups. → `reference/canonical/user/interfaces/z-wave/associations.md` +- **Mac Client** — Tour of the Indigo Mac client interface: the main window, device list, event log, editors, and key menu items. → `reference/canonical/user/mac-client.md` +- **Event Log Window** — Tour of the Indigo Mac client interface: the main window, device list, event log, editors, and key menu items. → `reference/canonical/user/mac-client/event-log.md` +- **Home Window** — Tour of the Indigo Mac client interface: the main window, device list, event log, editors, and key menu items. → `reference/canonical/user/mac-client/home-window.md` +- **Menus** — Tour of the Indigo Mac client interface: the main window, device list, event log, editors, and key menu items. → `reference/canonical/user/mac-client/menus.md` +- **License Transfers** — Step-by-step guide to transferring an Indigo license to another user. → `reference/canonical/user/maintenance/license-transfer.md` +- **Moving to Another Mac** — Step-by-step guide to moving your Indigo software to another computer. → `reference/canonical/user/maintenance/moving.md` +- **Uninstalling Indigo** — Step-by-step guide to uninstalling Indigo. → `reference/canonical/user/maintenance/uninstalling.md` +- **Upgrading Indigo** — Step-by-step guide to upgrading the Indigo software. → `reference/canonical/user/maintenance/upgrading.md` +- **Indigo Reflectors** — How to set up and use the Indigo Reflector Service to access your Indigo server remotely without port forwarding. → `reference/canonical/user/remote-access/reflector.md` +- **SSL Certificates Examples** — How to configure SSL/TLS certificates for the Indigo Web Server to enable secure HTTPS connections. → `reference/canonical/user/remote-access/ssl-certificates.md` +- **Indigo Touch for Web** — Guide to using Indigo Touch for Web — the browser-based control interface powered by the Indigo Web Server. → `reference/canonical/user/remote-access/touch-for-web.md` +- **Indigo Web Server** — Complete guide to configuring and using the Indigo Web Server (IWS): authentication, ports, SSL, and the REST/WebSocket APIs. → `reference/canonical/user/remote-access/web-server.md` +- **Insteon/X10 Signal Troubleshooting** — How to diagnose and fix Insteon and X10 power-line signal problems: bridging your home's power legs, changing the signal path, removing or filtering noisy electronics and signal absorbers, and isolating problem circuits. → `reference/canonical/user/troubleshooting/powerline-signal-troubleshooting.md` +- **Python Version Conflicts** — Explanation of Python version conflicts between Indigo's embedded Python and system Python, and how to resolve them. → `reference/canonical/user/troubleshooting/python-conflicts.md` ## Documentation + +- **Deletion Dependencies** — Reference table showing which Indigo objects depend on others and what is deleted or disabled when an object is removed. → `reference/canonical/user/concepts/deletion-dependencies.md` diff --git a/reference/canonical/VERSION b/reference/canonical/VERSION index 4f24465..b169cd2 100644 --- a/reference/canonical/VERSION +++ b/reference/canonical/VERSION @@ -1,7 +1,7 @@ indigo_version: 2025.2 source_index: https://docs.indigodomo.com/llms.txt source_full: https://docs.indigodomo.com/llms-full.txt -fetched_utc: 2026-07-09T22:05:28Z +fetched_utc: 2026-07-10T06:50:03Z sha256_full: 3d79e398f7093ce9199b055c5be56de60441192e07e0495ba31b0f4c86ace5bd -pages: 68 +pages: 127 generated_by: tools/refresh_canonical.py diff --git a/reference/canonical/plugins.md b/reference/canonical/plugins.md new file mode 100644 index 0000000..81b110e --- /dev/null +++ b/reference/canonical/plugins.md @@ -0,0 +1,27 @@ + + +# Bundled Plugins + +Indigo ships with a collection of plugins that extend the core product. Each is documented here; enable them from the **Plugins** menu in the Indigo Mac client. (For installing *third-party* plugins, see [managing plugins](../user/concepts/plugins.md#managing-plugins) in the Getting Started guide; to build your own, see [Plugin Development](../plugin-dev/index.md).) + +## Voice & integration + +- [Alexa](alexa/index.md) — make Indigo devices and action groups available to Amazon Alexa for voice control. +- [Email+](email.md) — send email from actions and trigger automations from received email. + +## Audio & media + +- [Airfoil Pro](airfoilpro.md) — control Airfoil 5+ audio routing from Indigo. + +## Data & devices + +- [EasyDAQ Relay Card](easydaq_1.md) — control EasyDAQ USB relay cards directly. +- [Global Property Manager](globalpropertymanager.md) — add custom properties to any Indigo object. +- [NOAA Weather](noaaweather.md) — pull U.S. NOAA weather conditions and forecasts into Indigo. +- [SQL Logger](sql_logger.md) — log device state changes and variable updates to a database. + +## Automation helpers + +- [Timers and Pesters](timersandpesters.md) — kitchen-timer-style timer devices and flexible repeating reminders. + +Looking for the `%%v:12345%%`-style substitution markup? That's a core Indigo feature, not a plugin — see [Substitutions](../user/automation/substitutions.md). diff --git a/reference/canonical/plugins/airfoilpro.md b/reference/canonical/plugins/airfoilpro.md new file mode 100644 index 0000000..ff8dec8 --- /dev/null +++ b/reference/canonical/plugins/airfoilpro.md @@ -0,0 +1,683 @@ + + +# Airfoil Pro +[Airfoil](http://rogueamoeba.com/airfoil/) is a great application from [Rogue Amoeba](http://rogueamoeba.com/) that allows you to stream sound from your Mac or Windows computer to any combination of Airplay Devices, Bluetooth speakers, and [Airfoil satellite clients](http://rogueamoeba.com/airfoil/#satellite) (iOS, Android, Mac, Windows, Linux) - and it keeps it all in sync. Many Indigo users use it in conjunction with Apple TVs, Airport Expresses, and other computers and iOS devices to create whole-home audio systems, all streaming from your Mac/Windows computer running iTunes or other music applications. + +The latest major release, [Airfoil v5](http://rogueamoeba.com/airfoil/), has a new API that enables a much more reliable and capable integration with Indigo. It works with both Airfoil 5 on [Mac](http://rogueamoeba.com/airfoil/mac/) and [Windows](http://rogueamoeba.com/airfoil/windows/) and can work with as many Airfoil instances as there are on your network. + +!!! note + This plugin requires v1.5 or later of the Airfoil API. This was delivered in Airfoil 5 for Mac and Windows. If you need support for earlier versions of Airfoil for Mac, please see [the legacy Airfoil plugin](https://github.com/IndigoDomotics/airfoil) that we open-sourced. Note, however, that it may not work with newer versions of Indigo. + +## Airfoil Device Types +Each Airfoil instance that can be found on your local network can be added as a device in Indigo. When you add an Airfoil device, each speaker that's available in that instance of Airfoil will also be represented by its own device. This gives you a much more flexible set of devices that can be used in triggers, actions, and control pages. + +### Airfoil Instance +This device type represents a single instance of Airfoil running on a Mac or Windows computer. Every Airfoil instance knows about the source that's currently selected, and in some cases (such as iTunes) knows about what's currently playing (album name, album art, artist, source name/id/icon, track name) and can control the source to some extent (toggle play/pause, next track, previous track). It also knows what sources are available so you can easily switch between them. + +#### Adding an Instance +To create an Airfoil Instance device, click the `New...` button above the devices list. In the resulting Create New Device dialog, select Airfoil Pro as the type and you will see the Add Airfoil Instance... dialog: + +![Add Airfoil Instance Image](../images/add_airfoil_instance.png) + +In the first popup, select the Airfoil instance that you want to add. This popup is dynamically generated based on Airfoil's discovery protocol. If you don't see your Airfoil instance, make sure Airfoil v5 is running on a Mac or Windows computer on the same network as your Indigo server Mac. + +The plugin can store a variety of images from Airfoil. You can use these images in refreshing image URLs on your control pages. The second field in the dialog is a full path to a directory where the plugin will store the image files. If you have multiple Airfoil instances, make sure you use a different directory since the image files have a fixed name. The plugin will store the following images in this directory: + +- `albumArt.png` - an image of the currently playing album track if the source supports it (notably, iTunes) +- `machineIcon.png` - an icon representing the computer that is running this instance of Airfoil +- `machineIconAndScreenshot.png` - a screenshot from the host computer with the machine icon overlaid (though this functionality seems to be missing in Airfoil versions through v5.1.0 - you just get the same image as the machine icon) +- `sourceIcon.png` - an icon representing the selected audio source in Airfoil. + +Leave the field empty if you don't wish for the plugin to store these images. + +One oversight that there is in the Airfoil API is the ability to know the play state of the source. So the plugin can't know whether iTunes is playing or paused. If you are using the iTunes Indigo plugin, you have this information, but it's in a different device which could make control page design a little tricky. To work around this missing functionality, we allow you to select an iTunes server Indigo device (that you've previously created) that represents the same iTunes server as the one your Airfoil instance is using as its source. The plugin will monitor that iTunes device and update the sourcePlayStatus state so that it mirrors the iTunes device. + +When you click the "Save" button, the plugin will create your Airfoil Instance device, and it will query Airfoil and get all it's known speakers. It will then create devices for each of those speakers (see the next section for details on those devices). + +This is what the Edit Device dialog will look like when it's finished: + +![Airfoil Edit Group Image](../images/airfoil_edit_group.png) + +Airfoil instances are actually a group of devices: the instance itself (the first tab), and then multiple speaker devices, one for each speaker device that your instance knows about. We set the name of the Airfoil Instance to the Airfoil name. For each speaker, we name the speaker with this pattern: "Speaker Name (Airfoil Instance Name speaker)" to help you see how the devices relate to each other. We also add a note to each speaker device with a bit more detail about its relationship to its parent Airfoil Instance device. + +Airfoil Instance devices have the following state changes that you can use in Triggers: + +![Airfoil Triggers Image](../images/airfoil_triggers.png) + +!!! warning + Due to changes that Apple has made to their API, the *`Source Status Is Playing`* trigger will no longer fire. This trigger option will be adjusted in a future release. + +Those states can also be displayed in Control Pages. + +#### States available to Scripts +If you want to use an Airfoil Instance device in a script, here are the state details: + +| **State Key** | **Value Type** | **Description** | +|-----------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| *`canConnect`* | boolean | This instance allows remote speakers to connect | +| *`canRemoteControl`* | boolean | This instance allows remote control of the source | +| *`instanceName`* | string | The name of the instance. On Mac systems, this is the name of the Mac as defined in the Sharing System Preference Panel | +| *`protocolVersion`* | string | This is the version of Airfoil's API that this instance uses. v1.5 is the minimum. | +| *`sourceAlbum`* | string | The name of the album that the selected source is playing (if sourceMetadataAvailable == True) | +| *`sourceArtist`* | string | The name of the artist of the album that the selected source is playing (if sourceMetadataAvailable == True) | +| *`sourceBundleId`* | string | The unique identifier of the source | +| *`sourceMachineModel`* | string | The model of the computer running Airfoil | +| *`sourceMachineName`* | string | The name of the computer running Airfoil (usually the same as the instanceName) | +| *`sourceMetadataAvailable`* | boolean | The source supplies metadata (album, artist, track, etc) | +| *`sourceName`* | string | The name of the selected source | +| *`sourcePlayStatus`* | string (playing, paused, stopped, unavailable, error) | If the source is iTunes and you've selected an iTunes server as the source in this device's config, this will mirror that device's playState | +| *`sourceTrackName`* | string | The name of the track that the current source is playing (if sourceMetadataAvailable == True) | +| *`status`* | string (disconnected, connected, unavailable) | The status of this device with respect to the Airfoil communication | + + +#### Notes +If you change the name of your Mac, you'll need to perform the `Define and Sync...` again - select the correct Airfoil instance in the sync dialog and `Save`. Unfortunately, Airfoil doesn't send out a name change notification so the plugin doesn't know what happened other than the instance it was talking to is now gone. + +### Speaker +Each Airfoil Instance device has a collection of "Speaker" devices in its group. These are all the various outputs to which Airfoil can direct its source audio. These devices are created automatically when you create your Airfoil Instance and any time a new source gets added to the instance. For instance, if you create an Airfoil Instance and it finds 3 speakers, then at a later time you add a Bluetooth speaker to the Mac that Airfoil is running on, the plugin will automatically create a new speaker device for that Bluetooth speaker. + +We never automatically delete speakers: if you have a Bluetooth speaker that fails, and you won't ever use it again, you'll need to remove it manually. + +!!! warning + You can't use the `Delete...` button above the device list without deleting ALL the devices in that Airfoil Instance Group. If you need to delete just a single speaker, select the `Plugins->Airfoil Pro->Permanently Delete Speaker` menu item. This will allow you to just delete a single speaker. + +An unfortunate side effect of how Airfoil handles AirPlay devices, like AppleTVs, is that if you change the name of them it will create a new speaker instance (rather than just replacing it). From the API perspective, it's just another new speaker that was added. What you'll need to do in that case is switch over any triggers, actions, and control pages that use the old speaker to use the newly created speaker, then delete the speaker manually. + +#### States available to Scripts { #speaker-states-available-to-scripts } +If you want to use an Airfoil Instance device in a script, here are the state details: + +| **State Key** | **Value Type** | **Description** | +|----------------------|-----------------------------------------------|---------------------------------------------------------------------------------| +| *`longIdentifier`* | string | The unique identifier of the speaker | +| *`name`* | string | The name of the speaker in Airfoil (which is different than its name in Indigo) | +| *`parentInstanceId`* | number | The device ID of the parent Airfoil Instance | +| *`status`* | string (connected, disconnected, unavailable) | The status of the speaker | +| *`type`* | string (local, airplay, Bluetooth, group) | The type of speaker | +| *`volume`* | number | The volume that the speaker is currently set to. | + + +## Airfoil Actions +The Airfoil plugin provides a variety of actions that allow you to fully manage an Airfoil Instance and Speakers. We'll separate these into Speaker actions and Instance actions. These actions are available on the `Type:` menu in the actions edit dialog under `Device Actions->Airfoil Pro Controls` submenu. + +![Action Menu Image](../images/actionmenu.png) + +For those interested in controlling Airfoil Pro devices from another plugin or script, you will find the details below after a description of each action in the **Scripting details** section. You don't need to know or understand those sections if you're not interested in writing scripts. + +### Notes for Script/Plugin Writers +If you examine the example scripts below, you'll note that each action call will return a result. Unless otherwise specified, it's just a boolean indicating if the action correctly ran. + +You may also note that the action calls are inside a try block. If you specify *waitUntilDone=True* in your action call, you may catch an exception if something happened during the action execution. The exception message will explain in a human-readable string what occurred. + +Finally, at the very end of the list are Script Actions - these are actions that don't really appear in the UI, but will return something useful for your script/plugin. See that section for more details. + +### Speaker Actions +The things you want to do with speaker actions are pretty simple: control whether a speaker is being used and setting the volume of the speaker. To that end, here are the actions. + +#### Connect Speaker +This action will cause Airfoil to begin broadcasting audio to the specified speaker. + +##### Scripting details +**Action id**: connect + +The deviceId is the Indigo ID of the Speaker device. + +No properties for scripting required. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + "connect", + deviceId=135305663, # ID of Speaker device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + + +#### Disconnect Speaker +This action will cause Airfoil to stop broadcasting audio to the specified speaker. + +##### Scripting details { #disconnect-speaker-scripting-details } +**Action id**: disconnect + +The deviceId is the Indigo ID of the Speaker device. + +No properties for scripting required. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + "disconnect", + deviceId=135305663, # ID of Speaker device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Toggle Speaker +This action will cause Airfoil to toggle the specified speaker between connected and disconnected. Useful to execute from a single element (i.e. button) from a control page. + +##### Scripting details { #toggle-speaker-scripting-details } +The deviceId is the Indigo ID of the Speaker device. + +**Action id**: toggle + +No properties for scripting required. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + "toggle", + deviceId=135305663, # ID of Speaker device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Save Current Speaker States +This action will save the connection state for each speaker on the selected Airfoil device. This is useful if you need to temporarily change the state of some speakers, but you want to be able to easily, set them back to how they were before the change. You can optionally specify that Airfoil Group states also be saved though this option is usually not very useful since storing the current state of all speakers will usually accomplish the same as restoring a group. + +##### Scripting details { #save-current-speaker-states-scripting-details } +**Action id**: saveCurrentSpeakerStates + +The deviceId is the Indigo ID of the Airfoil device. + +| *`includeAirfoilGroups`* | Optional (default is False) boolean specifying whether to include Airfoil Groups | +|--------------------------|----------------------------------------------------------------------------------| + + +Example 1 (no groups): + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + "saveCurrentSpeakerStates", + deviceId=135305663, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +Example 2 (include groups): + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + # This time, we'll add the includeAirfoilGroups property that will also store group states + result = airfoilPlugin.executeAction( + "saveCurrentSpeakerStates", + deviceId=135305663, # ID of Airfoil device + props={"includeAirfoilGroups": True}, + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Restore Saved Speaker States +This action will restore speaker states to what was previously saved using the above action. + +##### Scripting details { #restore-saved-speaker-states-scripting-details } +**Action id**: saveCurrentSpeakerStates + +The deviceId is the Indigo ID of the Airfoil device. + +Example 1 (no groups): + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + "restoreSavedSpeakerStates", + deviceId=135305663, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Set Volume +This action will cause Airfoil to set the volume of specified speaker. + +##### Scripting details { #set-volume-scripting-details } +**Action id**: setVolume + +The deviceId is the Indigo ID of the Speaker device. + +| *`volume`* | The volume (0-100) to set the speaker to | +|------------|------------------------------------------| + + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'setVolume', + deviceId=135305663, # ID of Speaker device + props={'volume': 50}, + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Increase Volume +This action will cause Airfoil to increase the volume of specified speaker by the specified amount (defaults to 5). + +##### Scripting details { #increase-volume-scripting-details } +**Action id**: increaseVolume + +The deviceId is the Indigo ID of the Speaker device. + +| *`volume`* | The delta (0-100) increase the speaker's volume by - default is 5 | +|------------|-------------------------------------------------------------------| + + +Example 1 (using default delta): + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'increaseVolume', + deviceId=135305663, # ID of Speaker device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +Example 2 (specifying delta): + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'increaseVolume', + deviceId=135305663, # ID of Speaker device + props={'volume': 15}, + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +!!! note + Because the Airfoil API doesn't directly support increase/decrease, the plugin gets the current volume from the speaker device and calculates the new volume. An unfortunate side effect is that if you send multiple increase/decrease actions in a brief amount of time, the plugin won't yet know that the speaker's volume has changed from the previous command and may not work. So space your increase/decrease commands out a bit to avoid this problem. + +#### Decrease Volume +This action will cause Airfoil to decrease the volume of specified speaker by the specified amount (defaults to 5). + +##### Scripting details { #decrease-volume-scripting-details } +**Action id**: decreaseVolume + +The deviceId is the Indigo ID of the Speaker device. + +| *`volume`* | The delta (0-100) increase the speaker's volume by | +|------------|----------------------------------------------------| + + +Example 1 (using default delta): + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'increaseVolume', + deviceId=135305663, # ID of Speaker device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +Example 2 (specifying delta): + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'decreaseVolume', + deviceId=135305663, # ID of Speaker device + props={'volume': 15}, + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +!!! note + Because the Airfoil API doesn't directly support increase/decrease, the plugin gets the current volume from the speaker device and calculates the new volume. An unfortunate side effect is that if you send multiple increase/decrease actions in a brief amount of time, the plugin won't yet know that the speaker's volume has changed from the previous command and may not work. So space your increase/decrease commands out a bit to avoid this problem. + +### Airfoil Instance Actions +Actions that you can perform on Airfoil Instance devices relate to the current source. + +#### Disconnect All Speakers +Tell Airfoil to disconnect all speakers. This is useful if you want to connect just the speakers in an Airfoil Group (disconnect everything first then connect the group). + +##### Scripting details { #disconnect-all-speakers-scripting-details } +**Action id**: disconnectAllSpeakers + +No properties for scripting required. The deviceId is the Indigo ID of the Airfoil device. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'disconnectAllSpeakers', + deviceId=12345678, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Change Source +This action allows you to change the audio source of the Airfoil instance (as if you changed it by selecting a new source from the popup in the Airfoil app). + +##### Scripting details { #change-source-scripting-details } +**Action id**: changeSource + +The deviceId is the Indigo ID of the Airfoil device. + +| *`sourceGroup`* | One of the following: 'audioDevices', 'recentApplications', 'systemAudio'. You can see what sources are known by selecting the `Plugins->Airfoil Pro->Show Sources` menu item and all source groups and sources will be shown in the event log. You can also call it programmatically (as shown below with the Show Speakers Action/Menu Item) and it will return a dictionary of valid sources. | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| *`source`* | The unique identifier of the source. | + + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + props = {"sourceGroup": "systemAudio", + "source": "com.rogueamoeba.source.systemaudio" + } + result = airfoilPlugin.executeAction( + "changeSource", + deviceId=1346588091, # ID of Airfoil device + props=props, + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Save Current Source +This action will save the currently selected source for the specified Airfoil device. This is useful if you need to temporarily change the source (for instance, to perform some kind of announcement), then switch it back to the previous source. + +##### Scripting details { #save-current-source-scripting-details } +**Action id**: saveCurrentSource + +The deviceId is the Indigo ID of the Airfoil device. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + "saveCurrentSource", + deviceId=1346588091, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Restore Saved Source +This action will restore the previously saved source for the specified Airfoil device. This is useful if you need to temporarily change the source (for instance, to perform some kind of announcement), then switch it back to the previous source. + +##### Scripting details { #restore-saved-source-scripting-details } +**Action id**: restoreSavedSource + +The deviceId is the Indigo ID of the Airfoil device. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + "restoreSavedSource", + deviceId=1346588091, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Toggle Play/Pause +Tell Airfoil to tell the source to toggle play/pause. This only works with some sources and there *aren't* discrete play and pause commands available in the Airfoil API. + +##### Scripting details { #toggle-playpause-scripting-details } +**Action id**: playPause + +No properties for scripting required. The deviceId is the Indigo ID of the Airfoil device. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'playPause', + deviceId=12345678, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Next Track +Tell Airfoil to tell the source to go to the next track. This only works with some sources. + +##### Scripting details { #next-track-scripting-details } +**Action id**: nextTrack + +No properties for scripting required. The deviceId is the Indigo ID of the Airfoil device. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'nextTrack', + deviceId=12345678, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +#### Previous Track +Tell Airfoil to tell the source to go to the next track. This only works with some sources. + +##### Scripting details { #previous-track-scripting-details } +**Action id**: prevTrack + +No properties for scripting required. The deviceId is the Indigo ID of the Airfoil device. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'prevTrack', + deviceId=12345678, # ID of Airfoil device + waitUntilDone=True + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +### Airfoil Scripting Actions +The following action is available specifically for scripts. + +#### = getSources +This script action will return an indigo.Dict object. The keys are the source groups, the values are lists of dicts with the following keys: friendlyName (the user-friendly name), icon (a binhex'd string that is the source's icon), identifier (the ID used in the source property above). You can unbinhex the icon and save it to a PNG file and store it somewhere for use if you like. + +**Action id**: getSources + +No properties are required. The deviceId is the Indigo ID of the Airfoil device. + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.airfoilpro" + +# Get a plugin object given the plugin id: +airfoil_plugin = indigo.server.getPlugin(plugin_id) + +if airfoilPlugin.isEnabled(): + try: + result = airfoilPlugin.executeAction( + 'getSources', + deviceId=12345678 # ID of Airfoil device + ) + except Exception as e: + print(f"Exception occurred: {e}") +``` + +The *result* that's returned from this call will look something like this: + +```text +Data : (dict) + audioDevices : (list) + Item : (dict) + friendlyName : Apple USB audio device (string) + icon : [SNIP] + identifier : AppleUSBAudioEngine:Apple Inc.:Apple USB audio device:241000:2,1 (string) + Item : (dict) + friendlyName : Built-in Microphone (string) + icon : [SNIP] + identifier : AppleHDAEngineInput:1B,0,1,0:1 (string) + Item : (dict) + friendlyName : USB audio CODEC (string) + icon : [SNIP] + identifier : AppleUSBAudioEngine:Burr-Brown from TI:USB audio CODEC:400000:2,1 (string) + recentApplications : (list) + Item : (dict) + friendlyName : iTunes (string) + icon : [SNIP] + identifier : /Applications/iTunes.app (string) + Item : (dict) + friendlyName : iMovie (string) + icon : [SNIP] + identifier : /Applications/iMovie.app (string) + systemAudio : (list) + Item : (dict) + friendlyName : System Audio (string) + icon : [SNIP] + identifier : com.rogueamoeba.source.systemaudio +``` + +That's an indigo.Dict() object. Each group is the key, and the value for each group is a list of "source" indigo.Dict()'s. Each source dict has the following keys: *friendlyName* (the user-friendly name), *icon* (a binhex'd string that is the source's icon - snipped from the above example to save space), *identifier* (the ID used in the source property above). You can unbinhex the icon and save it to a PNG file and store it somewhere for use if you like. You can use the group name and identifier combination in the changeSource action described above. diff --git a/reference/canonical/plugins/alexa.md b/reference/canonical/plugins/alexa.md new file mode 100644 index 0000000..269a829 --- /dev/null +++ b/reference/canonical/plugins/alexa.md @@ -0,0 +1,16 @@ + + +# Alexa +[Alexa](https://www.amazon.com/b?node=21576558011) is a smart assistant voice system from Amazon which is [integrated into many devices](https://www.amazon.com/b?node=15443147011), including the [Echo devices from Amazon](https://www.amazon.com/smart-home-devices/b/?ie=UTF8&node=9818047011&ref_=sv_devicesubnav_1), sound bars and smart speakers, watches, thermostats, TVs, headphones, etc., from a variety of manufacturers. + +Amazon has enabled integration with third parties like Indigo to integrate smart home devices so that you can use voice commands to control them (aka a *Smart Home Skill*). **In English-speaking regions**, we've also created a way to execute action groups and have the value of variables read to you (aka a *Custom Skill*). + +**Note**: **this capability was added in Indigo 2021.1** so if you are using an older version you will need to upgrade. If your Indigo Up-to-Date Subscription is active, and **you have your Indigo Reflector configured and working**, you just need to install **Indigo 2021.1** or later. You also **must have** OAuth enabled in the [Start Local Server dialog](../../user/getting-started/installation.md#starting-indigo-server) for Alexa to work. + +## In This Section + +- **[Smart Home Skill](smart-home-skill.md)** — voice control of devices. +- **[Custom Indigo Skill](custom-skill.md)** — run action groups and read variables by voice. +- **[Plugin Operations](operations.md)** — publishing devices and managing what Alexa sees. +- **[Migrating from the Alexa-Hue Bridge](migrating.md)** — moving off the legacy plugin. +- **[Troubleshooting](troubleshooting.md)** — when discovery or linking misbehaves. diff --git a/reference/canonical/plugins/alexa/custom-skill.md b/reference/canonical/plugins/alexa/custom-skill.md new file mode 100644 index 0000000..5570bbc --- /dev/null +++ b/reference/canonical/plugins/alexa/custom-skill.md @@ -0,0 +1,82 @@ + + +# Custom Indigo Skill +!!! warning "NOTE" + **the Custom Skill is available in English-speaking regions only**. + +When you enable the **Indigo Smart Home Skill** in the Alexa app, you also gain access to some custom functionality that's specific to Indigo. We enable you to hear the value of a variable (complete with speech markup), hear a list of all of your variables, and run Action Groups. + +Custom skill requests require that you preface your requests by saying *Alexa, tell Indigo* or *Alexa, ask Indigo*. These are called **invocations** and are needed so that Alexa can know where to direct the request. It's not needed for Smart Home Skills (ones that deal with Indigo devices as described above as well as devices from other skills) because Alexa knows details about each individual device and where to send the request based on that information. + +!!! warning "NOTE" + Unfortunately, the invocation for the skill is currently different in different regions. + +- US, UK - "indigo" is the invocation +- CA, AU - "indigo home" is the invocation + +We are attempting to get Amazon to help us correct this, but we are unsure if it's going to be possible or not at this time. + +## Speaking the Value of a Variable +!!! note "Note" + When naming variables for use with Alexa, you should use underscores_to_separate_words. That is how the plugin will map separate words from Alexa onto variables (which can't contain spaces). + +To hear the value of a variable, just ask Indigo for it. There are a variety of ways to ask, here are a few (variable names are in quotes, underscores are treated as spaces): + +- *Alexa, ask Indigo to get "current_weather_conditions"* +- *Alexa, ask Indigo to look up "current_weather_conditions"* +- *Alexa, ask Indigo to read "current_weather_conditions"* +- *Alexa, ask Indigo to say "current_weather_conditions"* +- *Alexa, ask Indigo to speak "current_weather_conditions"* +- *Alexa, ask Indigo to tell me "the_status_of_the_house"* +- *Alexa, ask Indigo for the value of variable "current_weather_conditions"* +- *Alexa, ask Indigo the value of "current_weather_conditions"* +- *Alexa, ask Indigo the current value of "weather_conditions"* + +You can also use *tell Indigo* interchangeably with *ask Indigo*. + +The default response (in the default voice) will be: + +*The value of variable "current weather conditions" is "mostly cloudy"* + +You can adjust how Alexa responds in a couple of ways: + +- You can use [Speech Synthesis Markup Language (SSML)](https://developer.amazon.com/en-US/docs/alexa/custom-skills/speech-synthesis-markup-language-ssml-reference.html) to mark up the text in a variable to customize how Alexa reads back the value. Any variable value that begins with a less than sign (<), which we use as a key that the text contains SSML, will be read exactly as specified in the variable without any additional words (i.e. *The value of variable* won't be prepended). If your markup text doesn't naturally begin with a markup tag, wrap the entire string in `` tags. +- Variable values that contain the device (%%d:deviceId:deviceState%%) or variable (%%v:variableId%%) markup values will be correctly substituted by Indigo. +- You may also specify in the plugin's config that all variable values should be read exactly as they are stored without the added verbiage. + + +### Get a List of Variables +You can hear a list of your variables as well. Here are a variety of ways to ask: + +- *Alexa, ask Indigo to get my variable list* +- *Alexa, ask Indigo to list my variables* +- *Alexa, ask Indigo to list all variables* +- *Alexa, ask Indigo what variables are available* + +You can also use *tell Indigo* interchangeably with *ask Indigo*. + +### Execute an Action Group +You can tell Indigo to execute an action group. Here are a variety of ways to ask (action group names are in quotes): + +- *Alexa, tell Indigo to arm "the kitchen zone"* +- *Alexa, tell Indigo to do "my favorite thing"* +- *Alexa, tell Indigo to execute "toggle music"* +- *Alexa, tell Indigo to launch "rocket"* +- *Alexa, tell Indigo to make "the house secure"* +- *Alexa, tell Indigo to perform "routine maintenance"* +- *Alexa, tell Indigo to play "my favorite playlist"* +- *Alexa, tell Indigo to reset "the alarm"* +- *Alexa, tell Indigo to restart "the laundry timer"* +- *Alexa, tell Indigo to restore "the standard speaker set"* +- *Alexa, tell Indigo to run "routine maintenance"* +- *Alexa, tell Indigo to start "the laundry timer"* +- *Alexa, tell Indigo to set "the playlist to classic rock"* + +Action group names can contain letters, numbers, and spaces only. If you say "playlist eighties music", the action group name will need to be "playlist 80s music". If you are unsure how to name an action group, just attempt to execute it with one of the above utterances. If Indigo doesn't find an action group matching what you said, it will log it to the Event Log window like this: + +`Alexa Error an action group named 'kitchen zone' does not exist in your indigo server` + +That will tell you the text that Alexa sent to the plugin, so you can name your action group exactly what's in single quotes and the next time it will work. + +!!! note + What you say before the action group name will work for any action group name. We picked the above examples only because they are normal complete English sentences, but you could just as well say *Alexa, tell Indigo to arm "the laundry timer"* and the effect would be the same as saying *Alexa, tell Indigo to start "the laundry timer"*. You can also use *tell Indigo* interchangeably with *ask Indigo*. diff --git a/reference/canonical/plugins/alexa/migrating.md b/reference/canonical/plugins/alexa/migrating.md new file mode 100644 index 0000000..393b197 --- /dev/null +++ b/reference/canonical/plugins/alexa/migrating.md @@ -0,0 +1,31 @@ + + +# Migrating from the Alexa Hue Bridge plugin +If you are using the Alexa-Hue Bridge plugin, you will definitely want to read through this section. + +We know there are users that have relied on the Alexa-Hue Bridge plugin even though it requires Echo hardware that is no longer available. It was a great stop-gap, and we really appreciate everyone who contributed to maintaining it through the years, particularly forum user @Autolog. + +If you are migrating, we highly recommend that you do a full switch rather than try to use both while switching. While it's possible to use both, doing a full switch will help you avoid a variety of issues, including Alexa caching, device name conflicts, etc. + +## Full Switch +Doing a full switch is pretty simple, just follow these steps: + +1. Disable the Alexa-Hue Bridge plugin. +1. In the [Alexa website](https://alexa.amazon.com/spa/index.html#appliances), remove all devices. The simplest way is to click the `Remove All` button at the bottom. Note, if you are using other smart home skills, using that button will also cause those devices to be forgotten, so when you do a discover later you'll need to perform any steps needed to make discover work on for that skill. +1. In Indigo, follow the directions above in the [Making a Device Available in Alexa](../alexa/smart-home-skill.md#making-a-device-available-in-alexa) to publish your devices. +1. Once you have all your devices published, you can confirm that they are all published by selecting the `Plugins->Alexa->Show Device Publications` menu item and it will print the list of publications in the Event Log window. +1. In the Alexa app, website, or using an Alexa enabled device, click/touch the Discover button or say "discover devices". + +This should make all of your devices available in Alexa. Whenever you ask an Alexa device to discover, you will see the following Event Log line followed by a summary of publications: + +`Alexa Alexa discovery request received, assembling reply...` + +### Partial Switch +If you want to attempt to switch one at a time, the process is more complicated and somewhat error-prone. The general process is: + +1. Disable the device from the Alexa-Hue Bridge plugin (see [the docs for the plugin](https://github.com/IndigoDomotics/alexa-hue-bridge/wiki) for details). This is very critical in order to avoid complications/confusion later. +1. In the [Alexa website](https://alexa.amazon.com/spa/index.html#appliances), remove that specific device. +1. In Indigo, follow the directions above in the [Making a Device Available in Alexa](../alexa/smart-home-skill.md#making-a-device-available-in-alexa) to publish your device. Be sure to confirm/select the appropriate subtype. +1. In the Alexa app, website, or using an Alexa enabled device, click/touch the Discover button or say "discover devices". + +Hopefully, Alexa will find your device and it will work properly. Unfortunately, sometimes that doesn't work. We believe that there are some caching issues within the Alexa environment where removing a device doesn't fully remove a device. If you experience this, you may need to remove the device again and wait a while before rerunning discovery. It may even require that you disable the Alexa plugin, rerun discovery, then enabling the Alexa plugin, and running discovery again. We haven't been able to find the silver bullet for this so it's a bit of trial and error. diff --git a/reference/canonical/plugins/alexa/operations.md b/reference/canonical/plugins/alexa/operations.md new file mode 100644 index 0000000..f2f460e --- /dev/null +++ b/reference/canonical/plugins/alexa/operations.md @@ -0,0 +1,79 @@ + + +# Alexa Plugin operations +## Plugin Startup +When the plugin starts up, you will see a list of what's published to Alexa in the Event log. It will look something like this: + +```text + Started plugin "Alexa 2024.1.0" + Alexa Finding devices to publish to Alexa... + Alexa ... '010 - Smart Fan Control (14287)' published as 'office fan' + Alexa ... '016 - Plug-In Appliance Module (ZL-PA-100)' published as 'office lamp' + Alexa ... '038 - Lamp Module (AD130)' published as 'blinds' + Alexa ... 'automatic door' published + Alexa ... 'FanLinc - Fan' published as 'ceiling fan' + Alexa ... 'FanLinc - Light' published as 'fan light' + Alexa ... 'Fortrezz Strobe' published as 'strobe' + Alexa ... 'Hue Bulb' published as 'office bulb' + Alexa ... 'Insteon Dimmer' published as 'valve' + Alexa ... 'Insteon On/Off' published as 'back door' + Alexa ... 'Insteon Thermostat' published as 'thermostat' + Alexa ... 'Kasa Plug' published as 'garage door' + Alexa ... 'Office Siren' published + Alexa ... 'outlet' published + Alexa ... 'Simple Virtual On/Off' published as 'simple switch' + Alexa A total of 15 devices are currently published to Alexa + Alexa Warning If you can't control a device, rerun discover from your Alexa device. +``` +### Showing Publications +You can also select the `Plugins->Alexa->Show Device Publications` menu item to show this list with more details and sorted by the Alexa name: +```text + Alexa Currently published devices (Alexa name first if different than Indigo name): + Alexa 'Office Siren' ('Office Siren') - Type: RelayDevice - Subtype: Siren + Alexa 'automatic door' ('automatic door') - Type: RelayDevice - Subtype: Door Controller + Alexa 'back door' ('Insteon On/Off') - Type: RelayDevice - Subtype: Lock + Alexa 'blinds' ('038 - Lamp Module (AD130)') - Type: DimmerDevice - Subtype: Blind + Alexa 'ceiling fan' ('FanLinc - Fan') - Type: SpeedControlDevice - Subtype: None + Alexa 'fan light' ('FanLinc - Light') - Type: DimmerDevice - Subtype: Dimmer + Alexa 'garage door' ('Kasa Plug') - Type: RelayDevice - Subtype: Garage Controller + Alexa 'office bulb' ('Hue Bulb') - Type: DimmerDevice - Subtype: Color Bulb + Alexa 'office fan' ('010 - Smart Fan Control (14287)') - Type: DimmerDevice - Subtype: Fan + Alexa 'office lamp' ('016 - Plug-In Appliance Module (ZL-PA-100)') - Type: RelayDevice - Subtype: Plug-In + Alexa 'outlet' ('outlet') - Type: RelayDevice - Subtype: Outlet + Alexa 'simple switch' ('Simple Virtual On/Off') - Type: RelayDevice - Subtype: Switch + Alexa 'strobe' ('Fortrezz Strobe') - Type: RelayDevice - Subtype: Plug-In + Alexa 'thermostat' ('Insteon Thermostat') - Type: ThermostatDevice - Subtype: None + Alexa 'valve' ('Insteon Dimmer') - Type: DimmerDevice - Subtype: Valve +``` +### Discovery Requests from Alexa +When the plugin receives a discover request from the Alexa servers, you will see something similar to this in the Event Log: +```text + Alexa Alexa discovery request received, assembling reply... + Alexa ...'ceiling fan' ('FanLinc - Fan') - Type: SpeedControlDevice - Subtype: None + Alexa ...'simple switch' ('Simple Virtual On/Off') - Type: RelayDevice - Subtype: Switch + Alexa ...'upstairs siren' ('Fortrezz Siren') - Type: RelayDevice - Subtype: Siren + Alexa ...'outlet' - Type: RelayDevice - Subtype: Outlet + Alexa ...'fan light' ('FanLinc - Light') - Type: DimmerDevice - Subtype: Dimmer + Alexa ...'office fan' ('010 - Smart Fan Control (14287)') - Type: DimmerDevice - Subtype: Fan + Alexa ...'back door' ('Insteon On/Off') - Type: RelayDevice - Subtype: Lock + Alexa ...'automatic door' - Type: RelayDevice - Subtype: Door Controller + Alexa ...'Office Siren' - Type: RelayDevice - Subtype: Siren + Alexa ...'thermostat' ('Insteon Thermostat') - Type: ThermostatDevice - Subtype: None + Alexa ...'blinds' ('038 - Lamp Module (AD130)') - Type: DimmerDevice - Subtype: Blind + Alexa ...'office lamp' ('016 - Plug-In Appliance Module (ZL-PA-100)') - Type: RelayDevice - Subtype: Plug-In + Alexa ...'office bulb' ('Hue Bulb') - Type: RelayDevice - Subtype: Plug-In + Alexa ...'strobe' ('Fortrezz Strobe') - Type: RelayDevice - Subtype: Plug-In + Alexa ...'garage door' ('Kasa Plug') - Type: RelayDevice - Subtype: Garage Controller + Alexa ...'outside lights' ('Outdoor Appliance Module (45604)') - Type: RelayDevice - Subtype: Plug-In + Alexa ...'valve' ('Insteon Dimmer') - Type: DimmerDevice - Subtype: Valve + Alexa Found 17 devices to publish, replying +``` +### Command Requests from Alexa +When an Alexa command is received, you will see something similar to this in the Event Log: + +```text + Alexa turning on 'Hue Bulb' + Sent Hue Lights "Hue Bulb" on to 100 at ramp rate 2.0 sec. + +This will allow you to easily see that the change was the result of an Alexa request. This will show for every change that the Alexa plugin makes. +``` diff --git a/reference/canonical/plugins/alexa/smart-home-skill.md b/reference/canonical/plugins/alexa/smart-home-skill.md new file mode 100644 index 0000000..17f59a4 --- /dev/null +++ b/reference/canonical/plugins/alexa/smart-home-skill.md @@ -0,0 +1,161 @@ + + +# Smart Home Skill +!!! Note + The Alexa skill is currently available in the Alexa skill stores for most of the regions in which we sell Indigo (US, Canada, UK, the Netherlands, Australia, New Zealand, France, Germany, Spain, Italy). + +We have implemented a skill which you can enable that will provide standard smart home device control. This enables an Alexa user to control devices in the exact same way regardless of how that device is connected to Alexa. This section will give you an overview of the device types in Indigo that you can publish to Alexa for control. We don't automatically publish your Indigo devices for a variety of reasons, but primarily as a security measure. You must make an explicit decision to enable voice control of a device. + +You must have your Indigo Reflector activated in order to proceed. + +You enable the Indigo Skill in the Alexa app (this is the iOS App as of June 2021, it may change): + +1. Open the Alexa App. +1. Go to the Devices list and click the link to Your Smart Home Skills. +1. Click Enable Smart Home Skills. +1. Tap the Search icon. +1. Search for "Indigo Smart Home". You should see a skill named **Indigo Smart Home Skill** in English-speaking regions and **Indigo Smart Home** everywhere else, with an icon that matches the logo of the Mac Client. +1. Add the skill. +1. Link the skill to your Indigo Account & license (currently by clicking/tapping the Settings button). + 1. Log in using your Indigo Account username and password. + 1. On the next page (the authorization page), if you have multiple Indigo Licenses, make sure you have the correct one selected (you must have an active Indigo Up-to-Date subscription); you can link one license to one Alexa (Amazon) account. If you see something else or don't see a license you were expecting to see, check the [Account Linking Issues](troubleshooting.md#account-linking-issues) troubleshooting section below for help. + +## Alexa Store Links +Here are direct links to the skills in their respective Alexa stores: + +- [Australia](https://www.amazon.com.au/dp/B097GBHBZG) +- [Canada](https://www.amazon.ca/dp/B097GBHBZG) +- [France](https://www.amazon.fr/dp/B09DCZDRRS) +- [German](https://www.amazon.de/dp/B09DCZDRRS) +- [Italy](https://www.amazon.it/dp/B09DCZDRRS) +- [Spain](https://www.amazon.es/dp/B09DCZDRRS) +- [United Kingdom](https://www.amazon.co.uk/dp/B097GBHBZG) +- [United States](https://www.amazon.com/dp/B097GBHBZG) + +## Making a Device Available in Alexa +To make a device available to Alexa, you must explicitly publish it. Use the`Plugins->Alexa->Manage Device Publications...` menu item to open the publication dialog: + +![Alexa Manage Publications Image](../../images/alexa_manage_publications.png) + +In this dialog, you will select a device from the popup. Note that the popup is divided into two sections: + +![Alexa Manage Device List Image](../../images/alexa_manage_device_list.png) + +The top part of the list are Indigo devices that can be published to Alexa, but haven't yet. If you select one of these devices, the dialog will show you the appropriate options for that device. For all devices, you can specify an Alternate Name which will be used in Alexa when you operate it (i.e. Alexa, turn on *office lamp*). If you leave this field blank, the actual Indigo device name will be used. Note that Alexa device names can only contain letters, numbers, and spaces. + +Some devices will also show a Type popup: + +![Alexa Type Popup Image](../../images/alexa_type_popup.png) + +You will use this popup to tell Alexa more specifically what kind of device it is. We will attempt to look at various other characteristics of the device to select what we believe is the appropriate type, but you may select any from the list, and we will relay that information to Alexa so you can control it using appropriate terminology (see below for specifics). + +The bottom part of the list are devices that you have already published to Alexa. If you select one of these devices, you can edit or unpublish the device. + +!!! warning + Be sure to click the Save button before moving on or your changes won't be saved. Also, if you make any changes, **you will need to rerun discovery from an Alexa device or the Alexa app before those changes will be reflected**. As a reminder, you must either click the discover devices button in the Alexa apps or ask "Alexa, discover devices" of an Alexa enabled device. + +## Device Types Supported +The following device types are supported: + +- On/Off devices (sometimes referred to as relay) - simple appliance control plug-in modules, outlets, and switches are the most common type. This also includes Locks and Garage Doors. +- Dimmer devices - dimmer switches and plug-in modules are the most common, though in Indigo there are a variety of other device types that Indigo sees as dimmers: Blinds/Drapes, Fans, Bulbs (including color), etc. +- Thermostats +- Fans - Indigo natively only supports the Insteon FanLinc fan as a proper fan device (with the right controls) - Z-Wave fan controllers are currently implemented as dimmers, but they will work as fans in Alexa if configured correctly. + +### On/Off Devices +This type of device has a boolean value, most often on/off or open/closed. To control from Alexa, you use phrases like: + +- *Alexa, turn on office lamp* +- *Alexa, turn off bedroom fan* +- *Alexa, open garage door* + +When you select an Indigo device that is a standard On/Off device to publish, you will get a popup that will help us tell Alexa how to control your device: + +![Alexa Relay Subtypes Image](../../images/alexa_relay_subtypes.png) + +We will take a guess at what the specific type of the device is, but we won't always guess correctly. For instance, if there isn't anything about your device that Indigo can determine, it will just automatically select `Switch`. You can override that setting however to make the device best match what it does. + +The options are: + +- Door Bell - as of this release, this will only allow you to turn on/off the doorbell, not accept ring events. We will look at adding that in a future release. +- Door Controller - if you have a device that physically operates a door (but not a garage door), you can use this device type. You can then say things like: + - *Alexa, open the front door* + - *Alexa, what's the status of the front door* +- Garage Controller - this is exactly what you think it is. You will be able to open/close (raise/lower) your garage door. Alexa uses this control type as a more secure option. When Alexa first discovers a garage door, it will not allow you to control the door by voice. Rather, it will tell you to control it manually or go to the Alexa app and configure the door for use with voice control. In the settings for the door in the Alexa app, you will be able to enter a 4 digit PIN for extra security. When you ask Alexa to open or raise the door, you will be prompted for your PIN code. If you have an automatic door controller (specified above) and want the extra security of a PIN code, you can select Garage Controller as well, and it should work just like a garage door. PIN codes are set per device so each can be different. You can say things like: + - *Alexa, open the garage door* + - *Alexa, is the garage door open* +- Lock - similar to a garage door, a lock device will need to have a PIN assigned for it in the Alexa app. Once that's done, when you attempt to unlock the door (*Alexa, unlock the back door*), it will prompt you for the PIN. You can say things like: + - *Alexa, lock the back door* + - *Alexa, is the back door locked* +- All the rest of the types will simply respond to standard on/off commands. There is currently no distinction other than the icon that shows up in the Alexa app. You can say things like: + - *Alexa, turn on bathroom exhaust fan* + - *Alexa turn off desk lamp* + +### Dimmer Devices +This type of device is most often a dimmable load, though there are some other options. Most of these device types will also respond to on/off commands like Relay Devices above. To control from Alexa, you use phrases like: + +- *Alexa, brighten office lamp to 35%* +- *Alexa, dim office lamp by 15%* + +If the devices support color and/or white temperature, you can use phrases like: + +- *Alexa, set color of office bulb to red* (color devices) +- *Alexa, set office bulb to daylight* (white color temperature) +- *Alexa, make office bulb warmer* (white color temperature) + +For white temperatures, the following table maps the names that Alexa expects to the color temp in kelvin: + +| **Shades of White** | **Temperature in Kelvin** | +|--------------------------|---------------------------| +| warm, warm white | 2200 | +| incandescent, soft white | 2700 | +| white | 4000 | +| daylight, daylight white | 5500 | +| cool, cool white | 7000 | + + +When you select an Indigo device that is a dimmer device to publish, you will get a popup that will help us tell Alexa how to control your device: + +![Alexa Dimmer Subtypes Image](../../images/alexa_dimmer_subtypes.png) + +We will take a guess at what the specific type of the device is, but we won't always guess correctly. For instance, if there isn't anything about your device that Indigo can determine, it will just automatically select `Dimmer`. You can override that setting however to make the device best match what it does. + +The options are: + +- `Blind` - use this type if your dimmer device actually controls blinds, shades, or drapes. You can say things like: + - *Alexa, raise the blinds to twenty-five percent* + - *Alexa, set the drapes to fifty percent* + - *Alexa, close the shades* + - *Alexa, what is the status of the shades* +- `Fan` - use this type if your device actually controls a fan (as of this release Z-Wave fan controllers are treated as dimmers in Indigo). Fan devices from Indigo in Alexa will support 4 modes: **Off**, **Low**, **Medium**, **High**. You can say things like: + - *Alexa, set ceiling fan to medium* + - *Alexa, set ceiling fan to highest* + - *Alexa, ceiling fan speed* + - *Alexa, turn off ceiling fan* +- `Valve` - use this type if your device controls a valve, or really any device that has a 0-100% range. You can say things like: + - *Alexa, set the valve to thirty percent* + - *Alexa, increase valve by ten percent* + - *Alexa, turn off the valve* +- All the rest will support standard on/off and dim/brighten. If the device supports color and/or white color temperature, those commands will be added to the standard on/off and dim/brighten commands (see the examples above). There is currently no distinction other than the icon that shows up in the Alexa app. + +### Indigo Fan Devices +Indigo has a native fan device type. Currently, the only built-in device using this type is the Insteon FanLinc. There are some other plugins which also support this device type. If you select a device of this type the only option will be the Alternative name as there are no other options. You can say things like: + + - *Alexa, set ceiling fan to medium* + - *Alexa, set ceiling fan to highest* + - *Alexa, increase ceiling fan speed* + - *Alexa, turn off ceiling fan* + +### Indigo Thermostat Devices +Any Indigo thermostat device can be added to Alexa. Schedule/program mode isn't supported on thermostats that offer that feature. + +**NOTE**: the Alexa implementation for thermostats is quite limited as it only fully supports thermostats that are in either heat or cool mode. In North America, most thermostats stay in *auto* mode, which allows (at least) two setpoints to be active at the same time to call for heat or cool depending on the temp. Alexa's support for *auto* mode is fundamentally read-only: you can't adjust either setpoint while in *auto*. Further, the error that Alexa will respond with implies that you have to manually set the mode on the thermostat itself to either *heat* or *cool* in order for you to adjust setpoints. This is incorrect in that you can say to Alexa "set the thermostat to heat", and that will correctly change mode from *auto* to *heat* (same applies to *cool*). + + +So, with that warning aside, you can say things like: + + - *Alexa, set the thermostat to cool* + - *Alexa, what is my thermostat set to* + - *Alexa, turn off the heat* (**Warning**: this will turn the thermostat off regardless of mode) + - *Alexa, set the AC to seventy-five* + - *Alexa, make it warmer in here* diff --git a/reference/canonical/plugins/alexa/troubleshooting.md b/reference/canonical/plugins/alexa/troubleshooting.md new file mode 100644 index 0000000..b1b036e --- /dev/null +++ b/reference/canonical/plugins/alexa/troubleshooting.md @@ -0,0 +1,104 @@ + + +# Alexa Troubleshooting +Because this integration is made up of a variety of parts, and because Alexa itself can talk to multiple smart home skills as well as allow the definition of custom "routines", there are a variety of places where things can go wrong. This section will hopefully cover many of those scenarios. + +If you don't find an answer to your problem in this section, post a detailed description of your issue and the steps you have taken (and any relevant Event Log entries) to the [Alexa plugin support forum](https://forums.indigodomo.com/viewforum.php?f=359). + +## Device Caching +The first and foremost issue that users experience with Alexa, device discovery and device changes, is that Amazon caches device definitions, and any changes (additions, changes, deletions) may take minutes to complete. Sometimes the changes don't propagate throughout their various caches at all. + +So, when making any changes, it's always a good idea to wait for maybe 10 minutes between any changes that you make. For instance, if you change the name of a device, run discovery as advised below, but wait for 10 minutes before looking for the change in the Alexa app or trying to control the device using the new name. + +Usually, when adding a new device, it happens pretty quickly. However, not always, and especially if it's combined with a change in another device. This seems not only to slowly propagate the change, but also slow the addition of a new device. + +If you want to delete a device (or all devices to start over), this seems to be the most problematic scenario for their caching scheme. You will want to wait 10 minutes to make sure that the deletion actually occurs before doing anything else. Users have reported that doing a Remove All from the Alexa website will continually fail and that the way to accomplish it is to delete a few at a time. While we haven't confirmed this behavior, it would not surprise us given all the caching issues we've experienced and read about. + +## Account Linking Issues +When you enable the Indigo Smart Home Skill in the Alexa app, you're required to link it to a [license in your Indigo Account](https://www.indigodomo.com/account/codes). You'll automatically be forwarded to the login page for your Indigo Account: log in using your normal credentials. You will then be forwarded to the skill authorization page which will have a popup that contains all of your licenses. Most users will only have a single license, but some will have multiple. You can only control a single Indigo Server from any given Alexa account. + +If you see an error page saying that you don't have any available licenses, this could be a result of a couple of things: + +1. You have previously linked your license to Alexa but haven't revoked it on the [Authorizations page in your Indigo Account](https://www.indigodomo.com/account/authorizations). This may happen if you disable the Indigo Skill then attempt to re-enable it. Click on the Revoke button next to the Alexa authorization for your license to revoke the authorization then try linking again. +1. Your Indigo Up-to-Date subscription has expired. To use Alexa (and similar types of integrations), you need to have an active Indigo Up-to-Date subscription and your reflector must be active. +1. Your Indigo License doesn't have an active/working Indigo Reflector (included with your UTD subscription). To use Alexa (and similar types of integrations), you need to have an active Indigo Up-to-Date subscription and [your reflector must be active](https://www.indigodomo.com/docs/reflectors). +1. You may also see this error if Alexa has had some issue talking to your Indigo Server. We don't know exactly why this happens, but the solution is the same as #1 above - revoke and relink and it should continue working. If you have repeated link failures, check to see if your internet connection has had any periodic issues as this can cause Alexa to forget about its link authentication. Also, if you have more than around 50 devices publishes, this seems to exacerbate the problem. We recommend that you keep the number of devices published to a smaller reasonable number that really need voice control. + +## Changing a Published Device in Indigo +### Changing the Indigo Name +If you specified an alternate name for a device when publishing it, then changing the Indigo name won't make any difference, and you won't need to do anything. + +If, however, you didn't specify an alternate name, then Indigo will use the Indigo device name. If you change it, then you will need to rerun discovery in the Alexa app or on an Alexa-enabled device. If discovering by voice command, Alexa will say that it couldn't find any new devices (which is technically correct), but the device will now respond to the new name. + +If it doesn't then the most likely scenario is that the new name conflicts with another device Alexa knows about. Check the list of devices in the Alexa app to ensure that there isn't a duplicate name. Also, when you check the list, make sure that the old device name is no longer in the list. If it is, confirm that you changed the name (and that you didn't specify an alternate name) then rerun discovery. + +Also, remember our discussion of device caches above: give Alexa at least 10 minutes for changes to propagate throughout their device caches. + +If you've made a change and waited, and it's still not responding, one other possibility is that you have a routine defined in Alexa with the name or a similar name - that may cause conflicts when Alexa attempts to determine what it is you're asking. + +### Changing the Alternate (Alexa) Name +If you change the alternate name, you will need to rerun discovery. If the new name doesn't work, try the troubleshooting tips in the [Changing the Indigo Name](../alexa/troubleshooting.md#changing-the-indigo-name) section just above this one. + +### Changing the Device Type +If you edit a device and change the type, protocol, or anything that changes the nature of the device, you will most likely want to follow this procedure: + +1. In the Alexa app, remove the device. +1. Go back to the [Publication Dialog](../alexa/smart-home-skill.md#making-a-device-available-in-alexa), select the device, and make sure that you are satisfied with the subtype (or change it as necessary). +1. Save any changes. +1. Rerun discovery in Alexa. + +It should say that it has found a new device (since you deleted it first) and you should now be able to control it based on the new type. Note that changing protocol might not require the process above (an Indigo dimmer device works the same no matter the protocol), but we have found that Alexa caches information about devices and just doing a discover after changing may not be enough to force Alexa to reset the device cache. + +## General Issues +Alexa uses some sophisticated caching mechanisms throughout their hosted systems in order to optimize performance/responsiveness. Unfortunately, sometimes that caching mechanism can lead to odd and misleading issues. Sometimes when you make changes (initial publishing, updating, removing publications) it can take a while for the change to propagate throughout their systems. The Indigo skill, which is hosted by Amazon (a requirement), does no caching of devices. The Alexa plugin does some local caching, but that has nothing to do with how Alexa interprets what you say and converts it into the command it sends to the plugin. + +The very first thing you want to check when troubleshooting any Alexa issues is the Event Log window. You will see various warnings and errors that will help you determine if there are issues. Those errors may help you to determine where to go next. First, ensure the following: + +1. Make sure that you have [enabled the Indigo Skill and linked it to your Indigo Account & license](smart-home-skill.md) successfully +1. Make sure that your [Indigo Up-to-Date subscription is active](https://www.indigodomo.com/account/codes/). +1. Ensure that your Indigo Reflector is configured and connected. Check this by hitting your reflector URL in a browser: https://YOURREFLECTORNAME.indigodomo.net/ + +Here are a few things to help you diagnose issues. + +### Alexa can't find a device + +1. Make sure that you have [enabled the Indigo Skill and linked it to your Indigo Account](smart-home-skill.md) & license successfully +1. Watch the Event Log window for [discovery requests](../alexa/operations.md#discovery-requests-from-alexa) + - If you don't see any discovery requests: + - Make sure that your reflector is up and running + - Make sure your Indigo Up-to-Date subscription hasn't lapsed + - Make sure you have OAuth enabled in the [Start Local Server dialog](../../user/getting-started/installation.md#starting-indigo-server) + + - If you see a discovery request: + - Make sure that the device you are publishing is in the list. Take note of the names of your published devices to ensure that they are unique - if you publish two devices with the same name Alexa will ignore or both of them. + - If the above step is fine, then make sure that you aren't using a name that's used by a device in some other smart home skill (some users use the Hue skill to directly control Hue lights, if you have the Alexa-Hue Bridge plugin enabled that may also be publishing a device with the same name). + - Make sure that you are giving Alexa enough time to update its caches - 10 minutes after a discovery is the recommended wait time. + - If you have a slow or unreliable internet connection, Alexa can time out a request rather quickly and will speak some error message. If you see inconsistent behavior, this may be a hint that there is some kind of internet connection issue between the Alexa hosted servers and your Indigo Server (see below for more details). + +### Alexa can't control a device +Some steps to try when Alexa says it can't find a device: + +1. Make sure you are clearly saying the device name. Alexa can sometimes hear something slightly different than what you're saying. +1. Make sure you have the device published in the plugin. You can do this by selecting the `Plugins->Alexa->Show Device Publications` menu item. Verify that you are saying the name that is published to Alexa if it's different than the name of the device in Indigo. +1. Rerun discovery from the Alexa app for an Alexa device. +1. Look in the Event Log window for errors when trying to control the device. + +### Alexa can't speak a variable value +Some steps to try when Alexa has a problem speaking the value of a variable: + +1. Make sure that the value doesn't contain any [SSML markup](https://developer.amazon.com/en-US/docs/alexa/custom-skills/speech-synthesis-markup-language-ssml-reference.html) symbols by themselves, like <, >, /, etc. Alexa will just throw a very unhelpful error (*"Sorry, I'm having trouble accessing your Indigo Skills skill right now"*) when it thinks that the string contains malformed SSML. +1. Make sure that the value of the variable is less than 8000 characters - that's the speech output limit for Alexa. + +### Alexa can't speak the variable list +Some steps to try when Alexa has a problem speaking the variable list: + +1. If you have too many variables, you may get the error *“There is a problem with the requested skill response”*. The issue is that the speech output sent to Alexa can't be longer than 8000 characters, so if you have a lot of variables or lots of variables with long names you may run into this situation. The next release of the plugin will only speak variables that have the "Remote Display" flag set for them, so you will be able to exclude variables using that mechanism without deleting them. + +### Alexa can't speak the variable of a variable +If the value of your variable contains an ampersand (&) or perhaps other special characters, you should replace them with the actual english word (and). Alternately, you can probably HTML encode the character as well (&). + +### Alexa says there are issues when you try various things +Alexa skills are hosted on their servers, and must communicate with your Indigo server through your reflector. If you have a poor internet connection, you may see some odd issues: not being able to discover, errors when you ask Indigo for things even though it appears on the Indigo side that they have happened, etc. Their API is very picky about response times, as slow response times is a poor user experience. This does mean, however, that anyone with slow connections (Satellite) or unreliable internet connections will experience various error messages from Alexa. Unfortunately, there is nothing we can do about this issue. + +### If All Else Fails = +If every other troubleshooting step has been taken, and you have multiple Indigo licenses, contact support (mentioning that you have multiple licenses) so we can more quickly determine if this is related to your problem. diff --git a/reference/canonical/plugins/easydaq_1.md b/reference/canonical/plugins/easydaq_1.md new file mode 100644 index 0000000..b1629ad --- /dev/null +++ b/reference/canonical/plugins/easydaq_1.md @@ -0,0 +1,216 @@ + + +# EasyDAQ Relay Card Plugin +The EasyDAQ Relay Card Plugin for Indigo integrates several [USB (and IP) controlled relay and digital input/output cards](http://www.easydaq.co.uk/) with Indigo. Using Indigo you can control the digital and relay output channels, execute actions when a digital input changes, and inspect all input and output channels remotely via Control Pages. + + +![EasyDAQ USB Controlled Relay and DIO Cards](../images/easydaq_20logo_20_100tint_.gif) + +## Cards Supported +Several versions of the EasyDAQ cards are supported: + +- USB4PRMxN, USB4PRMx, USB4SRMx (4 relays + 4 DIO channels) +- USB8VI4DIOSR (8 isolated inputs + 4 relays + 4 DIO channels) +- USB8PR2, USB8PR, USB8SR (8 relays) +- USB16PRMxN, NET16PRMx (8 relays + 8 relays/DIO + 8 DIO channels) +- USB24MxS (24 relays) +- USBDIO24 (24 DIO channels) + +### Adding Cards to Indigo +Each USB controlled card is added to Indigo as a separate Indigo Device. All EasyDAQ relay cards use the FTDI VCP driver, so be sure and [download and install](http://www.indigodomo.com/ftdiurl) it first. + +Next choose the `File->New Device...` menu item, select `Plugin` from the Type popup control, and `EasyDAQ Relay Card` from the Plugin popup control, and choose the correct Model. Press the `Edit Device Settings...` button to configure the card: + +![Easydaq Settings Window Image](../images/easydaq_settings_window.png) + +The FTDI VCP driver adds the virtual serial port. Note you must have the card plugged into your Mac for the port to be shown in the popup control. Or if you are using a network (IP) based card, you can select the Network Socket connection type and enter the IP and port address for the card. You can define custom labels for all the inputs and outputs, and for some channels, depending on the card model, choose if a digital input/output is being used as an input or an output. + +### Controlling Relay and Digital Outputs +The output channels are controlled via Indigo actions. The actions can be inside Triggers, Schedules, Action Groups, or assigned to Control Page controls. From the Action panel inside these dialogs choose `Plugin` from the Type popup control, and then choose the Action you want to perform and the target Device: + +![Easydaq Action Panel Window Image](../images/easydaq_action_panel_window.png) + +Some actions have additional options available via the `Edit...` button. For example, the `Change Multiple Outputs` action allows you to control (turn on, turn off, or toggle) all the outputs with a single, and very fast, action: + +![Easydaq Action Change Multi Window Image](../images/easydaq_action_change_multi_window.png) + +### Triggering Actions on a Digital Input Change +Indigo will automatically track all input and output channel states. To trigger an action when a particular channel state changes from OFF to ON (or ON to OFF) choose the `File->New Trigger` menu item, and select `Device State Changed` from the Type popup control. Next, select the Indigo device representing the EasyDAQ card you want to monitor, and then choose which channel change will cause the trigger: + +![Easydaq Trigger Device State Change Window Image](../images/easydaq_trigger_devstatechange_window.png) + +You can then use the Condition panel to add further logic, and the Actions panel to define the action you want executed (ex: turn on lights, send an email, etc.) + +### Preventing Floating Input Problems +Depending on the EasyDAQ model you are using, you may experience a floating input problem when an input is left in an open state. If you see a continuous stream of changes logged inside Indigo only when an input is in an open state, then you will need to use a [pull-up (or down) resistor](#pull-up-and-pull-down-resistors). + + +## Scripting Support +As with all plugins, actions defined by this plugin may be executed by [Python scripts](../scripting/tutorial.md#scripting-indigo-plugins). Here's the information you need to script the actions in this plugin. + +**Plugin ID**: com.perceptiveautomation.indigoplugin.easydaq-usb-relay-cards + +### Action specific properties +#### Turn On Output +**Action id**: turnOnOutput + +Properties for scripting: + +| *`channelSel`* | this is the channel number to turn on, values depend on the type of card you have | +|----------------|-----------------------------------------------------------------------------------| + + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.easydaq-usb-relay-cards" + +# Get a plugin object given the plugin id: +easyDaqPlugin = indigo.server.getPlugin(plugin_id) + +if easyDaqPlugin.isEnabled(): + easyDaqPlugin.executeAction( + "turnOnOutput", + deviceId=131523919, + props={'channelSel':1} + ) +``` + +#### Turn Off Output +**Action id**: turnOffOutput + +Properties for scripting: + +| *`channelSel`* | this is the channel number to turn off, values depend on the type of card you have | +|----------------|------------------------------------------------------------------------------------| + + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.easydaq-usb-relay-cards" + +# Get a plugin object given the plugin id: +easyDaqPlugin = indigo.server.getPlugin(plugin_id) + +if easyDaqPlugin.isEnabled(): + easyDaqPlugin.executeAction( + "turnOffOutput", + deviceId=131523919, + props={'channelSel':1} + ) +``` + +#### Toggle Output +**Action id**: toggleOutput + +Properties for scripting: + +| *`channelSel`* | this is the channel number to toggle, values depend on the type of card you have | +|----------------|----------------------------------------------------------------------------------| + + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.easydaq-usb-relay-cards" + +# Get a plugin object given the plugin id: +easyDaqPlugin = indigo.server.getPlugin(plugin_id) + +if easyDaqPlugin.isEnabled(): + easyDaqPlugin.executeAction( + "toggle", + deviceId=131523919, + props={'channelSel':1} + ) +``` + +#### All Outputs On +**Action id**: allOutputsOn + +No properties for scripting are required. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.easydaq-usb-relay-cards" + +# Get a plugin object given the plugin id: +easyDaqPlugin = indigo.server.getPlugin(plugin_id) + +if easyDaqPlugin.isEnabled(): + easyDaqPlugin.executeAction( + "allOutputsOn", + deviceId=131523919 + ) +``` + +#### All Outputs Off +**Action id**: allOutputsOff + +No properties for scripting are required. + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.easydaq-usb-relay-cards" + +# Get a plugin object given the plugin id: +easyDaqPlugin = indigo.server.getPlugin(plugin_id) + +if easyDaqPlugin.isEnabled(): + easyDaqPlugin.executeAction( + "allOutputsOff", + deviceId=131523919 + ) +``` + +#### Change Multiple Outputs +**Action id**: changeMultiple + +Properties for scripting: + +| *`channelSel#`* | this is the command for the channel and must be one of the following: "turnOn", "turnOff", "toggle" - note that you should have separate properties for each channel, see example below for details | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + + +Example: + +```python +plugin_id = "com.perceptiveautomation.indigoplugin.easydaq-usb-relay-cards" + +# Get a plugin object given the plugin id: +easyDaqPlugin = indigo.server.getPlugin(plugin_id) + +if easyDaqPlugin.isEnabled(): + easyDaqPlugin.executeAction( + "changeMultiple", + deviceId=131523919, + props={ + 'channelSel1':'turnOn', + 'channelSel8':'toggle', + 'channelSel17':'turnOff' + } + ) +``` + +## Pull-Up and Pull-Down Resistors { #pull-up-and-pull-down-resistors } +Home automation often involves interfacing with contact closure type switches. Some examples include: alarm magnetic reed door/window switches, water float level switches, push button switches, etc. + +Some input hardware can be directly wired to these switches, such that the INPUT pin/terminal goes directly to one switch wire while the other switch wire is connected to +5V. This hardware, like the Insteon I/O-Linc, has an internal circuit so that it can specifically be used for contact closure type circuits. + +However, some TTL based input hardware will have a "floating input" problem when the switch is open. In such an open state the INPUT pin on the hardware will be connected to nothing and the TTL circuitry will bounce between showing ON and OFF. You'll know this is a problem because there will be a continuous stream of changes logged inside Indigo when the switch is in the open state. + +The solution in this case is to use a pull-up resistor (RadioShack will have the 10K resistor needed) so that the INPUT pin is never left in a floating, or unconnected, state: + +![Pull Up Resistor Image](../images/pullup_resistor.png) + +When the closure switch is in the open state, the INPUT pin is pulled up to +5V through the 10K resistor. When the closure switch is in the closed state, INPUT will be forced to GND (+0V). Note the 10K resistor is needed so that there isn't an unloaded (no resistance) short between +5V and GND when the switch is closed. By using a 10K resistor, only a tiny amount of current will flow from +5V to GND when the switch is closed. + +Note the above circuit will have INPUT pulled to +5V when the circuit is open, and INPUT will be GND when the circuit is closed. If this is the opposite of what you want, then you can use a pull-down resistor circuit instead: + +![Pull Down Resistor Image](../images/pulldown_resistor.png) + +## Support and Troubleshooting +For usage or troubleshooting tips [discuss this device](https://forums.indigodomo.com/viewforum.php?f=93) on our forum. diff --git a/reference/canonical/plugins/email.md b/reference/canonical/plugins/email.md new file mode 100644 index 0000000..56e7a83 --- /dev/null +++ b/reference/canonical/plugins/email.md @@ -0,0 +1,279 @@ + + +# Email+ +The Email+ plugin is based on the [Better Email plugin](https://www.indigodomo.com/pluginstore/30/), which has been around for many years and is rock solid. With Indigo 2021.2 and the port to the M1 processor, we decided it was time to move away from our very old email solution to something that was newer and had more features. The plugin author graciously allowed us to include it with Indigo. We changed the name to avoid any confusion. + +**Note**: **this plugin was added in the Indigo 2021.2 installer**. If you were using the [Better Email plugin](https://www.indigodomo.com/pluginstore/30/) from the [Plugin Store](https://www.indigodomo.com/pluginstore/) before you upgraded, the upgrade process should have worked seamlessly, and you shouldn't need to do much. The one thing you may need to change are any [scripts that send emails using the Better Email plugin](https://github.com/FlyingDiver/Indigo-BetterEmail/wiki/Scripting-BetterEmail): you will need to change the id to `com.indigo.email` (see the [Scripting Emails](#scripting-emails) section below for details). The same applies to other plugins that were subscribing to [broadcast messages](#broadcast-messages). + +Use the [Email+ forum](https://forums.indigodomo.com/viewforum.php?f=360) for questions about this plugin. For users of Indigo 7.5 or earlier, we highly recommend that you use the Better Email Plugin (which we've left in the Plugin Store). You won't be able to install Better Email in Indigo versions later than 7.5 since they are basically the same plugin. + +## Email Devices and Usage +The plugin provides three types of Indigo devices: you must create instances of the device types below to be able to send and receive emails. + +### Sending Emails (SMTP Server devices) +The SMTP Server is the device type used for sending emails. To send an email, you first need to create an SMTP device. + +If you had a previous version of Indigo configured to send emails, the upgrade process will create this server for you based on your prior settings. The name of that server will be `Email+ SMTP Server`. + +In Indigo, create a new device, in the `Type` popup select **Email+** and for `Model` select **SMTP Server** + +![SMTP Server Image](../images/smtp_server.png) + +You will need to confirm your settings with your email provider. We **highly recommend** using a dedicated email address for Indigo, particularly if you are performing email scans. **NOTE**: it seems that most email providers are now using StartTLS as their encryption method, so if you get an error about *violation of protocol*, you probably need to change it to StartTLS. + +### Sending an Email +In the Actions tab, you can use the `Notification Actions->Send Email` action to send an email. + +The format can be either plain text or HTML. Variable (`%%v:VariableIDHere%%`) and device state (`%%d:DeviceIDHere:StateIDHere%%`) substitutions are available in all fields. + +#### Sending a Plain Text Email +When sending plain text email messages, simply enter the appropriate text in the Message field. + +![SMTP Send Email Image](../images/smtp_send_email.png) + +#### Sending an HTML Email +![Send HTML Email Image](../images/2023_1_send_html_email.png) + +When sending an HTML email, it's your responsibility to ensure that the Message field contains a valid HTML document - we don't attempt to validate it. The plugin supports both simple and more complex HTML constructions. For example, a simple HTML message might look like this: + +```text +

Heading 1

+
+
+Some plain text. +``` + +More complex HTML documents are also supported: + +```xml + + + + + A Title + + + + +

Heading 2

+

+ Some text with some styling applied. + + +``` + +There are several good reference sites for using HTML and CSS such as the Mozilla [HTML Reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference) and [CSS Reference](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference). + +#### Sending Attachments +Specify attachments by entering the full path to a file with each file separated by commas. For example, + +*`/Library/Application Support/Perceptive Automation/files/some_file.txt,/Library/Application Support/Perceptive Automation/files/another_file.txt`* + +(It's not necessary to escape spaces within the path.) + +#### Sending Event Log Data +In the Actions tab, you can use the `Notification Actions->Send Indigo Log Email` action to send parts of your Event Log lines: + +![SMTP Send Log Image](../images/smtp_send_log.png) + +Variable (`%%v:VariableIDHere%%`) and device state (`%%d:DeviceIDHere:StateIDHere%%`) substitutions are available in all fields. + +#### Email+ Actions +In addition to the `Notification Actions` mentioned above, there are four more Email+ actions to choose from. + +##### Poll Email Server Actions +1. You can use the `Email+ Actions->Poll All Email Servers` item to poll all configured SMTP servers to query for new messages. + +2. You can use the `Email+ Actions->Poll Email Server` item to poll a specific SMTP server for new messages. + +##### Email Queue Actions +1. You can use the `Email+ Actions->Clear All Email Queues` item to clear out all queued emails from all of your SMTP servers. If your email server is having issues, you may find that you want to clear out all pending emails that the plugin has queued up for your email server. + +2. You can use the `Email+ Actions->Clear Email Queue` item to clear out the email queue for a specific SMTP server. + +### Receiving Emails +There are two server types for receiving email: **IMAP**, which is the most fully-featured and is the best option, and **POP**, an older protocol used by older mail providers. + +#### IMAP Server +This is the primary device type used for scanning incoming emails. **Note**: we **highly recommend** using a dedicated email account for Indigo since there is post-processing that can happen, and we don't want accidental email deletions in an account that's used for other things. + +In Indigo, create a new device, in the `Type` popup select **Email+** and for `Model` select **IMAP Server** + +![IMAP Server Image](../images/imap_server.png) + +When configuring your **IMAP** device, you will need to confirm the settings with your email provider. The defaults for Encryption and Server Port are usually correct, though that is provider specific. Most email providers `Use IDLE`, but if things don't seem to be working you can check with your provider for this setting. + +There are 3 options for the `After Message is processed field`: + +- `Leave in INBOX` (default) - this is the safest option if you are using this email address for other things. It can lead to an ever-growing email list, so you'll need to delete messages yourself once you're sure you are done with them. +- `Delete Message` - if you are using a dedicated email address for Indigo, this is a good option since it will delete a message after it's been processed. This will keep the inbox from growing uncontrollably. +- `Move Message` - this is a compromise of the two options above: it keeps the INBOX clean, but it also keeps all emails if you want to manually manage them. + +The `Check All` button is really used for testing - it will process all emails regardless of whether they have been processed in the past or not. + +##### IMAP Mailbox Naming +When using the option to move processed messages to another mailbox, instead of deleting or leaving in the Inbox, you'll need to specify the name of the destination mailbox. Unfortunately, the naming scheme for IMAP mailboxes is server specific. + +There are two primary traits of the naming scheme that vary between servers. First, some servers require all mailboxes to be relative to the INBOX. Others do not. Second, the delimiter used in the mailbox path is not fixed. Most servers use either `/` or `.`. + +So, for a top level mailbox called "Processed", the most probable names to put in the destination folder field are: + +- Processed +- INBOX/Processed +- INBOX.Processed + +To provide some hints that might help determine the correct naming, if the plugin logging is set to "Detailed Debugging Messages" it will query the IMAP server for the list of names of the top-level mailboxes. The log will show something like this: + + Email+ Threaddebug Indigo IMAP: Mailbox list: + Email+ Threaddebug Indigo IMAP: Mailbox: (\Drafts \NoInferiors) "/" Drafts + Email+ Threaddebug Indigo IMAP: Mailbox: (\HasNoChildren) "/" INBOX + Email+ Threaddebug Indigo IMAP: Mailbox: (\NoInferiors) "/" OUTBOX + Email+ Threaddebug Indigo IMAP: Mailbox: (\HasNoChildren) "/" Processed + Email+ Threaddebug Indigo IMAP: Mailbox: (\Sent \NoInferiors) "/" Sent + Email+ Threaddebug Indigo IMAP: Mailbox: (\Junk \NoInferiors) "/" Spam + Email+ Threaddebug Indigo IMAP: Mailbox: (\Trash \HasNoChildren) "/" Trash + +The "/" specifies that the delimiter between name parts is "/". + + +#### POP Server +This is an alternative device type used for scanning incoming emails. It is an older protocol but may be the only option you have from your email provider. + +If you had a previous version of Indigo configured with email scanning, the upgrade process will create this server for you based on your prior settings. The name of that server will be `Email+ POP Server`. + +In Indigo, create a new device, in the `Type` popup select **Email+** and for `Model` select **POP Server** + +![POP Server Image](../images/pop_server.png) + +Again, if you want to use **POP** you'll need to confirm the settings with your email provider. + +### Incoming Email Events +There are a few events that can be used to fire triggers in Indigo. In the Trigger dialog, select Email Event: + +![Email Event List Image](../images/email_event_list.png) + +You can use these events to monitor incoming emails (and email errors). You can specify either an IMAP or a POP server as described above. + +![Email String Match Event Image](../images/email_string_match_event.png) + +- `String Match in Email` - this event will allow you to perform exact matches in the subject or body of an email, or the sender of the email. +- `RegEx Pattern Match in Email` - this will allow you to use [regular expressions](https://www.w3schools.com/python/python_regex.asp) to match some subset of text in the above 3 fields. +- `Server Connection Error` - this will fire a trigger when there is some kind of error in any of the 3 server types above. + +## Broadcast Messages +Other plugin developers can subscribe to messages from the Email+ plugin when emails are sent or received: + +```text +MessageType: messageReceived +Returns dictionary: +{ + 'messageFrom': , + 'messageTo': , + 'messageSubject': , + 'messageText': +} + +MessageType: messageSent +Returns dictionary: +{ + 'messageFrom': , + 'messageTo': , + 'messageSubject': , + 'messageText': +} +``` + +The plugin id for the plugin is `com.indigodomo.email` + +## Tips on IMAP Mailbox Naming +When using the IMAP device option to move processed messages to another mailbox, instead of deleting or leaving in the Inbox, you'll need to specify the name of the destination mailbox. Unfortunately, the naming scheme for IMAP mailboxes is server specific. + +There are two primary traits of the naming scheme that vary between servers. First, some servers require all mailboxes to be relative to the INBOX. Others do not. Second, the delimiter used in the mailbox path is not fixed. Most servers use either `/` or `.`. + +So, for a top level mailbox called "Processed", the most probable names to put in the destination folder field are: + +- Processed +- INBOX/Processed +- INBOX.Processed + +To provide some hints that might help determine the correct naming, if the plugin logging is set to "Detailed Debugging Messages" it will query the IMAP server for the list of names of the top-level mailboxes. The log will show something like this: + +```text +Email+ Threaddebug Indigo IMAP: Mailbox list: + Email+ Threaddebug Indigo IMAP: Mailbox: (\Drafts \NoInferiors) "/" Drafts + Email+ Threaddebug Indigo IMAP: Mailbox: (\HasNoChildren) "/" INBOX + Email+ Threaddebug Indigo IMAP: Mailbox: (\NoInferiors) "/" OUTBOX + Email+ Threaddebug Indigo IMAP: Mailbox: (\HasNoChildren) "/" Processed + Email+ Threaddebug Indigo IMAP: Mailbox: (\Sent \NoInferiors) "/" Sent + Email+ Threaddebug Indigo IMAP: Mailbox: (\Junk \NoInferiors) "/" Spam + Email+ Threaddebug Indigo IMAP: Mailbox: (\Trash \HasNoChildren) "/" Trash +``` + +The "/" specifies that the delimiter between name parts is "/". + +## Scripting Emails +You can send email messages from Python scripts in one of two ways. + +First, you can use the built-in sendEmailTo action defined in the [Indigo Object Model](https://www.indigodomo.com/docs/server_commands#send_email): + +`indigo.server.sendEmailTo("my.address@example.com", subject="Subject of email", body="Body of email")` + +This action will use the first SMTP Server device that is found as most users will only have one. + +However, if you have multiple SMTP devices and/or you want to add CC or BCC address, you want to send HTML emails, you want to add attachments, you can directly script the plugin. + +The following function can be called from within your scripts. +Be sure to put in the correct email address and the deviceID for an Email+ SMTP device. + +```python +def sendAlertEmail(subject, message): + plugin_id = "com.indigodomo.email" + plugin = indigo.server.getPlugin(plugin_id) + if plugin.isEnabled(): + plugin.executeAction( + "sendEmail", + deviceId=12345678, + props={ + 'emailTo':'foo@bar.com', + 'emailSubject': subject, + 'emailMessage': message + } + ) + return + +sendAlertEmail("Test Alert", "This is only a test") +``` + +There are additional optional properties you can include: + +```python +props = { + 'emailTo': 'address1, address2', + 'emailCC': 'address3, address4', + 'emailBCC': 'address5, address6', + 'emailSubject': 'Message Subject', + 'emailAttachments': 'file1, file2, file3', + 'emailFormat': 'plain', # (or 'html') + 'emailMessage': 'Message text' +} +plugin_id = "com.indigodomo.email" +plugin = indigo.server.getPlugin(plugin_id) +if plugin.isEnabled(): + plugin.executeAction( + "sendEmail", + deviceId=12345678, + props=props + ) +``` diff --git a/reference/canonical/plugins/globalpropertymanager.md b/reference/canonical/plugins/globalpropertymanager.md new file mode 100644 index 0000000..c94a7f6 --- /dev/null +++ b/reference/canonical/plugins/globalpropertymanager.md @@ -0,0 +1,78 @@ + + +# Global Property Manager +The Global Property Manager plugin gives users the ability to add custom properties to any Indigo object. + +This simple plugin allows anyone to add arbitrary properties to any device object. Properties are different than states +- they are somewhat hidden bits of information that can be used by Python scripts or other Plugins. For example, if you +have a script that needs to be able to connect a device to another Indigo object (like an Action Group), then in the +past you'd have to store it somewhere else like a file. With global properties, you can add extra properties to a +device that can be accessed by your script. + +## Plugin Config +The Global Property Manager plugin does not have any configuration settings. + +### Using the Plugin +![Global Property Manager Configuration Dialog Image](../images/global_property_manager_config_dialog.png) + +Before using the features of the Global Property Manager plugin, you must first enable it by going to the Indigo client +`Plugins` menu item, selecting the plugin, and then selecting `Enable`. Once the plugin is enabled, all the +plugin's features are accessed via the `Manage Global Object Properties...` plugin menu item. Once the dialog is +opened, you can manage your custom object properties. + +1. To add a property to an existing Indigo object, first select the type of object you want to edit. Use the +`Object Type` dropdown menu to select among devices, action groups, variables, triggers, schedules or control pages +(devices should be selected by default when the dialog is first opened). You can only add properties to objects that +already exist. + +2. Select the specific object you want to add a property to from the `Object` dropdown menu. + +3. At the bottom of the dialog are the controls to define your property, set its value, and add it to the selected +object. You must create at least a `key` name, but the value can be empty at the time the property is created. +Key names must be alphanumeric, with no punctuation, and must start with a letter. Key names must also be unique within +the object itself (you can add the same key name to other objects). + +You can use the controls in the center of the dialog to update or delete existing custom properties. You can change a +property name, update its value, or delete the property entirely. Editing or deleting a property only affects the +selected object. In other words, if you've added a property to multiple objects, you will need to edit each object +individually. Changes made using these controls are applied immediately and can not be undone. + +## Working With Custom Properties +Properties added using the Global Properties Manager plugin are added to an object's `sharedProps` dictionary. +Here is an example of how they appear when you print an object's details to the Indigo Events Log. + +```text +sharedProps : com.indigodomo.indigoserver : (dict) + tags : timer, kitchen, ventilation (string) +``` + +Working with these values in a Python script is very straightforward. + +```python +dev = indigo.devices[12345678] +props = dev.sharedProps +tags = props['tags'] +indigo.server.log(f"{tags}") +``` + +You can also modify `sharedProps` (add, update, delete) using the `replaceSharedPropsOnServer()` method. You +should always do this by first making a copy of the `sharedProps` dictionary to avoid making inadvertent changes to +other plugins' `sharedProps`. + +!!! warning + You should be very careful when using this approach as changes made this way can not be undone. + +```python +dev = indigo.devices[12345678] +props = dev.sharedProps +props['tags'] = props['tags'] + ", foobar" +dev.replaceSharedPropsOnServer(props) +``` + +## Scripting Support +Here's the plugin ID in case you need to programmatically restart the plugin: + +**Plugin ID**: com.indigodomo.indigoserver + +## Support and Troubleshooting +For usage or troubleshooting tips [discuss this plugin](https://forums.indigodomo.com/viewforum.php?f=406) on our forum. diff --git a/reference/canonical/plugins/noaaweather.md b/reference/canonical/plugins/noaaweather.md new file mode 100644 index 0000000..3c9800c --- /dev/null +++ b/reference/canonical/plugins/noaaweather.md @@ -0,0 +1,133 @@ + + +# NOAA Weather +This is the official weather plugin for Indigo. You may create as many "Weather Station" devices as you like. Each station will have a variety of device states that hold information that can be used in triggers, conditions, and on control pages. **NOTE**: some information may not be available for any given station - if the data isn't available in the NOAA data feed, the value of that particular state will be "- data unavailable -". + +[NOAA stations](http://www.weather.gov/xml/current_obs/) are primarily Airports in the US, and those tend to have the most data. There are other [NOAA stations](http://www.weather.gov/xml/current_obs/) as well but the data from them tends to be spotty at best. There is also [a map](https://madis-data.ncep.noaa.gov/MadisSurface/) you can use to locate other weather station locations. Why do we use NOAA data, which is **only available in the US**, rather than some other provider (like WeatherUnderground or WeatherBug)? Put simply, they either have severe restrictions on what commercial users can do with the data, or they require licensing fees. Neither of which we're currently prepared to deal with. NOAA data is completely free and unencumbered. You may have heard that Google has a weather API - which is sorta true. It's not a published API, and we're not big fans of using unpublished APIs (they tend to break with no warning). + +So, for now, NOAA is the best solution for our official weather plugin. The data quality is very good and is likely good enough for many of your purposes. You can also search the User Contribution Library for other [weather solutions.](http://www.indigodomo.com/library/index.php?keywords=weather) + +## Plugin Config +The plugin's config dialog has a setting to allow you to configure the display of temperature information in the Indigo UI to one of four settings: + +- Degrees F +- Degrees C +- Degrees F (Degrees C) +- Degrees C (Degrees F) + +The second setting in the dialog allows you to turn on extra debugging information in the Event Log. Unless you're trying to debug a problem it's probably best to leave that unchecked. + +### Creating a Weather Station Device +The NOAA Weather Plugin allows you to create Weather Station devices. To create a new one, switch to the device view and click the `New...` button. This will bring up the device edit dialog. Select `Plugin` from the `Type:` popup. Select `NOAA Weather` from the `Plugin:` popup, and select `Weather Station` from the `Model:` popup. Click on the `Edit Device Settings...` button, and you'll see the Weather Station Config UI. Enter the NOAA station id in the text box at the top. You can click on the "Find NOAA Stations" to have a browser window open to the NOAA webpage where you can start your search. + +Once you've found the station ID and entered it in the text field, click "Save". If we can successfully contact NOAA and get the station data, we'll close the dialog. If not we'll show you an error indicating that we couldn't get the station's data file. You should try another station if this happens or confirm that you entered the station id correctly. From time to time, the NOAA system may not be responding to API calls and, if you've entered the station ID correctly, you may need to wait and try again later. + +### Creating Weather Forecast, Current Conditions, and Weather Alerts Devices +There are three additional weather device types that can provide additional weather data -- Alerts, Conditions, and Forecast data. These devices are based on more precise location information -- your lat/long coordinates (or any valid coordinates you provide) -- rather than being linked to a weather station (which may not be nearby). The creation and configuration of these devices is very straightforward. + +The current conditions device is meant to mimic the original weather station device as closely as possible. Linking your logic to these new device types should work, but if you decide to transition to these new device types, you should confirm they are working the way you expect. + +### Weather Station and Current Conditions Device States +You can trigger off of various state changes on a Weather Station (or Current Conditions Device) - like when the temperature or wind direction change. Some of these states don't make for good triggers but will provide some nice information on a control page. + +![NOAA Trigger States Image](../images/noaatriggerstates.png) + +Weather Station device types provide you with several device states that you can use in the Trigger dialog: + +- `Current Condition` - The current condition in a word or two +- `Current Condition Icon` - The current condition icon - Indigo ships with "NOAA Condition+.png" and it's children, one for each condition that's returned in this field. So, in the control page editor, select this state and "NOAA Condition+.png" and you'll have a nice conditions icon (images provided by NOAA). +- `Dew Point °C` - Dew point in Celsius +- `Dew Point °F` - Dew point in Fahrenheit +- `Dew Point String` - Dew point in a human-readable string +- `Heat Index °C` - Heat index in Celsius +- `Heat Index °F` - Heat index in Fahrenheit +- `Heat Index String` - Heat index in a human-readable string +- `Humidity` - The relative humidity +- `Latitude` - Latitude +- `Location` - Location in human-readable form +- `Longitude` - Longitude +- `Observation Date/Time` - The last time NOAA updated the data. This field is in `YYYY-MM-DD HH:MM:SS` so it can be parsed by other software if needed. +- `Pressure (inches)` - Pressure in inches +- `Pressure (mbar)` - Pressure in millibars +- `Quality Codes` - For scripters to account for the relative quality of the various weather observations (JSON). [See below for what the codes mean.](#quality-codes) +- `Temperature °C` - Temperature in Celsius +- `Temperature °F` - Temperature in Fahrenheit +- `Temperature String` - Temperature in a human-readable string (i.e. "98.0 F (36.7 C)") - this is the state shown in the "State" column for a Weather Station device +- `Time Zone` - The timezone as it applies to the observed location. +- `Visibility` - Visibility in miles +- `Wind Degrees` - Wind direction in degrees +- `Wind Direction` - Wind direction description in something close to human-readable form +- `Wind Knots` - Wind speed in knots +- `Wind MPH` - Wind speed in miles per hour +- `Wind String` - A description of the wind in human-readable form + +### Weather Alert Device States +With Weather Alert Devices, the device's states will be blank unless there are active alerts. If there are active alerts, information on up to five alerts will be available. This information is provided for informational purposes only and should not be relied upon for the purposes of personal safety. + +### Weather Forecast Device States +There are several device states available with the Weather Forecast Device, each having an index value keyed to individual days. Up to 14 days' worth of information may be available. + + +## Quality Codes +The NOAA Weather plugin includes a `qualityCodes` state. This state includes information (from NOAA) on the perceived quality of select data elements. An example `qualityCodes` state value is: + + {"temperature": "V", "dewpoint": "V", "windDirection": "Z", "windSpeed": "Z", "windGust": "S", "barometricPressure": "V", "seaLevelPressure": "V", "visibility": "C", "precipitationLastHour": "C", "precipitationLast3Hours": "Z", "precipitationLast6Hours": "Z", "relativeHumidity": "V", "windChill": "V", "heatIndex": "V"} + +The various codes are as follows: + +| MADIS QC Information - Surface QC Data Descriptor Values | | +|----------------------------------------------------------------------------------------------|---------------------------------------------------| +| No QC available | | +| Z | Preliminary, no QC | +| Automated QC checks | | +| C | Coarse pass, passed level 1 | +| S | Screened, passed levels 1 and 2 | +| V | Verified, passed levels 1, 2, and 3 (BEST) | +| X | Rejected/erroneous, failed level 1 | +| Q | Questioned, passed level 1, failed 2 or 3, where: | +| Quality Levels | | +| level 1 = validity | | +| level 2 = internal consistency, temporal consistency, statistical spatial consistency checks | | +| level 3 = spatial consistency check | | + + +This information will give you some additional granularity with respect to how much you can trust the data. Accessing this data using a script is pretty straightforward. + + import json + + dev = indigo.devices[12345678] + codes = dev.states['qualityCodes'] + quality_codes = json.loads(codes) + temp_quality = quality_codes['temperature'] + + if temp_quality in ("X", "Q"): + indigo.server.log("don't trust") + else: + indigo.server.log("trust") + +## Weather Icons +### Weather Station and Current Condition Devices +You can link to the current condition icons in the "traditional" way. On a control page, select **Display Device State** and **Current Condition Icon**. Then select **As Image** and choose **NOAA Condition+.png**. This should work for both the Weather Station and Current Condition device types. + +#### Forecast Devices +For Forecast icons, the reference is a bit different. NOAA provides a detailed description of the icon like, `/icons/land/day/tsra,30?size=medium`. The way to display these images is to link to them directly via the NOAA API itself. Select Display Refreshing Image URL, set the icon size you want (medium is 86x86) and then in the URL field, enter a URL which is a combination of text and a device state substitution. The text part is `https://api.weather.gov` and then append the substitution string for the state you want like `%%d:123456789:icon_01%%`. So the full URL would be: + +`https://api.weather.gov%%d:123456789:icon_01%%` + +(replacing 123456789 with your device ID and then the icon you want like icon_01, icon_02, etc.) + +You can also construct refreshing image URLs for the current conditions icons, but the construction is a little different. The full URL for those would be something like, `https://api.weather.gov/icons/land/day/%%d:123456789:currentConditionIcon%%`. + +If you want to have both day and night versions, you'd need to create a variable value that is equal to `day` when Indigo's `isDaylight` variable is true and equal to `night` when `isDaylight` is false. Then add a variable substitution for that part of the URL, like: + +`https://api.weather.gov/icons/land/%%v:12345678%%/%%d:123456789:currentConditionIcon%%`. + +For all these URLs, there's no need to refresh the images more than once every half hour or so because the NOAA plugin weather devices don't update more frequently than that on their own. + +## Scripting Support +Here's the plugin ID in case you need to programmatically restart the plugin: + +**Plugin ID**: com.perceptiveautomation.indigoplugin.NOAAWeather + +## Support and Troubleshooting +For usage or troubleshooting tips [discuss this plugin](https://forums.indigodomo.com/viewforum.php?f=97) on our forum. diff --git a/reference/canonical/plugins/sql_logger.md b/reference/canonical/plugins/sql_logger.md new file mode 100644 index 0000000..91c75cf --- /dev/null +++ b/reference/canonical/plugins/sql_logger.md @@ -0,0 +1,149 @@ + + +# SQL Logger Plugin +The SQL Logger Plugin for Indigo automatically logs device state changes, variable value changes, and event log entries to either [PostgreSQL](http://www.postgresql.org/) or [SQLite](http://www.sqlite.org//). + +This allows Indigo to integrate with other applications or services, and allows for historical data recording. You can, for example, use PHP to dynamically generate graphs or charts of device states (like temperature) stored in a PostgreSQL database. + +By default, OS X 10.5 and higher includes the libraries needed to use SQLite, which makes using the SQLite option fast. + +Although more complicated, we have also put together basic instructions for using the more powerful PostgreSQL database server. + +## Configuring SQL Logger with SQLite +Choose the `Plugins->SQL Logger->Configure...` menu item, then select `SQLite` as the database type. + +By default, Indigo will create a SQLite database file inside the logs folder: + +`/Library/Application Support/Perceptive Automation/Indigo 6/Logs/indigo_history.sqlite` + +### Configuring SQL Logger with PostgreSQL +PostgreSQL is not included with the Mac OS X install (note it is included on more recent OS X Server installs), but it is free and there are some package installers available. Here are the basic steps for installing it: + +- Download a [PostgreSQL installer](https://www.postgresql.org/download/macosx/). Note there are other installers available elsewhere as well. +- Add the path to the PostgreSQL binary to your bash profile file. From the Terminal copy/paste: +`echo 'export PATH=$PATH:/Library/PostgreSQL/bin' >> ~/.bash_profile` + +- Next, open the System Preferences and choose the PostgreSQL Server icon that was added. You should now be able to start the server. Note that some installers seem to include a Server Manage.app application, but they may not work correctly. However, the panel in the System Preferences does appear to work. +- From the command line you can now try to connect to the server via: +`psql -U postgres` + +- Next, select the `Plugins->SQL Logger->Configure...` menu item, then select `PostgreSQL` as the database type. + +By default, Indigo will connect to the PostgreSQL server running on the same Mac (`127.0.0.1`) using the default PostgreSQL username of `postgres`, and will automatically create a new database named `indigo_history`. Your PostgreSQL install might also support local connections directly using the host name `/var/pgsql_socket/.s.PGSQL.5432`. + +### Logging Options +From the SQL Logging configuration dialog (`Plugins->SQL Logger->Configure...` menu item), you can choose which information the plugin should store in the database and specify if older data should automatically be pruned: + +![Plugin SQL Logger Configuration Image](../images/plugin_sqllogger_config1.png) + +Automatically pruning data from the tables will help keep the database size more manageable, but you can turn the option off if you want to manually clean up the database. + +Auto deleting unused tables will have the plugin remove any tables for devices or variables that are not defined in the current Indigo database. However, note that this means that if you switch Indigo database files then the device and variable history stored for the previous database will automatically be deleted from the SQLite/PostgreSQL databases. So turn these options off if you use multiple Indigo databases. + +### Database Table Format +Indigo creates a unique table for every device and variable to track its state/value history. Example database table names include: + +`device_history_9734822, device_history_12452348, device_history_8734522` +and +`variable_history_9872345, variable_history_3411246` + +To find the specific device or variable IDs used in the table name, right-click on the device (or variable) inside Indigo and choose the `Copy ID` menu item. Note the SQL Logger also writes to the Event Log any time it creates a new table and shows what table name was created for a specific device or variable. + +Columns are automatically created for the tables for every state used by that particular device. For example, here is the device history table for a dimmer switch, `device_history_9734822`: + +| ts | brightnesslevel | onoffstate | +|---------------------|-----------------|------------| +| 2012-05-16 16:00:32 | 0 | f | +| 2012-05-16 16:01:44 | 74 | t | +| 2012-05-16 16:01:44 | 29 | t | +| 2012-05-16 16:44:46 | 0 | f | +| 2012-05-16 16:45:03 | 29 | t | +| 2012-05-16 16:45:35 | 0 | f | +| 2012-05-16 18:20:09 | 28 | t | +| 2012-05-16 19:01:57 | 29 | t | +| 2012-05-16 19:15:12 | 38 | t | +| 2012-05-16 19:15:13 | 48 | t | + + +And here is the table created for a temperature humidity sensor, `device_history_12452348`: + +| ts | temperature | humidity | +|---------------------|-------------|----------| +| 2012-05-16 16:00:32 | 73 | 85 | +| 2012-05-16 16:01:44 | 74 | 85 | +| 2012-05-16 16:01:44 | 73 | 85 | +| 2012-05-16 16:44:46 | 72 | 86 | +| 2012-05-16 16:45:03 | 71 | 87 | +| 2012-05-16 16:45:35 | 68 | 87 | +| 2012-05-16 18:20:09 | 65 | 88 | +| 2012-05-16 19:01:57 | 67 | 87 | +| 2012-05-16 19:15:12 | 68 | 86 | +| 2012-05-16 19:15:13 | 69 | 86 | + + +Using SQL you can query the table for all the defined columns. + +Variable tables are similarly created -- one table per variable. However, they always have the same columns: `ts` and `value`. Here is an example table tracking a variable for alarmMode: + +| ts | value | +|---------------------|----------| +| 2012-05-16 16:00:32 | Idle | +| 2012-05-16 16:01:44 | Arm Home | +| 2012-05-16 16:01:44 | Idle | +| 2012-05-16 16:44:46 | Arm Away | + + +Lastly, a single table is created to track all event log entries, `eventlog_history`. + +### Example Queries +Below are some example SQLite and PostgreSQL queries. Note that the table names below are examples, and must be modified to match your unique table names. + +#### PostgreSQL Queries +PostgreSQL query to retrieve all event log history: +`psql indigo_history postgres -c "SELECT * FROM eventlog_history;"` +PostgreSQL query to retrieve all device history for a specific device: +`psql indigo_history postgres -c "SELECT * FROM device_history_692773228;"` +PostgreSQL query to retrieve the timestamp, rain rate and rain total from an Oregon Scientific rain sensor: +`psql indigo_history postgres -c "SELECT ts, rainrate, raintotal, currentdaytotal FROM device_history_849210623;"` + +#### SQLite Queries +For SQLite queries, first change to the directory in which the database file resides: +`cd /Library/Application\ Support/Perceptive\ Automation/Indigo\ 6/Logs/` + +SQLite query to retrieve all event log history: +`sqlite3 -header -column indigo_history.sqlite "SELECT * FROM eventlog_history;"` +SQLite query to retrieve all device history for a specific device: +`sqlite3 -header -column indigo_history.sqlite "SELECT * FROM device_history_692773228;"` +SQLite query to retrieve the timestamp, temperature, and humidity from an Oregon Scientific sensor: +`sqlite3 -header -column indigo_history.sqlite "SELECT datetime(ts,'localtime'), temperature, humidity FROM device_history_167703743;"` + +Note that when selecting the timestamp from a SQLite table you must use the notation `datetime(ts,'localtime')` so that the internally stored GMT time is translated to your local time. + +## Events +![SQL Logger Event Image](../images/plugin_sqllogger_event.png) + +The SQL Logger provides a useful event (even if it's not logging anything): `Error in Event Log`. This event will fire whenever an error (generated by the Indigo Server, by plugins, or both) appears in the event log. You can perform any actions (like sending an email, etc.). + +`Indigo Internal Errors` are errors generated by the IndigoServer directly - so errors from Insteon and X10 devices, errors with the built-in actions/events (sending emails), etc. These do not include errors that plugins generate or errors that are inserted from scripts. + +To use the `Specific Type` event type, you'll need to use the error type that's shown in the event log window. The error type is the beginning part of an event log line. Each event log entry has a beginning part, then a series of spaces, then the message. The beginning part is the event type. Error event types will always end in the word "Error". Here are some examples: + +```text +Aug 9, 2012 3:38:10 AM + My Type Error this is an error from a script + NOAA Weather Plus Error Error parsing XML from NOAA for device Weather Forecast: not well-formed (invalid token): line 1, column 111 +``` + +In the configuration dialog for `Error in Event Log`, when you select `Specific Type` from the `Errors to monitor for:` popup, a text field with the label `Event Type` will show. You'll enter the text shown above - so for instance if you want to monitor for the first error, you'd enter "My Type Error" in the text field (notice no spaces/tabs before or after). Then, every time an error of that type is detected by the SQL Logger plugin, it will fire that trigger. + +This is primarily useful for plugin errors although if you have scripts that generate errors it could be used for those as well. For plugins (unless the developer decides otherwise), errors will be generated using the plugin's name with " Error" appended. + +You can enter text in the String to Match field and the action will attempt to match it against the text in the log message. For instance, entering *Office Lamp* in the field will cause the event to fire only if "Office Lamp" is in the field (case-sensitive). You can also specify a regular expression for more advanced text matching. + +## Scripting Support +Here's the plugin ID in case you need to programmatically restart the plugin: + +**Plugin ID**: com.perceptiveautomation.indigoplugin.sql-logger + +## Support and Troubleshooting +For usage or troubleshooting tips [discuss this plugin](https://forums.indigodomo.com/viewforum.php?f=98) on our forum. diff --git a/reference/canonical/plugins/timersandpesters.md b/reference/canonical/plugins/timersandpesters.md new file mode 100644 index 0000000..836788e --- /dev/null +++ b/reference/canonical/plugins/timersandpesters.md @@ -0,0 +1,192 @@ + + +# Timers and Pesters +As the name implies, this plugin implements a very simple timer device object that works almost exactly like a manual kitchen timer (if the kitchen timer had the ability to pause and resume). Pesters are little mini schedules that can cycle for some fixed number of times. They are lightweight versions of Indigo [Schedules](../user/concepts/schedules.md#schedules). + +**Note**: make sure that the plugin is enabled or the options below will not be available. + +## Timers +Timers are very simple to use - they're pretty much like kitchen timers. The notable difference is that timers in Indigo are created with their start/run time as part of the timer device. This means when you start one it will use the time specified in the timer itself (this can be changed later - see the actions below). So, first, create a timer device. + +## Create a Timer +![Plugin Timers New Timer Image](../images/plugin_timers_new_timer.png) + +A timer is like any other device in Indigo - it shows up in the device list, it has states, etc. + +1. Select `DEVICES` (or one of its subfolders) from the [Outline View](../user/mac-client/home-window.md#outline-view) +1. Click on the `New...` button +1. In the resulting `Create New Device` dialog, select `Timers and Pesters` from the `Type:` popup +1. Select `Timer` from the `Model:` menu +1. In the resulting `Configure Timer` dialog, specify the amount of time the timer will default to when started and the time increments +1. Click `Save` +1. Name the timer something useful and close the `Create New Device` dialog + +The timer device you created has 6 device states: + +- `Timer Start Value` - the default value of the timer when the `Start Timer` action is selected. It's set when you create a timer device and may be modified either via the device dialog or by using the `Set Timer Start Value` action. +- `Timer Status String` - a human-readable string representing the state of the timer. This is what's shown in the "State" column in the device table and can be displayed in a control page. The format is this: "Active with D:HH:MM:SS left", "Paused with D:HH:MM:SS left", "Inactive". +- `Timer Status` - the status of a timer in a way that's useful for image selection, scripts, etc. Values are one of: "inactive", "active", "paused". +- `Time Left in Seconds` - the amount of time remaining in seconds for the timer. Inactive timers will have a value of 0. +- `Time Left in Minutes` - the amount of time remaining in minutes for the timer. Inactive timers will have a value of 0. +- `Time Left in Hours` - the amount of time remaining in hours for the timer. Inactive timers will have a value of 0. +- `Time Left in Days` - the amount of time remaining in days for the timer. Inactive timers will have a value of 0. + +## Use a Timer +There are two things you need to do to use a timer: control the timer (start, stop, pause, etc.) and trigger when a timer expires (when it runs out of time naturally as opposed to being stopped intentionally). + +### Timer Actions +![Plugin Timers Actions Image](../images/plugin_timers_actions.png) + +To operate/control the timer, you use the following actions (also available interactively from the plugin's submenu): + +- `Start Timer` - use this action to start a timer. The timer device will automatically start counting down and the state will change. When the countdown completes, the status will be set to "inactive" and any triggers that are triggering off of the `Timer Expired` event for this timer will be fired. The action will only start the timer when it's inactive and will be ignored when in any other state. +- `Restart Timer` - use this action to restart a timer using the default time set for the timer. The action will always work regardless of the timer's current state. +- `Pause Timer` - as the name implies, this action will pause the selected timer. The amount of time will not be modified so that you can resume the timer at will. The action will only pause an active timer and will be ignored when the timer is in any other state. +- `Resume Timer` - use this action resume a previously paused timer. The action will only resume a paused timer and will be ignored when the timer is in any other state. +- `Stop Timer` - use this action to stop a timer prematurely. The state becomes "Inactive" and all the time left states will be set to 0. It will **not** cause any `Timer Expired` triggers to fire. The action will be ignored if the timer is already inactive. +- `Set Timer Start Value` - use this action to set the default timer value without actually starting the timer. If the timer is running when it has its start value changed, it will stop running. + +### Timer Event +![Plugin Timers Events Image](../images/plugin_timers_events.png) + +There is also one custom event that you can use in a Trigger: `Timer Expired`. This allows you to easily know when a timer runs out of time versus when it's explicitly stopped (by the `Stop Timer` action described above). This is synonymous to when a kitchen timer starts beeping/ringing: if it runs out of time it rings but if you expressly turn it off then it doesn't. + +To create a timer expired trigger: + +1. Select `TRIGGERS` (or one of its subfolders) from the [Outline View](../user/mac-client/home-window.md#outline-view) +1. Click on the `New...` button +1. In the resulting `Create New Trigger` dialog, select `Timers and Pesters Event` from the `Type:` popup +1. Select `Timer Expired` from the `Event:` menu +1. In the resulting `Configure Timer Expired` dialog, specify the timer to watch +1. Click `Save` +1. Add any [Conditions](../user/concepts/conditions.md#conditions) you need +1. Add all the [Actions](../user/concepts/actions.md#actions) you want to perform when the timer expires +1. Name the trigger something useful and close the `Create New Trigger` dialog + +## Timer Uses +So, what else would you do with the timer aside from triggering off of its expiration? You can display the various states on a control page and use those states in triggers and conditions as well. You could also show the countdown on a control page if that information is useful. You could even have an audio countdown by speaking the time left on the timer. + +## Pesters +![Plugins Timers and Pesters Actions Image](../images/plugin_timers_pester_actions.png) + +Another very useful feature of this plugin is the "Create Pester" action. This action will create a little mini timer which will repeat a specified number of times, executing an action group each time through and will execute an optional action group at the end of its final occurrence. So - say you want to have your computer announce that it's time to take out the trash. However, if you're like me, once is never enough - I need to be nagged about it several times. Create a pester that repeats every 30 seconds for 5 times (so it doesn't go forever) that executes an action group that tells you to take out the trash. The final time can send an SMS to your phone. + +Pesters can be thought of as transient schedules - they only live for a limited amount of time. You give a pester a name so that you can later cancel it, or you can cancel all pesters. + +## Scripting Support +As with all plugins, actions defined by this plugin may be executed by [Python scripts](../scripting/tutorial.md#scripting-indigo-plugins). Here's the information you need to script the actions in this plugin. + +**Plugin ID**: com.perceptiveautomation.indigoplugin.SimpleTimer + +## Action specific properties +### Start Timer +**Action id**: startTimer + +No properties for scripting required. + +Example: + +```python +t_id = "com.perceptiveautomation.indigoplugin.timersandpesters" + +# Get a plugin object given the plugin id: +timerPlugin = indigo.server.getPlugin(t_id) +if timerPlugin.isEnabled(): + timerPlugin.executeAction("startTimer", deviceId=1604521627) +``` + + +#### Pause Timer +**Action id**: pauseTimer + +No properties for scripting required. + +Example: + +```python +t_id = "com.perceptiveautomation.indigoplugin.timersandpesters" + +# Get a plugin object given the plugin id: +timerPlugin = indigo.server.getPlugin(t_id) +if timerPlugin.isEnabled(): + timerPlugin.executeAction("pauseTimer", deviceId=1604521627) +``` + +#### Restart Timer +**Action id**: restartTimer + +No properties for scripting required. + +Example: + +```python +t_id = "com.perceptiveautomation.indigoplugin.timersandpesters" + +# Get a plugin object given the plugin id: +timerPlugin = indigo.server.getPlugin(t_id) +if timerPlugin.isEnabled(): + timerPlugin.executeAction("restartTimer", deviceId=1604521627) +``` + +#### Resume Timer +**Action id**: resumeTimer + +No properties for scripting required. + +Example: + +```python +t_id = "com.perceptiveautomation.indigoplugin.timersandpesters" + +# Get a plugin object given the plugin id: +timerPlugin = indigo.server.getPlugin(t_id) +if timerPlugin.isEnabled(): + timerPlugin.executeAction("resumeTimer", deviceId=1604521627) +``` + +#### Stop Timer +**Action id**: stopTimer + +No properties for scripting required. + +Example: + +```python +t_id = "com.perceptiveautomation.indigoplugin.timersandpesters" + +# Get a plugin object given the plugin id: +timerPlugin = indigo.server.getPlugin(t_id) +if timerPlugin.isEnabled(): + timerPlugin.executeAction("stopTimer", deviceId=1604521627) +``` + +#### Set Timer Start Value +**Action id**: setTimerStartValue + +Properties for scripting: + +| *`timer`* | the ID of the timer device | +|----------------|----------------------------------------------------------------------------------------------------------------------| +| *`amount`* | a positive integer representing the initial countdown amount | +| *`amountType`* | one of the following that represents the units of measure of the amount field: "seconds", "minutes", "hours", "days" | + + +Example: + +```python +t_id = "com.perceptiveautomation.indigoplugin.timersandpesters" + +# Get a plugin object given the plugin id: +timerPlugin = indigo.server.getPlugin(t_id) +if timerPlugin.isEnabled(): + timerPlugin.executeAction( + "setTimerStartValue", + deviceId=1604521627, + props={ + 'amount':'30', + 'amountType':'minutes'} + ) +``` + +## Support and Troubleshooting +For usage or troubleshooting tips [discuss this plugin](https://forums.indigodomo.com/viewforum.php?f=99) on our forum. diff --git a/reference/canonical/user.md b/reference/canonical/user.md new file mode 100644 index 0000000..7edd1c8 --- /dev/null +++ b/reference/canonical/user.md @@ -0,0 +1,31 @@ + + +# Indigo User Guide + +Welcome to the Indigo {{ version }} User Guide — everything you need to set up, use, and maintain Indigo, no programming required. + +## New to Indigo? + +Start with the [Getting Started guide](getting-started/index.md), which walks you through installing Indigo, connecting your hardware interface, adding your first devices, and creating your first automations. Then read the [Concept Overview](concepts/index.md) to understand Indigo's building blocks — devices, triggers, schedules, action groups, variables, and control pages — and take the [tour of the Mac client](mac-client/index.md). + +## Setting up your hardware + +Indigo supports several hardware interfaces, which can be active simultaneously. Read the guide for the technology you use: [Z-Wave®](interfaces/z-wave/index.md), [Insteon](interfaces/insteon/index.md), or [X10](interfaces/x10/index.md). The [Virtual Devices Interface](interfaces/virtual-devices.md) helps you integrate devices from different technologies — and 3rd party plugins — together. + +## Accessing Indigo remotely + +The [Indigo Web Server](remote-access/web-server.md) and [Indigo Touch for Web](remote-access/touch-for-web.md) put your home in your browser; [Indigo Touch for iOS](https://www.indigodomo.com/touch.html) puts it on your iPhone, iPad, and Apple Watch; and the [Indigo Reflector](remote-access/reflector.md) makes them reachable from anywhere without router configuration. + +## Going further + +The Advanced Automation section covers techniques that make automations dynamic: [substitutions](automation/substitutions.md), [event data passing](automation/event-data.md), [fetching URLs from actions](automation/get-contents-of-url.md), and [Apple Shortcuts integration](automation/apple-shortcuts.md). + +Indigo also ships with a collection of [bundled plugins](../plugins/index.md) — Alexa voice control, email, weather, timers, and more. + +## Maintaining your system + +When the time comes: [upgrading Indigo](maintenance/upgrading.md), [moving to another Mac](maintenance/moving.md), [transferring a license](maintenance/license-transfer.md), or [uninstalling](maintenance/uninstalling.md). + +## Beyond the User Guide + +Want to script Indigo with Python, build a plugin, or integrate an external system? See the [Scripting](../scripting/index.md), [Plugin Development](../plugin-dev/index.md), and [Integration APIs](../api/index.md) sections. diff --git a/reference/canonical/user/automation/apple-shortcuts.md b/reference/canonical/user/automation/apple-shortcuts.md new file mode 100644 index 0000000..f14b8e0 --- /dev/null +++ b/reference/canonical/user/automation/apple-shortcuts.md @@ -0,0 +1,335 @@ + + +# Using Apple Shortcuts with Indigo + +!!! abstract "In this guide" + How to use Apple Shortcuts with Indigo's HTTP API to control devices, run action groups, and query status from iOS, iPadOS, and macOS. Covers API key setup, building GET and POST shortcut actions, using the Indigo Reflector for remote access, and a known compatibility issue with macOS Sonoma 14.7.5. + +Apple's Shortcuts application allows you to create custom workflows on macOS, iOS and iPadOS (you can't currently run shortcuts on tvOS). You can also use Apple Shortcuts with Indigo to call many functions and use Indigo events to fire Apple shortcuts. Using Indigo's [HTTP API](../../api/http.md) with Apple's Shortcuts app is easy and there are different methods to accomplish this (this document uses Indigo's v2 API). + +!!! warning + Unfortunately, it looks like [Apple broke the shortcuts command line tool](https://discussions.apple.com/thread/256038658?sortBy=rank) (which we use to run shortcuts) in Sonoma 14.7.5. If you rely on shortcuts in Indigo you'll probably want to skip that release. We tested on Sequoia 15.3.1 and it works correctly. + +If you'd like to ask questions or share your Shortcuts success stories with others, use the [Apple Shortcuts Forum](https://forums.indigodomo.com/viewforum.php?f=298) + +* The shortcuts app for macOS is only available for Monterey (12.x) and newer versions. It has been available for iOS and iPadOS since version 12. + +## Obtaining an API Key +In order to use authorization keys as used in the following examples, you'll need an active Indigo Up-To-Date subscription and an activated reflector. + +1. Log into [your Indigo account](https://www.indigodomo.com/account/authorizations)'s Authorizations Page. +1. Go to `Add an API Key`. +1. Select the Server that you want to use to accept the key. +1. Click on the `Add API Key` button. + +!!! important + in order to use API Key authentication, you MUST have enabled *`Enable OAuth and API Key authentication`* in the Indigo ["Start Local Server"](../getting-started/installation.md#starting-indigo-server) dialog box. + +## Building Your First Shortcut +Building your shortcut in the Shortcuts app is largely the same whether you do it on macOS or iOS, and -- depending on the type of activity you want to initiate -- only takes a couple of steps. The information you'll need depends on what you want to do, but all the API events are constructed in the same way. For this example, we'll use the macOS Shortcuts App to build our shortcut (you can also do it on iOS and iPadOS). At first, this looks like a lot of steps, but there's actually only a few pieces of information required. **All values below are entered without quotes.** For our first example, we'll perform a simple Indigo Device Toggle. + +You'll need: + +- The base URL: `https://MY-REFLECTOR-NAME.indigodomo.net/v2/api/command/` (replace `MY-REFLECTOR-NAME` with the name of your active reflector), +- Your authentication key: `c2xr7q35-9385-10f9-3652-12z765j99vnv` (replace with your valid key. This one is fake.), +- The command you want to execute -- such as: `indigo.device.toggle`, +- The Indigo ID of the device (or action, or variable, etc.) you want the command to apply to: `123456`, and +- Any parameters you want to include (some are optional, some are required.) + +### The Steps + +1. New shortcut (`+` at the top) +1. In the search box on the right side, type "Get Contents of URL". +1. Drag (or double-click) the action to add it to the editor. +1. Click on the `URL` field and enter the base URL above. If using an external IP address or reflector make sure to use `https:` and not just `http:`. +1. Click on "Show More". +1. Select Method: `Post`. +1. Expand the Headers section by clicking on the `>`. +1. Within the Headers section, click the `+`. +1. Under Key: `Authorization`. +1. Under Value: `Bearer 2x7a35-9385-10f9-3652-12765:99vnv`. (The word `Bearer`, one space and then your API key.) +1. Make sure that `Request Body` is set to `JSON`. +1. Within the Request Body section, click the `+`. +1. Under Key: `message` (make sure the `Type` is set to `Text`). +1. Under Value: `indigo.device.toggle`. +1. Within the Request Body section, click the `+`. +1. Under Key: `objectId`. +1. Under Value: `123456` (your device ID, make sure the `Type` is set to `Number`.) + +At the top of the Shortcut editor window, you can change "Get Contents of URL" to something descriptive like "Toggle Living Room Lamp". Likewise, you can click on the icon to customize it to your taste. Finally, if you'd like, you can add the Shortcut to your dock (or home screen on iOS), a shortcuts widget, or simply fire them from within the Shortcuts app. + +![Shortcuts Get Contents of URL Image](../../images/screenshot_2023-02-24_at_12.31.40_pm.png) + +Once you've built and tested your first Shortcut, it's easy to duplicate and edit additional shortcuts. All HTTP API commands should work in a similar way. + +### Optional Parameters +In order to add parameters to the command (for those calls that take parameters -- not all commands do), you include those as a dictionary attached to the command payload like this: + +!!! note + "optional" here refers to our toggle device example. For other API commands, parameters may be required. + +![Shortcuts Get Contents of URL Optional Parameters Image](../../images/screenshot_2023-02-08_at_4.17.30_pm.png) + +Of course, you can add additional Shortcuts Apps and Actions to the workflow as needed. + +## Action Group Shortcuts +There is currently only one API command for Action Groups -- `indigo.actionGroup.execute` -- which requires two payload elements: + +- The command: `indigo.actionGroup.execute` (Text) +- The Action ID: 123456 (Number) + +![Action Groups Shortcuts Image](../../images/screenshot_2023-02-08_at_10.36.32_pm.png) + +## Variable Shortcuts +### Get a Variable Value +This example shows how to obtain a variable's value and do something with it -- in this case, speak the value aloud. The action you take in your shortcut could be any number of things. + +![Get a Variable Value Image](../../images/screenshot_2023-02-22_at_5.18.39_pm.png) + +- You can get an individual variable object by referencing its Indigo ID directly `%%https://MY-REFLECTOR-NAME.indigodomo.net/v2/api/indigo.variables/MY-VAR-ID%%` where you replace `MY-REFLECTOR-NAME` with your active reflector name and `MY-VAR-ID` with your variable's ID. + +- The "trick" to getting the variable's value into the `speak` action is to tell your shortcut what kind of data it is. To do this, click on `Get Contents of URL` **in the speak action**, set the data type to `Dictionary`, and set `Get Value for Key` to `value` (be sure to hit return or tab to get the setting `value` to stick.) + +![Get Contents of URL Image](../../images/screenshot_2023-02-22_at_5.19.04_pm.png) + +### Update a Variable Value +There is currently only one API command for Variables -- `indigo.variable.updateValue` -- which requires three payload elements: + +- The command: `indigo.variable.updateValue` (Text) +- The Action ID: 123456 (Number) +- A parameters dictionary that has one key/value pair (required): + - `key`: value, + - the new variable value which must be set to Text because all Indigo variable values are stored as text. + +![Update Variable Value JSON Image](../../images/screenshot_2023-02-13_at_6.55.07_am.png) + +### Variable Value as a Conditional +You can include conditions in your shortcuts and take action -- or not -- based on the condition. For example, turn on a light -- but only if it's dark outside. + +![Variable Value as a Conditional Image](../../images/screenshot_2023-02-22_at_5.44.27_pm.png) + +- As with the other examples, set up your `Get Contents of URL` action to get a variable's value -- in this example, the built-in variable `isDaylight`, +- Take the returned dictionary and extract the value of the `isDaylight` variable in a `Text` action, +- Add an `If` condition and, if the Text value is equal to `false` (Indigo variable values are always strings/text) then run your next shortcut action. Alternatively, you could send another command directly to the Indigo server (which is essentially what your linked shortcut is doing). +- If the Text value is not `false`, the `Otherwise` action will be executed. + +## Running an External Python Script +In most instances, it's recommended that you use Indigo's built in script actions, such as: [Execute Script](../concepts/actions.md#script-and-file-actions), [Run Shell Script](../concepts/actions.md#script-and-file-actions), and [Run Apple Shortcut](../concepts/actions.md#run-apple-shortcut). In some instances, however, you might want to use a shortcut to run a script outside the Indigo environment. Luckily, this is easy using Apple's Shortcuts ***Run Shell Script*** action. + +The example below prompts the user for text, passes the text to the script, receives the script's output, and sends that output to a macOS notification. This very basic example is simply to show how to pass input to your script and pass the script's output on to other steps. Note the use of *`sys.argv[1]`*. This statement is reading the second argument passed to the script (the first argument is its source--the shortcut itself--which we won't need). The second argument -- *`sys.argv[1]`* -- is passed as a string, and that's the bit we need. You'll need to account for whatever format your inputs and outputs turn out to be. These are the two most important settings to this example: + +1. Shell: *`Python 3`* +1. Pass Input: *`as arguments`* + +![Apple Shortcut Run Shell Script Image](../../images/apple_shortcut_run_shell_script.png) + +The rest is up to you. + +!!! note + The Run Shell Script action is not supported on iOS or tvOS. + +## Using Your Shortcuts +How you use your shortcuts is a matter of taste -- and you can always run them from the shortcuts app -- but here are a few other suggestions to get you started: + +- Save shortcuts to your Home Screen in iOS (using the Share menu), +- Using a Shortcuts Widget, +- Create a folder of your shortcuts on iOS to mimic a widget, +- Add shortcuts to the Dock in macOS (File menu), +- Using Siri: "Hey Siri -- Living Room Lamp" (name of the shortcut). + +### Location Based Shortcuts +You can run location-based shortcuts too, but they require "additional" steps and at least part of the automation must be built on an iPhone or iPad. There are several options to choose from, including: + +- Time of Day, +- Alarm, +- Sleep, +- Arrive, +- Leave, +- Before I Commute, and +- and many others. + +Location-based shortcuts are not currently available in macOS (so you'll need to set up the location control piece on iPhone or iPad). The `Leave` and `Arrive` shortcuts **cannot** be run automatically. They require confirmation each time they are run. There is currently no way to turn this requirement off. + +!!! tip + Using the Indigo Reflector service is recommended (the URL you use for a location-based shortcut can't be one that only works on your local network.) + +1. Review your automation. + +1. Create the shortcut using the steps outlined above using macOS or iOS. For example, you could update a variable value set to `Home` or `Away`. +1. In the Shortcuts app for iOS (or iPadOS), select `Automations` from the tab at the bottom. +1. Click the `+` at the top. +1. Choose "Create Personal Automation". +1. Choose `Arrive` or `Leave`. +1. On the Location setting, select `Choose`. +1. Select "Current Location" or whatever location you choose, then select `Done`. You can also adjust the range of the trigger in the bottom map panel (the minimum range is about 100 meters or 328 feet). +1. Select `Next`. +1. Search for and select "Run Shortcut". +1. Next to "Run", tap the word `Shortcut` and select the shortcut you created in step 1. Add any next actions as needed (not covered in this example). +1. Select `Done` + +Now, your iPhone (or iPad) should run your shortcut when you Arrive/Leave that location. + +If you don't like the requirement to confirm the shortcut each time, there are other apps that allow for URL calls to be fired based on location. + +## Firing Shortcuts From Indigo +Using shortcuts to make Indigo *do something* is an awesome feature. But you can also use Indigo to run your shortcuts as well. + +### Run from Indigo Action +The easiest way to run a shortcut is via an Indigo Action. Create a new Action and select `*Server Actions*` > `*Run Apple Script*`. You can optionally add text as input to the shortcut if you wish; otherwise, leave the Shortcut Input field blank. + +![Run Shortcut Action Image](../../images/run_shortcut_action_2023_1.png) + +### Run from the Command Line +When calling a shortcut from the "Run Shell Script" action, it's best to use the full path to the target: `%%/usr/bin/shortcuts%%` to make sure Indigo can find it. + +![Firing Shortcuts From Indigo Image](../../images/screenshot_2023-02-16_at_12.44.05_pm-2.png) + +This specific approach requires the shortcut to be accessible by the Indigo server machine. If you don't have access to your shortcuts on the server, there are other ways to do this such as using Indigo to send a text message and linking the shortcut to Messages. Note that the Run Shell Script action doesn't support pipes, so if you want to send data to the shortcut, read on. + +### Run Shell Script Action +Sometimes, you may want to pass information to your shortcut from Indigo. For example, you can have Indigo fire a Notification on the server machine that includes real-time information. In this example, Indigo is asking the shortcut to run, and then the shortcut requests the pertinent data through the HTTP API. + +1. Run the shortcut using a Run Shell Script Action. +1. Configure the shortcut to request the text value from Indigo using the appropriate API method outlined above. + +![Run Shell Script Action Image](../../images/screenshot_2023-02-16_at_10.58.59_am.png) + +### Run Python Script Action +If you'd like to avoid the round trip of the example above, you can pass data directly to a shortcut using a simple Python script. In this example, we'll use Indigo's built-in Run Embedded Script action (the script should take less than 10 seconds to complete; otherwise, use a linked script to avoid the time limitation). The following example is the bare minimum required to use this approach. + +#### os.system() +```python +import os + +val = indigo.variables[123456].value # The value to pass. In this case, a variable value. +os.system(f'/usr/bin/shortcuts run "Post Event to Calendar" <<< \"{val}\"') # Will return 0 on success; 256 on error. +``` +Note the escaped double-quotes for the shortcut payload. These are important to ensure that payloads with embedded spaces are sent as an encapsulated string object. For more information on the *`os.system()`* Python command, take a look at the [official docs](https://docs.python.org/3/library/os.html#os.system). + +**Apple Shortcut** + +- Get Text From - Shortcut Input +- Calendar - Add New Event + +![Post Event to Calendar Image](../../images/screenshot_2023-03-13_at_6.56.59_pm.png) + +#### subprocess.run() +When using the *`os.system()`* command, the function returns a 16-bit value (*`0`* on success / *`256`* on error) to let you know if the command was successful. If you'd like to get a value back to Indigo after running the shortcut, one way is to use the more robust *`subprocess.run()`* function. This function supports a **bytes object** return for more elaborate scripting capabilities. Here is an example of a call using the *`subprocess.run()`* function: + +```python +import subprocess +result = subprocess.run(['/usr/bin/shortcuts', 'run', 'My Shortcut'], input=b"Input Text", check=True, capture_output=True).stdout # 'result' is a bytes object. +``` +Notice that the input is also a bytes object and will need to be decoded to use it. With this command, the shortcut will receive *`b"Input Text"`* as input, and anything returned by the shortcut will be stored in the *`result`* variable. If the call is unsuccessful, subprocess will throw the relevant error trace. + +This type of call would be useful for things like getting a list of upcoming appointments or reminders. For example, you could send the number of appointments you want in the *`subprocess`* call and get the appointment details back in the result. + +### External Shell Scripts +You can also accomplish the same result using a shell script. + +1. Create your Notification shortcut named "Test Alert": +1. Create a new shortcut and add the "Show Notification" action. +1. For `Attachment`, select "Shortcut Input". +1. Double-click "Shortcut Input" and select Type: `Text` + +It should look something like this: + +![External Shell Scripts Image](../../images/screenshot_2023-02-16_at_10.40.56_am.png) + +Using a plain text editor, create a new file called `script1.sh` (or whatever), enter the following text, and save it. + +```bash +#!/bin/bash + +# Note that redirects such as `pipe` aren't supported in the Indigo Run Shell +# Script dialog and will require a script file method. + +echo "$1" | /usr/bin/shortcuts run "Test Alert" +``` + +We need to make our script executable, so in Terminal, head to the folder where your script is saved and type: +`chmod +x script1.sh` and hit return. Now we can run our shell script from Indigo. + +1. Under Actions, create a new Action (or add a new Action to an existing Action Group). +1. Select Type: `Run Shell Script`. +1. Select `Edit Action Settings`. +1. Enter the full path to your script and the custom message you want to send: `/Users/username/Temp/script1.sh "Hello world."` replacing `/Users/username/Temp/` with the path to your script. +1. If you like, you can elect to have the result saved to an Indigo Variable (optional). +1. Select `Save`, and then `OK`. + +From within Indigo, execute your action. The custom message you sent (in this example, "Hello world.") will be sent to the script and will appear in the resulting notification. + +![Run Shell Script Action Image](../../images/screenshot_2023-02-16_at_10.58.59_am.png) + +You probably want to send something more interesting than `Hello world.`, for example the value of some variable. We can do this using Indigo's substitutions feature. + +`/Users/username/Temp/script1.sh "%%v:568909175%%"` + +Notice the quotes around the substitution. If you don't enclose the substitution in quotes, you'll get the variable text value only up to the first space. Quotes will ensure the whole value is sent. + +![Test Alert Image](../../images/screenshot_2023-02-16_at_11.09.20_am.png) + +The opportunities here are only limited by the boundaries of the Shortcuts app. For example, you could add the value of a variable to your Calendar or send the value to a text message. + +## Firing Your Shortcuts with Siri +Of course, you can have Siri run your shortcut by saying the name of the shortcut you want to run. To run the `Toggle Living Room Lamp` shortcut, say, "Hey Siri. Toggle Living Room Lamp". However, once you begin to have a lot of shortcuts, it can be tough to remember the exact name of every shortcut in your collection. One thing that can help is to create multiple shortcuts with similar names that all point to the same "original" shortcut. That way, if you make a change to the original shortcut, you don't need to change the others (if you change the name of the original shortcut, the Shortcuts app will update the others). + +| Siri Phrase | Action taken | +|----------------------|---------------------------------------| +| "Party Time" | sets lights, temperature, tv, whatever | +| "Let's Party" | Runs Party Time shortcut | +| "It's Party Time" | Runs Party Time shortcut | +| "I'm Having a Party" | Runs Party Time shortcut | + + +![Firing Your Shortcuts With Siri Image](../../images/screenshot_2023-02-18_at_7.46.27_pm.png) + +## Ideas +### Calendar + +- Create a separate calendar called "Indigo Events" to track events over time. +- Add weather information to your Calendar. + +### Clock + +- Create an alarm on your phone. + +### Home + +- Use Indigo to trigger events with your HomeKit devices. +- Use HomeKit to trigger events with your Indigo server. + +### Messages + +- Send messages with important information about your Indigo server. +- Trigger your Indigo server by texting a phrase. + +## Tips +These tips can help make using shortcuts to control Indigo easier: + +- If you save your shortcuts to the Home Screen in iOS, be sure you're happy with the look of the icons before you add a bunch of them. Changes you make to the icons later in the Shortcuts app won't update home screen bookmarks automatically (they will change automatically in widgets). +- Put your most commonly used shortcuts first because widgets only display a few at a time. +- You can create shortcuts in the iOS app, but it is **much easier** to create them in macOS. +- With location-based automations, some (but not all) notifications can be silenced. When available, you will see a toggle for "Ask Before Running". If you set this to `off`, a new toggle will appear that says, "Notify When Run". If this is also set to `off`, then notifications for this automation will not be sent. Presently, there is no global setting to turn off all automation notifications. +- Create folders in the shortcuts app that mimic the folders in Indigo. If you find that you can't drag a shortcut to a new folder, it may help to create a "dummy" shortcut into the folder first. +- If using a local address such as `localhost:8176` or `10.0.1.123:8176` make sure to use `%%http://%%` and not `%%https://%%`) +- To use your shortcuts with Apple Watch, edit your shortcut, click on the **ⓘ** icon and select "Show on Apple Watch". +- **Indigo servers running versions of macOS prior to Monterey do not have local access to the Shortcuts app.** + +## Reference +### Command Line Commands +Here are a few commands you can run from the command line with the Shortcuts App that may be useful: + +| Command | Result | +|--------------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| `shortcuts run "My Shortcut"` | Run shortcut named "My Shortcut" | +| `%%shortcuts run "My Shortcut" <<< '{"message":"indigo.device.toggle", "objectId":"123456", "Arg":"Arg Value"}'%%` | Pass a dictionary to Indigo. | +| `shortcuts list` | List available shortcuts. | +| `shortcuts list --f` | List available folders. | +| `%%shortcuts list -f Living\ Room%%` | List all shortcuts in the "Living Room" folder. | +| `man shortcuts` | List of available commands. | + + +### Apple Documentation +[Shortcuts User Guide Mac](https://support.apple.com/guide/shortcuts-mac/welcome/mac) +[Shortcuts User Guide iOS/iPadOS](https://support.apple.com/guide/shortcuts/welcome/ios) diff --git a/reference/canonical/user/automation/event-data.md b/reference/canonical/user/automation/event-data.md new file mode 100644 index 0000000..3e56278 --- /dev/null +++ b/reference/canonical/user/automation/event-data.md @@ -0,0 +1,139 @@ + + +# Events Data Passing + +!!! abstract "In this guide" + How Indigo passes structured data from the event that fired — trigger details, device state changes, plugin metadata — to Python scripts and action groups. Covers the default `event_data` dictionary keys, plugin-specific additions, accessing data in embedded scripts, and chaining data through action group calls. + +Many users ask, "How do I know what caused an action to fire?" Our server architecture never passed through any source data before. But, now we do! All built-in triggers and schedules now pass through data that's specific to the event. Here are the basics. + +Events now pass an *`indigo.Dict`* that contains data about the firing event, be it a trigger, schedule, or plugin provided event that your plugin may provide. By default, every event dictionary will contain the following: + +```json +{ + "event-indigo-id": 1214985350, # the ID of the trigger, schedule, action group, etc + "event-type": "Trigger", # the event type - trigger, schedule, action group, etc. + "source": "server", # the source of the event (see description below) + "timestamp": "2025-08-07T14:32:21", # ISO formatted datetime string +} +``` + +The ID is the *`event-indigo-id`* for the instance passing the data - it could be a Trigger, a Schedule, an Action Group (more on this later). The *`event-type`* is just the IOM class name. The *`timestamp`* is an ISO formatted datetime that the event fired, so you can use *`datetime.fromisoformat()`* to convert it into a native *`datetime`* instance. + +The *`source`* item is a little more tricky. Here are the possible values: + +1. *`server`* - this is what will show if the server performed the event on its own during the normal course of operations. A device state change trigger, a schedule fires, etc. +1. *`python`* - this is what the source would be if the operation was started via an IOM command. So if you did a *`indigo.actionGroup.execute(12345)`* this is what the source would be. +1. *`api-http`* - similar to *`python`* above, but if the command came in through the HTTP API. +1. *`api-websocket`* - similar to *`api-http`*, but the command would have come through a websocket. + +Plugin supplied events (for instance, the Z-Wave Command Received event, email received event, or any event that your plugin may provide) will **add** the following plugin specific information: + +```json +{ + "event-plugin-event-id": "zwaveCommand", # ID of the plugin supplied event + "event-plugin-id": "com.perceptiveautomation.indigoplugin.zwave", # plugin id + "event-plugin-name": "Z-Wave", # plugin name + "event-type": "PluginEventTrigger", # will always be this class name +} +``` + +Plugin events have more data that's specific to the plugin: the event id (from your Events.xml file), your plugin ID, the name. The *`event-type`* for a plugin event will always be *`PluginEventTrigger`*. + +## How do you pass data through? +If your plugin supplies events, then you are aware that in your event handling code you eventually will call the *`execute()`* method on the event that the user configures, something like this: + +```python +indigo.trigger.execute(trigger_instance) +``` + +To pass through any extra triggering data that you might want to add, just add it: + +```python +message = {"somekey": "some value"} +indigo.trigger.execute(trigger_instance, trigger_data=message) +``` + +`message` can be either an `indigo.Dict` or a normal python *`dict`* instance, the server will convert it to an *`indigo.Dict`* before passing it along. It's just that simple. + +Some notes on standards for your data: + +- You won't want to duplicate any of the above built-in names as it would get overwritten. +- You probably want to name your keys with something that's easily identified with your plugin. For instance, the Z-Wave plugin uses the prefix `zwavecmd-` for it's keys that describe the event data that it passes through. +- We tried to use dashes `-` as separators rather than underscores - we think that's a better option for string keys. +- Keys should follow the restrictions on `indigo.Dict` keys (alphanumeric, dash, underscore, starting with a letter). + +FYI, you can pass arbitrary data around using the IOM and the various `.execute()` actions on Triggers, Schedules, and Action Groups. Just pass through *`trigger_data`*, *`schedule_data`*, *`event_data`* respectively to those function calls when performing them through the IOM. + +## How will users use the data? +The data is passed first to any **conditional scripts**. The data can be accessed like this: + +```python +# event_data is prepopulated with the indigo.Dict from the originating event +if event_data["source"] == "api-http": + # the triggering event came from the HTTP API, so you may want to look at something + # here. + pass +``` + +Regardless of where the data came from (trigger, schedule, etc.) the variable name will be *`event_data`*. + +Then, once the conditions have been evaluated, the *`event_data`* will become available to actions. We've updated the built-in actions where appropriate to use the data. + +We've added a new **Insert Event Data into Variable** action which will allow the user to insert all or part of the event data into the specified variable. If they specify a path (see the **box** library description above) and the result of the path is a simple type (string, bool, int, float) then that value will be inserted into the variable. If the result of the path is a collection (dict or list) or the user doesn't specify the path, then the collection will be converted to JSON and the JSON string will be inserted into the variable. + +There is also a new substitution, *`%%e:"path"%%`* that can be used anywhere a substitution is valid. If the user wants the whole thing, they would just use the empty string *`%%e:""%%`* and the entire string will be inserted. Again, simple types will be inserted directly, complex types will be inserted as JSON. + +Embedded script actions will also receive the data in the same way that conditional scripts do. **Note**: external (linked) scripts will not get the data in this release. We will gauge demand moving forward to determine if and when to add it there. + +## How will you get the data in your actions? +You can get the data directly in your actions as well. Event data will be passed to the action method handler if you modify your method signature: + +```python +def run_shortcut(self: indigo.PluginBase, + action: any, + dev: any, + caller_waiting_for_result: bool, + event_data: Optional[indigo.Dict]) -> Optional[indigo.Dict]: +``` + +This is a complete action handler with type hints. While we don't envision a scenario where *`event_data`* is passed `None`, it's possible that it may happen or could be optional at some point in the future. Your code should make sure that the data is present before assuming anything. + +## Examples of How Events Data Can Be Used +There are likely a lot of different scenarios where *`event_data`* is useful, but it may be helpful to see a complete working example all in one place. Here is a simple example just to show how straightforward the mechanism can be. + +Create an Action: + +- Create an Action Group called "Log Event Data" +- Select **Server Actions** > **Script and File Actions** > **Execute Script** +- Select Embedded Python and enter the following short script into the code block. Notice that we didn't do anything special to access the *`event_data`* payload. It's automatically supplied by the host process when the script is called **due to an event**. +```python +indigo.server.log(f"{event_data}") +``` + +- Select OK + +Create a Trigger to fire the action: + +- Create a Trigger called "Log Event Data" +- You can link it to an event, but for this example the event type doesn't matter +- You can also set a Condition, but for this example the condition doesn't matter either +- On the Actions tab, select **Server Actions** > **Execute Actions Group** +- Select the "Log Event Data" Action you created above +- Select OK + +Now, from the Actions list in Indigo, highlight the "Log Event Data" Trigger and select **Execute Actions Only**. When your Trigger fires the script, something similar to the following should appear in the Events log: + +```text +Trigger Event Data Trigger + Action Group Event Data Example + Script EventDataDict : (dict) + event-indigo-id : 553162605 (integer) + event-type : DeviceStateChangeTrigger (string) + source : server (string) + timestamp : 2025-10-31T10:18:37 (string) +``` +It's that simple. + +## Get Creative +The new *`event_data`* mechanism opens up a lot of possibilities for plugin developers. One thing that comes to mind almost immediately would be for plugins that provide virtual devices/wrappers/shims to allow the user to specify a path in the data then map that into either a custom state or a property (onState, etc.) Combine this functionality with [Webhook functionality](../../api/webhooks.md) and it would be possible to have a webhook directly update a virtual device. This would reduce a lot of glue code necessary now in handling those types of things. diff --git a/reference/canonical/user/automation/get-contents-of-url.md b/reference/canonical/user/automation/get-contents-of-url.md new file mode 100644 index 0000000..962bb7a --- /dev/null +++ b/reference/canonical/user/automation/get-contents-of-url.md @@ -0,0 +1,62 @@ + + +# Get Contents of URL Action + +!!! abstract "In this guide" + How to use the Get Contents of URL action to fetch data from HTTP endpoints and store the response in an Indigo variable. Covers the supported HTTP methods, authentication options, custom headers, the request body field with substitution support, and worked examples for common REST APIs. + +The Get Contents of URL Action allows users to query APIs and other URLs and save the results of the query to an Indigo variable for display or for further processing. + +![Get Contents of URL Action Image](../../images/get_contents_of_url_action.png) + +- `Enter the URL` - use this field to enter the URL of the target resource. +- `Method` - use this option to... The action supports all the major resource I/O methods including: `*GET*`, `*POST*`, `*PUT*`, `*PATCH*` and `*DELETE*`. +- `HTTP Auth` - if the target resource requires authentication (as most do), use this option to enter the necessary authentication details. + - `Auth Type` - use this option to select the authentication method used by the target resource. The control supports both `*BASIC*` and `*DIGEST*` auth types. + - `Username` - use this field to enter the username of the target resource. + - `Password` - use this field to enter the password of the target resource. +- `Show Headers` - There are two major sections to the Show Headers control: the first set of controls is used to edit or delete an existing header key/value pair, and the second set is for adding a new header. The checkbox is only used to show/hide the controls; any added headers are used even if the checkbox is unchecked. + - `Header` - use this option to select from a list of headers for the action. The list will be empty if no headers have been added. Use the add header controls to add a new header. + - `Key` - use this option to create your header key. You can create multiple keys, but only one at a time. + - `Value` - use this option to create your header value. You can create multiple values, but only one at a time. +- `Body` - use this field to enter the body message (including Indigo substitutions). Anything in this field will be inserted into the body of the HTTP message. We use it exactly as it comes from the field with no post-processing other than the normal device and variable substitutions. +- `Store Result in Variable` - use this option to store the results of the URL call to an Indigo variable. If enabled, you can select from a list of available variables. Note that Indigo stores all variable values as strings (text), so any value saved to a variable using the Get Contents from URL action will be coerced into a string. + +## Examples +Here are a couple of examples to get you started. + +### Example 1 +*`Enter the URL`* -> https://api.weather.gov/stations/KATT/observations/latest + +*`Method`* -> Get + +*`HTTP Auth`* -> False + +*`Show Headers`* -> False + +*`Body`* -> None + +*`Store result in variable`* -> True + +*`Variable`* -> [choose the appropriate variable] + +### Example 2 +*`Enter the URL`* -> https://httpbin.org/bearer + +*`Method`* -> Get + +*`HTTP Auth`* -> False + +*`Show Headers`* -> True + +Add a Header (be sure to click the *`Add Header`* button: + +*`Key`* -> Authorization + +*`Value`* -> Bearer indigo123 + +*`Body`* -> None + +*`Store result in variable`* -> True + +*`Variable`* -> [choose the appropriate variable] diff --git a/reference/canonical/user/automation/substitutions.md b/reference/canonical/user/automation/substitutions.md new file mode 100644 index 0000000..fd9ba51 --- /dev/null +++ b/reference/canonical/user/automation/substitutions.md @@ -0,0 +1,66 @@ + + +# Substitutions + +!!! abstract "In this guide" + How to use Indigo's substitution syntax to embed dynamic values — device states, variable contents, timestamps, and trigger event data — directly into action parameters, URLs, and plugin fields. Covers the substitution string format for each object type with examples, and notes where substitutions are and are not supported. + +One of Indigo's powerful features is substitutions. Substitutions are special codes that are used to reference other Indigo objects -- like devices, variables, and events -- to get values related to them. For example, you might use a variable substitution to get the current value of the variable you're referencing. All substitution expressions have a similar format: + +| Object | Substitution String | Example | Target | +| --- | --- | --- | --- | +| Devices | %%d:DEVICEID:STATEID%% | %%d:12345678:onOffState%% | the current onOffState of device 12345678 | +| Variables | %%v:VARIABLEID%% | %%v:234566789%% | the current value of variable 234566789 | +| Timestamps | %%t:"FORMATSTRING"%% | %%t:"%Y-%M-%D %H:%M"%% | the current time based on the provided *`datetime`* format specifier *`"%Y-%M-%D %H:%M"`* | +| Events | %%e:"PATH"%% | %%e:"a-list.[2].dict-in-list"%% | replaces the specified path string *`"a-list.[2].dict-in-list"`*with the corresponding value from the related *`event_data`* | + +Substitutions are used extensively throughout Indigo and Indigo Plugins. For example, you can use a device or variable substitution as a part of a Control Page Refreshing URL input like this: *`http:*www.example.com/images/%%v:2345678%%.jpg`* which will substitute the current value of variable 2345678 as the image filename. + +!!! note + While available in a wide array of instances, substitutions are not universally supported. You should confirm that substitutions are supported in each instance before attempting to use them. + +## Device Substitutions +Device substitutions allow you to reference a particular state's current value of the target device. Device states can have different value types -- like strings, numbers, booleans, etc. -- so it's important to ensure that the substitution will return a value type appropriate to your use case. + +| Substitution String | Example | Target | +| --- | --- | --- | +| %%d:DEVICEID:STATEID%% | %%d:12345678:onOffState%% | the current onOffState of device 12345678 | +| Example | Result | | +| %%d:12345678:brightnessLevel%% | 100 (integer) | | +| %%d:12345678:onOffState%% | on (on/off boolean) | | +| %%d:12345678:hvacFanModeIsAuto%% | true (boolean) | | + + +## Event Substitutions +Event substitutions allow you to reference a particular data element of an event-data payload. Event substitutions are somewhat of a special case and have a [separate page dedicated to them](../../scripting/reference/event-data-paths.md). + +| Substitution String | Example | Target | +| --- | --- | --- | +| %%e:"PATH"%% | %%e:"a-list[2].dict-in-list"%% | replaces the specified path string *`"a-list[2].dict-in-list"`*with the corresponding value from the related *`event_data`* | + + +## Plugin Substitutions +Many Indigo plugins support substitutions-- plugin developers are encouraged to make it clear where substitutions are permitted and to explain how they're used in the plugin's documentation. + + +## Timestamp Substitutions +Timestamp substitutions allow you to reference the current date/time based on the provided format specifier. There is a considerable number of online resources that explain the various datetime format specifiers. Do a search for "python datetime format specifiers" (there are some differences between programming languages), so be sure to search for ***python*** specifiers. + +| Substitution String | Example | Target | +| --- | --- | --- | +| %%t:"FORMATSTRING"%% | %%t:"%Y-%M-%D %H:%M"%% | the current time based on the provided *`datetime`* format specifier *`"%Y-%M-%D %H:%M"`* | +| Example | Result | | +| %%t:"%Y-%m-%d %H:%M"%% | "2025-10-22 13:03" | | +| %%t:"%Y-%m-%d"%% | "2025-10-22" | | +| %%t:"%H:%M:%S"%% | "13:03:49" | | + + +## Variable Substitutions +Variable substitutions allow you to reference the current value of the target variable. Since variables values are always strings, a variable substitution will always return a string. + +| Substitution String | Example | Target | +| --- | --- | --- | +| %%v:VARIABLEID%% | %%v:234566789%% | the current value of variable 234566789 | +| Example | Result | | +| %%v:12345678%% | "My variable value" | | +| %%v:2345678%% | "Another value" | | diff --git a/reference/canonical/user/concepts.md b/reference/canonical/user/concepts.md new file mode 100644 index 0000000..c6029d2 --- /dev/null +++ b/reference/canonical/user/concepts.md @@ -0,0 +1,25 @@ + + +# Core Concepts +Indigo has several high-level objects that you interact with: Devices, Triggers, Schedules, Action Groups, Control Pages, and Variables. While some of these objects are obvious, others aren't, so let's create some definitions (each one has a section with more detail below): + +| Object | Definition | | +| --- | --- | --- | +| [Devices](devices.md#devices) | A device is any "thing" that Indigo can interact with - usually it's some kind of hardware (light switch, appliance module, motion sensor, etc), but devices can also be other non-hardware things (iTunes server, calendar, etc). | | +| [Triggers](triggers.md#triggers) | A trigger is generally some kind of "event" that occurs. Indigo can use that event to execute actions in response. | | +| [Schedules](schedules.md#schedules) | A schedule is similar to a trigger, but the event that causes the execution of the actions is a temporal event of some kind. Either a fixed point in time (5/2/2011 at 1:00pm) or more likely some repeating time (every day at 1:00pm). | | +| [Action Groups](actions.md#action-groups) | Action Groups are collections of actions that may be reused (and modified) easily between multiple triggers, schedules, and control pages and executed via various clients (the Mac Client, the Indigo Web Server (IWS) web pages, Indigo Touch, etc). | +| [Control Pages](control-pages.md#control-pages) | Control Pages are user-created interfaces to control their Indigo system - for instance you could create a graphical floor plan with light icons in the various rooms. | +| [Variables](variables.md#variables) | A variable is a place where your home automation logic can store information that changes during the normal operation of your home and that can be used in other parts of your system: for instance, you can have a variable that represents whether your home is occupied or not - then you can have special automation logic that takes place when that variable changes. | | + + +That is the very high-level definition of the primary objects in Indigo. If you don't find what you're looking for there, check out our [Glossary Of Terms](../glossary.md) which includes just about every term we can think of that you might run across. Next, we want to go into a little more detail about each of the main object types to help you understand when and why you would want to use them. + +## Reading On + +You work with these objects through Indigo's clients: the [Mac Client](../mac-client/index.md) (where all configuration happens), [Indigo Touch for Web](../remote-access/touch-for-web.md) in any browser, and [Indigo Touch for iOS](https://www.indigodomo.com/touch.html) on your iPhone, iPad, and Apple Watch. + +Each object has its own chapter: [Devices](devices.md), [Triggers](triggers.md), [Schedules](schedules.md), [Actions & Action Groups](actions.md), [Variables](variables.md), [Control Pages](control-pages.md), and [Conditions](conditions.md) — which restrict *when* triggers and schedules execute. Finally, [Managing Plugins](plugins.md) covers what plugins are and how to install and manage them. + +--- +*Z-Wave® is a registered trademark of Sigma Designs, Inc. Indigo's support of Z-Wave hardware is neither endorsed nor certified by Sigma Designs.* diff --git a/reference/canonical/user/concepts/actions.md b/reference/canonical/user/concepts/actions.md new file mode 100644 index 0000000..df19568 --- /dev/null +++ b/reference/canonical/user/concepts/actions.md @@ -0,0 +1,434 @@ + + +# Actions & Action Groups + +## Actions +Actions are the individual commands that Indigo will perform: turn on a light, send an email, etc. You can specify as many actions as you like for each [Trigger](triggers.md#triggers), [Schedule](schedules.md#schedules), [Action Group](#action-groups), and [Control Page](control-pages.md#control-pages) element. + +On any dialog that has an area where you select actions (Triggers, Schedules, Action Groups, and Control Pages), The first thing you'll see is the `Type` popup: + +![Action Type Menu Image](../../images/action_type_menu.png) + +Actions are grouped into 6 main categories (some of those categories have subcategories) and then below those there is a category for each plugin that provides actions that aren't integrated into other menus. + +### Device Actions +![Device Actions Type Menu Image](../../images/device_actions_type_menu.png) + +The `Device Actions` category has 7 subcategories. Plugins can also add a submenu to this category for the actions they define that work directly on devices. By default, Indigo ships with the [Airfoil Pro](../../plugins/airfoilpro.md) and [Timers and Pesters](../../plugins/timersandpesters.md) plugins, which add subcategories to this menu. You may have other menus as well if you've installed 3rd party plugins. + +#### Universal Controls +![Universal Controls Menu Image](../../images/universal_controls_menu.png) + +These controls are either universal across most devices or are available on some specific types of devices (KeypadLincs for instance). + +- `Request Full Status Update` - ask the device to reply with all possible status information. This is dependent on the capabilities of the device. +- `Request Energy Update` - ask the device to reply with only its energy usage information. This is dependent on the capabilities of the device - many do not support energy monitoring. +- `Reset Energy Usage` - ask the device to reset the running total of energy usage. This is dependent on the capabilities of the device - many do not support energy monitoring. + +#### Light/Appliance Controls { #light-appliance-controls } +![Light Controls Menu Image](../../images/light_controls_menu.png) + +These controls are for lights and on/off (sometimes called relay) devices. + +- `All Off` - turn off all light and appliance devices. The `Devices:` popup lets you select `All Insteon/X10`, `All Insteon`, `All X10`, or a specific X10 house code. +- `All Lights On` - turn on all light devices with the same `Devices:` options as `All Off` +- `All Lights Off` - turn off all light devices with the same `Devices:` options as `All Off` +- `Turn On` - turn on a specific device with an optional complementary `Auto-off after X minutes` action +- `Turn Off` - turn of a specific device with an optional complementary `Auto-on after X minutes` action +- `Toggle On/Off` - turn on the device if it's off or off if it's on +- `Set Brightness` - set the brightness of a lamp device to a specific percentage (from 0-100) +- `Brighten by %` - increase the brightness of a lamp device by a specific percentage (from 0-100) +- `Dim by %` - increase the brightness of a lamp device by a specific percentage (from 0-100) +- `Match Brightness to Device` - set the brightness of any number of dimmer devices to the value of the selected dimmer device - so you can quickly and easily create a very simple scene. +- `Match Brightness to Variable` - set the brightness of any number of dimmer devices to the value of the selected variable. +- `Start Brighten` - for Insteon and Z-Wave dimmers, start to brighten the load (using the device's specific ramp rate). You can pair this with an `End Brighten/Dim` command or you can just allow it to brighten all the way to 100%. +- `Start Dim` - for Insteon and Z-Wave dimmers, start to dim the load (using the device's specific ramp rate). You can pair this with an `End Brighten/Dim` command or you can just allow it to dim until it's finished. Insteon devices will end up at 0% (off), but some Z-Wave devices may stop at 1% rather than being completely off. +- `End Brighten/Dim` - for Insteon and Z-Wave dimmers, end a previously issued `Start Brighten` or `Start Dim` and update the brightness of the device in Indigo at whatever level the dimmer was at when it stopped. +- `Match On State to Device` - set the on state of any number of on/off or dimmer devices to the value of the selected device which supports an on state. +- `Match On State to Keypad LED State` - set the on state of any number of on/off or dimmer devices to the value of the selected Insteon KeypadLinc button. +- `Match On State to Variable` - set the on state of any number of on/off or dimmer devices to the value of the selected variable. +- `Set RGBW Levels` - set the RGBW levels for lights that support setting their color. + +#### Sprinkler Controls { #sprinkler-controls } +![Sprinkler Action Image](../../images/sprinkler_action.png) + +These are the options for controlling your sprinkler: + +![Sprinkler Schedule Action Image](../../images/sprinkler_schedule_action.png) + +- `Run Schedule` - selecting this action will show you the zone list (shown above - note the list will scroll to show all available zones for the sprinkler) that will allow you to set the duration for each zone and optionally multiply those durations by the selected variable. This last option is useful if you change durations based on time of year - you can change the variable value but keep the existing schedule and it'll adjust the duration as appropriate. +- `Pause Schedule` - this action will pause the current schedule (if for instance you're walking to your car and don't want to get wet) +- `Resume Schedule` - this action will resume a previously paused schedule (once you're in your car) +- `Stop (all zones off & clear schedule)` - this action will completely stop the schedule +- `Activate Previous Zone` - this action will cause the schedule to back up one zone +- `Activate Next Zone` - this action will cause the schedule to jump to the next zone +- `Turn on Specific Zone` - this action will turn on a specific zone for the maximum run time specified in the sprinkler's definition and will turn off after it's done + +#### Thermostat Controls { #thermostat-controls } +![Thermostat Actions Type Menu Image](../../images/thermostat_actions_type_menu.png) + +There are 13 basic actions available: + +- `Set Heat Setpoint` - set the heat setpoint to an absolute temperature +- `Increase Heat Setpoint` - increase the heat setpoint by some number of degrees +- `Decrease Heat Setpoint` - decrease the heat setpoint by some number of degrees +- `Set Cool Setpoint` - set the cool setpoint to an absolute temperature +- `Increase Cool Setpoint` - increase the cool setpoint by some number of degrees +- `Decrease Cool Setpoint` - decrease the cool setpoint by some number of degrees +- `Set Main Mode` - set the mode of the thermostat to one of the following: + - `All Off` - set the HVAC unit so that both heat and cool setpoints are ignored - the unit will not come on at all + - `Heat On` - activate the HVAC unit so that only the heat setpoint is used + - `Cool On`- activate the HVAC unit so that only the cool setpoint is used + - `Heat/Cool On` - activate the HVAC unit so that both heat and cool setpoints are used + - `Run Heat Program` - tell the thermostat to run the heat program that is programmed directly into the thermostat (see the thermostat documentation for details) + - `Run Cool Program` - tell the thermostat to run the cool program that is programmed directly into the thermostat (see the thermostat documentation for details) + - `Run Heat/Cool Program` - tell the thermostat to run the heat/cool program that is programmed directly into the thermostat (see the thermostat documentation for details) +- `Set Fan Mode` - set the fan mode of the thermostat to one of the following: + - `Fan Auto On` - set the fan so that it only runs as needed + - `Fan Always On` - turn the fan on so it'll continuously run +- `Get All Status` - get all information from the thermostat +- `Get Current Mode` - get the current mode +- `Get Ambient Temperature` - update the temperature +- `Get Humidity` - get the humidity +- `Get Setpoints` - get the setpoints +- `Cycle Through Thermostat Modes` - this will allow you to easily cycle through thermostat modes in this order: Off, Cool, Heat, Auto. Especially useful in conjunction with the "Thermostat Mode+.png" image on a control page - just add this as a server action and you have a simple control for adjusting the thermostat mode - each time you tap/click the image, the thermostat selected will cycle to the next mode just like pressing the Mode button on the thermostat itself (if it has one). +- `Toggle Thermostat Fan Mode` - like the action above, this method will toggle between the two fan modes: Fan On (always on) and Fan Auto (automatic). Again, useful with the "Thermostat Fan Mode+.png" image file. + +v1 Insteon thermostat adaptors didn't broadcast out changes to update its internal state representations for the thermostats - which is why there are so many options to get status. Indigo catches the v2 thermostat update broadcasts so the need to manually get updates should be reduced. + +#### Fan Speed Controls +![Fan Speed Control Actions Image](../../images/fan_speed_control_actions.png) + +Here are the 7 actions for fan speed control: + +- `Set Fan Speed` - set the speed of the device to a specific level +- `Increase Fan Speed` - increase the fan speed by some # of units - for instance, on a FanLinc that's currently on `Low`, increasing the fan speed by 1 will set it to `Medium` +- `Decrease Fan Speed` - decrease the fan speed similarly to the above Increase Fan Speed +- `Turn Fan On (resume last speed)` - this will turn the fan on to its last speed setting +- `Turn Fan Off` - turn the fan off completely +- `Toggle Fan On/Off` - toggle between on and off +- `Cycle Through Fan Speeds` - use this action to cycle through the fan speeds in highest to lowest speed order. It's basically an electronic version of pulling a fan's chain. + +#### Input / Output Device Controls { #input-output-device-controls } +![I/O Action Image](../../images/io_action.png) + +There are eight actions available: + +- `Turn On Output` - turn on the specified output +- `Turn Off Output` - turn off the specified output +- `Turn Off All Outputs` - turn off all outputs +- `Get All Status` - get the status of all inputs and outputs +- `Get Binary Outputs Status` - get the status of all the binary outputs +- `Get Binary Inputs Status` - get the status of all the binary inputs +- `Get Analog Inputs Values` - get the voltage value of all the analog inputs +- `Get Sensor Inputs Values` - get the value of the 1-wire sensor bus (only available on some I/O devices) + +#### Virtual Device Controls +![Virtual Devices Controls Image](../../images/virtual_devices_controls.png) + +There are a few controls specific to Virtual Devices: + +- `Update Device Group Saved State` - updates the saved state of all devices in a device group so the next ON command will match their current settings. +- `Set Virtual On/Off Device State` - explicitly sets the state of a virtual on/off device. Useful if the state gets out of sync or is not maintained by a variable. + +#### Brand Specific Controls +![Brand Specific Controls Image](../../images/brand_specific_controls.png) + +The Brand Specific Controls submenu contains submenus that hold device specific commands that are unique to a particular brand of device (manufacturer). There are two described below: + +##### Insteon +![Insteon Specific Actions Image](../../images/insteon_specific_actions.png) + +- `Beep Device` - ask the device to beep. This function is dependent on the capabilities of the device. +- `Turn On Single KeypadLinc Button ` - turn on one individual KeypadLinc button. +- `Turn On Single KeypadLinc Button ` - turn off one individual KeypadLinc button. +- `Set All KeypadLinc Buttons ` - turn on/off groups of buttons. Why not just have multiple actions using the built-in Turn ON/Turn OFF LED actions? Because each of those requires a lot of Insteon traffic - and if you need to set several buttons at once this action will do it in one (or two if you want to maintain some buttons) action(s). It's more efficient and easier to configure (one action versus potentially seven actions). Select the action you want to take for each button: `Turn On`, `Turn Off`, `Leave Alone`. The latter option will require that we query the KPL to find the states first so if you select that for any of the buttons the action may execute a bit slower than it would otherwise. **Note**: using this action, which is sending raw Insteon commands through the IndigoServer, will cause the KeypadLinc's button states in Indigo to become out of sync. This is because the server doesn't know that you're changing the button states given that it's just a raw command message that it's being asked to send to the PowerLinc. If you need to keep the states in sync then add another action to do a status request to the KeypadLinc (after a short delay to avoid collisions). +- `Set KeypadLinc Auto-Off Button Group ` - specify what buttons will go off automatically when you press any other button. Useful in conjunction with Toggle Mode below for creating "radio groups". See the [Fanlinc And Keypadlinc](../interfaces/insteon/fanlinc_and_keypadlinc.md) article for usage examples. +- `Set KeypadLinc Button Toggle Mode ` - specify whether a button toggles (alternates between ON and OFF when pressed) or whether it sends a single command anytime it's pressed (can send either ON or OFF). Useful in conjunction with Auto-Off groups above for creating "radio groups". See the [Fanlinc And Keypadlinc](../interfaces/insteon/fanlinc_and_keypadlinc.md) article for usage examples. +- `Set LED Brightness ` - set the brightness of the LEDs on certain devices. Newer KeypadLincs are supported as well as some SwitchLinc models. Unfortunately there isn't really a way to tell you which devices are supported so you'll just have to try it and see if it works. +- `Set i3 Dimmer/Relay Mode ` - set the behavior for i3 modules that support both on/off and dimmable loads. +- `Set i3 Dial Off Behavior ` - set the behavior when an i3 Dial is fully rotated counterclockwise: off or dim to 1%. +- `Set Motion Sensor LED Brightness ` - set the brightness of the LED that flashes inside the motion sensor when motion is detected. While the brightness value is between 0 and 255, 0 does not mean the LED is completely off - it's just very dim. Note: only revision 2 Motion Sensors with jumper 5 set can be configured. +- `Set Motion Sensor Timeout ` - set the timeout value between the time the motion sensor stops detecting motion and when it sends the OFF command. The timeout values work like this: 0 is equal to 30 seconds and 255 is equal to 2 hours. Values in between are proportional to those values. Note: only revision 2 Motion Sensors with jumper 5 set can be configured. +- `Set Motion Sensor Day/Night Sensitivity ` - set the sensitivity for when the motion sensor detects changes from dawn to dusk and vice versa. The sensitivity values work like this: 0 will make the sensor register day all the time and 255 is equal to night all the time. Values in between are proportional to those values. **Note**: only revision 2 Motion Sensors with jumper 5 set can be configured and Motion Sensor II models will interpret 0 as 3. +- `Set I/O Linc Momentary Mode ` - set the momentary mode of an I/O Linc to A, B, C, or None (the built-in UI only sets A or None). +- `Set I/O Linc Momentary Duration ` - set the duration the output will be on before it automatically goes off (if momentary mode is turned on with the above command). +- `Configure SynchroLinc ` - configure the Trigger Watts, Threshold Watts, and Delay Seconds in a SynchroLinc. Here are the details of those settings: + - Trigger Watts (0 to 1800 watts in 0.5 watt steps): the wattage needed before the SynchroLinc broadcasts. + - Threshold Watts (aka hysteresis, 0 to 127.5 watts in 0.5 watt steps): tolerance before on/off toggle is sent. + - Delay Seconds (0.15 to 38.25 seconds): prevents message flooding if thresholdWatts is too low. +- `Set Siren Alarm Sound` - configure the sound that will be played the next time the alarm is activated. Choose between chime (doorbell) or siren (loud). The sound will change if this action is called while the siren is sounding. +- `Set Siren LED Mode` - configure what the LED on the siren does. Choices are: On Solid, Blink on Insteon Traffic, Off +- `Set Load Sense for OutletLinc` - configure the load sense on either outlet in the OutletLinc (dual outlet only) + +##### HomeSeer +The HomeSeer 200+ series of devices (WD200+, WS200+, FC200+, and HSM200 as of this release) allow the various LEDs on those devices to be controlled in a variety of ways. These actions enable controlling those features. + +![Homeseer Specific Actions Image](../../images/homeseer_specific_actions.png) + +- `Set LED Mode` - set the mode of the LEDs on the switch. The default `Normal (load status)` behavior is for them to represent the brightness to which the switch is set. You can set the switch to `Status (custom status)` which will allow you to individually turn on and off each LED and set its color. You can also set the bottom LED's behavior. +- `Set LED Color and On/Off State` - when the switch is in `Status` mode, you can use this action to turn on/off and set the color of any of the LEDs. +- `Set LEDs Blinking Behavior` - start/stop LEDs from blinking. + +##### Inovelli +Several recent Inovelli devices (LZW30, LZW30-SN, LZW31, LZW31-SN and LZW36 as of this release) allow the various LEDs on those devices to be controlled in a variety of ways. These actions enable controlling those features. + +![Inovelli Specific Actions Image](../../images/inovelli_specific_actions.png) + +- `Set LED Brightness when Off` - this will set how bright the LED is when the device is off (nice for night time to easily locate switch in the dark). +- `Set LED Brightness when On` - this will set how bright the LED is when the device is on. +- `Set LED Color` - sets the color of the LED. +- `Set Notification` - some Inovelli devices allow you to set what they refer to as a notification. This is a combination of color, brightness, effect (pulse, flash, etc), and duration. The net effect is that you can change the behavior of a device's LED temporarily (with or without an automatic timeout) to act as a visual notification. When the notification times out (or is explicitly cleared) it will revert to its previous setting. +- `Clear Notification` - clears a previously set notification (does nothing if no notification is active on a device). + +##### Zooz +The Zooz ZEN30 allows the various LEDs on it to be controlled in a variety of ways. These actions enable controlling those features. + +![Zooz Specific Actions Image](../../images/zooz_specific_actions.png) + +- `Set Default Brightness` - set the brightness that the dimmer device will come on to. Note this only applies to manual operation - Z-Wave ON commands will always result in the switch returning to its previous brightness. +- `Set LED Brightness` - set how bright the LEDs are. +- `Set LED Color` - set the color of the LEDs. + +### Server Actions +![Server Actions Type Menu Image](../../images/server_actions_type_menu_2023_1.png) + +The Server Actions category has three actions and three subcategories, described below: + +#### Execute Action Group { #execute-action-group } +Executes a specified Action Group. + +#### Remove Delayed Actions { #remove-delayed-actions } +Removes delayed actions, with the following options: + +- `Remove all delayed actions` - removes all delayed actions regardless of delay type +- `Remove for device` - removes any delays for the selected device +- `Remove for trigger` - removes any delays from the selected trigger +- `Remove for schedule` - removes any delays from the selected schedule + +#### Reset Interface Connections { #reset-interface-connections } +Resets the Insteon and X10 RF interfaces. + +#### Script and File Actions +![Script Actions Type Menu Image](../../images/script_actions_type_menu_2023_1.png) + +##### Execute Script { #execute-script } +![Execute Script Action Image](../../images/execute_script_action.png) + +The `Execute Script` action allows you to execute a Python script as an embedded script or stored in a script file. In general, you should use embedded scripts for scripts that are short and very quick to execute. + +Embedded scripts will be limited to 10 seconds of execution time - if they run longer than that they will be killed. If you have a script that is a long running script you should save it in a separate file and execute it from the file by selecting the File radio button then selecting the file. Scripts executed from files are executed in their own process and are therefore much less likely to adversely effect the server process if they don't work as expected. + +For embedded scripts, you can click the `Compile` button and we'll do our best to check the script for syntax errors. Click the `Run` button to have the script executed immediately. + +##### Open File +![Open File Action Image](../../images/open_file_action.png) + +This will open the specified file (full path using *nix slashes ("/")) using the default application. If it's the path to an application (e.g. "/Applications/TextEdit.app") then it will launch that app. You can also add command-line options and include [Indigo substitutions](../automation/substitutions.md). Note: file paths that contain spaces will need to have the spaces escaped with a backslash - /some\ path/that\ has/escaped\ spaces/. + +##### Run Shell Script +![Run Shell Script Action Image](../../images/run_shell_script_action.png) + +This will run the specified script file optionally with the output being inserted into the specified variable. The script must be marked executable and **a valid** shebang (#!/path/to/shell) must be specified at the top of the script. You can also add command-line options and include markup that will do variable (%%v:VARIDHERE%%) and device state (%%d:DEVIDHERE:STATEIDHERE%%) substitutions. Note: file paths that contain spaces will need to have the spaces escaped with a backslash - /some\ path/that\ has/escaped\ spaces/. + +**Note**: if you're running a Python script you'll probably just want to use the Execute Script action since script files run from this plugin won't have access to the IOM (*`import indigo`*, which is Python-only). + +#### Log Actions +![Log Actions Type Menu Image](../../images/log_actions_type_menu_2023_1.png) + +##### Write to Log +![](../../images/write_to_log.png){ width=600 } + +This will write the specified text into the event log - optionally with the specified type string. The **Text to Log** field supports the various [Indigo substitutions](../automation/substitutions.md). + +In addition, you can select from three logging levels: `Info (normal)`, `Warning`, or `Error`. The log message will be appropriately colored based on the chosen logging level. + +##### Email Event Log Data +![Email Log Action Image](../../images/email_log_action.png) + +This action will send an email to the specified email addresses that contains the specified number of lines from the log file. This is useful for debugging problems (among other things). Tip: this action is also available interactively by selecting the `Help->Email Log...` menu item. + +##### Enable/Disable/Reload Actions { #enable-device } +![Enable Type Menu Image](../../images/enable_type_menu_2023_1.png) + +`Enable Device` - This action will enable Indigo communication with the selected device. You can specify an optional complementary `Auto-disable after X minutes` action. + +`Enable Trigger` - This action will enable processing of the selected trigger. You can specify an optional complementary `Auto-disable after X minutes` action. + +`Enable Schedule` - This action will enable processing of the selected schedule. You can specify an optional complementary `Auto-disable after X minutes` action. + +`Disable Device` - This action will disable Indigo communication with the selected device. You can specify an optional complementary `Auto-enable after X minutes` action. + +`Disable Trigger` - This action will disable processing of the selected trigger. You can specify an optional complementary `Auto-enable after X minutes` action. + +`Disable Schedule` - This action will disable processing of the selected schedule. You can specify an optional complementary `Auto-enable after X minutes` action. + +`Reload Plugin` - This action will restart the specified plugin. You must know the ID of the plugin: you can copy the ID in a [plug's submenu on the Plugins menu](plugins.md#individual-plugin-submenu) or from the plugin's detail page in the [Plugin Store](https://www.indigodomo.com/pluginstore/). + +![Reload Plugin Dialog Image](../../images/reload_plugin_dialog.png) + +#### Get Contents of URL +Use this action to query an API and (optionally) save the results to an Indigo variable. For more details on this action type, refer to the [Get Contents of URL Action](../automation/get-contents-of-url.md) page. + +#### Run Apple Shortcut +Use this action type to allow Indigo to fire Apple Shortcuts, provided your server is running a version of macOS that supports the Shortcuts app. The configuration dialog will present a list of all Shortcuts on the server machine as well as an input field to pass optional text to the selected shortcut when it's run. + +![](../../images/run_apple_shortcut.png){ width=600 } + +The mechanism in Shortcuts to get a dictionary from input is extremely picky about the JSON that it's fed. When checked, the checkbox in this dialog explicitly encodes the input as JSON to make things work better. It defaults to off so existing shortcuts won't be encoded. If you pass an [event substitution](../automation/substitutions.md) in the input field like *`%%e:"some_data[0].value"%%`*, you will need to tick the Send JSON checkbox before the shortcut will work. + +You can also optionally save any return data to a variable. + +### Variable Actions +![Variable Actions Type Menu Image](../../images/variable_actions_type_menu.png) + +There are five actions that are specific to variables: + +#### Modify Variable { #modify-variable } +![Modify Variable Action Image](../../images/modify_variable_action.png) + +Select a variable to modify, then select the options. + +#### Insert Device State into Variable +![Insert Device State Into Variable Action Image](../../images/insert_device_state_into_variable_action.png) + +This will insert the selected state of the selected device into the specified variable. After you specify the device, click the `Edit Action Settings...` button and it will open a dialog (shown above) with a list of all possible states for the device you selected and a popup of all variables. You can create a trigger that executes when a device's state changes and have it insert the new state into the variable. + +#### Insert Timestamp into Variable +![Insert Timestamp Into Variable Action Image](../../images/insert_timestamp_into_variable_action.png) + +Click the `Edit Action Settings...` button and it will open a dialog (shown above). Here you will select the variable and, optionally, the format string as defined in the [Python datetime string formatting](http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior) documentation (see the chart at the bottom for format specifiers). The format in the `Format string` field is the default format. + +#### Insert Event Data into Variable +![Instert Event Data into Variable](images/insert_event_data_into_variable.png){ width=600 } + +Click the `Edit Action Settings...` button and it will open a dialog (shown above). Here you will select the variable and, optionally, the `Path string` if you want to access specific parts of the event data. More information can be found on the [Path Strings](../../scripting/reference/event-data-paths.md) page. + +#### Toggle Variable +![Toggle Variable Action Image](../../images/toggle_variable_action.png) + +Click the `Edit Action Settings...` button and it will open a dialog (shown above). Here you will select the variable and the values that will be toggled. The first 4 options (`true/false`, `on/off`, `yes/no`, `enabled/disabled`) on the `Toggle values` menu are self explanatory (although note that values will be converted to lower-case for comparisons). The last option, `Custom Values`, will allow you to specify the values. We will first try to match the custom variables without converting to lowercase (some unicode characters behave oddly when lowercased) and if we don't find a match then we'll convert. Finally, if nothing matches, we'll just set the value to the first value. + +#### Set Variable to Variable +![Set Variable to Variable Action Image](../../images/set_variable_to_variable_action.png) + +Click the `Edit Action Settings...` button and it will open a dialog (shown above). Here you will select the destination and source variables. + +### Notification Actions +![Notification Actions Type Menu Image](../../images/notification_actions_type_menu.png) + +In the standard install of Indigo, there is one action: Send Email. Plugins are allowed to add menu items to this category so there may be more options if you've installed some 3rd party plugins. + +#### Send Email { #send-email } +Email support is handled by the Email+ plugin - see [the plugin's documentation](../../plugins/email.md) for details on how to configure and use it. + +#### Send Indigo Log Email +Use this action to send the Indigo log in an email. + +### Z-Wave Actions +![Z-Wave Actions Type Menu Image](../../images/zwave_actions_type_menu.png) + +#### Modify Configuration Parameter +![Z-Wave Modify Configuration Parameter Action Image](../../images/zwave_modify_config_param_action.png) + +Some Z-Wave devices provide configuration options through the use of configuration parameters. These are generally outlined in the documentation that comes with a device. Indigo often times support setting these parameters directly in the device config dialog, but because of the sheer number of Z-Wave devices we can't add every one. This menu item will allow you to set any config parameter that a device accepts. + +**Note**: this process can cause your device to not function correctly if incorrect parameters are entered so you'll want to make sure you are very careful to use only the params specified for the specific device. + +#### Send Raw Z-Wave Command +![Z-Wave Send Raw Command Action Image](../../images/zwave_send_raw_command_action.png) + +This menu selection can be used to send arbitrary Z-Wave protocol-level commands to any Z-Wave device. This is generally only useful when Support instructs you to do so. Note battery operated devices allow for the option to queue the command to be sent the next time the device wakes. + +#### Inclusion Mode Commands +This set of actions all require no parameters - they simply control the inclusion process. + +- `Start Controller Inclusion Mode` - this will tell the Z-Wave interface to start looking for inclusion requests on the network, and when one is seen it will include the device **without** encryption (recommended for the majority of device types for performance reasons) +- `Start Controller Inclusion Mode with Encryption` - this will tell the Z-Wave interface to start looking for inclusion requests on the network, and when one is seen it will include the device **with** encryption (recommended only for the most sensitive device types like locks) +- `Start Controller Exclusion Mode` - this will tell the Z-Wave interface to start looking for exclusion requests on the network, and when one is seen it will exclude the device (remove it from the network) +- `Stop Inclusion / Exclusion` - this will tell the Z-Wave interface to stop looking for inclusion and exclusion requests on the network + +#### Start Z-Wave Network Optimize +![Z-Wave Network Optimize Action Image](../../images/zwave_network_optimize_action.png) + +Indigo can optimize your Z-Wave network by having devices rediscover which devices they are close enough to communicate with. This information is then reported back to the Z-Wave Controller so network routing tables can be updated. You can specify `All Devices` (which will go through all of your devices - this can be quite time consuming so use during low-traffic times) or you can specify a single device. + +There is a corresponding `Stop Z-Wave Network Optimize` action that will stop the optimization process. + +### Insteon Actions +![Insteon Actions Type Menu Image](../../images/insteon_actions_type_menu.png) + +#### Execute Insteon Scene { #execute-insteon-scene } +![Insteon Scene Action Image](../../images/insteon_scene_action.png) + +There are nine commands that you can send to an Insteon scene: + +- `Scene On` - send the ON command to every device in the group - if the device has an adjustable ramp rate and/or brightness value, those are honored +- `Scene Instant On (to 100%)` - send the ON command to every device in the group - but ignore ramp rates and default brightness values (everything comes on full immediately) +- `Scene Off` - send the OFF command to every device in the group - if the device has an adjustable ramp rate it will be honored +- `Scene Instant Off` - send the OFF command to every device in the group - ignore ramp rates (everything goes off immediately) +- `Scene Increase by 3%` - will send a command to the scene to increase all members by 3% +- `Scene Decrease by 3%` - will send a command to the scene to decrease all members by 3% +- `Scene Start Increase` - will send a command to the scene to begin ramping the devices in the scene up (brighten for lighting loads). The ramping will continue until the `Scene Stop Increase/Decrease` command is sent. +- `Scene Start Decrease` - will send a command to the scene to begin ramping the devices in the scene down (dim for lighting loads). The ramping will continue until the `Scene Stop Increase/Decrease` command is sent. +- `Scene Stop Increase/Decrease` - will send a command to the scene to stop any ramping started by the Scene Start commands above. + +The `Scene:` popup represents the Insteon scene number - any name that you've assigned to that scene will also show up in the text field beside it (you can change the name there also if you like). Use the `Send On` and `Send Off` buttons to test your scene commands. + +The table will show you what devices are in the scene. The columns are pretty self explanatory perhaps with the exception of the Status column. That column shows the status of the device's **settings** in the scene (edited, added, deleted, etc.) because you can modify scenes without actually performing the link sync. If you have a scene that isn't working correctly the value in that column might help you understand why it isn't working. + +Finally, if you need to add, modify, or delete a device from the scene, click on the `Modify this Scene...` button. See the [Indigo and Insteon Link Management](../interfaces/insteon/index.md#managing-insteon-links) page for more details. + +#### Send Raw Insteon Command +![Insteon Raw Action Image](../../images/insteon_raw_action.png) + +This action will allow you to send a raw Insteon command to any Insteon device. You can send standard messages (2 bytes) or extended messages (16 bytes). You can also have the results of the command inserted into a variable for later processing. + +### Plugin Actions + +Plugins may provide actions that can perform a variety of tasks. See the plugin's documentation for more details. You can [check the list of built-in plugins](../../plugins/index.md) for actions they provide. + +### Action Options +![Lower Action Dialog Image](../../images/lower_action_dialog.png) + +There are three options to each action (and in fact are the only configurable options if you select `None` as the action `Type:`): + +- `Delay by hours:minutes:seconds` - this will delay the execution of the action by some amount of time (not over 24 hours) +- `Override previous delay` - this will automatically delete any previous delays specified for the action above +- `Speak` - if you enter text in the text box Indigo will use the voice synthesis to speak the text + + +## Managing Multiple Actions { #managing-multiple-actions } +![Lower Action Dialog Image](../../images/lower_action_dialog.png) + +Use the `Add New` button below the `Speak:` text area and the separator if you would like to add an additional action. You can then use the `Prev` and `Next` buttons to select which action's settings are being displayed. Press the `Show All` button to see a list of all the actions: + +![Multiple Actions List Image](../../images/multiple_actions_list.png) + +You can then Duplicate or Delete the selected action, or use the `Up` / `Down` buttons to reorder the list of actions. To edit a specific action's settings, double-click on the action or press the `Edit...` button. + +****Important!**** +While you can order the actions in any order you like, Indigo will attempt to execute all actions in parallel. It's not always possible for various reasons, but that's the intent. If you want to order the execution, then you'll need to add delays which will delay the action's execution from the time of the event. So, if you have 3 actions and you want the first to execute immediately, the second to execute a minute after the event, and the third to execute two minutes after the event, then add a one minute delay to the second and a two minute delay after the third. + + +## Action Groups { #action-groups } +Action Groups are groups of actions that can be specified separately from [Trigger](triggers.md#triggers), [Schedule](schedules.md#schedules), and [Control Page](control-pages.md#control-pages) elements, so that they can be reused. For instance, if you have a group of lights you turn on at the same time, you can create an action group for those lights and just execute that group as part of the various triggers, schedules and control page elements. If you need to add a light, you only need to add it to the group rather than edit each individual trigger, schedule, etc. that needs to control that group. Action groups are also optionally shown in remote clients so it's an easy way to control some collection of devices from those clients without having to adjust each one manually. + +> It is important to note that individual actions are run independently. If you need your actions to be executed in a specific order, you can use "Delay by" (see image). Very often, even short delays will be enough). + +To create a new action group: + +1. Select `Action Group List` from the `View` menu. +1. Press the `New...` button at the top of the main window. +1. `Name` the group, for example "going to bed." +1. Optionally give the group some `Notes`. +1. Select the action `Type:` and select the various options. (See the [actions](#actions) section above for details on all of the action's settings, and information on [managing multiple actions](#managing-multiple-actions) to the Action Group) + +![Action Group Dialog Image](../../images/action_group_dialog.png) + +Indigo includes a built-in Web server that allows remote execution of your Action Groups from [Indigo Touch](http://www.indigodomo.com/touch) or any modern Web browser (Safari, Firefox, Opera). Follow the instructions in the [Starting Indigo Server](../getting-started/installation.md#starting-indigo-server) section of the Getting Started guide to make sure that the following options are enabled: `Start and connect to Indigo Server on this computer`, `Allow remote access`, and `Enable iPhone, iPod touch, and remote Web browser access`. + +The `Display in remote UI` option at the bottom of the dialog will make this action group show up in remote clients like Indigo Touch or the web pages. When you see them in those UIs you can tap/click the action group and it will be executed so it's an easy way to control scenes from those clients. + +!!! tip "TIP" + if the Action Group is in a folder, that folder must also be marked for [Remote Display](../mac-client/home-window.md#outline-view). diff --git a/reference/canonical/user/concepts/conditions.md b/reference/canonical/user/concepts/conditions.md new file mode 100644 index 0000000..1150a81 --- /dev/null +++ b/reference/canonical/user/concepts/conditions.md @@ -0,0 +1,91 @@ + + +# Conditions { #conditions } +On the Trigger and Schedule dialog, there's a tab named `Condition`. If you select this tab, you'll see something like this: + +![Conditions Tab Image](../../images/conditions_tab.png) + +Conditions allow you to specify extra logic that's evaluated at execution time to determine if the actions associated with the trigger or schedule should be executed. Most conditions will be set to `Always` - in other words, there are no additional conditions associated with the trigger or schedule. However, there are many situations where you need to factor in other information at execution time that can help determine if the actions should be performed. + +A simple example might be a motion sensor triggering a light - you might want motion detected by the motion sensor to turn on a light, but only between the hours of 6pm and 11pm. You can currently do that by creating a schedule that enables a trigger at 6pm and another one that disables the trigger at 11pm. But that's 3 moving parts (two schedules and the trigger). Using a condition, you can reduce that to just a single trigger and the following condition: + +![Motion Sensor Condition Example Image](../../images/motion_sensor_condition_example.png) + +This condition says that if the current time is greater than 6pm and less than 11:00pm then the actions will be executed. + +Another example that can't be accomplished easily without writing a script is having multiple conditions. For instance, let's say you have a sprinkler schedule that runs periodically. However, there are several conditions in which you don't want the sprinkler to run: + +1. if you've left your windows open +1. if it's too cold outside +1. if it has rained more than 3/4 of an inch in the last 24 hours. + +Let's assume that you have a script running that populates Indigo variables with data from a weather station: "rain_total" holds the rain total for the last 24 hours, and "outside_temp" holds the temperature in Fahrenheit. Further, let's say you have a variable, "windows_open", that's either true or false indicating whether the windows in your house are open or not. + +Given all of these conditions, here's how the condition editor would look: + +![Sprinkler Condition Image](../../images/sprinkler_condition.png) + +This is a negative condition - if `None` of the rules are true then the actions will execute. It could also be written as an `All` rule if you switched the tests around: + +![Sprinkler Condition Using All Image](../../images/sprinkler_condition_using_all.png) + +This version says that if `All` the conditions are true (windows aren't open, temperature is greater than 40, and rain total is less than 3/4 of an inch) the actions will execute. + +Note for variable comparisons: `is true` will evaluate **true** if the value is one of these: "true", "on", "yes", and "1" and will evaluate **false** if it's anything else. `is false` will evaluate **true** if the value is one of these: "false", "off", "no", and "0" and will evaluate **false** if it's anything else. + +To add a rule, click the plus (+) button next to a rule to add a rule directly below it. Click the minus (-) button to remove a rule. To create a sub-rule group, hold down the option key on your keyboard and the plus button becomes an ellipsis (…) button. Clicking on this will create a sub-rule group (Any, All, None). For instance, here's an arbitrarily complex (but nonsensical) rule with several sub-groups: + +![Complex Condition Rule Image](../../images/complex_condition_rule.png) + +To reorder rules, simply drag them around. As you can see, the condition rule editor is extremely powerful - you can create complex multiple conditional logic without resorting to a script. And it's available to Lite users as well (whereas script conditions aren't). The Insert into Event Log Window button will put a textual representation of your rule into the event log for handy copy/paste into a forum post - this will help others see what your logic is to assist in debugging: + +```text +"All" "of the following rules are true" + "If dark" + "Any" "of the following rules are true" + "If current date" "is between" 8/1 "and" 8/31 + "If variable" houseMode "is equal to" "value" "away" + "None" "of the following rules are true" + "If variable" test1 "is equal to" "variable" test2 + "If variable" test3 "is between" "5" "and" "10" +``` + +## Condition Scripts +If, however, you still can't express your conditional logic using the rule editor, you can still select the `If Python script returns True:` radio button and write a Python script that programmatically returns **True** or **False**. + +For example, +```text +if [some condition evaluates as True]: + return True # the condition passed so your trigger or schedule will execute +else: + return False # the condition didn't pass so your trigger or schedule will not execute +``` +The `*return False*` component is optional since only a `*True*` return will be acted upon. + +In Indigo {{ version }}+, you can access the new Event Data dictionary that's passed through the chain to perform custom logic. For instance, you can create a simple condition script that will look at the event data from a Z-Wave Command Received trigger to decide if you want the actions to process or not. This is what the event_data dictionary would look like from a Z-Wave Command Received trigger: + +```text +event_data = { + "event-indigo-id": 886317539, + "event-plugin-event-id": "zwaveCommand", + "event-plugin-id": "com.perceptiveautomation.indigoplugin.zwave", + "event-plugin-name": "Z-Wave", + "event-type": "PluginEventTrigger", + "timestamp": "2025-07-25T17:18:25", + "zwavecmd-device-id": 1191650674, + "zwavecmd-node-id": 2, + "zwavecmd-scene-id": 255 +} +``` + +The script could look something like this: + +```text +# Devices that you want to continue processing +my_device_list = [1234567890, 837603829, 1191650674] +if event_data["zwavecmd-device-id"] in my_device_list: + return True +return False +``` + +The `event_data` dictionary is automatically made available to your script, so you can just get the Indigo device ID out of that dict and see if it's in the list of device IDs in your condition script. If it is, it will continue processing, if not it will stop processing. diff --git a/reference/canonical/user/concepts/control-pages.md b/reference/canonical/user/concepts/control-pages.md new file mode 100644 index 0000000..3a29d86 --- /dev/null +++ b/reference/canonical/user/concepts/control-pages.md @@ -0,0 +1,146 @@ + + +# Control Pages +Control pages are graphical pages that you use to control Indigo, either through a web browser or Indigo Touch. Indigo has built-in control pages available on the web (Indigo Touch has built-in base functionality that matches them), and also allows you to design custom graphical pages - from the background image and/or color to the placement of text labels, control images, and what actions clicking/tapping on those images performs. + +## Control Page Editor { #control-page-editor } +To create a new Control Page, select `View->Control Pages`, then click the `New...` button above the control page list. You will be shown the control page editor window: + +![Control Page Editor Image](../../images/control_page_editor.png) + +The editor window has 4 areas - the first is the the global control area. In this area you'll find buttons to create new page elements (labels, controls, etc), duplicate existing elements, delete elements, and turn on/off some features of the editor. Select `Snap to grid` to have page elements snap to a grid that overlays the design area (see the next item). Select `Show grid` to show the aforementioned grid. Select Edit z-order to show you the order of the page elements and allow you to change them. Higher numbered elements are drawn last, so if you have overlapping controls the one with the highest order will be drawn last. + +The second area is the design area. This is where you'll graphically lay out your control page. It operates much like many drawing programs - you select objects and drag them around to position them. The default new control page contains two elements: a graphical server status icon and a server status text area. By the way, you can have only one of each of these element types on your control page. + +The white area is the visible area that you'll see on the web page or in Indigo Touch. The gray area is just the image border area - items in the gray area will not show on the control page. If you have the `Edit z-order` checkbox described above checked, you'll see controls like this for each page element: + +![Page Element Examples Image](../../images/page_element_examples.png) + +In the example above, you see 4 page elements: the graphical server status element, the server status text area, a device state element using a ceiling fan image, and another device state element using a lightbulb image. The ceiling fan element is selected, as you can tell by the blue brackets at each corner of the image. Because I also have the z-order checkbox selected, you see the `z: #` next to each element, and above and below that for the selected element you see up/down arrows, one with a line above/below and one without. The arrows that aren't pointing to lines will move the element up/down one step at a time. The arrows that point to lines will move the element to the top/bottom of the element hierarchy. + +If you have a page element that's showing a textual description, then you'll notice a little resize icon at the lower left corner of the text - this control will allow you to adjust the width of the text field so that it can accommodate longer test. Text can only be a single line at the moment but you can make it as wide as the entire page. + +The third area is the page element detail area. This area changes based on what's selected in the design area and what options are selected for the page element. If no page element is selected in the design area, then you'll see the information about the page itself: + +![Control Page Information Image](../../images/control_page_information.png) + +This is where you set global information about the page itself. The `Page Name:` and `Description:` fields are pretty self-explanatory. Check the `Hide Tab Bar at bottom of Indigo Touch when shown` to have the bottom navigation bar hidden when this page is viewed in Indigo Touch. You can use a `Background image:` by selecting it from the popup, such as a floorplan or other image. You can add your own image by creating a PNG file and adding it to the backgrounds folder (to open that folder in the Finder just click the `Show Folder` button - and if you add an image while Indigo is running, click the `Refresh` button to have it added to the popup). **Note**: some versions of Indigo don't like spaces in the background image name so just replace spaces with another character such as an underscore. + +If you aren't using a background image, your background image is smaller than the total size of the page, or if your background image has transparency identified, you can specify the color of the rest of the background by clicking on the `Background color:` colorwell. Finally, you can have the page size constrained to the size of the background image or you can specify your own page size. Here are a few design tips for designing pages for Indigo Touch on various devices: + +- iPhone/iPod touch + - Viewable Portrait size: 320x416 + - Viewable Landscape size: 480x268 +- iPad + - Viewable Portrait size: 768x960 + - Viewable Landscape size: 1024x704 + +If you look closely at the numbers, you'll see that on the iPad, the Indigo Touch header that's displayed above the control page is 64pix regardless of screen orientation. However, it appears that the header is decreased to 52px when in landscape mode on the iPhone/iPod touch. This is verified in both iOS 3.x and 4.x. + +[Page element details](#page-element-details) will vary based on what's displayed - we'll go into those details a bit later. + +The final section is the bottom control area - the `Help`, `Cancel`, `Browser Preview`, and `Save and Close` buttons are also pretty self-explanatory (the Help button may have gotten you to this page in fact). + +### Other Editor Features +The Control Page editor now supports Cut/Copy/Paste between control pages as well as drag and drop. You can drag and drop page elements between pages and drop devices on a control page to add them. You can also drag control page elements to the Finder, which will create a clipping file. You can then switch databases, and drag those clipping files back onto a control page and it will import them. The clipping files will initially be titled with the XML text that's being exported, but you can change the name of the clipping file - so if you're sending it to someone else you can give it a more descriptive name. This is a good way to share groups of page elements with others. + +The Control Page list in the [Home Window](../mac-client/home-window.md#home-window) will allow you to drag Control Pages out to the Finder. This will create a clipping file that can then be dragged back onto the Control Page list (for instance, in another database) and the whole control page will be recreated. Note, however, that if the target doesn't have the same devices, variables, action groups, and images, you'll need to edit the resulting page elements. The clipping files will initially be titled with the XML text that's being exported, but you can change the name of the clipping file - so if you're sending it to someone else you can give it a more descriptive name. This is a good way to share control pages with others. To import a control page, just drag it from the Finder to the Control Page list. + +### Page Element Details +As we stated above, each page element represents some kind of object - also called controls. Specifically, there 6 different types of controls. + +#### Device State +![Device State Page Element Image](../../images/device_state_page_element.png) + +When you select `Device State` from the `Display:` popup, you're shown a list of devices in the `For:` popup. Once you've selected a device, the next popup will show the list of states for that device. + +The next row of options allow you to have the control represented by an image or in text. Images may be used to represent the state of most common devices - we provide quite a few different images. If you'd like to use custom images, check out the section below on creating and using [custom images](#custom-images-on-control-pages). + +The next row of options is for the `Caption:` field - static text that can be used as a label for the control. It can be placed on any side of the control (left, right, above, below) as well as centered on top (good for buttons). + +The next two options, `[Client action:](#client-actions)` and `[Server action:](actions.md#server-actions)` allow you to specify what happens when the control is interacted with (via click or tap) and are describe in separate sections below. + +#### Variable Value +![Variable Value Page Element Image](../../images/variable_value_page_element.png) + +Variable Value controls have the exact same options as [device state](#device-state) controls, but rather than use the device state it uses the value of the variable you selected in the `For:` popup to select the correct image or as the text to display. + +#### Static Image/Caption +![Static Image Page Element Image](../../images/static_image_page_element.png) + +Static Image/Caption controls are simpler than the other controls: they can have an image and/or static text caption. + +#### Refreshing Image URL +![Refreshing Image URL Page Element Image](../../images/refreshing_image_url_page_element.png) + +Refreshing Image URL controls allow you to specify a URL to an image that is refreshed periodically (specified in the `Refresh rate:` popup). Just specify the image size, URL, and refresh rate. + +You can include markup that will do variable (%%v:VARIDHERE%%) and device state (%%d:DEVIDHERE:STATEIDHERE%%) substitutions as a part of a refreshing image URL. Note: file paths that contain spaces will need to have the spaces escaped with a backslash - *`/some\ path/that\ has/escaped\ spaces/`*. When you use substitutions in refreshing image URLs, you will receive a warning in the event log (when you edit the control page -- not each time the control page is displayed): + +*`Warning (client) control page image URL contains a substitution: you will have to manually specify the image size for it to display correctly`* + +As the warning suggests, you'll have to manually set the width and height of the control to match whatever the refreshing image will be after the substitution or the image will be distorted when it's displayed. + +#### Server Status Text +![Server Status Text Page Element Image](../../images/server_status_text_page_element.png) + +This control will show the latest status update message from the server as text. You can have only one of these controls on your control page. + +#### Server Status Icon +![Server Status Icon Page Element Image](../../images/server_status_icon_page_element.png) + +This control will show a spinning icon when the server is performing some request for the control page. You can have only one of these controls on your control page. + +#### Client Actions +![Client Actions Control Page Popup Image](../../images/client_actions_cp_popup.png) + +For every page element, you can have one of three client actions performed whenever the page element is clicked/touched: + +1. `Popup UI Controls` - this will cause the client to pop up a dialog with the controls appropriate for the device or variable selected (it doesn't do anything for other page element types). +1. `Advance to Control Page` - this will cause the client to display the selected control page. This version will leave bread crumbs so you can come back to the current page using the back button (a new browser window if the `Opens new window` checkbox is checked). +1. `Replace with Control Page` - this will cause the client to display the selected control page. This version will replace the current page such that the back button won't go back to the current page (no bread crumbs). +1. `Back to Previous Page` - this will cause the client to go back to the previous page. Useful if you want to create your own navigation. +1. `Back to Control Page List` - this will cause the client to go back to the list of available control pages. Useful if you want to create your own navigation. +1. `Go to External URL` - this will cause the client to open the provided URL in a browser window (a new browser window if the `Opens new window` checkbox is checked). In Indigo Touch, it will cause Mobile Safari to open and show the page specified by the URL. + +#### Server Actions +Every page element may also have server actions performed - these are the typical [actions](actions.md#actions) described above. Just like [Triggers](triggers.md#triggers) and [Schedules](schedules.md#schedules), you can specify a single action or multiple actions. + +### Show in Browser +In the main Control Pages view in the Indigo Client UI, you can select a Control Page and then click on *`Show in Browser`* to view the page in your default browser. Once that's done, you can take note of the URL in your browser's address field should you want to copy it and create a bookmark or other link to load the page directly in the future. The direct URL will look something like, *`http:*my_indigo_ip:8176/web/controlpage.html?id=123456789`* where *`123456789`// is the Indigo ID of the page. + +## Custom Images on Control Pages { #custom-images-on-control-pages } +There are several sub-folders to add custom images to control pages inside: + +```text +/Library/Application Support/Perceptive Automation/Indigo YYYY.R/Web Assets/images/ +``` + +Note Indigo 7 and earlier stores the images inside: + +```text +/Library/Application Support/Perceptive Automation/Indigo X.Y/IndigoWebServer/images/ +``` + +And also note that's the Library folder at the top level of your hard drive, not the one in your user directory. You'll find a couple of directories under there: + +- `backgrounds` - put images here that you want to use for control page backgrounds +- `controls` - in this directory, there are 3 more: + - `devices` - in this directory, put in images to represent devices. In Indigo 4.1 and higher, we've added some heuristics that will allow you to add many more images. See [Image Selection Heuristics](#image-selection-heuristics) below for details. + - `static` - in this directory, you can just put static images that are shown when you select `Static Image / Caption` from the `Display:` popup in the control page editor. + - `variable` - in this directory, you can put images that represent variables. In Indigo 4.1 and higher, we've added some heuristics that will allow you to add many more images. See [Image Selection Heuristics](#image-selection-heuristics) below for details. + +So, adding images is as simple as inserting them into the correct directory above based on what you want to use them for and restarting the Indigo Server. Images should be in the PNG format. When upgrading Indigo, v7 and above should automatically move over any custom images, but you may need to move them over manually if upgrading from an older version. Also, if you edit an existing custom image, you may need to restart the client (or clear the cache in Indigo Touch from the settings dialog) in order to see the changes. + +### Image Selection Heuristics +Before v4.1, we had a simple mechanism for selecting images based on values: for devices, you could have a file named `MyDeviceImage.png`, which would be shown if the device was OFF, and `MyDeviceImage+on.png`, which would be shown if the device was ON. Likewise, for variables, you could create an image called `MyVariableImage.png`, which would show when false, and `MyVariableImage+true.png` which would show when the variable value was true. + +We've expanded the image selection criteria so that it can find much more interesting images based on values. To signify that an image should use these more complex image heuristics (described below), end the base file name with a "+": `ImageName+.png`. The "+" at the end is a hint to the Indigo Web Server and Indigo Touch that it may need to contact the server for the right image. The heuristic works like this now: + +1. Search for an image of the form `ImageName+VALUE.png`, where VALUE is the current value. For ON/OFF type devices it will be on and off; just like before. For devices that have numerical state values (brightness, temperature, etc.) it will be the numerical value for that state. For variables, it's a bit different: it will be an exact match of the current value of the variable. So if your current variable value is "summer", then we'll look for an image named `ImageName+summer.png`. Spaces should work correctly as well, but other special characters may cause problems, so be careful as you plan specific values. If the variable value is empty then the base image `ImageName+.png` will be used. +2. If a match isn't found above, then Indigo attempts to find a numeric match in the following way: search for an image with a name that is the closest increment counting by 5. So, for instance, if the value of the device or variable is 13 (and there was no exact match to `ImageName+13.png`), we'll look for an image named `ImageName+15.png`. If that isn't matched, we'll look for the next closest increment counting by ten (in this example, `ImageName+10.png` since 13 is closer to 10 than to 20). Next, we'll look for the next increment counting by 20 (`ImageName+20.png`). Finally, if that isn't matched, we'll look for the next increment by counting by 25 (`ImageName+25.png`). This will work for variables that are valid integers (whole numbers) as well. +3. If neither #1 nor #2 match, then the intention was to have the base image `ImageName+.png` displayed. (A bug in image selection in Indigo 5 and fixed in later versions however will result in no image. A workaround is to add an image named `ImageName+true.png` which will be used in this case.) + +Note that the dimensions of all the images with the same base image name must be the same. If they are not the layout of some of the images will be incorrect. + +We think this will give you much more flexibility in displaying images that match your needs. This works for all control pages regardless of whether they're viewed in a web browser or in Indigo Touch. diff --git a/reference/canonical/user/concepts/deletion-dependencies.md b/reference/canonical/user/concepts/deletion-dependencies.md new file mode 100644 index 0000000..d61c1ac --- /dev/null +++ b/reference/canonical/user/concepts/deletion-dependencies.md @@ -0,0 +1,21 @@ + + +# Deletion Dependencies + +!!! abstract "In this guide" + When deleting an Indigo object, a confirmation dialog shows any dependent objects that will also be affected or + deleted. You can also inspect dependencies at any time by right-clicking an object and choosing Show Dependencies. + +When an object (Device, Trigger, Schedule, Action Group, Control Page, or Variable) is deleted, you will be presented a dialog to confirm. If there are any other objects that are dependent on the object you're deleting, the dialog will show you the dependencies. + +![Dependency Sheet Image](../../images/depencency_sheet.png) + +If you double-click on the dependency, the edit dialog for that object will open so you can change/remove it. If you want the dependent objects to be deleted, just click the `Delete` button. + +Specifically - if the object being deleted will render the dependent object useless. For instance, a trigger event that's defined with the device you're deleting in the device state changed definition, then the entire object will be deleted - in this case the trigger. Same with conditions. If the object is used in one of several actions or if it's used on a control page, just the action or page element will be deleted. + +You may also right-click on any object to pop up the contextual menu and a new menu item, Show Dependencies, will allow you to open a separate window showing the dependencies for the object: + +![Dependency Window Image](../../images/dependency_window.png) + +This should be a big help in figuring out what a given object's dependencies are and allow you to quickly change those relationships. diff --git a/reference/canonical/user/concepts/devices.md b/reference/canonical/user/concepts/devices.md new file mode 100644 index 0000000..e63dc56 --- /dev/null +++ b/reference/canonical/user/concepts/devices.md @@ -0,0 +1,39 @@ + + +# Devices { #devices } +Devices in Indigo are "things" that Indigo can interact with. Not only can Indigo interact with Z-Wave®, Insteon, and X10 devices but Indigo also supports devices provided by third party plugins. This greatly expands the kind of devices that can be defined in Indigo. + +There are two primary ways you can use a device in Indigo: you can use changes in its various states to [trigger](triggers.md#triggers) some actions (e.g. when the motion sensor detects motion) and you can tell a device to perform some action (e.g. turn on the porch light). Indigo also provides you various ways to interactively control these devices and inspect their state (Indigo Touch, Indigo Web Server web pages, etc.) + +Here is the device dialog: + +![Device Dialog New Image](../../images/device_dialog_new.png) + +The first thing that you need to select is the `Type`. Indigo includes support for the following device types: [Z-Wave](../interfaces/z-wave/index.md), [Insteon](../interfaces/insteon/index.md), and [X10](../interfaces/x10/index.md) (click on the types for details of how to manage devices of that type). Indigo also has a [Virtual Devices interface type](../interfaces/virtual-devices.md) and the following plugins which add additional device types: + +- [EasyDAQ Relay Card](../../plugins/easydaq_1.md) +- [NOAA Weather](../../plugins/noaaweather.md) +- [Timers and Pesters](../../plugins/timersandpesters.md) + +If you add other 3rd party plugins that supply devices, they will show up on the `Type` menu as well. There are over 95 3rd party plugins listed on our [Plugin List](http://www.indigodomo.com/plugins) that cover many other types of devices, including alarm panels, media servers, A/V equipment, and much more. If you're a programmer and would like to develop plugins, check out our [Plugin Development](../../plugin-dev/index.md) section for all the docs you need to get started building Indigo plugins. + +Once you've selected a device type, the fields and buttons between the `Type` popup and the tab view at the bottom of the screen will adjust based on the type of device that you select. The tab view will show at least one tab (titled "Settings") for every device. Here's an example of a Z-Wave module: + +![Device Dialog Z-Wave Image](../../images/device_dialog_zwave.png) + +Inside each tab, you have the `Name` field, which represents the unique name of this device. Next you have the `Notes` field - it's a free-form text field that you can put anything into you want - perhaps to help describe what features you're using, where it's physically located, or significant triggers that use it. You can put whatever you like in that field. + +## Device Options +At the bottom of the tab, you have two options for each device: + +1. `Enable Indigo communication` checkbox - this is useful if you have a device that you're temporarily taking out of service or moving. If you uncheck this checkbox, Indigo will not attempt to communicate with it in any way - so you won't receive errors in the Event Log when any action is taken for this device. +1. `Display in remote UI` checkbox which, as it says, lets you see this device in remote client applications. + +## Devices with Multiple Personalities +Some devices have multiple "personalities" - in other words a single physical device can actually represent multiple devices. The Insteon FanLinc is one example: it's a single module that has Fan Speed controls and Dimmer controls. In Indigo, each of these is represented as a different device in the various device lists. However, when you edit one of them, each device will be represented in a single dialog with multiple tabs: + +![Fanlinc Dimmer Image](../../images/fanlinc_dimmer.png) +![Fanlinc Fanspeed Image](../../images/fanlinc_fanspeed.png) +![Device Dialog Multiple Personalities Image](../../images/device_dialog_multiple_personalities.png) + +To get started adding devices to Indigo, visit the page that's appropriate for the technology you're using: [Z-Wave](../interfaces/z-wave/index.md), [Insteon](../interfaces/insteon/index.md), [X10](../interfaces/x10/index.md), or visit the documentation for the [plugin](http://www.indigodomo.com/plugins) that supports the devices you want to add. diff --git a/reference/canonical/user/concepts/plugins.md b/reference/canonical/user/concepts/plugins.md new file mode 100644 index 0000000..4ced499 --- /dev/null +++ b/reference/canonical/user/concepts/plugins.md @@ -0,0 +1,129 @@ + + +# Plugins + +## Managing Plugins +Indigo includes the ability to use plugins developed by 3rd party developers (see our [Plugin Store](https://www.indigodomo.com/pluginstore/) for available plugins) and includes a few useful plugins with the Indigo installation. + +### Installing/Updating Plugins { #installing-updating-plugins } +Installing new plugins is pretty simple (updating plugins is the same process, it will just replace the existing one if there is an older version installed). We're going to describe a couple of ways of installing them primarily based on where you get the plugin. While you may get a plugin from anywhere, we recommending getting them from our [Plugin Store](https://www.indigodomo.com/pluginstore/). To download and install a plugin from the store, this is the process (we're using Safari in these steps, so you may need to adjust accordingly if using another browser): + +1. In Safari on your Indigo Server Mac, go to the [Plugin Store](https://www.indigodomo.com/pluginstore/) and navigate to the Plugin you want to install. ![Plugin Store Detail Image](../../images/pluginstore_detail.png) +1. Make sure that the plugin is supported by this Indigo release (look for the **Requires** field). This is an important step because there may be older plugins which aren't compatible with the current version of Indigo. +1. Click the `Download Latest Release` button, which will download the plugin. If the release isn't compatible with your version of Indigo, you can click on the **Releases** tab, and look through the list for a version that works with your version of Indigo (click on it and then click the `Download this release` link). +1. When the download is complete, click on the down arrow in the title bar which will show the plugin download.![Plugin Store Safari Download Image](../../images/pluginstore_safari_download.png) +1. Most plugins will show the plugin directly as the above image. If it does, double click it and proceed to step 8 below. +1. If you see a folder icon (usually with an odd name) in the download dropdown rather than the plugin icon, double-click on the folder and it'll switch to the Finder with the download folder open. +1. In the Finder window that's now showing, you should see the plugin which will end in `.indigoPlugin`. Double-click that file.
![Plugin Install Permission Image](../../images/plugin_install_permission.png) +1. You will be switched to the Indigo Client app, and you'll a dialog window which asks you if you want to install and enable the plugin. You will see a different dialog if the version number is lower than an already-installed version; for safety, Indigo will ask you to confirm that you want to downgrade the plugin. +1. **NOTE**: due to a bug in some macOS releases, this step may try to launch a previous version of Indigo. If it does, quit it, then right-click the plugin file, select the `Open With` menu item, then select Indigo {{ version }}.![Open With Menu Item Image](../../images/openwithmenuitem.png) +1. Click the `Install and Enable` button. +1. Done! + +Many plugins require some kind of configuration for the plugin itself. If that's the case, then when you click the `Install and Enable` button, the plugin's configuration dialog may automatically popup: + +![Plugin Configuration Dialog](../../images/plugin_config_dialog.png) + +Complete the dialog as necessary (sometimes, as with the example above, you don't have to do anything) and click the `Save` button. **Note**: if you click the `Cancel` button, the plugin may not be fully operational until you completely fill out the dialog and save it. + +That's it. As you can see, the experience using the Plugin Store in Safari is straight-forward. However, you may find plugins in other places. When you get a file that ends in `.indigoPlugin` on your Indigo Server Mac, you can always double-click it in the Finder and then you jump to step 8 above. We encourage all of our 3rd party plugin developers to put their plugins in the Plugin Store so it's easy to find them - you should be cautious about installing plugins that you get from other locations. + +### Plugin Menus in Indigo +There are a variety of menus in Indigo which will reflect plugin functionality. The first is the main Plugins menu in the Indigo menu bar. + +#### Main Plugins Menu +This is the meta-menu for many things related to plugins. + +![Plugins Menu Image](../../images/plugins_menu.png) + +The `Reload Libraries and Attachments` menu item will allow scripters to add Python libraries to specific locations and use them in Indigo (see [Shared Classes and Methods in Python Files](../../scripting/tutorial.md#shared-classes-and-methods-in-python-files-python-modules) for details). + +The next section of the menu is dedicated to each plugin that's installed on your system. As you can see, you can tell at a glance the status of the plugin itself: + +- ![Gray Dot Image](../../images/idpng_dot_gray_2x.png) a gray dot means the plugin is disabled +- ![Green Dot No Arrow Image](../../images/idpng_dot_green_2x.png) a green dot with no arrows means the plugin is enabled and up to date. +- ![Green Dot Black Arrow Image](../../images/idpng_dot_greenblackarrow_2x.png) a green dot with a black arrow means the plugin is enabled and there is an update available that will work with your Indigo version +- ![Green Dot Red Arrow Image](../../images/idpng_dot_greenredarrow_2x.png) a green dot with a red arrow means the plugin is enabled and there is an update available but it won't work with your version of Indigo + +There are yellow versions of the dots - the meaning is the same as the green version except it's indicating that the plugin is using an API version that was deprecated with Indigo 2023. You should check the [Plugin Store](https://pluginstore.indigodomo.com) for an updated version or contact the plugin developer. + +- ![Yellow Dot With No Arrows Image](../../images/idpng_dot_yellow_2x.png) a yellow dot with no arrows means the plugin is enabled but needs updating before the next Indigo release +- ![Green Dot with Black Arrow Image](../../images/idpng_dot_yellowblackarrow_2x.png) a yellow dot with a black arrow means the plugin is enabled and there is an update available that will work with your Indigo version - you should install the update before upgrading to the next version of Indigo +- ![Green Dot with Red Arrow Image](../../images/idpng_dot_yellowredarrow_2x.png) a yellow dot with a red arrow means the plugin is enabled and there is an update available but it won't work with your version of Indigo + +There is also a red version of the dot, which can mean several things. + +- ![Red Dot Image](../../images/idpng_dot_red_2x.png) the plugin is not compatible with your version of Indigo and we are not aware of a version that will work with your version of Indigo. +- ![Red Dot Image](../../images/idpng_dot_red_2x.png) the plugin has failed due to a catastrophic error that has caused the plugin to crash or has caused Indigo to stop the plugin. An error will be output to the log to explain the problem. +- ![Red Dot Image](../../images/idpng_dot_red_2x.png) the plugin's *`self.stopPlugin()`* method has been called for any reason. + +We'll discuss how to change/deal with those states later, but this menu provides a very simple visual dashboard for plugin status. + +The `Manage Plugins...` menu item will open the [the Plugins tab of the Indigo Preferences](#the-plugins-tab-of-the-indigo-preferences) and is discussed below. + +The `Plugin Store` menu item will open the [Plugin Store](https://www.indigodomo.com/pluginstore/) in your default browser, and the `Show Scripts Folder` will open the Scripts folder (where you can save external scripts in a version-agnostic way). + +The `Open Scripting Shell` menu item will launch the Terminal app and open a window with a Python shell running with all the Indigo API loaded. See the [Indigo Scripting Tutorial](../../scripting/tutorial.md) for more information. + +#### Individual Plugin Submenu +Each plugin installed will have its own submenu on the `Plugins` menu. For instance, here's the 3rd party [Harmony Hub plugin](https://www.indigodomo.com/pluginstore/32/) submenu when it's enabled: + +![Plugin Enabled Submenu Image](../../images/plugin_enabled_submenu.png) + +The top section will be available for every plugin + + - the first menu item will Enable/Disable a plugin and is a toggle - select `Enable` to enable the plugin and `Disable` to disable the plugin. + - the `Reload` menu item will reload the plugin and will only be present if the plugin is enabled. + - there may be a couple more menus if you have the `Enable debugging menus` item selected in [#the Plugins tab of the Indigo Preferences](#the-plugins-tab-of-the-indigo-preferences) (and are discussed in that section). + +The next section contains: + + - the `Configure...` menu item will open a config dialog if the plugin has plugin-specific configuration items (if not or if the plugin is disabled, it will not be present). + - the `Show in Plugin Store...` menu item will open the plugin's entry in the Plugin Store in the default browser. If there is an available plugin update that will work on your version of Indigo, the menu title will be `Download New Version...` which will also open the plugin's entry in the Plugin Store in the default browser so you can download the new version, and if there is an incompatible version the menu title will be `Incompatible Version Available...` which will drop a sheet showing what version of Indigo is required to run the new plugin version. This menu item will always show, but if it's grayed out it means the plugin isn't from the [Plugin Store](https://www.indigodomo.com/pluginstore/). + - the `Copy Plugin ID` menu item will always show, and when selected will copy the plugin's unique ID for use in scripts. + - the `About...` menu item will always show the current version of the plugin and will always be enabled. + +Any sections below this are specific to the plugin and will contain commands that the plugin presents to the user. If the plugin is disabled, no additional sections will be displayed. + +#### Other Menus with Plugin Items +There are several other places where plugins may insert menu items in the Indigo Mac UI. The first place is in the [Device Create/Edit window](devices.md#devices): + +![Plugin New Device Image](../../images/plugin_new_device.png) + +The top half of that menu allows you to create devices from the built-in interfaces. Anything in the bottom half represents plugins that supply new device types that you can create and use in the same way you work with built-in devices (switches, thermostats, etc.). The next place is in the [Trigger Create/Edit dialog](triggers.md#triggers): + +![Plugin Events Image](../../images/plugin_events.png) + +The last section of that menu will show plugins that supply custom events that you can trigger from. The final place that plugins can add menu items is in the [Action Create/Edit window](actions.md#actions): + +![Plugin Actions Image](../../images/plugin_actions.png) + +There are actually 3 places where plugins can add menu items to the actions windows: The first is at the bottom of the [Device Actions submenu](actions.md#device-actions): menus here are for plugin actions that act on devices. The second place is on the [Notification Action submenu](actions.md#notification-actions): plugins that supply some kind of notification action will put their actions on this submenu. Finally, at the bottom of the [Action Type menu](actions.md#actions) itself: this is where plugins will add actions that don't fit into the other two categories. + +As you can see, plugin integration in Indigo is quite extensive. + +### The Plugins tab of the Indigo Preferences +![Plugins Tab Image](../../images/plugins_tab.png) + +You can also enable/disable a plugin and download a new plugin version from the Plugins tab in the Indigo Preferences. You open the config window choosing the `Indigo {{ version }}->Preferences...` menu item and clicking the `Plugins` tab or by selecting the `Plugins->Manage Plugins...` menu item discussed above. + +You can enable/disable the plugin from this list (by checking the `Enabled` checkbox) and you can double-click on the plugin's name (or select it and click the `Configure...` button) to open the configuration dialog for the plugin (if there is one and the plugin is enabled). Again, if this is the first time the plugin has been enabled this will open the configuration dialog for the individual plugin if the plugin supports a one. + +You can also see the current version of the plugin and the version of the most recent release if there is a newer version. If the newer version is not compatible with your version of Indigo, it will show up in red. Double click the new version number open the [Plugin Store](https://www.indigodomo.com/pluginstore/) entry for that plugin in your default browser where you can download the new version and install (see [Installing Plugins](#installing-updating-plugins) above for the process). + +At the bottom of this tab, you'll notice a section labeled `Development`. There are 2 options here to help plugin developers with the various tasks needed to develop and test plugins: + +- the `Enable debugging menus` checkbox will add two new menus to the plugin's menus: `Reload in Debugger` will reload the plugin and connect to the selected debugger; `Reload in Interactive Shell` will open a terminal window with a Python shell that's connected to the plugin so the developer can run commands and inspect arbitrary objects in the running plugin. +- the `Use debugger` popup is used to tell Indigo which debugger to start the plugin up when you use the above menu items. + +See the [Python Debugger Support](https://forums.indigodomo.com/viewtopic.php?f=2&t=17039#p126068) forum post for further details on how to use these features to aid in developing a plugin. + +### Uninstalling a Plugin +If you would like to permanently remove/uninstall a plugin (rather than just disabling it by unchecking the Enabled button or using the menu item for the plugin), you may do so by following these steps: + +1. In the Indigo app, select the `Help->Show Indigo Server Install Folder` menu item. This will switch you to the Finder and open a window to the Indigo install folder. +1. Switch back to Indigo and shut down the Indigo Server by selecting the `Indigo {{ version }}->Stop Server` menu item in the Mac client (you can leave the client app running). +1. In the Finder window opened in step 1, you'll see two folders: `Plugins` and `Plugins (Disabled)`. Depending on whether the plugin is enabled or not will determine which folder it's in. Open the appropriate folder and delete the unwanted plugin. Check to make sure that somehow there aren't plugins in both locations. +1. Switch back to the Indigo {{ version }} Mac client and click on the `Start Local Server...` button in the `Server Connection Status` dialog. + +The plugin will no longer show in the Plugins tab or in the Plugins menu. diff --git a/reference/canonical/user/concepts/schedules.md b/reference/canonical/user/concepts/schedules.md new file mode 100644 index 0000000..8257bb6 --- /dev/null +++ b/reference/canonical/user/concepts/schedules.md @@ -0,0 +1,49 @@ + + +# Schedules { #schedules } +Schedules are collections of actions that are executed based on a time/date (temporal) specification - they are "scheduled" to execute. Here is the Schedule dialog: + +![Schedule Dialog Image](../../images/schedule_dialog.png) + +As with [trigger dialog](triggers.md#triggers), the schedule dialog has 3 tabs: `Schedule` is for specifying the temporal settings; `Condition` is for specifying further conditions that can determine if the actions are executed, and finally the `Actions` that will execute. [Conditions](conditions.md#conditions) and [Actions](actions.md#action-groups) are discussed in a later section. The two main sections of the `Schedule` tab separate the temporal settings into two parts - the time of day and the date. + +## Time +The `Time` section allows you to specify the time of day that the schedule will execute. There are 4 main options: + +- Absolute time - in the case of the figure above, the schedule will execute at 2:18pm local time +- Time relative to Sunrise - so some number of minutes before or after sunrise depending on the value in the text box (use negative numbers for before sunrise). For more specific options click the `Customize` button (see image below): + - `At sunrise` is the default (0 is inserted into the text box on the main dialog) + - X `minutes before sunrise` (-X is inserted into the text box on the main dialog) + - X `minutes after sunrise` (X is inserted into the text box on the main dialog) + - `Force trigger time to Y at the earliest` will cause the trigger to execute at the specified time if the minutes before sunrise specification is earlier than Y + - `Force trigger time to Y at the latest` will cause the trigger to execute at the specified time if the minutes after sunrise specification is later than Y + +![Schedule Time Customize Sheet Image](../../images/schedule_time_customize_sheet.png) + +- Time relative to Sunset - works the same as the above option but with respect to Sunset rather than Sunrise +- Every X hours Y minutes Z seconds - this is the typical repeating setting. + +You can also randomize all of the above settings by entering a non-zero value in the `Randomize by` text box. Each execution will add the randomized amount of time. Use this setting to create schedules that have that "lived in" look. + +## Date +The Date section allows you to specify the date(s) on which the schedule will execute. There are 5 primary options: + +- Absolute Date - execute this schedule on a specific date +- Repeating every number of days - the default option repeats every day though you can change that to every X number of days +- Absolute days of the week - execute only on certain days of the week (not that darkened days are selected, lightened aren't) +- Absolute days of the month - specify each day of the month on which to execute the schedule separated by a comma +- Fixed days of the month - specify advanced day settings such as third Thursday of the month + +Below those 5 options are a couple of modifiers which may or may not be available based on the primary option you've selected: + +- Repeat allows you to specify repetition. This one changes based on what you have selected above: + - For absolute date you can specify yearly repetitions (e.g. every year, every 3 years, etc.) + - Disabled for repeating every number of days since that already specifies repetition + - For Absolute days of the week you can specify weekly repetitions (e.g. every week, every 6 weeks, etc.) + - For Absolute days of the month and Fixed days of the month you can specify monthly repetitions (e.g. every month, every 4 weeks, etc.) + +- Start on allows you to specify some date in the future to begin on (disabled for the first option since that specifies an absolute date) +- Optional End on date so you can specify an absolute date on which to stop any repetition. + +## Other Options +There are two options at the bottom of the dialog. The first is `Hide executions in Event Log` which will suppress any log messages indicating that this schedule has executed. This especially useful for schedules that repeat very frequently (every X minutes for instance). The second is `Automatically delete after next execution` which will do exactly that - after the next time that the schedule executes it will be deleted **regardless** of the time or date settings. diff --git a/reference/canonical/user/concepts/triggers.md b/reference/canonical/user/concepts/triggers.md new file mode 100644 index 0000000..cbed886 --- /dev/null +++ b/reference/canonical/user/concepts/triggers.md @@ -0,0 +1,116 @@ + + +# Triggers { #triggers } +A trigger is an action (or collection of actions) that Indigo executes when some "event" occurs - the event "triggers" the actions. For instance, when a motion sensor detects motion, that's an event. When Indigo gets a signal from the motion sensor that it has detected motion, it will look for triggers that need to be executed based on that event. Here's the Trigger dialog: + +![Trigger Dialog Image](../../images/trigger_dialog.png) + +We'll look at each of the specific trigger types next, but first we'd like to point out a couple of other features. First, you'll notice that there are three tabs in the dialog: Trigger, Condition, and Actions. The first tab lets you define the trigger event. The second allows you to specify conditions which will be evaluated at runtime to determine whether the actions should be executed. See the [Conditions](conditions.md#conditions) section for more information. Lastly, the Actions tab allows you to define the actions that this trigger will execute. See [Actions and Action Groups](actions.md#action-groups) for more information. + +Let's look at the various built-in events that Indigo can use in triggers along with their dialogs. + +## Device State Changed +![Device State Changed Trigger Image](../../images/device_state_changed_trigger.png) + +Use the Type `Device State Changed` to trigger an action whenever a device's state changes. For example, you could create a Trigger Action for whenever a specific light's brightness becomes greater than 75% or for when your thermostat's temperature drops below 55 degrees. + +A device state can change as a result of the following: a direct Insteon or X10 command sent to that device from a remote control or motion detector, a device action Indigo has sent the device, or the reception of a new status state from the device itself. + +Unlike Insteon modules, not all X10 modules transmit their current states when they are changed directly at the device itself. For example, in order for Indigo to know that you have turned a hallway light on at the light switch itself, the light switch module must be a 2-way module that can transmit X10 signals back to Indigo. We recommend that our users only purchase these 2-way X10 modules in cases where Indigo needs to be aware of the status changes triggered at the device itself. Each X10 transmitter in your system will reduce the X10 signal strength throughout your home wiring. + +!!! tip "TIP" + Read our online [troubleshooting information page](../troubleshooting/powerline-signal-troubleshooting.md) if you are having problems reliably sending or receiving Insteon or X10 commands. + +## Variable Changed +![Variable Changed Trigger Image](../../images/variable_changed_trigger.png) + +Use the Type `Variable Changed` to trigger an action whenever an Indigo variable value changes. Variable values can change as a result of a Modify Variable action or from the user directly modifying the value. See the [Variables](variables.md#variables) section for more information about using variables. + +Note: `becomes true` will fire when the value becomes "true", "on", "yes", and "1" (if it wasn't one of those values previously). `becomes false` will fire when the value becomes "false", "off", "no", and "0" (if it wasn't one of those values previously). Any other value will be neither true nor false and neither will fire. + +## Email Event +![Email Event Image](../../images/email_event_2023_1.png) + +Use the Type `Email Event` to trigger an action based on emails sent to Indigo. There are three email event types to choose from. + +- `String Match in Email` - use this option to trigger an event when an email is received that matches a particular string pattern you choose. Select "Edit Event Settings" to choose the Email device, match in `Message Text`, `Message Subject`, or `Message From`, and the string pattern to match. Note that this is an exact text match, so this trigger will only fire when the string matches the target text 100 percent. +- `Regex Pattern Match in Email` - use this option to trigger an event when an email is received that matches a portion of the text pattern you choose. The match is done using a Regular Expression pattern match, which allows greater flexibility and the ability to match on a portion of the target text. Select "Edit Event Settings" to choose the Email device, match in `Message Text`, `Message Subject`, or `Message From`, and the regex pattern to match. For more information on regular expressions, visit https://www.regular-expressions.info/tutorial.html. +- `Server Connection Error` - use this option to trigger an event when the connection to a specific email server is lost. Select "Edit Event Settings" to select the email device you want to monitor. + +See the configuring email settings section for more information about having Indigo send and receive emails. + +## Indigo Server Startup +Use the Type `Indigo Server Startup` to trigger an action when the Indigo Server process is first launched. + +There are no options for this type of trigger. + +## Power Failure +Use the Type `Power Failure` to trigger an action whenever the computer interface detects a power failure. For Indigo to receive this information from the computer interface, the computer running Indigo must be connected to an uninterruptible power supply (UPS). Otherwise, the command from the interface will be sent to a computer with no power. + +There are no options for this type of trigger. + +## Interface Connection Initialized +Use the Type `Interface Connection Initialized` to trigger an action whenever the communication between Indigo and the interface is successfully started. + +There are no options for this type of trigger. + +## Interface Connection Failure +Use the Type `Interface Connection Failure` to trigger an action whenever the communication between Indigo and the interface fails. An unplugged USB cable or a malfunctioning interface can cause this error. + +There are no options for this type of trigger. + +## Z-Wave Command Received +![Z-Wave Command Received Trigger Image](../../images/zwave_command_received_trigger.png) + +Use the Type `Z-Wave Command Received` to trigger an action when Z-Wave messages are sent from a device, like a scene controller or motion sensor, and then received by the Z-Wave interface. Each device type will have different options based on its capability + +### Match Raw Packet +One option that is available for all Z-Wave devices is the `Match Raw Packet` option. This allows you to specify a pattern to watch for in all incoming Z-Wave messages. This is a pretty technical option, but allows for a lot of flexibility if you can decipher the incoming messsages. In the `Match bytes` field you can specify specific hexadecimal bytes in an incoming message, and you can include ***** (asterisk) to match 0 or more bytes and **?** (question mark) to match exactly one byte. For example: + +`* 0x7D 0x84 0x07 *` + +would trigger on this message received from a device: + +`0x01 0x08 0x00 0x04 0x00 0x7D 0x02 0x84 0x07 0x0F` + +The `Write Recent Packets to Log` button will write the last 60 seconds of incoming packets to the Event Log window. You can then copy/paste the packet you want to match into the `Match bytes` field. + +## Insteon Command Received +![Insteon Command Received Trigger](../../images/insteon_command_received_trigger.png) + +Use the Type `Insteon Command Received` to trigger an action when Insteon commands are sent from a device, like a KeypadLinc, and then received by the PowerLinc interface. Select the Insteon command from the `Received` popup that you want to cause the trigger, along with the `Device` from which the command was sent. For devices with multiple buttons, like the KeypadLinc and ControLinc, you can also choose which button press causes the trigger via the `Using button popup. + +!!! tip "TIP" + The `Double Tab On` and `Double Tap Off` command types are useful for triggering lighting scenes at a wall switch (like the SwitchLinc). For example, you could create a `Double Tap Off` trigger action that turns off all the lights in the house when a SwitchLinc near the back door is pressed twice. + +!!! tip "TIP" + Read our online [troubleshooting information page](../troubleshooting/powerline-signal-troubleshooting.md) if you are having problems reliably sending or receiving Insteon commands. + +## X10/RF Command Received +![X10 Command Received Trigger Image](../../images/x10_command_received_trigger.png) + +Use the Type `X10/RF Command Received` to trigger an action when X10 commands are sent from a device, like a PalmPad, SwitchLinc 2-Way Dimmer, etc, and then received by the X10 or RF interface. Select the X10 command from the Received popup that you want to cause the trigger, along with the `Device` or X10 `Address` for that command. + +Choose `A/V Button Pressed` from the `Received` popup to trigger an action using one of the X10 universal remote controls, such as those included in the X10 "Entertainment Anywhere" kits. + +!!! tip "TIP" + Read our online [troubleshooting information page](../troubleshooting/powerline-signal-troubleshooting.md) if you are having problems reliably sending or receiving X10 commands. + +## Plugin Events { #plugin-events } +Plugins may define events as well - these will be listed below the `X10/RF Command Received` event in the `Type` popup. + +## Web Server Event +![](../../images/webhook_trigger.png){ width=500 } + +Use the type *`Web Server Event`* to trigger an action when a webhook is called. Set the type *`Web Server Event`* and set the Event to *`Webhook`*. + +| Field | Description | +| --- | --- | +| Webhook ID | This is a random code generated by Indigo. It's used to identify which webhook is associated with the event. You can use the code provided or use one of your own. NOTE: if someone has your Reflector URL and the webhook ID, they can cause the event to fire. If you use your own ID, it's best not to make it easily guessable. | +| Webhook Method
[POST] | Use *`POST`* to indicate that the webhook is sending information to Indigo and not expecting data in return (your call will be | +| POST Processing
[JSON] | this type of webhook will accept a POST and interpret the payload as JSON. | +| POST Processing
[HTML Form] | this type of webhook will accept a POST with optional form data, which will be converted into a dict of name value pairs and passed through as data. | +| Webhook Method
[GET] | this type of webhook will accept a GET and will pass through any query arguments as the data element. GET webhooks do not have settings for processing the associated payload. | + + +You can find more information on the [Webhooks](../../api/webhooks.md) page. You can find more information about using substitutions on the Indigo [substitutions page](../automation/substitutions.md). diff --git a/reference/canonical/user/concepts/variables.md b/reference/canonical/user/concepts/variables.md new file mode 100644 index 0000000..d2876af --- /dev/null +++ b/reference/canonical/user/concepts/variables.md @@ -0,0 +1,18 @@ + + +# Variables { #variables } +Variables are used to hold information that can help your home automation logic. You can use variable information to display on control pages, as part of your conditional logic (see [Conditions](conditions.md#conditions) below), or as a trigger for some other action. + +To manage your variables, select `Window->Variable List` and you'll see the Variable List window: + +![Variable Window Image](../../images/variable_window.png) + +This window is broken up into 3 sections. The top section lets you create new variables, duplicate existing variables, and delete variables. It also lets you search your variable list (either name or value) by typing some text into the search box. + +The middle section is the actual variable table. It actually has two parts: the table header and the table itself. If you right click on the table header, it will allow you to customize what columns show up in the table. To change a variable `Name`, just double click on the name and type in a new name. Note that variable names can contain only alpha-numeric characters and underscores "_" and must be unique. Variable values may contain pretty much anything and can be changed by double-clicking on them. + +The `Remote Display` column indicates whether a variable will be shown in the built-in variable list in remote clients. The `ID` column shows the unique identifier for the variable - you'll need this if you're planning on writing Python scripts. + +If you right-click a variable, you can toggle the Remote Display attribute or copy the variable id to the clipboard (for easy pasting into scripts). You can also select the `Show Dependencies` option to open a window that shows all other objects that are dependent on that variable. See [Deletion Dependencies](deletion-dependencies.md) for more information. + +The bottom section are the folder control buttons. Clicking on the plus (`+`) will add a new folder, and clicking on the minus (`-`) will delete the selected folder. If the folder isn't empty when you try to delete it, a sheet will come down prompting you to decide if you want to delete all the enclosed variables or if you want to move them out of the folder first. If you right click on a folder in the list, you can toggle whether the folder shows up in remote clients and you can copy the unique folder id to the clipboard for use in scripts. diff --git a/reference/canonical/user/getting-started.md b/reference/canonical/user/getting-started.md new file mode 100644 index 0000000..37d0689 --- /dev/null +++ b/reference/canonical/user/getting-started.md @@ -0,0 +1,75 @@ + + +# Getting Started + +!!! abstract "In this article" + This guide walks you through everything needed to get Indigo running: verifying Mac requirements, connecting hardware interface devices, adding your first Z-Wave, Insteon, or X10 devices, and creating basic automations. Read through all topics in this section before setting up your system to understand the full scope of what's required. + +## Welcome to Indigo {{ version }}! +Indigo is a powerful Mac-based home control server that integrates an assortment of popular Z-Wave®, Insteon and X10 hardware devices, as well as a variety of other hardware via 3rd party plugins, to provide monitoring and control of your home. Depending on your needs and budget, you can create a simple system that controls only a couple of lights or you can automate your entire home. + +We recommend that you read through all of the topics in this Introduction section to get a firm grasp of the pieces required to begin your home automation experience. + +### Indigo Software and Mac Requirements +To install the Indigo software, you'll need a Mac that meets these OS and hardware requirements: + +- [Mac OS X 10.13](https://en.wikipedia.org/wiki/MacOS_Sierra) or higher +- [Any Mac capable of running Mac OS X 10.13](https://en.wikipedia.org/wiki/MacOS_Sierra#System_requirements) + +Indigo requires you to leave your Mac running all the time (though the display can go to sleep) in order to control your home automation; you should take this into consideration when choosing a location for your Mac. + +### Indigo Home Automation Technology Support +The other major piece of the home automation puzzle are the devices that you want to control. Lights, thermostats, sprinklers, door locks, motion sensors, alarm panels, A/V equipment, etc. Indigo supports a large variety of these devices. Check out our [database of devices that have been tested with Indigo](https://www.indigodomo.com/devices/) (including via 3rd party plugins). + +Out of the box, Indigo supports the following Home Automation protocols (simultaneously) via separate [Interface Hardware](https://www.indigodomo.com/devices/interfaces/) devices: + + + +#### Z-Wave { #connecting-z-wave-interfaces } +[Z-Wave](../interfaces/z-wave/about.md) is a very popular home automation technology that's used worldwide. There are [many different manufacturers](https://z-wavealliance.org/z-wave_alliance_member_companies/) of Z-Wave devices so the selection is quite good. To use Z-Wave with Indigo, you'll need a Z-Wave interface (often referred to as a dongle): Indigo supports Z-Wave via a variety of [Hardware Interfaces](https://www.indigodomo.com/devices/interfaces/). + +The types of Z-Wave devices that Indigo currently supports include: + +- ON/OFF devices (plug-in modules, switches, and outlets), +- Dimmers (plug-in modules and switches), +- Sensors (contact, magnetic, motion, temperature, etc.), +- Thermostats, and +- Locks. + +Other device types will be added over time. Check our [Compatible Devices list](https://www.indigodomo.com/devices/) to see if a specific module has been tested. Note however that just because a module isn't listed doesn't mean that it won't work - Z-Wave is architected such that devices that correctly support Z-Wave features should automatically work. There are so many different devices from many different manufacturers that we will never be able to test them all. If you have a device that isn't listed but works, please feel free to report it to us and we'll add it to the list. There is a very simple mechanism to report devices, described in [Editing a Z-Wave Device's Properties](../interfaces/z-wave/index.md#editing-a-z-wave-device-s-properties) towards the end of that section. + +#### Insteon { #connecting-insteon-and-x10-interfaces } +[Insteon](../interfaces/insteon/index.md) is a protocol developed by SmartLabs, parent company of Smarthome.com, which is widely used in North America and is moving into other markets as well. There are a few 3rd party vendors that make Insteon hardware but most devices are made by SmartLabs. To use Insteon with Indigo, you'll need an Insteon interface. You can find a complete list of Insteon interfaces that are supported on our [Built-in Interface Hardware Support](https://www.indigodomo.com/devices/interfaces/) list. Indigo supports the vast majority of Insteon devices - see our [Compatible Devices list](http://www.indigodomo.com/devices/) for a complete list. + +#### X10 +[X10](../interfaces/x10/index.md) is a legacy technology that works primarily over the power line though some devices are wireless (using the X10 RF protocol). We don't recommend anyone start a new home automation system using X10 because of its poor reliability and relative lack of X10 hardware - however, if you have existing X10 devices you can definitely use them with Indigo if you have a compatible X10 interface. You can find a complete list of X10 interfaces that are supported on our [Built-in Interface Hardware Support](https://www.indigodomo.com/devices/interfaces/) list. + +#### Other Devices +If you don't have any of the above hardware, you can still install and use Indigo - particularly if you have hardware supported by one of the [many 3rd party plugins](https://www.indigodomo.com/pluginstore/). For instance: [RFXtrx433](http://www.indigodomo.com/pluginstore/17/) with support for Home Easy/Chacon, X10 RF, LightwaveRF, and many different types of sensors; [Ecobee](https://www.indigodomo.com/pluginstore/193/) and [a variety of TRV](http://www.indigodomo.com/pluginstore/201/) Thermostats; Alarm Panels; A/V equipment; etc. See our [Plugin Store](http://www.indigodomo.com/pluginstore/) for all available 3rd party plugins. Indigo also ships with some [useful plugins](../../plugins/index.md) out of the box. Some plugin developers have reported devices that have been tested with their plugin and Indigo: see our [Compatible Devices list](http://www.indigodomo.com/devices/) for those devices. + +### Other Sources for Help +For specific questions or discussions on the hardware above, we recommend you join us on our [online forum](https://forums.indigodomo.com/). + +You can also visit our [website](http://www.indigodomo.com/) for valuable [support resources](http://www.indigodomo.com/support/): + +- The [FAQ](http://www.indigodomo.com/indigo/faq.html) has answers to the most common questions +- Add lots of extra functionality via 3rd Party Plugins available in our [Plugin Store](https://www.indigodomo.com/pluginstore/) +- Visit our [User Contribution Library](http://www.indigodomo.com/library/index.php) to download the latest plugins, scripts, and icons/graphics for extending Indigo + +Now, you know what the parts of your system will be and where to go for more information and help. Now let's get started with the actual installation. + +## Setting Up Indigo + +With the background above, work through these chapters in order: + +1. **[Installation & Server Setup](installation.md)** — install the software, start and configure the Indigo Server, set your location. +2. **[Managing the Built-in Interfaces](interfaces.md)** — enable and configure the Z-Wave, Insteon, X10, and Virtual Devices interfaces, then add your devices using the per-technology guides. + +When your system is up and running, see [Accessing Indigo Remotely](remote-access.md) in the Remote Access section to reach your server from other Macs, Indigo Touch, and web browsers. + +## Where to Go Next +Congratulations! You should now have a basic functioning Indigo installation that's ready for you to start adding devices and defining your home automation logic. We suggest that you next go to the [Overview of Devices, Triggers, Schedules, Action Groups, Control Pages, and Variables](../concepts/index.md) - that will give you the information you need to begin using the features of Indigo. + + +--- +*Z-Wave® is a registered trademark of Sigma Designs, Inc. Indigo's support of Z-Wave hardware is neither endorsed nor certified by Sigma Designs.* diff --git a/reference/canonical/user/getting-started/installation.md b/reference/canonical/user/getting-started/installation.md new file mode 100644 index 0000000..49159d7 --- /dev/null +++ b/reference/canonical/user/getting-started/installation.md @@ -0,0 +1,154 @@ + + +# Installation & Server Setup + +## Installing Indigo +Indigo can run as a standalone application on a single Mac or can be run in a client/server mode on two or more Macs. In either case, you must first run the Indigo installer on the main Mac (also referred to as the server Mac) to which the home automation [interface hardware](https://www.indigodomo.com/devices/interfaces/) (Z-Stick, PowerLinc, CM15, etc.) will be connected. Just [download](http://www.indigodomo.com/downloads) the latest Indigo installer (you must be logged in to your [Indigo Account](https://www.indigodomo.com/acccount/codes/) to see the downloads available to you). This should download the disk image. In Safari, click the downloads button (the down arrow to the right of the URL/search bar). You should see an entry titled "Indigo.dmg". Double-click the installer file to switch to the Finder. A dialog will show the disk image is being mounted. Once it's mounted, a window will open with the following files: + +1. A ReadMe.html file - read this for any late breaking information about Indigo or the installation process. +1. The Indigo Installer.pkg file - double-click this to start the Indigo installation. Follow the instructions provided by the installer. On the Installation Type screen, press the Install button (do not use Customize) to install all the Indigo packages (Server, Server Scripts, Drivers, and Client) on your designated hard drive. Note: you must install and run Indigo from an account on your Mac that has administrator privileges. + +### Location of Indigo Files after Installation +The Indigo {{ version }} application can be found here: + + /Applications/Indigo {{ version }}.app + +And the Indigo database files, log files, scripts files, and other settings/support files are stored in: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/ + +By default, database files are stored in the `Databases` folder in that folder. + +!!! note + This is the Library folder at the top level of your hard drive, not the one in your User folder. Lion and greater hide these folders by default, but if you select the `Go->Go to Folder…` menu item in the Finder and paste in the path above it will open that folder in a Finder window. + +### Installing Indigo Client on another Mac (optional) +If you have only a single Mac, then your installation is now complete and you are ready to start Indigo. However, Indigo has been designed as a client/server application to allow remote control and configuration from anywhere (*extra network configuration is required if you want to access your server from a client over the Internet and is outside the scope of this manual - post on the online support forum for assistance). The client-only installation process installs only the files needed to remotely access the primary Indigo server running on your main Mac. + +1. Copy the Indigo Installer.mpkg file to your other Mac. +1. Double click the Indigo Installer.mpkg icon to start the Indigo installation. +1. Follow the instructions provided by the installer process. On the Installation Type screen, press the Customize button and then deselect all the package options (Indigo Server, Indigo Plugins, Indigo Server Scripts, Indigo Drivers) except for the Indigo Client package. +1. Press the Install button to install just the Indigo Client package. +1. **Note**: It is **not** necessary to restart your Mac after installing the Indigo Client package only. + +If you have other Macs on your home network, then you can optionally repeat the above Indigo Client installation on each of them. + +Now you can [start Indigo](#starting-indigo-server) and configure the server, and then [remotely control](remote-access.md#remote-indigo-access) Indigo from your iPad, iPhone or iPod Touch using [Indigo Touch](http://www.indigodomo.com/touch), a Web browser or the Indigo Client. + +### Repairing an Installation + +If you experience issues with your Indigo installation, such as file permissions or missing or corrupt python modules, you can attempt to repair those by rerunning the Indigo installer. This will reinstall the Indigo application and all of its dependencies but it will not touch your Indigo database, plugin preferences, or scripts you've added to the shared directories. This is the standard way to get Indigo back to it's installed state. + +## Starting Indigo Server +Indigo can run as a standalone application or can be run in a client/server mode. The latter allows the server to run invisibly in the background without the client application UI showing and is the recommended option. Regardless of which you are doing, the first step [after installation](#installing-indigo) is to launch Indigo and configure the local server. + +1. Double click the `Indigo {{ version }}` application (`/Applications/Indigo {{ version }}.app`). +1. If this is the first time to run `Indigo {{ version }}` on this Mac, then press the `Start Local Server...` button in the connection status window. +1. If you want to reconfigure the Indigo Server on a Mac already running Indigo, then select the `Indigo {{ version }}->Start Local Server...` menu item. + +![Start Server Dialog Image](../../images/start_server_dialog.png) + +!!! info "Password Field Behavior" + The length of the entry in the password field does not reflect the length of the actual password entered. This is intentional and is meant to add a layer of security so a bad actor can't guess the true password's length. + +### Standard startup mode +Choose the `Standard Indigo Startup` radio button to start the Indigo Server process independently of the Indigo Client. This will allow the server to run in the background on your Mac with no visible UI, even when the Indigo Client is not running. This will also start the built-in Web server, allowing remote access from Web browsers on other computers and remote access from iPhones and iPod Touches. + +Use the `Auto start Indigo Server on user login` checkbox to have the Indigo Server automatically launched whenever your current OS X administrator user account is logged in. This option will also make sure the Indigo Server process is automatically relaunched if it crashes. + +Use the `Allow remote access` checkbox to enable [remote access](remote-access.md#remote-indigo-access) from other Macs and Web browsers. You must enter a username and password if you enable remote access. + +Use the `Override Web server port number:` checkbox to change the TCP/IP port number that the web server uses to serve content and browsers will use to browse the web control pages. + +Use the `Enable secure internet access via Indigo Reflector` checkbox for secure Web browser access from anywhere. This option requires a you to have configured a [Reflector](../remote-access/reflector.md), which handles maintaining the secure connection to Indigo Server automatically. Reflectors are included as part of your [Up-to-Date subscription](http://www.indigodomo.com/blog/2016/11/09/indigo-date/). + +- `Outgoing reflector port selection`: Some ISPs, especially satellite providers, may block incoming and outgoing connections -- particularly if they sit idle for a time (which, in our opinion is ridiculous) -- this setting provides a few options to hopefully work around these limitations. The setting you choose does not have any impact on performance. Further, the reflector port selection (or, in fact, the reflector itself) should have no impact on local web traffic performance (since the reflector isn't involved when a local network connection is made). If you're experiencing slowness with a local connection, check your router to ensure it isn't blocking or otherwise interfering with Bonjour traffic. + +Use the `Enable OAuth and API Key authentication` checkbox to enable 3rd party services like Alexa. It also will allow REST API calls to use an API key for authentication rather than a username/password. This is more secure since you can revoke a key if it gets compromised without having to change passwords in wherever you may need to use them. + +Use the `Enable remote Indigo client access` checkbox to allow [remote Indigo Clients](remote-access.md#remote-indigo-access) on other Macs to connect to the Indigo Server. Note that this only works on your local network - the Indigo Reflector service is only for Indigo Touch and other web access, not for configuration client connections. + +Use the `Override Indigo server port number:` checkbox to change the TCP/IP port number that the Mac OS X client uses to connect to the server. + +### Custom single app startup +This is a legacy setting and should only be used if instructed by Indigo Customer Support. + +### Starting the Server +Press the `Start Server` button, or the `Restart Server` button if the server is already running, to start the local Indigo Server. If `Allow remote access` is enabled, then the built-in Web server will also be started. + +The Indigo Client will automatically connect to the Indigo Server. If this is the first time to launch the Indigo Server on this Mac, then you will be prompted to accept the License Agreement and to enter your Registration Code. The Indigo Client will then load and display the current house database file. + +If you are running in client/server mode, then you can quit the Indigo Client at anytime and the Indigo Server will continue to run in the background processing your home control logic and schedules. Additionally, you can [remotely access](remote-access.md#remote-indigo-access) the Indigo Server from Indigo Clients on other Macs or from remote Web browsers that have internet access to the server Mac. + +If you are running in standalone mode, then quitting the Indigo Client will automatically quit the Indigo Server. + +If this is the first time you've started the server, you'll be prompted first to click through our End User License Agreement (EULA), then you'll see the Indigo Account Log In dialog: + +![Login Dialog Image](../../images/login_dialog.png) + +and enter your Indigo Account username (or email) and password. The server will then continue to start up. + +If you purchased a retail license from a reseller, you must follow the directions supplied by your reseller. It may be in an email or they may include a printed sheet with your shipment. Usually this will just tell you to create a new Indigo Account (click the `Create New Account` button) and fill out the form. + +If you just want to run the client and connect to a server on a different Mac, then click the `Connect to Remote Server...` button. + +### Backing Up Indigo +Backing up your Indigo installation is very simple: just make sure that your backup program is backing up this folder: + + /Library/Application Support/Perceptive Automation/ + +Note: this is the Library folder at the top level of your hard drive, not the one in your User folder. Use the `Go->Go to Folder...` menu item in the Finder and paste in the path above to get there easily). Another thing to note is that it's possible that you've stored your database in a non-standard location, like for instance the Documents folder in the home folder for the account under which Indigo is installed. If that's the case you'll need to make sure that you've backed it up as well. You can tell the location of your database file by Command-clicking the database name in the title bar of the Home Window. + +Time Machine will do this by default. To recover, just recover that directory and then run the Indigo {{ version }} installer again (which will repair any permission issues that Time Machine may have introduced). + + +## General Configuration Settings { #general-configuration-settings } +![General Preferences Tab Image](../../images/general_prefs_tab.png) + +You can configure other Indigo settings by opening the preferences dialog (selecting the `Indigo {{ version }}->Preferences...` menu item) and clicking on the `General` tab. + +The first section of the tab is about update checking. The first checkbox will have the client check with our servers to see if there's an update to Indigo available when the client first starts up. If there is, it will let you know. The second checkbox will send anonymous information to us (and it really is anonymous) about your install - this helps us to better prioritize what future enhancements to add. The last checkbox will also check to see if there's a newer beta version available - if you aren't interested in getting betas then leave it unchecked. + +You can have Indigo check for updates immediately by selecting the `Indigo {{ version }}->Check for Updates...` menu item. + +The next section we talked about above - how many days of event log files to keep. + +The last section is a rather technical configuration parameter - it is possible to get into an unending (infinite) loop when you're setting up your triggers. For instance, if you have a trigger the fires on a variable change, and it changes the variable to some new value each time, that would cause the trigger to fire again. Setting this value will cause it to stop eventually. Leaving it set to 5 is probably the best idea. + + +## Specifying your Latitude and Longitude { #specifying-your-latitude-and-longitude } +Indigo uses your current Latitude and Longitude coordinates to calculate precisely when sunset and sunrise will occur every day. Indigo automatically extracts your location from the System Preferences. To do this, it must have access to Location Services on your Mac (and WiFi must be turned on for Location Services to work). When Indigo first launches, you'll be prompted to allow access to Location data. If for some reason it's not working, check the Location Services section on the Privacy tab of the Security & Privacy section of your System Preferences and make sure that IndigoServer is enabled (has a checkbox beside it). + +### Configuring your System Location + +1. Choose `System Preferences` from the `Apple` menu. +1. Select the `Date & Time` icon. +1. Select the `Time Zone` panel. +1. If the current `Closet City` location is not near your location, then follow the instructions on the panel to choose your location. +If you would like to precisely specify your location, then you can override the system location from within Indigo. + +### Overriding the System Location +By default, Indigo will use Location Services to determine the location of your Mac. You will be asked the first time you start your server to grant permission for **IndigoServer** to access you Mac's location. If Indigo doesn't seem to be running schedules at the right time, make sure that Indigo is authorized to access Location Services. Open the System Preferences, select the Security & Privacy preference, click on the Privacy tab and you should see IndigoServer in the list - make sure the check box beside it is enabled: + +![Location Services Image](../../images/location_services.png) + +You can, however, manually specify the latitude and longitude: + +![Longitude Latitude Tab Image](../../images/longlat_tab.png) + +- Choose the `Indigo {{ version }}->Preferences...` menu item, then make sure the `Sunset & Sunrise` tab is selected. +- Select the `Override system location` checkbox. +- Enter your exact `Latitude` and `Longitude` coordinates. + + +## Modifying System Settings for Continuous Operation +Indigo requires your Mac to be on and awake for processing. You can, however, set the display to go to sleep: the Indigo Server will not need the display to be active to function. + + +## Modify Energy Saver Settings to Prevent Computer Sleep + +- Choose `System Preferences` from the `Apple` menu. +- Select the `Energy Saver` icon. +- Move the `Computer sleep:` slider to `Never`. +- Uncheck `Put the hard disk(s) to sleep when possible`. +- Select the `Start up automatically after a power failure` checkbox. diff --git a/reference/canonical/user/getting-started/interfaces.md b/reference/canonical/user/getting-started/interfaces.md new file mode 100644 index 0000000..62cf32e --- /dev/null +++ b/reference/canonical/user/getting-started/interfaces.md @@ -0,0 +1,21 @@ + + +# Managing the Built-in Interfaces { #managing-the-built-in-interfaces } +Indigo has 4 built in interfaces: Z-Wave, Insteon, X10, and Virtual Devices. + +You manage them from the Interfaces menu: + +![Interfaces Menu Image](../../images/interfaces_menu.png) + +The first thing you'll notice is the dot beside the names in that menu. A green dot means that the interface is enabled. If the dot is gray, it means that it's disabled. This allows you to see what's enabled by just looking at the menu. Each interface (and its submenu) is described below. If you select the `Manage Interfaces...` menu item, it will open the Preferences dialog with the Interfaces tab selected: + +![Interfaces Tab Image](../../images/interfaces_tab.png) + +You can enable/disable an interface just by clicking the checkbox (rather than selecting the Enable/Disable menu item on each interface's submenu). Likewise, if an interface has any configuration options, you can open those dialogs by selecting the interface and clicking on the `Configure...` button (rather than selecting the `Configure...` menu item on each interface's submenu). + +For detailed information specific to the interface, look to the appropriate guide for the technology: + +- [Configuring and Managing your Z-Wave Network](../interfaces/z-wave/index.md) +- [Configuring and Managing your Insteon Network](../interfaces/insteon/index.md) +- [Configuring and Using X10 devices](../interfaces/x10/index.md) +- [Using the Virtual Devices Interface](../interfaces/virtual-devices.md) diff --git a/reference/canonical/user/getting-started/remote-access.md b/reference/canonical/user/getting-started/remote-access.md new file mode 100644 index 0000000..21ae3ba --- /dev/null +++ b/reference/canonical/user/getting-started/remote-access.md @@ -0,0 +1,99 @@ + + +# Accessing Indigo Remotely + +## Remote Indigo Access +After you have [started the Indigo Server](installation.md#starting-indigo-server) in client/server mode, you can remotely access it from other Macs using the Indigo Client, from your iPad, iPhone or iPod Touch using [Indigo Touch](http://www.indigodomo.com/touch), or from any modern Web browser (Safari, Firefox, Opera). + +The following steps explain how to access the Indigo Server from **within the local area network** (LAN) of your house. Configuring your network to allow Indigo Server access from outside your home (on the other side of your router/cable modem) is more complex and will depend on your network topology, router type, and ISP features (static versus dynamic IP addresses). For this reason, we are only providing instructions on how to get local (in house) remote access to Indigo Server. + +If you desire easy remote Indigo Server access from outside your home, then you will want to [activate the reflector](../remote-access/reflector.md) that's part of your Up-to-Date subscription. This provides secure [Indigo Touch](http://www.indigodomo.com/touch) access from anywhere with no network configuration needed. As long as your Up-to-Date subscription is active you'll have remote access. + +Alternatively, you can configure your network by consulting your router user manual and, if your ISP does not provide a static IP address, using a dynamic DNS mapping service like DynDNS.com. Because of the potential complexity involved in manually configuring networks and routers for this type of access, Perceptive Automation cannot provide direct support answers about router port forwarding or IP discovery issues. Users having difficulty configuring their networking hardware should post on the [online support forum](https://forums.indigodomo.com/). Be sure and include details about the type of hardware you have and what steps you have tried. + + +## Modifying Firewall Settings +If you are using the macOS built-in Firewall, and depending on how you have your firewall configured, you may be prompted by the firewall with the following dialogs the first time you start Indigo: + +![Firewall Prompt Image](../../images/firewall_prompt.png) +![IPH Firewall Prompt Image](../../images/iph_firewall_prompt.png) + +You **must** click the Allow button in those dialogs (if they pop up) or Indigo will not function correctly. + + +## Discovering the Indigo Server IP Address (LAN only) +The Indigo Web Server advertises itself via Bonjour, so [Indigo Touch](http://www.indigodomo.com/touch) and Safari (by clicking on the bookmarks icon, then selecting Bonjour) will automatically find any local servers. In addition to that, when connecting to a local server for the first time, [Indigo Touch](http://www.indigodomo.com/touch) will also automatically fetch Reflector settings for that connection so that you'll be able to connect outside your LAN via LTE/4G/3G/Edge. + +For other browsers to remotely access the Web server, we need to know the network IP address for the Mac running Indigo Server. This address will be used on the remote Mac or Web browser when connecting to the Indigo Server. By selecting the active network in the Network System Preference, you can see the IP address for your Indigo Server Mac. For WiFi, it might look something like this: + +![Network WiFi Image](../../images/network_wifi.png) + +and a wired Ethernet connection might look something like this: + +![Network Wired Image](../../images/network_wired.png) + +Note the IP address under the **Status** section. + +You now have the IP address for the Mac running Indigo Server. Depending on your home network setup, this IP address may change periodically, such as when the Indigo Server Mac or router is restarted. If this happens, then you can use the steps above to discover the IP address again, or you can configure a static (not dynamic) IP address for the Mac running Indigo Server (that is an exercise left to you as it would be totally dependent on your network configuration). + + +## Remote Access Using the Indigo Client + +1. If you haven't already installed the client on the remote Mac, run the Indigo Installer on the remote Mac and on the **Installation Type** step click the **Customize** button. Unselect everything except the **Indigo Client** line and click **Install**. +1. Double click the `Indigo {{ version }}` application (inside `/Applications/Indigo {{ version }}.app`) on the remote Mac. +1. If this is the first time to run Indigo on this remote Mac, then press the `Connect to Remote Server...` button in the connection status window. +1. If you are wanting to connect to a different Indigo Server, then select the `Indigo {{ version }}->Connect to Remote Server...` menu item. +1. Enter the `IP address` for the Indigo Server Mac discovered in the section above. +1. If you overrode the Indigo Server port number (default: `1176`) in the Start Local Server dialog on the server Mac, then select the `Override default port number` checkbox and enter your custom port number. +1. Press the `Connect` button. + +![Client Connect Dialog Image](../../images/client_connect_dialog.png) + +!!! warning "Indigo Mac Client and the Indigo Reflector" + The Indigo Mac Client doesn't use the [Indigo Reflector](../remote-access/reflector.md) service. Connecting an Indigo Mac Client to a server over the internet is a complex topic that is well beyond this document – we suggest you search our online forums for others that have configured this type of access. + + +## Remote Access Using Indigo Touch +[Indigo Touch](http://www.indigodomo.com/touch), the iPhone and iPod Touch application from Indigo Domotics, allows the user to view and control Devices, activate Action Groups, view Variables, and access custom Control Pages. One of the best features of [Indigo Touch](http://www.indigodomo.com/touch) is its ability to automatically detect and configure network connections. If your iPhone (or iPod Touch) is connected to your local wireless LAN, then it should automatically discover your server. In [Indigo Touch](http://www.indigodomo.com/touch), tap the `Settings` button. You should see the name of your Database in the list. Tap on it, and it will connect (it will ask for your username/password if you have one set, but it will remember it going forward so you won't have to type it in again). + +At this point, [Indigo Touch](http://www.indigodomo.com/touch) will also query the server to see if you have an [Indigo Reflector](../remote-access/reflector.md) set up for the server. This makes connecting to your home server via [Indigo Touch](http://www.indigodomo.com/touch) completely seamless. If you have a reflector set up and running, then [Indigo Touch](http://www.indigodomo.com/touch) will automatically attempt to connect no matter where you are or how you're connected. If you're local, it will use the local WiFi network, if you're on a remote WiFi network, it will attempt to use the reflector account. If you're iPhone is on LTE/4G/3G/Edge, it will also attempt to connect via your reflector account. This makes [Indigo Touch](http://www.indigodomo.com/touch) truly location agnostic! + +You can, however, configure a connection manually. Simply tap `Manually Add Server` on the `Settings` screen in [Indigo Touch](http://www.indigodomo.com/touch) and you can enter your host/ip address and port number. + + +## Remote Access Using a Web Browser +Indigo, when run in client/server mode, will automatically start its built-in Web server on launch. This allows access from remote Macs, PCs, and other internet devices like the iOS devices, Android devices, etc. Any device that can run a modern Web browser (Safari, Chrome, Firefox) will work. + +To access the Indigo Web Server use the IP address you discovered in the section above along with the Indigo Web Server port number (default: 8176). The URL will look like this (substitute your server's correct IP address): + + http://192.168.1.23:8176/ + +See the [using Control Pages](../concepts/control-pages.md) section for information on how to create custom browser accessible interface pages. + + +## Indigo Touch and Your Reflector +[Indigo Touch](http://www.indigodomo.com/touch.html) for iOS is transparently integrated with the Indigo Reflector service. When you use your iOS device (iPhone, iPad, etc.) to connect to Indigo while in your house (and on your local Wi-Fi network), Indigo Touch will automatically retrieve and remember your reflector address. You can press the settings (gear) icon on the top toolbar then find the `Reflector` item near the bottom to verify that it is working correctly. + +Once Indigo automatically detects your reflector address, it will seamlessly change between using the local Bonjour detected address and the remote reflector address. Just launch Indigo Touch and it works, no matter where you are! + + +## Reset Your Reflector's Activation +If you are switching to a different reflector that you've asked us to create for you, or you've been instructed by support to reset your current reflector's activation, then follow these steps: + +1. Shut down the Indigo Server (select `Indigo {{ version }}->Stop Server`) but don't quit the Indigo Client +1. Switch to your browser and [log out of your Indigo Account](http://www.indigodomo.com/account/logout/) +1. Go to the [reflector list](http://www.indigodomo.com/account/reflectors/) in your Indigo Account (you'll need to log back in) and click the `Reset` link beside your reflector's status (it should say *Activated* before your press *Reset*) +1. Switch back to the Indigo Client and click on the `Start Local Server` button + +You should now see an `Activate Reflector` button towards the bottom of the dialog. Click that, log in to your reflector account, and select the appropriate reflector. If the reflector you want to use doesn't show in the list of inactive reflectors, [contact us](http://www.indigodomo.com/#contact) with the name of the reflector you're trying to activate and what steps you've performed. + +### Manual Reset +If the procedure above doesn't work, and *​only* ​if instructed by support, follow these steps to manually reset your Indigo Client reflector settings: + +1. Shut down the Indigo Server (select `Indigo {{ version }}->Stop Server`) but don't quit the Indigo Client +1. Switch to your browser and [log out of your Indigo Account](http://www.indigodomo.com/account/logout/) +1. Go to the [reflector list](http://www.indigodomo.com/account/reflectors/) in your Indigo Account (you'll need to log back in) and click the `Reset` link beside your reflector's status (it should say *Activated* before your press *Reset*). If the reflector has already been deactivated that is fine – just skip this step. +1. In the Finder, select `Go->Go to Folder…` +1. In the resulting dialog, copy and paste the following: `/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Preferences/` +1. In the resulting Finder window, delete the folder named `PrismReflector` +1. Switch back to the Indigo Client and click on the `Start Local Server` button diff --git a/reference/canonical/user/glossary.md b/reference/canonical/user/glossary.md new file mode 100644 index 0000000..4424241 --- /dev/null +++ b/reference/canonical/user/glossary.md @@ -0,0 +1,42 @@ + + +# Glossary of Terms +There tends to be a lot of home automation specific and other jargon used in documents, wiki articles, and in the support forums. This is where we'll capture those so it's easy to find the definition you need. + +| Term | Definition | +|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Action | Indigo actions are discrete tasks that cause things to happen -- such as turning on a light, changing a setpoint, writing information to the log, and so on. Indigo ships with many standard actions and plugin developers can create actions that apply to their plugins. | +| Action Group | [Action groups](concepts/actions.md#action-groups) are collections of actions that may be reused (and modified) easily between multiple triggers, schedules, and control pages and executed via various clients (the Mac Client, the Indigo Web Server (IWS) web pages, Indigo Touch, etc). | +| API | An API (Application Programming Interface) is a set of rules and protocols that allow different applications to exchange information with one another. It helps developers and users to integrate, leverage, or share data and processes from other systems without having to create their own. | +| AppleScript | A macOS scripting language that allows applications to be controlled and automated. AppleScript is considered a legacy scripting language in Indigo. | +| Association | A process used to link two or more Z-Wave devices together so they essentially react as a single device. | +| Control Page | [Control pages](concepts/control-pages.md#control-pages) are user-created interfaces to control their Indigo system - for instance you could create a graphical floor plan with light icons in the various rooms. | +| Condition | In Indigo, a condition is a logical test that's used to determine whether something should happen. For example, you might only want something to happen at nighttime, or only when all the windows are closed. | +| Controller | In Indigo, a controller is a device that controls another device. Z-Wave controllers include various peripherals such as USB sticks -- which send commands from Indigo to a device (like a dimmer) or from the device to Indigo. A controller may also be a responder (i.e. Insteon KeypadLinc). We've adopted the term from various Insteon documentation. | +| Developer | A person who writes plugins or scripts for the Indigo Server (IS). | +| Exclude/Exclusion | Used to remove a device from a Z-Wave controller. | +| Include/Inclusion | Used to add a device to a Z-Wave controller. | +| Insteon | A home automation protocol developed by SmartHome that uses a dual-band (powerline + RF) mesh network so devices can communicate directly with one another. Indigo supports Insteon devices via a USB PLM (PowerLinc Modem). | +| Insteon Link | A connection between two Insteon devices such that one device controls the other based on some input - a button press, etc. | +| Device | A [device](concepts/devices.md#devices) is any "thing" that Indigo can interact with - usually it's some kind of hardware (light switch, appliance module, motion sensor, etc.), but devices can also be other non-hardware things (iTunes server, calendar, etc.). Devices can also be "virtual" objects supported by plugins that have the potential to do all kinds of useful things. | +| I/O Device | Any device that has binary or analog inputs or outputs. These devices are generally used to interface at a low-level to other devices (security systems, sensors, etc). | +| Indigo Object Model | The Indigo Object Model (IOM) is how the various objects in Indigo are modeled in Python objects for scripters and plugin developers. | +| Interface | Indigo provides support for several different interface types, including: Z-Wave, Insteon/X10 Powerline, X10 RF, and Virtual Devices (software-based interface). Additional interfaces may be supported through user-submitted plugins. | +| JSON | JSON (JavaScript Object Notation) is a lightweight, human-readable data format used to represent structured information as key-value pairs and lists. It is widely used for data exchange between Indigo plugins, scripts, and external APIs and web services. | +| Node | A node is used to refer to a single device on a Z-Wave network. Nodes are assigned a unique node number by the Z-Wave controller. | +| Object | In Indigo, an object is any item managed by the server — such as a device, trigger, schedule, action group, control page, or variable. Objects are accessible to scripters and plugin developers via the [Indigo Object Model (IOM)](../scripting/iom-concepts.md). | +| Plugin | Indigo supports ways to extend its functionality such as Indigo Server (IS) plugins. IS plugins can extend Indigo by adding additional devices types, trigger events, and actions. | +| Python | The programming language used to write Indigo scripts and plugins. Indigo embeds a Python interpreter, allowing scripters and developers to automate logic, interact with the [Indigo Object Model (IOM)](../scripting/iom-concepts.md), and extend Indigo's capabilities beyond its built-in features. | +| Reflector | Indigo's secure tunnel service for remote access without the need for a VPN. | +| Responder | In Indigo terminology, it's a device that responds to commands. A responder may also be a controller (i.e. Insteon KeypadLinc). We've adopted the term from various Insteon documentation. | +| REST | REST (Representational State Transfer) is an architectural style for web APIs that uses standard HTTP methods (GET, POST, PUT, DELETE) to interact with resources. The Indigo Web Server (IWS) exposes a RESTful API that allows external applications and scripts to query and control Indigo objects over the network. Indigo's REST API has been deprecated in favor of the websocket and HTTP APIs. | +| RF | RF (Radio Frequency) interfaces use wireless radio waves to communicate with the Indigo Server. | +| Schedule | A [schedule](concepts/schedules.md#schedules) is similar to a trigger, but the event that causes the execution of the actions is a temporal event of some kind. Either a fixed point in time (5/2/2011 at 1:00pm) or more likely some repeating time (every day at 1:00pm). | +| Scripter | Someone who uses Python scripts to implement automation logic in Indigo via embedded or file-based script actions and script conditions. | +| Sync/Synchronize | A process initiated in Indigo to refresh a device's settings, states and other information in the Indigo server. Not all devices support a synchronization and battery devices that support synchronization will be updated at the next polling time. | +| Trigger | A [trigger](concepts/triggers.md#triggers) is generally some kind of "event" that occurs. Indigo can use that event to execute actions in response. For example, turn on an exhaust fan if the humidity exceeds a certain level. | +| Variable | A [variable](concepts/variables.md#variables) is a place where your home automation logic can store information that changes during the normal operation of your home and that can be used in other parts of your system: for instance, you can have a variable that represents whether your home is occupied or not - then you can have special automation logic that takes place when that variable changes. Indigo variables store values as plain text. | +| Webhook | an HTTP request that lets external services trigger Indigo actions. | +| X10 | One of the earliest home automation protocols, X10 sends on/off and dim commands over a home's existing electrical wiring (powerline). Indigo supports X10 devices through compatible controllers. X10 is considered a legacy protocol in Indigo. | +| XML | XML (Extensible Markup Language) is a structured text format that uses nested tags to represent data in a human- and machine-readable way. Indigo uses XML extensively for plugin device definitions, action configurations, and preferences files. | +| Z-Wave | A low-power wireless mesh networking protocol designed specifically for home automation. Z-Wave devices communicate in the sub-GHz band (908 MHz in North America) and support two-way communication. Indigo supports Z-Wave devices via a Z-Wave USB controller (often called a Z-Stick). | diff --git a/reference/canonical/user/interfaces/insteon.md b/reference/canonical/user/interfaces/insteon.md new file mode 100644 index 0000000..200c0e9 --- /dev/null +++ b/reference/canonical/user/interfaces/insteon.md @@ -0,0 +1,328 @@ + + +# Managing Your Insteon Network in Indigo + +!!! abstract "In this guide" + How to connect an Insteon interface to Indigo, add and configure Insteon devices, and manage Insteon links so that devices can control each other without manual button-pressing at each fixture. Also covers replacing a failed device or PowerLinc controller while preserving your link database. + +Indigo provides a variety of tools for managing your Insteon network - not only can you add/control/delete devices, but you can also manage Insteon Links so that you don't need to walk around your house pressing buttons (see the [Managing Insteon Links](#managing-insteon-links) section for details). You can also [replace devices](#replacing-and-resyncing-devices) and even your [PowerLinc controller](#replacing-your-powerlinc) and Indigo will make sure that all links are modified so your network continues to work with as little manual intervention as possible. The first thing you should do, of course, is [connect and configure your Insteon interface](#connecting-insteon-and-x10-power-line-interfaces). + +Insteon is primarily a power line technology, and as such is susceptible to signal noise. Check out the [signal troubleshooting](../../troubleshooting/powerline-signal-troubleshooting.md) page for common causes and solutions to signal issues. + +## Connecting Insteon and X10 Power Line Interfaces +Connecting an Insteon (or X10 power line) interface to Indigo requires a couple of steps, described below. Check out our [supported interfaces list](http://www.indigodomo.com/devices/interfaces/) to see if the interface you want to use has been tested with Indigo. + +### Install the FTDI VCP Drivers +The **PowerLinc 2412U, [2413U](http://www.indigodomo.com/hardware/powerlinc2413u), and [2448A7H (Insteon RF USB Adaptor)](http://www.indigodomo.com/hardware/powerlinc2448)** interfaces should be plugged directly into one of your Mac's USB ports (preferably not into a USB hub port) and require the FTDI Virtual COM Port (VCP) driver to be installed. **If you are using Mac OS X 10.9 (Mavericks) or better, it has the driver already installed.** + +For earlier versions of the OS, you can get the driver installer at [FTDI's website](http://www.indigodomo.com/ftdiurl) - be sure to get the installer that's appropriate for the architecture of your machine (Intel or PowerPC). If you select **PowerLinc 2412U/2412S/2413U/2413S/2448** from the Interface type popup menu in the Preferences dialog (see below), then Indigo will alert you if the driver is not installed on your Mac. If you're using a PowerLinc 2412S/2413S with a separate USB to serial adapter, you can ignore that warning alert. **Note**: there are known issues with the FTDI driver and macOS High Sierra, Mojave, and Catalina on ***some*** Macs - check out our [blog post](http://www.indigodomo.com/blog/2018/01/25/high-sierra-driver-bug-workaround/) for details. + +The **PowerLinc 2414U/1132CU/1132U** (all of which have now been discontinued) and **CM15A** (aka CM15Pro) interfaces should also be plugged directly into your computer (preferably not into a USB hub port) - the Indigo installer automatically installed the drivers for these interfaces. Make sure you have restarted after the installation process. If you reinstall your OS, then you will need to rerun the Indigo installer for the driver. + +The other supported interfaces (**PowerLinc 2412S/2413S, CM11 / HD11, LynX-PLC**) are serial based, and will require a USB serial port adapter. If you are using one of the serial based interfaces, then make sure that the latest drivers for the USB serial adapter are installed on your system. Look on the adapter manufacturer's website for the latest driver downloads. If you don't already have a serial-to-USB adapter, we highly recommend getting one that uses the same FTDI chipset that the PowerLincs use since it seems to be the most reliable. + +**Note**: PowerLincs are quite sensitive to USB versions and hubs. It's known that there are often times failures on hubs (as mentioned above), but we also know that there are also failures on USB3 ports. In this last case, you may need to find a USB2 hub and use that for the PowerLinc. + +Check the [Interface Hardware](https://www.indigodomo.com/devices/interfaces/) list to see what interfaces we've actually tested. + +### Connecting the Interface +Plug the interface directly into an outlet (with the exception of the Insteon RF USB Adapter). Do not plug the interface into your computer's power strip because many power strips contain filters that will severely degrade the Insteon / X10 signal quality being received and transmitted by the interface. Additionally, uninterruptible power supplies (UPSs) can cause signal quality problems. If at all possible plug the interface into a different outlet than used by power strips and UPSs. Signal filters are available to isolate computer power strips and UPSs as well. + +If you are using the **CM11 / HD11** or **CM15A** interface, then do not install the battery into the interface. Indigo does not support uploading macros to these interfaces so the battery should not be used. + +### Configuring Indigo to use Your Interface + +1. Choose `Indigo {{ version }}->Preferences...` menu, then make sure the `Interfaces` tab is selected. +1. Select the `Enabled` checkbox next to the `Insteon / X10 Powerline Interface` item. +1. Double-click the `Insteon/X10 Power Line Interface` line in the table (you can also get to this dialog by selecting the `Interfaces->Insteon/X10 Power Line->Configure…` menu item) +1. Choose your `Interface type` in the popup menu. + - If you are using the **PowerLinc 2412U/2413U/2448A7H** interface, then the `Serial port:` popup menu will be enabled and the [FTDI driver](http://www.indigodomo.com/ftdiurl) (see Install the Correct Drivers above) will create a new `Serial port:` popup menu item that looks like `usbserial-XXXXXXXX`. Select that item. **NOTE**: you ***must*** have the FTDI driver installed already. + - If you are using the **PowerLinc 2414U/1132CU/1132U** or the **CM15** interface, then the `Serial port:` popup menu will be disabled because these interfaces do not use a virtual serial port driver. + - If you are using one of the serial based interfaces (**PowerLinc 2412S, CM11 / HD11, LynX-PLC**), then the `Serial port:` popup menu will be enabled and you should choose which serial port adapter name the interface is connected to in the `Serial port:` popup menu. **NOTE`**: if no names are listed in the `Serial port:` popup menu, then you probably do not have the proper driver installed for your USB serial adapter. Download your adapter's driver from the driver manufacturer's website. +1. Optionally select the `Group addresses on transmission` checkbox to combine like-command transmissions together. For example A1-On, A3-On, A4-On, would be transmitted as A1, A3, A4, On. +1. Some interfaces, such as the PowerLinc V2 and LynX-PLC, have additional settings that can be accessed from the Interface Options... button. Generally, these options don't need to be changed unless you're troubleshooting a problem. + +![Insteon X10 Configuration Dialog Image](../../../images/insteon_x10_config_dialog.png) + +If you click on the `Interface Options...` button, you'll see something like this: + +![Insteon Advanced Options Image](../../../images/insteonadvancedoptions.png) + +You should only use these options on the recommendation of Indigo Support. + +### Enabling and Disabling Communication +Choose the `Interfaces->Insteon/X10 Power Line->Disable` (or `Enable`) menu item to disable/enable the interface. + +## Adding and Managing Insteon Devices +Indigo uses Smart Link Syncing to quickly define and link Insteon devices with the PowerLinc. This link syncing process will allow Indigo to control and see messages from the device. + +First, make sure that Indigo has enabled communication with the interface. If Indigo is not online with the interface, then choose the `Interfaces->Insteon/X10 Power Line->Enable` menu item. See [connecting the Interface](#connecting-insteon-and-x10-power-line-interfaces) above for more details. + +Additionally, make sure you have Insteon range extenders or other dual-band modules correctly installed on opposite power legs. If the range extenders or other dual-band devices are improperly installed or missing, then you may not be able to control some of your Insteon devices. See the instructions included with your Access Point RF pair for installation details. + +!!! tip "TIP" + Access Point RFs do not bridge X10 signals, so if you also have X10 devices you will likely need an additional bridge. + +To add a new Insteon device: + +1. Select Devices in the [Outline View of the Home window](../../mac-client/home-window.md#home-window). +1. Press the `New...` button at the top of the Home window and select `Insteon` from the `Type` popup. + +Here's the Insteon device dialog: + +![Insteon Device Detail Image](../../../images/insteon_device_detail.png) + +The `Define and Sync...` button will open the `Define Insteon Define` dialog: + +![Define Insteon Dialog Image](../../../images/define_insteon_dialog.png) + +This is how you initially add an Insteon device to Indigo. The directions on this dialog are quite self-explanatory. When you click the `Start` button you'll see the checkboxes turn green when each step is complete, and the `Close` button will enable when the process is complete. The sync process can take a few minutes to complete. Lamp and appliance devices normally take less than a minute, but KeypadLincs and ControLincs can take a few minutes because of the additional link information needed for all the buttons. + +If the sync process fails or does not complete, then make sure that the device is correctly wired or plugged in, both Access Point RFs are installed and on opposite power legs, and that you do not have an uninterruptible power supply (UPS) or surge protector strip plugged into the outlet the PowerLinc is using. If syncing still fails and the device is portable (ApplianceLinc or LampLinc), then try plugging it directly into the pass through outlet on the PowerLinc. See our [signal troubleshooting tips](../../troubleshooting/powerline-signal-troubleshooting.md) for additional help. + +After the sync dialog is closed, some devices, such as the KeypadLinc, EZRain, Thermostat Adapter, Motion Sensor, and EZIO8SA, have additional custom settings shown in the main device dialog. + +## Replacing and Resyncing Devices +### Resyncing Links +The `Re-Sync Links...` button on the device edit dialog will open the `Synchronize Insteon Device Links` dialog: + +![Start Sync Dialog Image](../../../images/start_sync_dialog.png) + +Use this dialog to resync a device when its links have been altered outside of Indigo. You may be asked to use this dialog by technical support when troubleshooting device problems. + +### Replacing a Device +To replace a device that's malfunctioned, just open the edit dialog for the device and click the `Define and Sync...` button again to open the `Define Insteon Device` dialog. Enter the address of the replacement module (and make sure it has been installed) and click the `Start` button just like you did when you originally added the device. This will maintain all the links that you created to and from the device as well as maintain any Triggers, Schedules, Conditions, Actions, and Control Pages that might use the device. + +## Managing Insteon Links +The last button, `Manage Links...` is how Indigo allows you to remotely manage Insteon links without having to walk around pressing set buttons (there is also a menu item on the Insteon/X10 Power Line submenu to access the dialog). + +The Insteon protocol has linking built-in as part of its core functionality. The idea is that one device, a controller in Insteon speak, can be linked to another device, a responder, then from that point forward the controller device sends its command directly to the responder device. So, for instance, you can link a KeypadLinc button to a SwitchLinc so that when you press the button on the KPL the SwitchLinc responds. That's normally done by pressing various buttons on each device in specific ways until the link is established. + +The manual linking method is useful if you don't have a software-controlled environment. However, since you've decided to have Indigo automate your home, you do have software to help you manage your automation needs. We've worked very hard to allow Indigo to perform the majority of link management tasks remotely so you don't have to walk around pressing buttons. + +For some background on Insteon links, we have put together a separate page that discusses [Insteon Scenes](insteon_links.md). We highly recommend that you read through that page as it will give you a better understanding of what links are and how they work. + +### Managing Insteon Device Links +The primary place that you'll manage links between devices is in the Manage Insteon Device Links dialog. Select the `Interfaces->Insteon/X10 Power Line->Manage Device Links` menu item and the dialog will pop up: + +![Device Links Dialog Image](../../../images/device_links_dialog.png) + +The dialog may look slightly different depending on the roles that the device selected in the popup at the top can play. As we mentioned earlier, devices that can control other devices are called "controllers" and devices that can be controlled are called "responders". Many devices are both controllers and responders (the example above is a SwitchLinc, which is both). These links are also called groups and/or scenes, depending on usage, so keep that in mind. + +For example, you can use Indigo to remotely program the button on a RemoteLinc to: set a ceiling fan (FanLinc) to Medium, brighten a dimmer to 75% over 2 seconds, turn off an on/off device. + +![Device Links Example Image](../../../images/device_links_example.png) + +Indigo automatically creates the links to define the scene in most remote modules. This means you do not have to press-and-hold the set button or up paddle on most remote modules. Indigo will do it all remotely for you with a single press of the Sync Now button. + +You can also define Indigo initiated scenes to control multiple remote modules in unison. See the defining [Insteon scenes section](#defining-the-scene) for more information on this capability. + +#### Responder Modules vs. Controller Modules +Every Insteon module is either a *responder module*, a *controller module* or both: + +- *Responder modules* respond to incoming Insteon commands by controlling a load (light or appliance), a thermostat setting, sprinkler valves, low-voltage relays, etc. Examples of responder modules include: LampLinc, ApplianceLinc, and the EZRain sprinkler controller. +- *Controller modules* send outgoing Insteon commands onto the power line or via RF to modules that are responders. Examples of controller modules include: RemoteLinc, ControLinc, and the PowerLinc computer interface. +- Some modules are both *responders* and *controllers*. For example, a KeypadLinc can respond to a RemoteLinc, but it can also control other modules, such as a LampLinc. + +#### Defining the Scene between Modules +First, select the module you want to edit. You can choose to edit either the controller module in the scene (ex: RemoteLinc) or the responder module in the scene (ex: LampLinc). + +1. Select the `Interfaces->Insteon/X10 Power Line->Manage Device Links` menu item. +1. Select the module's device name to edit in the `Show links used by device` popup control. + +If the module you selected is a controller (RemoteLinc, KeypadLinc, SwitchLinc, etc.), then you can add or edit responders: + +1. If you want to add a new responder module to the scene, then press the `New Link to Responder` button. If you want to change the settings (brightness, ramp rate duration, etc.) of an existing responder module in the scene, then select that module's link in the table with the `Link to Responder Device` column title. +1. Choose the button or group number that identifies the scene you are defining in the controller (ex: RemoteLinc button #1) from the `broadcast of button/group number` popup control. +1. Choose the responder module's device name from the responder popup control (ex: LampLinc). +1. When responding to a scene command, most modules will control the main load (light or appliance) connected to that module. For these modules (SwitchLinc, ToggleLinc, LampLinc, etc.) you can specify the exact brightness you want for that module as well as a duration for how quickly the module should go to that brightness: Some modules will have different options. For example, when a KeypadLinc is responding to a scene command, it can turn one of the secondary button LEDs on instead of controlling the main load, or the thermostat module can respond to a scene command by changing both the thermostat operation mode and the current `cool` and `heat` setpoint temperatures. +1. Optionally turn on the `Persistent` checkbox to force this link to automatically be restored whenever either the responder module or controller module is synced. If the modules are ever reset, replaced, or have this link modified, then Indigo will automatically rewrite the original link on the next sync operation. +1. Repeat steps 1 through 5 for every new responder module that you want to add to the selected controller. + +If the module you selected is a responder (LampLinc, Thermostat Adapter, KeypadLinc, SwitchLinc, etc.), then you can add or edit controllers: + +1. If you want to add a controller of the selected responder module, then press the `New Link to Controller` button. If you want to change the settings (brightness, ramp rate duration, etc.) used by the selected module in a controller's scene, then select the controller module's link in the table with the `Link to Controller Device` column title. +1. Choose the controller module's device name from the On controller popup control (ex: RemoteLinc). +1. Choose the button or group number that identifies the controller scene for which you want the responder to listen (ex: RemoteLinc button #3) from the `broadcast of button/group number` popup control. +1. When responding to a scene command, most modules will control the main load (light or appliance) connected to that module. For these modules (SwitchLinc, ToggleLinc, LampLinc, etc.) you can specify the exact brightness you want for that module as well as a duration for how quickly the module should go to that brightness using the % text box and the rate popup. Some modules will have different options. For example, when a KeypadLinc is responding to a scene command, it can turn one of the secondary button LEDs on instead of controlling the main load, or the thermostat module can respond to a scene command by changing both the thermostat operation mode via the mode popup and the current `cool` and `heat` setpoint temperatures via those text boxes. +1. Optionally turn on the `Persistent` checkbox to force this link to automatically be restored whenever either the responder module or controller module is synced. If the modules are ever reset, replaced, or have this link modified, then Indigo will automatically rewrite the original link on the next sync operation. +1. Repeat steps 1 through 5 for every new controller module you want to add for the selected responder. + +Lastly, to have Indigo write all of your link changes to the remote modules, press the `Sync Now` button to have Indigo immediately write all changed links to the remote modules. Or, press the `Close (Sync Later)` button to close the link editor window and write the changes to the modules at a later time. When you are ready to write the changes to the remote modules, select `Start Sync Device Links...` from the `Interfaces->Insteon/X10 Power Line` menu, and then press the `Sync Changes Only` button. + +#### Manually Creating Links between Modules +In addition to using Indigo's remote link and scene management, you can also manually create the links physically at the devices themselves. Follow the instructions that came with the hardware for the exact steps, which usually involves creating the links by press-and-holding the set button or up paddles for 10 seconds on each module. + +If you manually create or delete a link, then you must tell Indigo to [re-sync those modules](#insteon-link-syncing). This enables Indigo to read in the link changes, and is required for Indigo to accurately show the state of the modules as they change. + +### Managing Insteon PowerLinc Scenes +Insteon scenes (also called groups) can be used to control multiple Insteon modules, such as light switch modules, lamp or appliance plug-in modules, and thermostat modules, all in unison. For example, you could create a *home theater lighting* scene that turns off all lighting in your media room, except for a few sconce side lights which are set to 20% brightness. You can create lighting scenes for any activity you desire: *dining*, *entertaining*, *sleeping*, *reading in bed*, *emergency*, etc. + +![Manage Powerlinc Scenes Image](../../../images/manage_powerlinc_scenes.png) + +Indigo can remotely create scenes in the computer interface (PowerLinc) that control multiple remote modules. Indigo automatically creates the links to define the scene in both the PowerLinc and most remote modules. This means you do not have to press-and-hold the button on either the PowerLinc or most remote modules. Indigo will do it all remotely for you with a single press of the Sync Now button. + +Once Indigo writes the links defining the scene to the PowerLinc and remote modules, you can execute the scene from any [Trigger](../../concepts/triggers.md#triggers), [Schedule](../../concepts/schedules.md#schedules), or [Action Group](../../concepts/actions.md#action-groups) using the `Execute Insteon Scene` [action](../../concepts/actions.md#execute-insteon-scene). + +Indigo can also remotely create and edit scenes between remote modules (ex: from a KeypadLinc to a LampLinc). See [Managing Insteon Device Links](#managing-insteon-device-links) for more information on this capability. + +#### Defining the Scene +First, specify which PowerLinc Group/Scene number you want to use: + +1. Choose `Manage PowerLinc Links...` from the `Interfaces->Insteon/X10 Power Line` menu. +1. Select a `PowerLinc Group/Scene` number to use for the scene. Use 1 if this is your first scene. +1. Optionally enter a `PowerLinc Group/Scene` name in the edit field (ex: "reading in bed"). + +Next, create a new link for every responder module in the scene: + +1. If you want to add a new responder module to the scene, then press the `New Link to Responder` button. If you want to change the settings (brightness, ramp rate duration, etc.) of an existing responder module in the scene, then select that module's link in the table in the top-half of the window. +1. Choose the responder module's device name from the `responder` popup control. +1. When responding to a scene command most modules will control the main load (light or appliance) connected to that module. For these modules (SwitchLinc, ToggleLinc, LampLinc, etc.) you can specify the exact brightness you want for that module as well as a duration for how quickly the module should go to that brightness by using the % text box and the duration popup. Some modules will have different options. For example, when a KeypadLinc is responding to a scene command it can turn one of the secondary button LEDs on instead of controlling the main load, or the thermostat module can respond to a scene command by changing both the thermostat operation mode via the mode popup and the current `cool` and `heat` setpoint temperatures using the text boxes. +1. Optionally turn on the `Persistent` checkbox to force this link to automatically be restored whenever the responder module is synced. If the responder module is ever reset, replaced, or has this link modified, then Indigo will automatically rewrite the original link into the device when it is next synced. +1. Repeat steps 1 through 4 for every new module you want to add to the scene. + +Lastly, have Indigo write all of your link changes to both the PowerLinc and the remote modules by pressing the `Sync Now` button to have Indigo immediately write all changed links to the PowerLinc and remote modules. Or, press the `Close (Sync Later)` button to close the link editor window and write the changes to the modules at a later time. When you are ready to write the changes to the PowerLinc and remote modules select `Start Sync Device Links...` from the `Interfaces->Insteon/X10 Power Line` menu, and then press the `Sync Changes Only` button. + +You can test the scene after the links are written by using the Send On and Send Off buttons. + +#### Executing the Scene +The Indigo scene can now be executed from any Trigger, Schedule, or Action Group: + +1. Follow the instructions to create a [Trigger](../../concepts/triggers.md#triggers), [Schedule](../../concepts/schedules.md#schedules), or [Action Group](../../concepts/actions.md#action-groups). +1. Select the `Actions` tab inside the edit window. +1. Select `Insteon Actions->[Execute Insteon Scene](../../concepts/actions.md#execute-insteon-scene)` from the action `Type` popup item. +1. Use the `Send` popup item to select which scene command to send: + - `Group On` will command all the responder modules to their scene-specific brightness using their scene-specific ramp rate duration, if any. + - `Group On to 100% (instant / ignore rate)` will set the brightness of dimmable modules to 100% immediately, ignoring any ramp rate duration. + - `Group Off` will turn off all the responder modules using their scene-specific ramp rate duration, if any. + - `Group Off (instant / ignore rate)` will turn off all the modules immediately, ignoring any ramp rate duration. +1. Select the scene number defined previously (see above) from the `Scene` popup item. + +Note: you can press the `Modify this Scene button...` to add a new responder module to the currently selected scene, or you can double-click a device in the scene list to edit its settings (brightness, ramp rate duration, etc.). + +### Insteon Link Syncing +Indigo's smart Insteon Link Syncing makes it easy to set up and keep all of your devices working with your PowerLinc. This link syncing process allows Indigo to control devices, and to update its internal device state (on / off / brightness) as the device is controlled locally (at the switch) or remotely by other devices. Indigo shows the state of all Insteon devices as they change, even if the change is because of a command from another device. For example, a LampLinc that is turned ON from a ControLinc will immediately show as ON within Indigo. Indigo automatically does link syncing when you first create the device. + +If, after the device is initially created, a remote device has any additional controller links added (ex: LampLinc is controlled by a KeypadLinc), then that device (LampLinc in this case) should have its links re-synced. This option is available from the Device dialog and will ensure Indigo has an accurate representation of the device's internal links, allowing it to correctly show state (on / off / brightness) changes as they occur. + +#### Re-Syncing a Single Insteon Device + - Make sure the device is properly wired or plugged in. + - Select Device List from the View menu. + - Double-click the device you need to re-sync. + - Press the Re-Sync Links... button. + - Press the Start Sync button. + - Wait for the Smart Link Syncing steps to complete and press the Close button. + - The sync process can take a few minutes to complete. Lamp and appliance devices normally take less than a minute, but KeypadLincs and ControLincs can take a few minutes because of the additional link information needed for all the buttons. + +Battery powered devices will need to be awake for a sync to complete. If you see an error that says the device is asleep, you will need to have that device handy and hit the sync button. Sometimes just operating the device will be enough to wake it up, but that's device specific. For a door sensor, for instance, you may be able to wake it up enough for a sync just by tripping the sensor. + +#### Re-Syncing All Insteon Devices +In addition to syncing individual devices, you can also batch sync all of your Insteon devices. Depending on the number of Insteon devices you have, this process can take a significant amount of time to complete. Because control of your devices will be limited during the synchronization process, it is recommended that you start the synchronization process at night or before you leave the house. + + - Make sure all devices are properly wired or plugged in. + - Select Start Sync Device Links... from the Interface menu. + - Press the Sync All Devices button. + - Watch the Event Log window to see when the synchronization process is complete. + - The batch synchronization process can be canceled at any time. + - Select Stop Sync Device Links from the Interface menu. + - Watch the Event Log window to see when the synchronization process is canceled. + +## Resetting your PowerLinc +Sometimes, customer support will ask you to reset your PowerLinc. Here's the process: + +1. In Indigo 5 or above, select the `Interfaces->Insteon/X10 Power Line->Disable` menu item +1. Unplug your PowerLinc and wait about 15 seconds +1. Press and hold the black set button on the side +1. While holding the button, plug it back in and continue to hold the button for about 15 seconds +1. Release the button +1. In Indigo, select the `Interfaces->Insteon/X10 Power Line->Enable` menu item +1. Select the `Interfaces->Insteon/X10 Power Line->Configure...` menu item +1. Click the `Interface Options...` button +1. Click the `Sync Links` button + +The last step will take a while, so watch the Event Log window for progress. + +## Replacing Your PowerLinc +If your PowerLinc is ever replaced, then you must re-sync all of your devices. This will ensure that all devices have their internal links updated to reflect the new PowerLinc's Insteon address. If you are replacing a 2414U with a newer PowerLinc, you may also need to [install the drivers](#install-the-ftdi-vcp-drivers) for your new PowerLinc. + +Once you have the driver installed, just connect the PowerLinc to your Mac. If you're switching from a 2414 to one of the current ones, you'll need to select it in the [config dialog for Insteon](#configuring-indigo-to-use-your-interface). Otherwise, you'll need to select the new Serial Port in that same dialog. Once you click "Save" on that dialog, Indigo will prompt you to resync all links - do that. Once it's done, all links in all devices should be correct. Be sure to have any battery-powered devices close at hand - you'll need to press and hold the set button to wake them up. + +Note: that any links that you create, either using the UIs described above, or by manual linking must be marked as Persistent in the link dialogs in order for them to be recreated correctly. For links that you create manually between devices, when you have the manual links created successfully, you must come back to Indigo and sync the device(s) links. The manual links will show up in the dialogs - you must then mark them as `Persistent in order for them to be retained when doing a resync/replacement. + +## Other Insteon Features in Indigo +The `Interfaces->Insteon/X10 Power Line` submenu contains a collection of miscellaneous Insteon commands that will help you manage specific aspects of devices as well as do so low-level Insteon commands not directly supported in the UI: + +![Insteon Menu Image](../../../images/insteon_menu.png) + +Note that these are also actions available in the [Insteon Brand Specific](../../concepts/actions.md#insteon) submenu. + +### Execute Raw Insteon Command +This action will allow you to send a raw Insteon command to any Insteon device. You can send standard messages (2 bytes) or extended messages (16 bytes). You can also have the results of the command inserted into a variable for later processing. + +#### Set Motion Sensor LED Brightness +This action will set the brightness of the LED that flashes inside the motion sensor when motion is detected. While the brightness value is between 0 and 255, 0 does not mean the LED is completely off - it's just very dim. Note: only revision 2 Motion Sensors with jumper 5 set can be configured. + +#### Set Motion Sensor Timeout +This action will set the timeout value between the time the motion sensor stops detecting motion and when it sends the OFF command. The timeout values work like this: 0 is equal to 30 seconds and 255 is equal to 2 hours. Values in between are proportional to those values. + +**Note**: only revision 2 Motion Sensors with jumper 5 set can be configured. + +**Note**: a value of 0 will be interpreted as 3 for Motion Sensor II models. + +#### Set Motion Sensor Day/Night Sensitivity +This action will set the sensitivity for when the motion sensor detects changes from dawn to dusk and vice versa. The sensitivity values work like this: 0 will make the sensor register day all the time and 255 is equal to night all the time. Values in between are proportional to those values. Note: only revision 2 Motion Sensors with jumper 5 set can be configured. + +#### Set LED Brightness +This action will set the brightness of the LEDs on certain devices. Newer KeypadLincs are supported as well as some SwitchLinc models. Unfortunately there isn't really a way to tell you which devices are supported so you'll just have to try it and see if it works. + +You can script this action from Python: + +```python +insteonId = "com.perceptiveautomation.indigoplugin.InsteonCommands" +insteonPlugin = indigo.server.getPlugin(insteonId) +if insteonPlugin.isEnabled(): + actionProps = dict() + actionProps["brightness"] = 1 # a value from 1-100 + actionProps["device"] = 123456 # the ID of the KeypadLinc or SwitchLinc + actionProps["brightenMethod"] = "kpl" # the device is a KeypadLinc - use "swl" if it's a SwitchLinc + insteonPlugin.executeAction("setLedBrightness", props=actionProps) +``` + +#### Set KeypadLinc Auto-Off Button Group +This action will allow you to specify what buttons will go off automatically when you press any other button. Useful in conjunction with Toggle Mode below for creating "radio groups". See the [Fanlinc And Keypadlinc](fanlinc_and_keypadlinc.md) article for usage examples. + +#### Set KeypadLinc Button Toggle Mode +This action will allow you to specify whether a button toggles (alternates between ON and OFF when pressed) or whether it sends a single command anytime it's pressed (can send either ON or OFF). Useful in conjunction with Auto-Off groups above for creating "radio groups". See the [Fanlinc And Keypadlinc](fanlinc_and_keypadlinc.md) article for usage examples. + +#### Turn On/Off KeypadLinc Buttons +This action allows you to turn on/off groups of buttons. Why not just have multiple actions using the built-in Turn ON/Turn OFF LED actions? Because each of those requires a lot of Insteon traffic - and if you need to set several buttons at once this action will do it in one (or two if you want to maintain some buttons) action(s). It's more efficient and easier to configure (one action versus potentially seven actions). Select the action you want to take for each button: `Turn On`, `Turn Off`, `Leave Alone`. The latter option will require that we query the KPL to find the states first so if you select that for any of the buttons the action may execute a bit slower than it would otherwise. + +Note: using this action, which is sending raw Insteon commands through the IndigoServer, will cause the KeypadLinc's button states in Indigo to become out of sync. This is because the server doesn't know that you're changing the button states given that it's just a raw command message that it's being asked to send to the PowerLinc. If you need to keep the states in sync then add another action to do a status request to the KeypadLinc (after a short delay to avoid collisions). + +#### Configure SynchroLinc +This action will allow you to configure the Trigger Watts, Threshold Watts, and Delay Seconds in a SynchroLinc. Here are the details of those settings: + +- Trigger Watts (0 to 1800 watts in 0.5 watt steps): the wattage needed before the SynchroLinc broadcasts. +- Threshold Watts (aka hysteresis, 0 to 127.5 watts in 0.5 watt steps): tolerance before on/off toggle is sent. +- Delay Seconds (0.15 to 38.25 seconds): prevents message flooding if thresholdWatts is too low. + +#### Set I/O Linc Momentary Mode +This action will allow you to set the momentary mode of an I/O Linc to A, B, C, or None (the built-in UI only sets A or None). + +#### Set Siren Alarm Sound +This action will allow you to set the sound that the siren makes when it's turned on. The choices are chime which is a softer sound, and siren which is a very loud sound. + +#### Set Siren LED Mode +This action will allow you to set how the LED on the siren behaves. The LED can always be on or off, or it can flicker based on Insteon traffic. + +#### Set OutletLinc Load Sense +This action will allow you to turn the load sense feature of the dual outlet OutletLinc on and off (on either the top or bottom outlet). + +### Troubleshooting +If you can't get a device to sync, follow these steps: + +1. Hold down the shift & option keys while selecting the **Interfaces->Insteon/X10 Power Line->Configure...** menu item +1. In the resulting dialog, check the box next to **LILO debug logging** (leave the dialog open) +1. Switch back to the home window and try the define and sync with the AL again - you'll see a lot of debugging information show up in the Event Log window. +1. Starting with the first part of the define and sync, copy/paste all the event log lines into an email to support@indigodomo.com. +1. Switch back to the Insteon Debugging window and uncheck the **LILO debug logging** checkbox (and close the dialog) diff --git a/reference/canonical/user/interfaces/insteon/advanced-powerlinc.md b/reference/canonical/user/interfaces/insteon/advanced-powerlinc.md new file mode 100644 index 0000000..e0851c3 --- /dev/null +++ b/reference/canonical/user/interfaces/insteon/advanced-powerlinc.md @@ -0,0 +1,18 @@ + + +# Advanced PowerLinc Options + +!!! abstract "In this guide" + Covers the Advanced PowerLinc Options dialog: LED brightness controls, signal timing settings, and link sync operations including full factory reset. These options are only needed for specific troubleshooting scenarios or when instructed by Indigo support. + +Indigo provides some advanced options for the various PowerLinc Insteon interfaces. Select `Configure...` from the `Interfaces->Insteon/X10 Power Line` menu, then (assuming you have a PowerLinc interface selected) click on the `Interface Options...` button. You'll see the `Advanced PowerLinc Options` dialog: + +![Advanced Powerlinc Options Image](../../../images/advanced_powerlinc_options.png) + +The first two options should always be checked by default - you really only want to disable those options if the Indigo Support team recommends it. + +From this dialog, you can also perform some other link syncing operations: + +- Start/Stop Link Sync (same as using the menu items on the `Interfaces->Insteon/X10 Power Line` menu) +- On your PowerLinc, you can clear all of its internal links, read all the links, and sync links. You normally won't use these options unless instructed by Indigo Support +- You can completely reset your PowerLinc and resync the links all in one go - this is roughly synonymous to doing a factory reset, but not quite. Indigo support will often recommend doing a factory reset vs using this option because the factory reset performs some actions that we can't do through software. diff --git a/reference/canonical/user/interfaces/insteon/fanlinc_and_keypadlinc.md b/reference/canonical/user/interfaces/insteon/fanlinc_and_keypadlinc.md new file mode 100644 index 0000000..46f39b2 --- /dev/null +++ b/reference/canonical/user/interfaces/insteon/fanlinc_and_keypadlinc.md @@ -0,0 +1,69 @@ + + +# FanLinc and KeypadLinc + +The FanLinc is a great device - it's custom-made to control ceiling fans including the light kits attached. And, if you consider a 6-button KeypadLinc and how it might control a FanLinc, we think you'll see that they are a great combination: + +![Fan Linc Image](../../../images/kpl_fanlinc_buttons.png) + +When you look at the above image, it looks very logical and you would intuit that when you press the ON button the light goes on and when you press the OFF button the light goes off. Press and hold ON and it brightens, etc. When you press the `FAN HIGH` button the fan would switch to HIGH, etc. Think for a minute what the behavior of the LEDs on those center 4 buttons would be and you'd probably come up with the following: press HIGH and it would light up and the other three would be out. Press `FAN MED` and that light would go on and the `FAN HIGH` button would go out. Logical, right? + +This functionality is called (in most UI terminology) a radio group. One and only one button **must** be lit at a time. This is not how KeypadLinc buttons work by default - they generally work independently of one another. You can, however, tell the KeypadLinc to create radio groups like that. It can be done manually at the KeypadLinc (read the supplied instructions that came with your KeypadLinc for details) but it's quite tedious. Because we figured a good number of you might be interested in doing this, we added some Insteon commands that will allow you to configure the KeypadLinc so that it has a radio group like this. + +In fact, there are two parts to setting up a radio group. First, you have to configure which buttons go OFF when another button is pressed. So, for instance, when you press the `FAN HIGH` button (button 3 in Insteon terminology), you want the `FAN MED`, `FAN LOW`, and `FAN OFF` buttons to go off if they're on. And so on for each of the other buttons. Each of these is a separate Insteon instruction to the KeypadLinc. + +But that doesn't get you all the way there - the buttons are still toggling between ON and OFF which you don't want - you always want one and only one button lit because one of the buttons represents OFF. So the next step you want to take is to set each of the buttons into Non-Toggle Mode - and have the button always send an ON command when pressed (so it lights up if it's not already lit). + +Ok - so we've established that there are two steps to creating a radio group: create the Auto-Off groups for each button then put each button into Non-Toggle mode and tell them to send ON every time. How do you actually do it? First, you need to create the KeypadLinc radio groups (only available in Pro versions). + +## Creating Radio Groups in Indigo 6 Pro and above + +In Indigo 6, we added some convenient menu items on the `Interfaces->Insteon/X10 Power Line` submenu to perform some advanced Insteon configuration functions. First, you want to create the auto-off button groups which will cause the other buttons to go off when one of the buttons is pressed (goes on). Select the `Interfaces->Insteon/X10 Power Line->Set KeypadLinc Auto-Off Button Group...` menu item, and you'll see this dialog: + +![Auto Off Button Group Menu Image](../../../images/auto_off_button_group_menu.png) + +Select the KeypadLinc you want to work with from the KeypadLinc popup. Then, for each button in the group, repeat these steps: + +1. Select a button in the group (for instance, button 3) that, when pressed, should cause the other buttons to go out +2. Select the checkboxes next to the other buttons in the group (for instance, 4, 5, and 6) that should go out when the button selected above is pressed +3. Click `Execute` + +Repeat for buttons 4-6. This creates the auto off functionality. + +### Setting Buttons Into Non-Toggle Mode + +Next, we want to configure the buttons to always go ON (and send the ON command) when pressed. This is called non-toggle mode because the buttons don't toggle on and off when you press them. Select the `Interfaces->Insteon/X10 Power Line->Set KeypadLinc Button Toggle Mode...` menu item, and you'll see this dialog: + +![Button Toggle Mode Menu Image](../../../images/button_toggle_mode_menu.png) + +Select the `Non-Toggle` checkbox for each button in the group (3, 4, 5, and 6). Leave the `Button X sends ON` checkbox checked, since you want those buttons to always send ON commands. When you have them all selected, click `Execute`. + +That's it - your buttons are now configured in a radio group. Proceed to the [Creating the Links](#creating-the-links) section for the next steps. + +## Creating Radio Groups in Indigo 5 Pro + +With Indigo 5.1.1 we released a plugin called Insteon Commands. This plugin allowed us to add more obscure and/or advanced Insteon commands to Indigo more quickly than adding it natively to the Mac client UI. + +What you'll do is create an Action Group that executes several plugin actions, each of which will send the appropriate commands to the KeypadLinc. Once you've created the Action Group, you will execute it and several seconds later your KeypadLinc will be configured correctly. Specifically, you'll need to use two of the actions in this plugin to create your radio group. First, an Action Group (called "Set up radio group" or something) and create a `Set KeypadLinc Auto-Off Button Group` for each button (3-6) that will turn OFF all the other buttons. For instance, here's the configuration for button 3: + +![Auto Off Button Group Image](../../../images/autooffbuttongroup.png) + +Repeat the action for each of the other (4-6) buttons, turning off the rest. Next, create a `Set KeypadLinc Button Toggle Mode` action that sets buttons 3-6 to Non-Toggle mode (and leave the `Button # sends ON` checkboxes checked): + +![Toggle Button Image](../../../images/togglebutton.png) + +That's it - execute the Action Group and the buttons should be set up such that when you press one it will go on and the others will go off. If not, revisit each of your actions and make sure that you have them configured correctly. + +## Creating the Links { #creating-the-links } + +Good - you've taken the first step to get your 6 button KeypadLinc controlling your FanLinc. The next step is to link the KeypadLinc buttons to the FanLinc so that when you press them they control the fan and light respectively. Creating Insteon links is covered in the [Managing Insteon Devices](index.md) document - you want to link button 1 to the FanLinc lights and buttons 3-6 to high, medium, low, and off respectively. + +Congratulations! You now have the KeypadLinc directly controlling fan speeds via the middle 4 buttons and the fan light being controlled by the top and bottom buttons. Done! + +## Almost Done + +Well, we're almost done. If you never intend to control the fan from Indigo, then yes, you're done. However, if you also want to control the fan from Indigo as well as from the KeypadLinc, you need to do just a bit more work. As you might have read in the multi-way groups and KeypadLinc Buttons articles, keeping KeypadLinc buttons in sync when controlling the lights they're linked to requires a little more work. This is because when you control a device from Indigo, we have to use direct commands. This will not cause the links you've created between devices to be activated (there isn't a way to simulate a button press on a KPL to cause that behavior). Because of that, the KeypadLinc buttons that are linked to other devices can get out of sync if the device is controlled from Indigo. + +One other thing that complicates this particular scenario is the fact that Indigo can't create multiple links to the same device in a single group. For instance, you can't create a PowerLinc scene that includes multiple buttons on the same KeypadLinc. This is a limitation in Indigo that's not likely to be overcome soon because of the nature of how those links are maintained and how Indigo treats devices and links. Because of these things, you'll need to control the FanLinc Fan through Action Groups (rather than directly) so that the KeypadLinc's buttons will stay in sync. Fear not, there's an action in the [Insteon Actions](index.md) section that will help with that as well. + +The simplest approach is to create 4 triggers - one each for when the Fan speed becomes `High`, `Medium`, `Low`, and `Off`. The action for those actions will be to set the KPL's button LEDs appropriately. Rather than setting each LED separately using the built-in mechanism for setting LEDs (which would require a lot of Insteon communication), you can use the `Turn On/Off KeypadLinc Buttons` action in the [Insteon Actions](index.md) section of the Action type popup. That will only send 1 command to the KPL to set the state of all buttons. So, for the trigger that fires when the Fan speed becomes `High`, in the action's config dialog you would select the KeypadLinc, then select `Turn Off` for buttons 1, 2, 4, 5, 6, 7, 8 and `Turn On` for button 3. Now, you might be asking yourself why we'd want to turn off 1, 2, 7, and 8. Actually, because this is a 6 button KeypadLinc, those actions will be ignored since 1 and 2 are the load ON button and 7 and 8 are the load OFF button. The only important ones to turn off are 4 (`Medium`), 5 (`Low`), and 6 (`Off`) since the fan is on `High`, and turn button 3 (`High`) on. Now, if you're operating the switch buttons manually, this will already be the case - but that's OK. If you're operating the fan from somewhere else - like a control page - this will keep the KeypadLinc's LEDs in sync. diff --git a/reference/canonical/user/interfaces/insteon/insteon_links.md b/reference/canonical/user/interfaces/insteon/insteon_links.md new file mode 100644 index 0000000..b49aa14 --- /dev/null +++ b/reference/canonical/user/interfaces/insteon/insteon_links.md @@ -0,0 +1,33 @@ + + +# Insteon Links + +Insteon devices provide a simple way to link together so that one device knows about and can (optionally) control another. And, unlike X10, you can link multiple devices together in different ways to create groups or scenes. For instance, let's say you have a SwitchLinc called "Dining Room", a KeypadLinc (that has 6 buttons) called "Hallway", a LampLinc called "Office", and another SwitchLinc called "Media Room". You could link these devices together in the following ways (these are just a few examples): + +1. Button 3 (the first small button) on "Hallway" could control "Office" such that pressing and holding (when off) would brighten that light, and doing so when it was on would dim that light. +2. By linking together "Dining Room", "Hallway", and "Media Room", you could have all of those lights come on, dim, brighten, and go off at the same time, same rate, etc. +3. You could have a button 4 on "Hallway" set each light to a different setting, creating a scene. + +All of these things can be done using just the link protocols that are part of the Insteon specification. Creating these links manually in the devices can be a little cumbersome - you have to walk around your house putting each device into link mode, for each link you want to establish, on each device. For the last example, assuming you wanted to set "Dining Room", "Office", and "Media Room", you would need to touch "Hallway", then the device, to create the link. That's 6 device touches for just that scene. + +That's where Indigo can help. Indigo will allow you to [create almost any Insteon links](index.md) that can be created manually, without having to walk around your house putting switches into link mode, setting options, etc. Indigo talks to the Insteon network via the PowerLinc 2414U interface. This interface is just like any other device: it can create links, etc. What's special about the PowerLinc is that it has a USB port that allows your Mac to communicate with it. So, your Mac can see what Insteon signals are being sent and can send those signals as well. + +You can accomplish many of your Home Automation scenarios without Insteon links - for instance, you could have Indigo listen for a button press on "Hallway", and then Indigo would perform the actions of setting each light to a different brightness. There is a lot of flexibility in this approach because it's easier to change what actions are performed and Indigo has a much wider variety of actions to perform - not only directly controlling HA devices, but using more logic to determine if an action should be performed. + +For instance, let's say that we want button 4 to operate as described above, but also if the time of day is between dusk and dawn, you want it to additionally turn on a new switch, called "Porch Light". Using only Insteon links, you couldn't accomplish this logic. However, if you were using Indigo, you could accomplish this. There are several ways, but the easiest would be to create 2 almost identical trigger actions: both would trigger when button 4 of "Hallway" was turned on. The difference would be that the condition for one would be "If dark" and the other would be "If daylight". The actions for both would be identical except you'd add another action to the "If dark" trigger that would also turn on "Porch Light". + +So, why would you choose one over the other? Here are some advantages and disadvantages to each approach: + +**Insteon Links** + +- Don't require Indigo to be running to work +- Act instantaneously - that is, if dimmable lights are linked together, they can dim and brighten at the same rate as you hold down the button/switch +- Links aren't necessarily easily edited or altered - it's a little more difficult to see what's linked to what + +**Indigo Triggers** + +- Allow for considerable flexibility - Indigo has many more action types +- Require Indigo to be running +- Because of the extra step of communication between Indigo and the PLC, actions aren't necessarily immediate - a delay of up to a couple of seconds between the time the trigger fires and the time that Indigo can start sending Insteon commands is possible. + +So, now that you have a general idea of each method, the good news is that you can use both at the same time! So, for instance, after you set up button 4 using Insteon links as described above, you could then add a trigger action in Indigo that would, if it's dark, turn on "Porch Light" as well. diff --git a/reference/canonical/user/interfaces/insteon/powerlinc-2413s.md b/reference/canonical/user/interfaces/insteon/powerlinc-2413s.md new file mode 100644 index 0000000..5660a25 --- /dev/null +++ b/reference/canonical/user/interfaces/insteon/powerlinc-2413s.md @@ -0,0 +1,14 @@ + + +# PowerLinc 2413s + +!!! abstract "In this guide" + Setup instructions for users running the PowerLinc 2413S serial Insteon interface via a USB-to-serial adapter. Includes a factory reset procedure for units previously used with another home controller (ISY, etc.) and driver installation notes. + +Although Indigo officially supports the USB PowerLinc 2413U interface, users have reported success using the serial version (2413S) along with USB to serial adapters. Note that if the 2413S was previously used with another home controller (ISY, etc.) then you should first factory reset it: + +1. Unplug the PowerLinc 2413S from the Mac. +1. Unplug the PowerLinc 2413S from the wall outlet. +1. Hold down the SET button on the device for 20 seconds. +1. While still holding the SET button plug it back into the wall and keep holding the SET button for 20 additional seconds, then release. +1. Install the USB to serial adapter driver, plug the adapter into the 2413S and your Mac, then select the correct Serial Port in the interface settings for the device. diff --git a/reference/canonical/user/interfaces/virtual-devices.md b/reference/canonical/user/interfaces/virtual-devices.md new file mode 100644 index 0000000..8d792e2 --- /dev/null +++ b/reference/canonical/user/interfaces/virtual-devices.md @@ -0,0 +1,174 @@ + + +# Virtual Devices Interface + +!!! abstract "In this guide" + How to enable and use Indigo's Virtual Devices Interface to create non-physical device types — Device Groups, Aggregate and Average Sensors, Virtual Dimmers, and more — that track or aggregate the states of real hardware devices. Covers enabling the interface and configuring each device type. + +Indigo provides a Virtual Devices Interface type that provides users with several new device types, each discussed below. If you want to use Virtual Devices, make sure to enable them by selecting the `Interfaces->Virtual Devices->Enable` menu item. + +To add a virtual device to Indigo, follow these steps: + +1. Select `DEVICES` in the Main Window outline view or select one of the sub-folders. +1. Click the `New...` button. You'll see the `Create New Device` dialog. +1. Select `Virtual Devices` from the Type popup menu. +1. Select the model of virtual device you want to create (described below). + +## Device Groups +With the addition of Z-Wave (and various plugins that define dimmer and relay devices) it has become apparent that we need to provide some way to create technology-agnostic groups of devices. You can, of course, control groups of devices through Action Groups, and for most cases that's good enough. + +However, there are some cases where you want a group to track the state of the devices it contains. So not only do you want to turn on/off a group, you want to know when any of the devices in the group "leave" the definition of the group by changing. So we've created a new "Device Group" device to help you with that. + +We've also added a twist to this device. When we create the device (and anytime later), we save off the current state of each device in the group. It's like taking a snapshot of each device. When you turn ON the group, we'll use the value that the device was when you last saved the device states. We think you'll really love this feature since you can set all the devices how you want them, then save the device states. + +To create a device group, you just create a new device, select `Virtual Devices` from the `Type` menu, select `Device Group` from the model menu, and you'll see the configuration dialog: + +![Device Group Configuration Image](../../images/device_group_config.png) + +Select the devices you want to be in the group (only dimmer devices, relay (on/off) devices, and sensor devices that support an on/off state are available). To select multiple, hold down the command key and click the device in the list. Notice that the devices all have something in parentheses after the name - that's the current value of the device that will be saved. If it's a dimmer device, it shows the brightness and if it's a relay (On/Off) device, it shows whether it's on or off. When you save, that's the value that will be saved. These values will be used when the group is turned on. + +Next, you specify how the plugin will manage the ON state of the device group. The two choices are: + +- All devices are ON - the group state will be set to ON when all devices in the group are ON +- Any device is ON - the group state will be set to ON when any of the devices in the group are ON + +Finally, you need to specify how Indigo will determine if a device is ON or OFF. For dimmer devices, you have the following options: + +- Brightness >= saved value - by selecting this option, the device will be considered ON when the brightness is greater than or equal to the value of the brightness saved for that device. Note that you can have a brightness set to 0 when the group was saved, in which case when the group is turned on the brightness will be set to 0. +- Brightness > 0 (On) - by selecting this option, the device will be considered ON when the brightness is greater than 0. So it will be considered on even at very dim settings. + +For relay (on/off) and sensor devices, you have the following options: + +- Equal to saved value - by selecting this option, the device will be considered ON when it is equal to how it was set when you saved the state for that device. This way, you can add a device when it's off and turning on the group will in fact turn off the device. +- On - this is the most obvious option - if the device is really ON, then it's considered ON. + +To use a device group, just use the standard `Control Light/Appliance` action to turn it ON/OFF, and create triggers on the group's ON and OFF state via the `Device State Changed` trigger type. Turning a device group on will set all the devices to their respective saved state. You can also update the states of the devices in the group at any time by using the `Update Device Group States` action or menu item. That's it! + +## Sprinkler Group +We've regularly heard that users have multiple sprinkler controllers and would like to treat them as a single controller. This Virtual Device does just that. You can specify up to 4 different physical sprinkler devices: + +![Sprinkler Group Configuration Image](../../images/sprinkler_group_config.png) + +Indigo will treat the resulting group as a single sprinkler. You can create standard sprinkler schedules for it and never have to worry that there might be multiple sprinkler controllers running at the same time. + +## Virtual On/Off Devices +One of the things that we often see are people who want to create a device that can be turned ON and OFF, but don't have the knowledge or expertise to build a full-on plugin. And sometimes a full plugin would be overkill, particularly if the device is so custom that it really wouldn't be useful to anyone else. + +That's where the `Virtual ON/OFF Device` comes in. This device type will allow users create custom devices without the need to build an entire plugin. In fact, the first iteration of this device doesn't even require any programming at all! Virtual devices can be shown in the Indigo UI, the Indigo Web UI, and the Indigo Touch UI as on/off style devices and can be controlled using the normal on/off UI controls. + +To create a virtual device, you just create a new device, select `Device Collection` from the `Type` menu, select `Virtual On/Off Device` from the model menu, and you'll see the configuration dialog: + +![Pseudo On Off Configuration Image](../../images/pseudo_onoff_config.png) + +### Execution Models +We intend to support several different ways that users can have virtual devices accomplish their tasks: + +- Action Groups - where the functions are carried out by Action Groups (with a little assist from Variables if you want) + +We've only implemented Action Groups, but in future releases we may add other execution models. + +#### Action Groups +In order to make virtual devices simple enough for non-technical users to use them, we started with the Action Groups execution model. This means that you specify an action group to execute for each of the major tasks that a ON/OFF Device can perform: turn on, turn off, toggle, and get status. Here's the config dialog for Action Groups: + +![Pseudo On Off Configuration Image](../../images/pseudo_onoff_config.png) + +The first thing you'll select are the action groups to execute when the device is turned on and off. So if you click the `Turn On` button or select the `Turn Off` action in the `Control Light/Appliance action`, for example, the appropriate action group will be executed. These two are the minimum requirements for this type of virtual device. + +Next, you can specify an action group that will toggle a device - so if there's some way for your action group to determine at runtime how a toggle should work then you can specify it. If not, just leave the checkbox unchecked. + +##### Automatic State Maintenance +Finally, your virtual device can maintain a state if you like. But, Action Groups can't directly manipulate state you say, right? Well, that's true. However, Action Groups can modify a variable. So, we've allowed you to select a variable and we'll monitor that variable for any change. If the value of the variable becomes "on" (or "true", "open", "1", "yes", "enabled"), we set the state of the virtual device to on. If the variable becomes "off" (or "false", "closed", "0", "no", "disabled"), then we set the state to off. + +If you set the value of the variable to anything else, we'll set the state of the device to whatever you entered for the variable value AND we'll mark it as having an error. This will cause the device to turn red in the device list to help show you that there's a problem. (Z-Wave devices will do this as well and eventually Insteon devices will too). + +So your device's state will mirror the value in the variable. You can also specify an action group that will be called when you request a status update via the UI or via an action. + +Note: if you don't enable `Supports Status`, your virtual device will always show as being "off" in the UI and triggers that watch for state change will never fire. That may be fine for your particular needs so we made it optional. + +##### Scripting State Maintenance +You can also set the on state of a virtual device: + +```python +virtual_devices_interface = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.devicecollection") +if virtual_devices_interface.isEnabled(): + virtual_devices_interface.executeAction('setVirtualDeviceState', deviceId=DEVICEIDHERE, props={'newValue': 'on'}) +``` + +Use **on** or **off** to set the state, anything else will be interpreted as an error and will show accordingly in the UI. + +So that's it - you can implement a very simple On/Off virtual device just by specifying a few action groups. + +## Virtual Sensors +Virtual Sensors are plugin devices that are linked to external Python scripts that send instructions to the Virtual Device so it can be used to track a desired status. The device also sends information back to the external script for further processing if needed. + +Say you want to use an external script to send a value to the Virtual Device based on some logic in your script and then fire an Indigo Trigger based on the result. You would create a Virtual Sensor, link it to your external script, and set up an update Action to tell the Virtual Sensor to request a status update from your script. + +![Virtual Sensor Configuration Dialog Image](images/virtual_sensor_config_dialog.png) + +### Supported States +Virtual Devices support two states and **must** support at least one of the following: + +- On State - your device will have an on/off state. +- Sensor Value - your device will have a sensor value. + +#### Script Locations +You can add scripts directly to the *`/Library/Application Support/Perceptive Automation/Python3-includes`* folder, or you can point to a script in any location that Indigo has the authority to access. Python scripts that are saved to the above folder will be available in the Script File dropdown menu. Alternatively, you can check the Custom Location checkbox and a field will open for you to enter the full path to the script file. + +##### Controlling Scripts +You control the state of Virtual Sensor Devices with Python scripts (the device executes the controlling scripts directly). The controlling script must have a *`virtual_sensor_status()`* method which the Virtual Sensor Device will call, and **must** return a valid dictionary with the following possible keys (types shown in brackets): + +```python +# If you want to pass something to the Indigo Event Log, you will need to import the +# logging module and access the parent plugin's logging instance. +import logging +logger = logging.getLogger("Plugin") + +def virtual_sensor_status(device: indigo.Device, action_props: dict) -> dict: + """ + This is the only method that the virtual sensor will call, unless you make calls to + other parts of your script from here. + + :device: a copy of the virtual sensor device object [indigo.Device] + :action_props: any action object properties provided [dict] + :returns: updated sensor values [dict] + """ + payload = dict() + payload['onState'] = True # must be a bool [True/False] + payload['onStateUiValue'] = "Closed" # Can essentially be any valid string [string] + payload['sensorValue'] = 32 # note that Indigo always stores this as a float [int or float] + payload['sensorValueUiValue'] = "32º" # the value in Indigo's UI. [string] + payload['icon'] = "indigo.kStateImageSel.TemperatureSensor" # i.e., [indigo.kStateImageSel] + + logger.info("Linked script executed.") + return payload +``` +`*device*` -- in this context, the `*device*` parameter will contain a copy of the Virtual Sensor device that is linked to the script. +`*action_props*` -- in this context, the `*action_props*` parameter will contain any props passed from the Indigo Action that caused the Virtual Sensor device to update. If the device was updated by a *`Send Status Request`* or a "generic" Indigo Action refresh call, *`action_props`* will be an empty dictionary. + +The Virtual Sensor will adjust its states based on the values returned from the *`virtual_sensor_status`* method. When that method is executed, you can make calls to other parts of your script in order to determine what the payload values should be. If the update is completed successfully, the Virtual Sensor will provide a copy of the *`device`* object and an *`action_props`* dict when it requests an update from your script. + +##### Triggers and Actions +Virtual Devices will respond to an Indigo Action call. When the Update Virtual Sensor Action is called, the Virtual Device will reach out to your script and update its states accordingly. You can also refresh the Virtual Sensor device by making a call to Indigo's API. + +The `*indigo.actionGroup.execute*` API command message doesn't include action props, so the `*action_props*` property above will be an empty dict. You can execute this command message from both the Websocket and HTTP APIs. + +```python +{ + "id": "optional-custom-user-message", + "message": "indigo.actionGroup.execute", + "objectId": 123456789 +} +``` + +The `*plugin.executeAction*` API command message can include optional props, and is currently only available in the HTTP API command space. +```python +{ + "id": some-optional-message-ID, + "message": "plugin.executeAction", + "pluginId": "com.some.indigo.plugin", # the plugin's bundle identifier + "actionId": "some_plugin_action", # the ID of the plugin action found in the plugin's Actions.xml file + "deviceId": 12345678, # the device ID targeted by the plugin action (not all actions will require a device ID). + "props": {"prop1": "foo", "prop2": "bar"}, + "waitUntilDone": True +} +``` diff --git a/reference/canonical/user/interfaces/x10.md b/reference/canonical/user/interfaces/x10.md new file mode 100644 index 0000000..2d22ce3 --- /dev/null +++ b/reference/canonical/user/interfaces/x10.md @@ -0,0 +1,32 @@ + + +# Connecting X10 Interfaces + +!!! abstract "In this guide" + How to connect an X10 RF interface and add X10 devices to Indigo using house/unit codes. Covers the device type selection dialog, the Module Definition dialog for unlisted devices, and how to control X10 devices from Indigo actions. + +If you are using a PowerLinc or CM15 then enable it as described in the [Managing Insteon Devices](../insteon/index.md#connecting-insteon-and-x10-power-line-interfaces) document. + +The process for connecting X10 **RF** Interfaces is basically the same as for power line interfaces - you just need to select the correct serial port. The W800USB will require installing the [FTDI drivers](../insteon/index.md#install-the-ftdi-vcp-drivers) mentioned above. You only need to use this interface if you're using a separate X10 RF interface like the W800 or MR26. + +![X10 RF Configuration Dialog Image](../../../images/x10_rf_config_dialog.png) + +## Adding and Managing X10 Devices +First, make sure that Indigo has enabled communication with the interface. If Indigo is not online with the interface, then choose the `Interfaces->Insteon/X10 Power Line->Enable` menu item. See [connecting the Interface](../../getting-started/index.md#connecting-insteon-and-x10-interfaces) in the [Getting Started](../../getting-started/index.md) guide for more details. + +!!! tip "TIP" + You may also need to bridge the two phases of your power line to get reliable communication. Search for "X10 signal bridge" in your favorite search engine for details. + +To add an X10 device, select `DEVICES` in the outline view (or one of it's sub-folders) and click the `New...` button. Select `X10` from the `Type:` popup and you'll see the following: + +![X10 Device Detail Image](../../../images/x10_device_detail.png) + +Every X10 device in Indigo is defined by a collection of settings that detail the characteristics of that device. For example, there are several different X10 codes used to dim and brighten light switch devices. Depending on the type of device module used, it will respond to some X10 codes for dimming but not others. And some devices have additional features, like the ability to transmit back to Indigo when the device is turned on and off locally at the device itself. + +Normally, you will not need to worry about these device settings. By choosing the correct device type in the device dialog, Indigo automatically chooses the correct settings for that particular device module. + +However, you may have a device module not currently listed in the Type popup menu. To use devices that are not defined in the device Type popup, you can click the `Definition...` button you will be shown the `Module Definition` dialog: + +![X10 Definitions Dialog Image](../../../images/x10_definitions_dialog.png) + +If you know the specific features of your X10 device you can manually set them here. If you have difficulties finding the settings for a device you have, then visit our [online support forum](https://forums.indigodomo.com/). It is possible that one of our users has already discovered the correct settings to use. diff --git a/reference/canonical/user/interfaces/x10/rf-options.md b/reference/canonical/user/interfaces/x10/rf-options.md new file mode 100644 index 0000000..7e02bc7 --- /dev/null +++ b/reference/canonical/user/interfaces/x10/rf-options.md @@ -0,0 +1,12 @@ + + +# X10 RF Options + +!!! abstract "In this guide" + Covers the RF Interface Options dialog for X10 RF interfaces, where you specify which house codes the interface monitors and optionally remap and retransmit received signals on the power line. + +Indigo provides some advanced options for the various X10 RF interfaces (including the CM15 which is both Power Line and RF). Select `Configure...` from the `Interfaces->X10 RF` menu, then click on the `Interface Options...` button. You'll see the `RF Interface Options` dialog: + +![X10 RF Options Image](../../../images/x10_rf_options.png) + +This dialog will allow you to specify which X10 house codes the interface will respond to. You can also optionally have that house code remapped to another house code and retransmitted on the PowerLine. diff --git a/reference/canonical/user/interfaces/z-wave.md b/reference/canonical/user/interfaces/z-wave.md new file mode 100644 index 0000000..0409d9d --- /dev/null +++ b/reference/canonical/user/interfaces/z-wave.md @@ -0,0 +1,268 @@ + + +# Managing Your Z-Wave® Network + +!!! abstract "In this guide" + How to connect and configure a Z-Wave interface, add and interview Z-Wave devices, perform secure inclusion for locks and sensors, and troubleshoot common interview failures. Also covers Z-Wave network repair, device removal, and managing device associations. + +Indigo provides several tools to manage your [Z-Wave](about.md) network. Not only can you create/control/delete devices but you can also [manage device associations and scenes](#manage-associations). See the [Connecting Z-Wave Interfaces](#connecting-z-wave-interfaces) section below for details on connecting and configuring your Z-Wave interface. + +Tip: if you're having issues with Indigo communicating with some of your Z-Wave devices, look at the position of your Z-Stick. If you have it plugged directly into your Mac then the chances are that the signal range is reduced somewhat. Also, if there are any other electronics close to it (external hard drives, etc.) then you may want to try to move the interface around a little. For the Z-Stick, try a USB hub with connectors on the top that allow you to position it vertically. A word of warning: some users have used short USB extension cables successfully but others have found that these sometimes cause communication errors with the Z-Stick. + +## Connecting Z-Wave Interfaces +First, check out our [supported interfaces list](http://www.indigodomo.com/devices/interfaces/) to see if the interface you want to use has been tested with Indigo. + +### Install the Appropriate Drivers +The [Aeotec Z-Stick Gen5/Gen5+](https://aeotec.com/z-wave-usb-stick/) uses a built-in driver included with Mac OS X (AppleUSBCDC Modem), so you don't need to install any drivers for it. Note that if you move the stick to a different port or if you upgrade to a new OS version you will need to reselect the serial port. + +The Aeotec [Z-Stick Series 2](https://smile.amazon.com/Aeon-Labs-DSA02203-ZWUS-Z-Wave-Z-Stick/dp/B003MWQ30E/) and [Z-Stick 7](https://aeotec.com/products/aeotec-z-stick-7/) interfaces require that you install the [Silicon Labs VCP Driver Kit](http://www.indigodomo.com/silabsurl) for Mac OS X. Make sure you have restarted after the installation process. If you reinstall your OS, then you will need to rerun the driver installer. Warning: Before upgrading macOS to the next major revision, please visit the [Announcements section of our forums](https://forums.indigodomo.com/viewforum.php?f=2) to see if there are potential issues with the OS update. + +The [SmartStick+](https://shop.homeseer.com/collections/z-wave-usb-sticks-network-controllers/products/homeseer-smartstick-g-usb-z-wave-stick) is a serial interface from HomeSeer that also uses the built-in driver included with Mac OS X (AppleUSBCDC Modem), so you don't need to install any drivers for it. Note that if you move the stick to a different port or if you upgrade to a new OS version you will need to reselect the serial port. + +The [GoControl QuickStick Combo](https://smile.amazon.com/QuickStick-Combo-HUSBZB-1-Nortek-Cert/dp/B0157GOEA8/) is an interface that includes both Z-Wave and Zigbee (though Zigbee isn't supported natively in Indigo). It also requires that you install the [Silicon Labs VCP Driver Kit](http://www.indigodomo.com/silabsurl) for Mac OS X, specifically v5 or later. It will then present 2 new serial ports: GoControl_zwave (which is the one you select) and GoControl_zigbee (for the Zigbee interface). + +As mentioned before, other Z-Wave Interfaces that support the Z-Wave Serial API may be compatible and those may require other drivers. Check the [Interface Hardware](https://www.indigodomo.com/devices/interfaces/) list to see what interfaces we've actually tested. + +### Connecting the Z-Wave Interface +Plug the Z-Stick into an available USB port connected to your Mac. We've done some testing with this interface connected to a USB hub with favorable results (unlike some other Insteon and X10 interfaces). However, if you experience any type of errors when trying to configure/use the interface you may try plugging the stick directly into a USB port on your Mac. + +Tip: We highly recommend that you position your Z-Stick carefully. If you have it plugged directly into your Mac then the chances are that the range is reduced and you may have problems communicating with devices that are physically far away. Also, we recommend getting a powered USB hub that allows the Z-Stick to stand straight up for the best signal. Avoid using USB extension cables as they have been known to cause issues. + +### Configuring Indigo to use Your Z-Wave Interface +![Z-Wave Configuration Dialog Image](../../../images/zwave_configuration_dialog.png) + +Once you have your interface plugged into a USB port, you can enable and configure Z-Wave in Indigo: + +1. Choose the `Interfaces->Z-Wave->Enable` menu item. This should cause the `Configure Z-Wave` dialog to open automatically (but only the first time you enable Z-Wave - you can select the `Interfaces->Z-Wave->Configure...` menu item to get back to the configuration dialog later): +1. The default `Connection Type` of `Local (physical)` is correct (assuming you've plugged your Z-Stick directly into your Mac). +1. On the `Serial Port` popup, you should select the serial port titled `SLAB_USBtoUART` (for Z-Stick Series 2) or one that *starts* with `usbmodem` (for Z-Stick Gen5), depending on which Z-Stick version you have. If you have two serial ports that start with `SLAB_USBtoUART` that means that you have multiple devices that use the Silicon Labs VCP driver - you'll just need to try each one to determine which is the correct port if you don't know beforehand. Unfortunately, that driver doesn't handle multiple devices using the Silicon Labs chip very well, and that number may change when you reboot. +1. Unless instructed by Perceptive Automation support, you should leave the `Show debug logging of interface communication` checkbox unchecked. +1. Save the `Configure Z-Wave` dialog. + +### Enabling and Disabling Z-Wave Communication +Choose the `Interfaces->Z-Wave->Disable` (or `Enable`) menu item to disable/enable the interface. + +We recommend that you finish skimming this document and the overview document so that you'll get a firm understanding of the basics of Indigo. However, if you want to jump ahead, you can go directly to the document that discusses how to create and manage your [Z-Wave network](index.md). + +## Adding a Z-Wave Device +Indigo supports a [variety of Z-Wave devices](http://www.indigodomo.com/devices/#zwave). + +Before proceeding, make sure that you have [connected and enabled your Z-Wave interface](../../getting-started/index.md#connecting-z-wave-interfaces). + +To add a Z-Wave device to Indigo, follow these steps: + +1. Select `DEVICES` in the Main Window outline view or select one of the sub-folders. +1. Click the `New...` button. You'll see the `Create New Device` dialog. +1. Select `Z-Wave` from the Type popup menu. +1. Click the `Define and Sync...` button. +1. You'll see the `Synchronize Z-Wave Device` dialog. +1. Follow the directions on the dialog to complete setting up the device. + +![Z-Wave New Device Dialog Image](../../../images/zwave_new_device_dialog.png) + +Note: all battery-powered Z-Wave devices will go to sleep to conserve battery power - when they are asleep, they will not respond to commands. Indigo needs to send the device some commands when it's adding the device, so you'll need to follow the manufacturer's instructions to wake the device up when you actually add the device to Indigo. + +IMPORTANT: When adding a device (particularly a battery-powered device), the device may enter sleep mode before we can finish all the sync activities needed to add the device. If this happens, you'll get an error before the sync is finished. In this case, you can often just repeatedly tap the include button/paddle, tamper button/mechanism, etc., to keep the device awake. Another option is to remove the batteries from the device and wait a few minutes. Then reinsert them (which will often put the device into an awake status for several minutes) then do the sync again. + +### Using Encryption +As mentioned in the dialog, we recommend using encryption only for devices where it is beneficial or required (like locks). Although encryption increases security, it can also degrade responsiveness of the hardware and increase the potential for network congestion and retries. The additional commands required for encryption can also decrease battery life. + +### Changing Existing Hardware Inclusion to Use Encryption +If you added a device to the network (Z-Wave Controller) without encryption enabled and then wish to enable encryption you must first remove it from the network. This is because the encryption key exchange can only occur with Indigo if the device has just been added to the network (within a few seconds), and before a device can be added to the network it must not be included in any networks. To do this you can use the `[Interfaces->Z-Wave->Start Controller Exclusion Mode](#start-controller-exclusion-mode)` menu item to put the Z-Wave Controller into exclusion mode, then follow the steps from the device's manual to have it exclude itself from the network. Once excluded (you can see the progress in the `[Event Log window](../../mac-client/event-log.md#event-log-window)`), you can then use the `New with Encryption Enabled` button inside the Synchronize Z-Wave Device dialog to re-add it to the network with encryption. + +### Moving a Z-Wave Lock from a Different Controller to Indigo +If you have a Z-Wave lock currently included with another controller, you must first exclude the lock from the network before adding it to Indigo with encryption enabled. To do this you can use the `[Interfaces->Z-Wave->Start Controller Exclusion Mode](#start-controller-exclusion-mode)` menu item to put the Z-Wave Controller into exclusion mode, then follow the steps from the device's manual to have it exclude itself from the network. Note you do not have to use the original controller to perform the exclusion -- you can use Indigo's exclusion process. Once excluded (you can see the progress in the `[Event Log window](../../mac-client/event-log.md#event-log-window)`), you can then use the `New with Encryption Enabled` button inside the Synchronize Z-Wave Device dialog to add it to Indigo's Z-Wave network with encryption. Follow the instructions from the lock's manual for the inclusion steps required. Note that either the Z-Wave Controller used by your Mac or a device that supports Z-Wave beaming will need to be close to the lock for the communication to succeed. + +### Editing a Z-Wave Device's Properties { #editing-a-z-wave-device-s-properties } +Once you've defined your device, you can edit its properties. If you've still got the device dialog open, you can skip the first three steps below. + +1. Select `DEVICES` in the Main Window outline view or select one of the sub-folders. +1. Find the device in the device table and double-click it (or select it and click the `Edit...` button) +1. You'll see the standard `Edit Device` dialog +1. Click on the `Edit Device Settings...` button and you'll see the configuration dialog: + +![Z-Wave Dialog Settings Image](../../../images/zwave_dialog_thermo_settings.png) + +The top part of that dialog shows some details about the device that will help support when diagnosing problems. + +Next, the polling properties for the device are shown if they are applicable to the device type. The first thing you need to determine is if the device needs to be polled to check for status changes. Most devices will require some kind of polling to stay in sync. There are a few devices that Indigo can determine status changes on automatically, and we'll turn off the checkbox for those when we define the device. There are many devices that don't send out this information though (primarily because of some patents held by Lutron) so we give the option to poll the device. + +Next, select the desired polling interval. This setting is quite important actually - the more frequently you poll a device the more congested your network will become. In fact, we can't guarantee an exact polling frequency below 5 minutes because we have to watch for the network to become idle before we can try polling. So, we suggest that the less important devices to keep in sync are polled at longer intervals and more critical devices get polled immediately. You can also poll devices that can't or don't get manually operated at a much lower frequency because Indigo will update the state as soon as the command to operate the device is acknowledged. + +The top item on the list, `Only When Activity Detected`, is a great optimization - some devices send out a message whenever they change - they don't actually send the necessary information for Indigo to automatically update state, but it is enough to bump the device to the top of the poll list so that the status update will occur much more quickly. And it keeps us from having to poll the device at regular intervals because we can just poll it when we see this specific message. How do you know to select this option? You can try the setting out: just select `Only When Activity Detected` and save the device. Then, go manually operate the device. If the status updates (within about 10 seconds) then you can leave it. If the status never updates then you'll need to pick one of the other intervals as described above. + +The fastest polling option is `As Often as Possible` - we'll poll the device as frequently as we can, given the conditions of the Z-wave network. + +Also shown in the settings dialog are any configuration parameters specific to that device (in this example the temperature units and display contrast). Indigo only shows settings if there is a custom device profile for a particular device. However, if no settings are shown you can still modify any configuration parameters by using the `[Interfaces->Z-Wave->Modify Configuration Parameter...](#modify-configuration-parameter)` menu item. + +If a `Submit Device Information` button is visible, then you can use it to help us learn more about the device. When pressed a page will open in your browser asking for some more information that will help us and other users more effectively use the device. Please take time to accurately fill out the form as much as possible. The more information we have the more likely we will be able to add a custom device profile to fully support the device. + +Maintaining our [Z-Wave Supported Device List](http://www.indigodomo.com/devices/#zwave) is a community effort since we can't possibly directly test every Z-Wave device available worldwide. We appreciate your help! + +## Resyncing a Z-Wave Device +Sometimes you may be instructed by support to resync your device - the process is quite simple: + +1. Select `DEVICES` in the Main Window outline view or select one of the sub-folders. +1. Find the device in the device table and double click it (or select it and click the `Edit...` button). +1. Click the `Define and Sync...` button. +1. Click on the `Sync` button. +1. When the `Synchronize Z-Wave Device` dialog disappears, just close the `Edit Device` dialog. + +This will tell Indigo to query the device and update various information about it and may help with some communication issues. + +## Replacing a Z-Wave Device +If a Z-Wave device fails (and depending on the type), you may be able to just replace it with a new one and all Triggers, Conditions, Actions, and Control Pages will continue to work. To replace a device: + +1. Select `DEVICES` in the Main Window outline view or select one of the sub-folders. +1. Find the device in the device table and double click it (or select it and click the `Edit...` button). +1. Click the `Define and Sync...` button. +1. Follow the instructions on the dialog to use your controller to include the device into your network if you haven't already. +1. Select the new device in the `Sync using node` popup. +1. Click on the "Sync" button. +1. When the `Synchronize Z-Wave Device` dialog disappears, just close the `Edit Device` dialog. + +Note that not all devices can be replaced. Specifically, if a [device has multiple personalities](../../concepts/devices.md#devices-with-multiple-personalities) (like, for instance, a multi-sensor that has a motion sensor, temp sensor, humidity sensor, etc.) and any of those dependent devices are used in Triggers, Conditions, Actions, or Control Pages, then you'll get an error message in the `[Event Log window](../../mac-client/event-log.md#event-log-window)` saying that you need to manually resolve those conflicts (or manually delete the device). Indigo helps with this process - see [Deletion Dependencies](../../concepts/deletion-dependencies.md) for details. + +IMPORTANT: When replacing or resyncing a device (particularly a battery-powered device), the device may enter sleep mode before we can finish all the sync activities needed to re-add the device. If this happens, you'll get an error before the sync is finished. In this case, you can often just repeatedly tap the include button/paddle, tamper button/mechanism, etc., to keep the device awake. Another option is to remove the batteries from the device and wait a few minutes. Then reinsert them (which will often put the device into an awake status for several minutes) then do the sync again. + +## Excluding a Z-Wave Device +From time to time, you may find the need to exclude a device from your Z-Wave network. For example: + +- you want to factory reset it (resetting doesn't necessarily require a device to be excluded from the network), +- replace a device with a newer device, or +- add a device to your setup that was previously included in another controller. + +There are some important points to remember about device exclusion: + +- Excluding a device from the controller releases the device from the controller and allows it to be used with another controller. +- If your controller has failed and you want to add your device to a new controller, you can perform the exclusion with your new controller (essentially any controller can exclude a device--even if the device was included with a different controller). +- Just because you've excluded a device from the network, doesn't mean that all the other devices that used to talk to it know it's gone. That's why it's always a good idea to optimize your network after making big changes (adding or removing many devices or changing the location of many devices or the controller). + +You can usually preserve your Indigo setup when excluding a device. The Indigo device object and all the things that refer to it are independent of the physical device itself. Simply exclude the first device, include the second one and then point your Indigo device definition to the new device. It will be shown in the `Sync using node` dropdown as an Available Node ID: + +![Available Node ID](../../../images/available_node_id.png){ width=400 } + +This assumes that you're replacing a device with one that is of a similar type. + +To exclude a device: + +- Depending on your device, you may need to bring the device into close proximity with the controller. Alternatively, if your controller supports it, you can take your controller to the device. +- Select the `Interfaces→Start Controller Exclusion Mode`. +- Following your device's instructions, initiate an exclude action (different devices may require different steps). +- If the exclusion has been done successfully, Indigo will automatically exit the exclusion and the device should no longer appear in the Z-Wave device list. + +## Deleting a Z-Wave Device +When deleting a Z-Wave device, it's always a good idea to exclude it from your network after you've deleted it in Indigo (if it's still functional). So, the process is this: + +1. Select `DEVICES` in the Main Window outline view or select one of the sub-folders. +1. Find the device in the device table and select it. +1. Click the `Delete...` button (or press the Delete key on the keyboard). + +If the device has any [deletion dependencies](../../concepts/deletion-dependencies.md), Indigo will show the dependency dialog that will allow you to review and/or modify any of those dependencies. If you choose to continue the deletion process, the device will be deleted along with the dependencies. + +The last thing you'll want to do is to exclude the device from your network if it's still functional. To do this you can use the `[Interfaces->Z-Wave->Start Controller Exclusion Mode](#start-controller-exclusion-mode)` menu item to put the Z-Wave Controller into exclusion mode, then follow the steps from the device's manual to have it exclude itself from the network. + +## Replacing a Z-Wave Controller +You may need to replace your controller. This section describes the steps involved in moving your Z-Wave devices to a new controller. + +If your controller doesn't have a physical inclusion button you must follow this process. You may also use this process even if your controller does have a button (such as the Aeotec Z-Stick) as it's the more "universal" approach: + +1. Remove your old controller from your Mac. +1. Plug your new controller into your Mac and [reconfigure the Indigo Z-Wave Interface](../../getting-started/index.md#connecting-z-wave-interfaces) to use the new serial port. +1. Select the `Interfaces->Start Controller Exclusion Mode`. Note you can exclude from any controller, not just the one it was included with. +1. Go to the Z-Wave device closest to your Mac that’s not battery powered (also skip any that require encryption) and perform its exclusion process. +1. Go back to your Mac, edit the device you just excluded, click the `Define and Sync` button and press the `New with Encryption Disabled` (only select Enabled if you're including a device which requires encryption to work correctly, such as a lock). +1. Go back to your device and perform its inclusion process (press its LINK button, etc.). +1. Return to your Mac (it should say `Inclusion into network successful` in green just under the `Add to network` buttons), confirm that the new node shows up in the popup at the bottom, and then press `Sync`. +1. Repeat steps 3-7 for each non-battery powered device from the closest to your Mac to the furthest. +1. Repeat steps 3-7 for each battery powered device or devices that require encryption. +1. Finally, select the `Interfaces->Z-Wave->Optimize Z-Wave Network...` menu item and click `Start Optimization` - you can do this at night just before going to bed when the network is likely to be the least busy. + +If your controller has a physical button, you may choose to follow this process because it requires fewer walks from your Mac to the devices being moved to the new controller: + +1. Remove your old Z-Stick from your Mac. +1. Plug your new Z-Stick into your Mac and [reconfigure the Indigo Z-Wave Interface](../../getting-started/index.md#connecting-z-wave-interfaces) to use the new serial port. +1. Unplug your new Z-Stick from the Mac and take it to the Z-Wave device closest to your Mac that’s not battery powered (also skip any that require encryption) and exclude it. Note you can exclude from any controller, not just the one it was included with. +1. While at the device, include it into the new Z-Stick. +1. Plug the new Z-Stick back in to your Mac. +1. Open the config dialog for the device you included and click the `Define and Sync` button. +1. Select the new node number from the popup at the bottom and `Sync`. +1. Repeat steps 3-7 for each non-battery powered device from the closest to your Mac to the furthest. +1. Repeat steps 3-7 for each battery powered device or devices that require encryption. +1. Finally, select the `Interfaces->Z-Wave->Optimize Z-Wave Network...` menu item and click `Start Optimization` - you can do this at night just before going to bed when the network is likely to be the least busy. + +## Z-Wave Menu Options +The `Interfaces->Z-Wave` submenu contains several Z-Wave specific menu items to help manage your Z-Wave network and devices. Below are the current options. + +![Z-Wave Menu Image](../../../images/zwave_menu.png) + +### Manage Associations +![Z-Wave Dialog Manage Associations Image](../../../images/zwave_dialog_manage_associations.png) + +Indigo supports defining Z-Wave Associations (which are similar to Insteon links) between devices that support that functionality. Note that battery operated devices which are asleep will need to be woken up (per their instructions manual) for associations to be edited. + +### Modify Configuration Parameter +![Z-Wave Dialog Modify Configuration Parameters Image](../../../images/zwave_dialog_modify_config_parms.png) + +Some Z-Wave devices provide configuration options through the use of configuration parameters. These are generally outlined in the documentation that comes with a device. Indigo often times support setting these parameters directly in the device config dialog, but because of the sheer number of Z-Wave devices we can't add every one. This menu item will allow you to set any config parameter that a device accepts. + +**Note** - this process can cause your device to not function correctly if incorrect parameters are entered so you'll want to make sure you are very careful to use only the params specified for the specific device. + +### Send Raw Z-Wave Command +![Z-Wave Dialog Send Raw Command Image](../../../images/zwave_dialog_send_raw.png) + +This menu selection can be used to send arbitrary Z-Wave protocol-level commands to any Z-Wave device. This is generally only useful when Support instructs you to do so. Note battery operated devices allow for the option to queue the command to be sent the next time the device wakes. + +### Start Controller Inclusion Mode +This menu selection puts the Z-Wave Controller into inclusion mode. You can then follow the steps from the device's manual to have it include itself from the network. Open and watch the `[Event Log window](../../mac-client/event-log.md#event-log-window)` for progress as it is included. This menu item is functionality the same as using the `New with Encryption Disabled` button inside the `[Synchronize Z-Wave Device](#adding-a-z-wave-device)` dialog. + +### Start Controller Inclusion Mode with Encryption +This menu selection puts the Z-Wave Controller into inclusion mode with encryption enabled. You can then follow the steps from the device's manual to have it include itself from the network. Open and watch the `[Event Log window](../../mac-client/event-log.md#event-log-window)` for progress as it is included. This menu item is functionality the same as using the `New with Encryption Enabled` button inside the `[Synchronize Z-Wave Device](#adding-a-z-wave-device)` dialog. + +### Start Controller Exclusion Mode +This menu selection puts the Z-Wave Controller into exclusion mode. You can then follow the steps from the device's manual to have it exclude itself from the network. Open and watch the `[Event Log window](../../mac-client/event-log.md#event-log-window)` for progress as it is excluded. Note Indigo is able to exclude devices from any Z-Wave network. + +### Stop Inclusion / Exclusion +This menu selection exits both inclusion and exclusion mode. + +### Optimize Z-Wave Network +![Z-Wave Dialog Optimize Network Image](../../../images/zwave_dialog_optimize_network.png) + +Indigo can optimize your Z-Wave network by having devices rediscover which devices they are close enough to communicate with. This information is then reported back to the Z-Wave Controller so network routing tables can be updated. + +### Report Failed Modules to Event Log +This menu item will write any devices that the Z-Wave interface believes may have failed to the Indigo Events Log. This list is managed by the Z-Wave interface (not by Indigo) and it's important to note that **the listed devices may not have actually failed** (the interface may list a device that it hasn't received a transmission from for a while, for example). It's recommended that you use this menu item from time to time to ensure that the interface has the correct information for your devices. + +```text +January 1, 1970 at 12:34:56 AM + Z-Wave found failed module reported by controller "028 - Energy Meter Device" + Z-Wave found failed module reported by controller "042 - Dehumidifier" +``` + +If you see a device listed that you believe should not be listed, it is often enough to simply browse to that device in the Indigo UI, open the Edit Device dialog, and perform a **Define and Sync** operation. Indigo will attempt to refresh the device's information and, if successful, tell the Z-Wave interface to remove the device from the failed devices list. After performing this operation, you can confirm the device has been removed from the list by rerunning the **Report Failed Modules to Event Log** step. + +If the interface doesn't think that any devices are in a failed state, running the report will result in + +```text +Z-Wave no failed modules found in controller +``` + +### Remove Failed Device from Controller +If a Z-Wave device has failed or is no longer available to your network, you can use this menu item to remove it from the Z-Wave interface. + +You may have to attempt to resync the device in order for it to be listed as failed. + +- If an Indigo device object still exists, you can open the Edit Device dialog and attempt to **Define and Sync** the device. If it has truly failed, the sync operation will fail, and the interface will add it to its internal failed list. +- If an Indigo device object is no longer available, you can simply create a new device, attempt to sync the failed device and, when the operation has failed, and the interface will add it to its internal failed list. + +If you select this menu item and the Z-Wave interface doesn't have any failed devices in its list, Indigo will return this message: + +```text +Z-Wave no failed modules found in controller +``` + +### Reset Z-Wave Interface +You can completely reset your Z-Wave interface by selecting this menu item. **You should only do this if instructed by Support**. + +--- +*Z-Wave® is a registered trademark of Sigma Designs, Inc. Indigo's support of Z-Wave hardware is neither endorsed nor certified by Sigma Designs.* diff --git a/reference/canonical/user/interfaces/z-wave/about.md b/reference/canonical/user/interfaces/z-wave/about.md new file mode 100644 index 0000000..417da41 --- /dev/null +++ b/reference/canonical/user/interfaces/z-wave/about.md @@ -0,0 +1,76 @@ + + +# Z-Wave® Terminology and Technical Overview + +Z-Wave is a wireless (RF) home automation technology that's available worldwide. There are several characteristics of Z-Wave technology that we think are important for users to understand. In this article, we'll attempt to explain these features in terms that our users will find easily understood. + +This page is about the Z-Wave technology in general terms: if you're ready to get started using Z-Wave with Indigo, check out the [Managing Your Z-Wave Network](index.md) document. + +## Overview +Z-Wave is a wireless mesh network technology. That is, all signals are transmitted over RF (for those with power line-based systems, no more signal noise problems from stuff plugged into the wall). Z-Wave is a proprietary technology, owned by Silicon Labs, and licensed to a variety of vendors. The [Z-Wave Alliance](https://z-wavealliance.org) was formed by various vendors to help assure interoperability between devices. + +Z-Wave is a mesh network - where each node knows about the ones around it so that a message can be sent through various devices on the network until it reaches its destination. This increases network and message reliability. + +Z-Wave devices operate on different frequencies, so you'll find devices specific for North America (908MHz), Europe (868MHz) and Australia/New Zealand (921MHz). Many vendors supply devices for each so finding devices in your area shouldn't be a problem. + +## Controllers +If you are an existing Indigo user, specifically one who uses INSTEON, you may recognize the term "controller" to mean a device which can control other devices: KeypadLinc, RemoteLinc, SwitchLincs, etc. You can link a controller directly to a "responder" such that when a button is pressed on a keypad or switch, a command is sent directly from it to the linked "responder" device. Z-Wave has a similar mechanism ([Associations](#associations)) which we'll discuss in a bit. + +However, Z-Wave uses the word "controller" differently. + +### Primary Controller +The Z-Wave primary controller is responsible for assigning network id and node ids to devices (Z-Wave devices are referred to as a "node") and to create Secondary Controllers. This controller is the one that keeps the definitive list of nodes on the network. There must always be a primary controller in any Z-Wave network. For Indigo controlled Z-Wave networks, the primary controller will be the Z-Stick - it will create the network id (or home id) and will assign node id's to any device that's added to the network (see [Including/Excluding a Device](#including-excluding) below for more details on how to add devices to the network). + +### Controller Types +Controllers are generally one of two types. Portable controllers are handheld controllers, like remote controls, which can move around your house. Because these controllers can be at any place in the house, they must constantly be asking for nodes around it so they can maintain the routing information. + +Static controllers are controllers that don't move around so don't necessarily need to update routing information very often. The Z-Stick is primarily a static controller - however, since it can be moved around to include other devices it may need routing updates more frequently. Other types of static controllers are some scene controllers (synonymous to the INSTEON KeypadLinc), some switches, etc. + +## Devices +There are Z-Wave devices of all types you'd expect with any mature home automation technology: plug-in modules (aka wall-warts), switches, outlets, thermostats, motion sensors, etc. Z-Wave also supports locks from a variety of vendors. + +### Including/Excluding a Device in a Z-Wave Network { #including-excluding } +When you add a device to a network via the controller, it's called "including" the device (i.e. the inclusion process). Each device may have a different inclusion process. Likewise, you must exclude a device from the network if you are no longer using it. + +You can usually [include and exclude devices directly from Indigo](index.md). Older versions require you to take your controller to the device to include/exclude it using the button on the controller. + +Devices must be awake to be included into the Z-Wave controller (the procedure for each device that supports sleep is different so you'll need to refer to the docs for your device). Once included, Indigo may attempt to queue up messages to the device and wait for it to wake up. That behavior may or may not work based on the capability of the device, so if you need to communicate with a sleeping device (for instance to update any configuration parameters) you may need to manually wake it up. + +## Associations +Z-Wave associations are used when one module needs to command one or more other modules. For example, an association with a switch module could be created to control a remote lamp module when the switch is turned ON and OFF. Associations are also used between a module and the Z-Stick used by Indigo. In that case, the association is often used so that Indigo can update its UI when a module changes states, or so that user defined Triggers can be executed when a button is pressed. + +## Routing and Network Healing +Z-Wave uses a routed mesh network for extending the range between all modules. For reliable communication to occur between distant modules, an established route, or path, needs to be created. Indigo tells the Z-Stick to create these routes when a module is Defined or Synced. If you move modules to different locations it may be necessary to re-Sync them so that their new routes can be established. If you are unable to communicate with a distant module, then try re-Syncing modules that are nearby the distant module to help establish a new route. + +## Glossary of Terms + +| Term | Definition | +|---|---| +| **Association** | A pre-defined grouping of Z-Wave devices that allows them to interact with each other. | +| **Command Class** | A standard set of instructions that defines how a Z-Wave device can communicate and perform specific actions. | +| **Controller** | A hardware device that acts as the primary hub and manages the Z-Wave network, including routing and security. | +| **Encryption** | Devices that support encryption use a secure transmission protocol to relay traffic. Not all devices support encryption, and it is recommended that encryption should only be used in circumstances where security is important like door locks. | +| **Exclusion** | Exclusion mode is a controller state that allows devices to be removed from a Z-Wave network. | +| **Hop Limit** | In a Z-Wave network, the hop limit is four hops. This means that a signal can travel through a maximum of four intermediate Z-Wave devices (routers) to reach its destination. The maximum range with four hops is roughly 600 feet (or 200 meters). | +| **Hub** | A hardware device that typically contains both communication circuits and a software application to manage a Z-Wave network. Indigo, along with a Z-Wave hardware controller, acts as the hub in a Z-Wave network. | +| **Inclusion** | Inclusion mode is a controller state that allows devices to be added to a Z-Wave network. | +| **Interface** | The software component used to communicate between Indigo and the Z-Wave Network. | +| **Mesh Network** | A network where devices communicate with each other directly or through intermediate nodes, allowing for a wider range and better signal reliability. | +| **Node** | A single device in a Z-Wave network. | +| **NodeID** | A unique identifier for each Z-Wave node within the network. | +| **Optimization** | Indigo supports a feature to optimize the Z-Wave network by iterating through all network devices to "refresh" their settings and routing tables. This is typically only required when significant changes are made to a network (for example, many devices are added/moved/removed from the network). | +| **Parameter** | Z-Wave devices typically have parameters that dictate how the device behaves. For example, a dimmer may have a setting to control how quickly a light's intensity will change, or determine how frequently a battery-powered device sends data. | +| **Primary Controller** | The main controller that manages the Z-Wave network. | +| **Repeater** | A Z-Wave device whose purpose is simply to pass traffic along the network. Repeaters help extend the range of the network. | +| **Secondary Controller** | A secondary controller can control Z-Wave devices, but it cannot add new devices to the network (only the primary controller can include or exclude devices). Secondary controllers are added or removed from the network by the primary controller. An example of a secondary controller would be a hand-held Z-Wave remote. | +| **Raw Command** | Raw commands are how Indigo communicates with the Z-Wave network. Indigo supports sending custom raw commands via the Z-Wave interface. This is more of an advanced feature. | +| **Sensor** | A device that detects and transmits information to the network, such as temperature or motion. | +| **Z-Wave** | A wireless communications protocol that uses low-energy radio waves to connect smart devices in a mesh network. | + +## Further Reading +If you want even more detailed information about Z-Wave, here are some resources we suggest: + +- [Z-Wave on Wikipedia](https://en.wikipedia.org/wiki/Z-Wave) +- [Z-Wave Alliance](https://z-wavealliance.org) + +--- diff --git a/reference/canonical/user/interfaces/z-wave/associations.md b/reference/canonical/user/interfaces/z-wave/associations.md new file mode 100644 index 0000000..73d6a45 --- /dev/null +++ b/reference/canonical/user/interfaces/z-wave/associations.md @@ -0,0 +1,17 @@ + + +# Indigo Z-Wave® Association Management + +!!! abstract "In this guide" + How to view and manage Z-Wave device associations using Indigo's Association Management dialog. Z-Wave associations allow devices to control each other directly (similar to Insteon links); this guide covers selecting a controlling device, choosing an association group, and adding or removing responding devices. + +Z-Wave has a couple of mechanisms that allow devices to control and respond to each other directly (similar to how [Insteon links](../insteon/index.md) work). Currently, Indigo supports the management of one of these mechanisms - Associations. Some Z-Wave devices can control associations - we'll call them association controllers. These devices may have multiple groups that they can control as well. All devices can respond to an association - we'll call these association responders. + +To edit associations, select `Interfaces->Z-Wave->Manage Associations...`. + +![Z-Wave Associations Image](../../../images/zwave_associations.png) + +The `Controlling device` popup lists all Z-Wave devices in your system that support control associations. Once you select one of those (if you have any), then the `Controlling group` popup will show how many different association groups the device can control. The `Responding devices` list shows all Z-Wave devices that are being controlled by the selected device/group. Select any you want to delete and click the `Remove Selected Device` button to remove them from the association. Select a device from the `Device to add popup` and click `Add Responding Device` to add the device to the association. + +--- +*Z-Wave® is a registered trademark of Sigma Designs, Inc. Indigo's support of Z-Wave hardware is neither endorsed nor certified by Sigma Designs.* diff --git a/reference/canonical/user/mac-client.md b/reference/canonical/user/mac-client.md new file mode 100644 index 0000000..6cc8eae --- /dev/null +++ b/reference/canonical/user/mac-client.md @@ -0,0 +1,21 @@ + + +# Indigo Mac Client + +!!! abstract "In this article" + A tour of the Indigo Mac Client's Home Window: the Outline View, Item List, Item Detail panel, Status Bar, and key menus. Understanding this layout is the starting point for configuring all devices, triggers, schedules, and control pages. + +When you double-click on the `Indigo {{ version }}` icon in the `Applications` folder, you're actually starting the Indigo Mac Client, which will start up the Indigo Server process according to the options selected in the [Start Server](../getting-started/installation.md#starting-indigo-server) dialog. + +## In This Section + +The Mac Client is where all configuration happens. This section tours it: + +- **[Home Window](home-window.md)** — the main window: the Outline View, Item List, Item Detail panel, and Status Bar. +- **[Event Log Window](event-log.md)** — a live view of everything the Indigo Server is doing. +- **[Menus](menus.md)** — a reference for every menu in the Mac Client. + +The Variable Window is covered in [Variables](../concepts/variables.md). + +--- +*Z-Wave® is a registered trademark of Sigma Designs, Inc. Indigo's support of Z-Wave hardware is neither endorsed nor certified by Sigma Designs.* diff --git a/reference/canonical/user/mac-client/event-log.md b/reference/canonical/user/mac-client/event-log.md new file mode 100644 index 0000000..27c2b8c --- /dev/null +++ b/reference/canonical/user/mac-client/event-log.md @@ -0,0 +1,9 @@ + + +# Event Log Window { #event-log-window } +![Event Log Window Image](../../images/event_log_window.png) + +The event log window shows you most everything the Indigo Server is doing at any given time. You see incoming and outgoing traffic, trigger and schedule executions, and other useful diagnostic information. + +- `Show Event Logs Folder` - this option opens the Logs folder in the Finder. Here you will find one file for each day's events. You can change how many day's worth of event log files are stored by selecting `Indigo {{ version }}->General Settings...` and then selecting the `General` tab. There, you can enter the number of days of event log files that you want to keep. Indigo Server will delete all files outside of that period of time. +- `Clear Window` - this option clears the log entries from the Event Log window. diff --git a/reference/canonical/user/mac-client/home-window.md b/reference/canonical/user/mac-client/home-window.md new file mode 100644 index 0000000..2b226e1 --- /dev/null +++ b/reference/canonical/user/mac-client/home-window.md @@ -0,0 +1,239 @@ + + +# Home Window +The Home Window in the Mac client looks like this: + +![Main Window Image](../../images/main_window.png) + +The Home Window has 4 areas: + +1. Outline View +1. Item List +1. Item Detail +1. Status Bar + +The first 3 areas can be resized using the standard macOS split view handles (see the **red** arrows in the above image). + +## Outline View +The outline view shows all high-level objects (except [Variables](../concepts/variables.md#variables) which have their own window): [Overview](../concepts/devices.md#devices), [Overview](../concepts/triggers.md#triggers), [Overview](../concepts/schedules.md#schedules), [Overview](../concepts/actions.md#action-groups), and [Overview](../concepts/control-pages.md#control-pages). Selecting one of these in the outline view will switch the Item List to view all of those types of objects. The same goes for folders that are under the high-level headings except only the objects in those folders will show. + +![Outline View Controls Image](../../images/outline_view_controls.png) + +To create a new folder, select the main object type in the list then click the plus (`+`) button lower-left corner of the outline view. A new folder will appear and you can just start typing its new name. + +You can select a folder then click on the gear icon in the lower-left (see the image above) or right-click the folder (bring up the contextual menu). The resulting menu will have the following options: + +- ` Rename Folder...` allows you to rename the folder. +- `Delete Folder` will do just that. If the folder isn't empty, it will show you a sheet with 3 options: `Cancel` (do nothing), `Delete Items` (delete the items in the folder along with the folder), or `Move Items` (move the items to the parent first then delete the folder). +- `Disable/Enable Remote Display` (for devices, action groups, and control pages) will show/hide it in remote clients (like [Indigo Touch for iOS and Web](http://www.indigodomo.com/touch.html), the [DomoPad 3rd party client for Android](https://forums.indigodomo.com/viewtopic.php?f=73&t=11536), etc). +- `Copy ID (123456789)` will copy the unique folder ID for use in Python scripts. + +To move an object to a folder, just drag it from the list view onto the folder (or top-level object) - somewhat like moving mail messages from the inbox to a mail folder in the Mail application. + +## Item List +The Item List contains the items contained in the object that's selected in the Outline View - so if DEVICES is selected, then all devices in your system are shown. If you have one of the device folders selected, only the devices in that folder are shown. + +The buttons above the table view perform actions on items in the list - the buttons will work on whatever list is displayed in the Item List. So, if you have DEVICES (or a device folder) selected in the Outline View, the item list will show devices and the buttons will operate on that list - `New...` device, `Edit...` the selected device, `Duplicate` the selected device, or `Delete` the selected device(s). The search bar will filter the list. + +The image above shows all possible columns in the device view. However, if you right-click on the table header: + +![Device Column Selection Menu Image](../../images/device_column_selection_menu.png) + +you can customize what columns are shown by checking/unchecking them in the list. Several of the columns have a checkbox in them - you can check/uncheck the feature for the object by clicking on the checkbox. In a few rare cases the checkbox will be disabled (grayed out). + +Every Item List is customizable in this regard. Also, if you right-click on a device: + +![Device Contextual Menu Image](../../images/device_contextual_menu.png) + +This menu will: + +1. Take you to the How-To wiki for that device type - if it's a plugin device, it will take you to the help page supplied by the plugin developer. +1. Toggle remote display - this tells Indigo whether to show the device in remote clients. +1. Toggle communication with the device - this effectively enables/disables the device. If a device is disabled, it will show up gray in the list. +1. Open a window that shows all other objects that are dependent on this device. See [Deletion Dependencies](../concepts/deletion-dependencies.md) for more information. +1. Copy the unique ID of the device to the clipboard - to assist in writing Python scripts that use the device +1. Copy a Python script string that will return an instance of the selected device. It will look like this: `indigo.devices[91776575] # "Living Room Switch"` +1. Print all the information about a device to the Event Log window. It will look something like this: +```text +address : 3B.04.7A +batteryLevel : None +blueLevel : None +brightness : 0 +buttonConfiguredCount : 0 +buttonGroupCount : 1 +configured : True +defaultBrightness : 100 +description : valve +deviceTypeId : +displayStateId : brightnessLevel +displayStateImageSel : DimmerOff +displayStateValRaw : 0 +displayStateValUi : 0 +enabled : True +energyAccumBaseTime : None +energyAccumTimeDelta : None +energyAccumTotal : None +energyCurLevel : None +errorState : +folderId : 810233868 +globalProps : MetaProps : (dict) + com.indigodomo.indigoplugin.alexa : (dict) + publish-device : true (bool) + sub-type : Valve (string) + voice-name : valve (string) +greenLevel : None +id : 1508839119 +lastChanged : 2021-09-25 08:24:22 +lastSuccessfulComm : 2021-09-25 08:24:22 +ledStates : [] +model : LampLinc (dual-band) +name : Insteon Dimmer +onBrightensToDefaultToggle : True +onBrightensToLast : False +onState : False +ownerProps : emptyDict : (dict) +pluginId : +pluginProps : emptyDict : (dict) +protocol : Insteon +redLevel : None +remoteDisplay : True +sharedProps : com.indigodomo.indigoserver : (dict) +states : States : (dict) + brightnessLevel : 0 (integer) + onOffState : off (on/off bool) +subModel : Plug-In +subType : Plug-In +supportsAllLightsOnOff : True +supportsAllOff : True +supportsColor : False +supportsRGB : False +supportsRGBandWhiteSimultaneously : False +supportsStatusRequest : True +supportsTwoWhiteLevels : False +supportsTwoWhiteLevelsSimultaneously : False +supportsWhite : False +supportsWhiteTemperature : False +version : 67 +whiteLevel : None +whiteLevel2 : None +whiteTemperature : None +``` + +Triggers and Schedules have a contextual menu when you right-click on them that will allow you to: + +1. Enable/disable the event. +1. Hide executions in the event log - they trigger will continue to execute but nothing will be reported in the Event Log window. +1. Open a window that shows all other objects that are dependent on this trigger/schedule. See [Deletion Dependencies](../concepts/deletion-dependencies.md) for more information. +1. Copy the unique ID of the trigger or schedule to the clipboard - to assist in writing Python scripts +1. Copy a Python script string that will return an instance of the selected device. It will look something like this: `indigo.triggers[565290390] # "Motion Sensor Dawn Triggered"` + +Action Groups have a contextual menu when you right-click on them that will allow you to: + +1. Toggle remote display - this tells Indigo whether to show the device in remote clients. +1. Open a window that shows all other objects that are dependent on this action group. See [Deletion Dependencies](../concepts/deletion-dependencies.md) for more information. +1. Copy the unique ID of the device to the clipboard - to assist in writing Python scripts that use the device +1. Copy a Python script string that will return an instance of the selected device. It will look something like this: `indigo.actionGroups[1703232002] # "Toggle Variable"` + +And finally, Control Pages also have a contextual menu: + +1. Toggle remote display - this tells Indigo whether to show the device in remote clients. +1. Show in Browser - open the control page in the default browser. +1. Copy the unique ID of the device to the clipboard - to assist in writing Python scripts that use the device +1. Copy a Python script string that will return an instance of the selected device. It will look something like this: `indigo.controlPages[249813574] # "iPad Landscape"` + +## Item Detail +The item detail area shows controls and extra state information depending on what type of object is selected. + +### Devices +Device controls are separated into a variety of control tiles that are laid out in a grid in the Item Detail area. We also refer to this as the control area. If you have no device selected, the control area is blank. If you have a single device selected, you may see a variety of different control tiles. The first tile that will always be showing is the Device Details tile: + +![Device Details Tile Image](../../images/device_details_tile.png) +![Device Details Tile Image](../../images/device_details_tile2.png) + +The information in the tile will be specific to the device type. For instance, battery powered devices (that report their battery status) will show the battery level. For sensor devices, the sensor reading will show (temp, humidity, etc. for instance). All devices, regardless of type, will show `Last Update` - the last date/time that the device was changed in any way. + +Plugin devices, regardless of whether they implement one of the built-in device types below or if they are completely custom devices, will also have a `Custom States` tile that will show all the device's custom states. This tile is always below the first row of tiles so you may need to scroll or resize the Item Detail area to see it: + +![Custom States Tile Image](../../images/custom_states_tile.png) + +If you right-click a custom state, you will see the following contextual menu with several options: + +![Device State Context Menu Image](../../images/device_state_context_menu.png) + +1. Copy Python Reference will copy the full reference to that state that you can use in a Python script. It will look something like this: `indigo.devices[1604256801].states["album"] # State "album" of "MightMini iTunes"` +1. Copy State Value will copy the string value of the state to the clipboard so you can paste it somewhere else. +1. Copy State ID will copy the ID of the state for use in a Python script. +1. Copy Substitution String will copy the appropriately marked up string that you can use in a variety of dialogs to substitute the value of the state at runtime. It will look something like: `%%d:1604256801:album%%` + +Other device types will show specific control tiles based on their type as discussed below. + +#### Lights/Appliances +For lights (dimmers) and appliance modules (relays or On/Off devices), you see `On/Off/Brightness Controls` tile: + +![On Off Dimmer Tile Image](../../images/on_off_dimmer_tile.png) + +If the device doesn't support dimming, those controls will be hidden. You'll also notice that in the Device Details tile, `On State` and `Brightness` (if it's a dimmer) will show the current values. + +For lights that allow users to set the color, you'll see the `Color Controls` tile: + +![Color Controls Tile Image](../../images/color_controls_tile.png) + +The top row of controls allow you to turn the light On, Off, and the last text field will allow you to type in the brightness (0-100). The second row of controls allows you to set the color and if the light supports it, the white value (also 0-100). If the light doesn't support setting white separately, the slider and text field will not show. The last row will allow you to se the temperature of the white (again, if the light supports it). If the light doesn't allow setting temperature, the `Send Status Request` button will show instead. + +#### Sensors (Motion Sensors, Energy Meters like the iMeter, etc.) +![Sensor Controls Tile Image](../../images/sensor_controls_tile.png) + +Sensor devices have their own control tile as well. Some of those devices can be explicitly turned On and Off (thus the buttons) and can respond to status requests. The buttons will be enabled/disabled based on the device's capabilities. + +One thing to note about some battery powered devices: the **Status Request''''** button may be enabled because some of those devices have the option to be plugged in (for instance, the Aeotec MultiSensor) and will respond to status requests when plugged in but not when running on battery power. + +Also, some energy monitoring devices, such as the iMeter, keep running totals of energy usage that can be reset by the user. For those, a `Reset` button will be placed next to the Total Usage in the `Device Details` tile. + +#### Speed Controls +![Speed Controls Image](../../images/speed_controls.png) + +Speed control devices are devices that can control the speed of some kind of motor. For instance, the Insteon FanLinc. And, in fact, the controls are currently tailored to the FanLinc's High, Medium, Low, and Off settings. When we run across more of these types of devices we'll customize the controls appropriately. + +#### Sprinklers +![Sprinkler Controls Image](../../images/sprinkler_controls.png) + +The sprinkler tile allows you to turn on a specific zone, go to the next or previous zone, update the valve status. And, if a schedule is currently running, pause/resume it, begin running the previous schedule, and stop all activity. + +#### Thermostats +![Thermostat Controls Image](../../images/thermostat_controls.png) + +The thermostat tile shows the current temperature, humidity, mode, cool/heat setpoints, and fan mode. You can also adjust all of those as well as refresh the values and turn everything off. Note that on rev2 thermostat adaptors the circles next to cool and heat setpoints will be lit if their respective HVAC system is actually running (A/C or heater). + +#### Generic Output Devices +![I/O Controls Image](../../images/io_controls.png) + +Output Controls tile shows the state of all the output states available for the device and you can update them immediately using the `Send Status Request` button. The button grid shows all available outputs and their status. Use the `Turn Off All Outputs` button to turn off all binary outputs. + +### Triggers and Schedules +![Trigger Schedule Controls Image](../../images/trigger_schedule_controls.png) + +The detail area for triggers and schedules is identical - it shows the triggering event (either a state change or some time/date description), whether the condition is always, rules, or a script, and a summary of actions. Depending on your interface, a popup may allow you to specify how the object is processed: + +- `Enabled and Upload` - this means that it will be processed both while Indigo Server is running and it will be uploaded to your standalone controller (if it supports uploading). +- `Enable` - this means that it will be processed while Indigo Server is running, and mirrors the Enabled column in the list if it's visible. +- `Upload` - this means that it will only be uploaded and executed by your standalone controller (if it supports uploading) - while Indigo Server is controlling the logic it will not be enabled +- `Disabled` - this means that it's completely disabled - it also mirrors the Enabled column in the list if it's available. + +The `Execute Conditional Actions` button will execute all the actions associated with the object, but only after any conditions specified in the Conditions tab are evaluated (so you can test the conditions). + +The `Execute Actions Only` button will do exactly that - execute all the actions associated with the object without evaluating any conditions specified in the Conditions tab. + +### Action Groups +![Action Group Controls Image](../../images/action_group_controls.png) + +The action group detail shows a list of all the actions in the group. The `Execute Actions Now` button will do exactly that - execute all the actions associated with the action group. + +### Control Pages +The only thing in the detail area for a control page is the `Show in Browser` button, which will open the selected page in the default browser. + +## Status Bar +The status bar along the bottom of the window has several elements. First, there's the communication queue indicator. It's the longish rectangle next to the Indigo icon. This indicator will show green bars going from right to left, and purple bars going from left to right. Green bars indicate outgoing communication purple bars show incoming communications. If you see green bars begin to build up, you can tell that something is keeping the outgoing command queue from processing correctly. + +Next to that bar you'll see the names of the interfaces you have configured. If they are in green, then they are functioning properly. If they are in red with a line through them, Indigo can't communicate with them. If they are gray, they are offline for some reason. + +The next four sets are pretty self-explanatory: the next sunrise time, the next sunset time, the current time (for the Indigo Server, so it may be different than the client time if you're running the client on a different machine), and the next time a schedule is going to execute. diff --git a/reference/canonical/user/mac-client/menus.md b/reference/canonical/user/mac-client/menus.md new file mode 100644 index 0000000..14d8f7a --- /dev/null +++ b/reference/canonical/user/mac-client/menus.md @@ -0,0 +1,69 @@ + + +# Menus +In this section, we'll go through each of the menus in Indigo. + +## Indigo {{ version }} Menu +![Indigo Menu Image](../../images/indigo_menu_2023_1.png) + +- `About Indigo {{ version }}` - this will show the About window which will show what client and server versions you're running and will show your registration code +- `Start Local Server...` - this will open the [Start Server dialog](../getting-started/installation.md#starting-indigo-server) +- `Stop Server` - this will stop the Indigo Server +- `Connect to Remote Server...` - this option will allow you to connect to a different Indigo server or a server running on another Mac +- `Close Connection` - this will close the connection to the server +- `General Settings...` - this opens the [preferences dialog](../getting-started/installation.md#general-configuration-settings) +- `Advanced Web Server Settings...` - this opens the [Indigo Web Server Settings dialog](../remote-access/web-server.md#advanced-web-server-settings) +- `License Details...` - this opens the Subscription Status window that will show you the status of your License and it's associated Up-to-Date Subscription: + +![Subscription Status Image](../../images/subscription_status.png) + +- `Check for Updates...` - this will have the server your connected to contact us to see if there is an update available + +## File Menu +![File Menu Image](../../images/file_menu.png) + +- `New Database...` - this will close the current database and create a new one - you'll be prompted for a name and save location +- `Select Database...` - this will allow you to switch to a different database +- `Close Window` - this will close the frontmost window +- `New Device...` - this will switch the Home Window to the devices view and open the [new device dialog](../concepts/devices.md#devices) +- `New Trigger...` - this will switch the Home Window to the triggers view and open the [new trigger dialog](../concepts/triggers.md#triggers) +- `New Schedule...` - this will switch the Home Window to the schedules view and open the [new schedule dialog](../concepts/schedules.md#schedules) +- `New Action Group...` - this will switch the Home Window to the action groups view and open the [new action group dialog](../concepts/actions.md#action-groups) + +## Edit Menu +The Edit menu has the standard options on it that you would expect any Mac app to have. Note that the Delete and Duplicate options are available for most items in the user interface. + +## View Menu +The View menu allows you to switch between views in the Home Window just as if you had clicked the major item types in the outline view: Devices, Triggers, Schedules, Action Groups and Control Pages. + +## Interfaces Menu +The [Interfaces Menu](../getting-started/interfaces.md#managing-the-built-in-interfaces) is discussed in the [Getting Started Guide](../getting-started/index.md). + +## Plugins Menu +The [Plugins Menu](../concepts/plugins.md#plugin-menus-in-indigo) is discussed in the [Getting Started Guide](../getting-started/index.md). + +## Window Menu +![Window Menu Image](../../images/window_menu_2023_1.png) + +- `Home Window` - this will show/bring to front the Home Window +- `Event Log` - this will show/bring to front the Event Log Window +- `Variable List` - this will show/bring to the front the Variable List Window + +The bottom of the menu will display the list of open windows, where the name of the active database will replace "Home Window". + +## Help Menu +![Help Menu Image](../../images/help_menu_2023_1.png) + +- `Help for XXXX` - this will change slightly based on what window is selected and what's selected in that window - but it will open the default browser to the page in the help documentation for that particular item +- `Email Log...` - this option emails some of your event log data to the specified email address. Particularly useful for technical support +- `Show AppleScript Usage in Event Log` - this option prints a list of AppleScripts that are embedded in actions that you have specified. This will help to identify and replace those scripts. +- `Show Event Logs Folder` - this option will switch to the Finder and open the folder that contains the Event Log log files. +- `Show Web Assets Folder` - this option switches to the Finder and open the folder that contains custom images, text files, etc., that you might want to give Indigo (and others) access to through the Indigo Web Server. +- `Show Indigo Server Install Folder` - this option opens a Finder window that displays the folder of the currently running Indigo installation. This will only run from the server machine (you'll receive a warning otherwise). +- `Indigo Documentation` - this option will open your browser to the landing page for all Indigo {{ version }} documentation +- `Getting Started Guide` - this option opens your browser to the Getting Started Guide, the place where everyone new to Indigo should start +- `Managing a Z-Wave Network` - this option opens a browser window to the [Managing Your Z-Wave Network](../interfaces/z-wave/index.md) document in our Documentation wiki +- `Managing an Insteon Network` - this option opens a browser window to the [Managing Your Insteon Network](../interfaces/insteon/index.md) document in our Documentation wiki +- `Online Support Forum` - this option opens your browser to our [support forum](https://forums.indigodomo.com) - it's very active and is the primary place where you should seek help - we answer questions there very quickly and in fact we have many helpful users that can help as well +- `Compatible Devices` - this option opens a browser window on our new [Compatible Devices list](https://www.indigodomo.com/devices/) that shows which devices and interfaces have been tested with Indigo and includes devices supported by 3rd party plugins +- `Plugin Store` - this option opens your browser to our [Plugin Store](https://www.indigodomo.com/pluginstore/) where you can browse and download hundreds of 3rd party plugins that add functionality to Indigo diff --git a/reference/canonical/user/maintenance/license-transfer.md b/reference/canonical/user/maintenance/license-transfer.md new file mode 100644 index 0000000..2ee2488 --- /dev/null +++ b/reference/canonical/user/maintenance/license-transfer.md @@ -0,0 +1,13 @@ + + +# Transferring Your Indigo License to Another User + +!!! abstract "License Transfers" + This guide describes the necessary steps for transferring your Indigo license to another user. + +In some cases, you may wish to transfer your license to another user--for example, if you sell your home along with the Indigo system. We are happy to assist you in this process, and there are only a few steps you need to take. It is important that the steps be taken **in this order**: + +1. Have the new owner create a new Indigo Account and ask them to let you know the username/email on that account (don't need their password). +1. In your Indigo Account, cancel your subscription by clicking on the **Manage Subscription** link next to your license. Note that we can't transfer subscriptions, only licenses. Any time remaining on the subscription will be honored for the new user, but they need to renew, and catch-up the subscription when it expires. +1. Send us an email with the username/email for the new user's account (along with which license you want to transfer if you have multiple - use the activation name to identify it) and we will transfer the license. +1. When we're done with that, the new owner will need to deactivate/reactivate the license by selecting the **Indigo 20XX.Y** -> **License Details...** menu item and first clicking on the **Deactivate License** button then--in the resulting dialog--log in using the username/password they created in the step 1 above. diff --git a/reference/canonical/user/maintenance/moving.md b/reference/canonical/user/maintenance/moving.md new file mode 100644 index 0000000..4dffd7a --- /dev/null +++ b/reference/canonical/user/maintenance/moving.md @@ -0,0 +1,36 @@ + + +# Moving Indigo to Another Computer + +!!! abstract "In this guide" + This guide describes how to move your Indigo installation to another computer, another computer with a different processor architecture, or restoring from a backup. + +## Moving Indigo to another Mac or Restoring From a Backup +Note this process can also be followed to recover from a backup, though if your system crashed then you may need to contact us directly to perform step #1 for you. + +1. Deactivate Indigo on your Mac by selecting the `Indigo {{ version }}->License Details...` menu item and clicking the `Deactivate License` button. Do this while the Indigo Server is still running (do not shutdown the Indigo Server first) +1. Copy this folder over to the new Mac: `/Library/Application Support/Perceptive Automation/Indigo {{ version }}/` (if restoring from a backup, you'll need to locate this folder in whatever backup system you use) +1. Install Indigo {{ version }} on the new Mac ([download](https://www.indigodomo.com/downloads.html) and run the installer - you must be logged in to your Indigo Account to see all the installers available to you) + +!!! warning "NOTE" + this is not the Library folder that's in your home directory - it's the one at the top level of your hard drive. The easiest way to get there is to select the `Go->Go To Folder...` menu item in the Finder and paste in this: + +`/Library/Application Support/` + +It'll open the correct folder and you'll see the "Perceptive Automation" folder - that's the one you want to copy over. That should get all of your customizations and allow the installer to update anything as necessary. You may also need to install the drivers for the technology you use - see the appropriate section below for details. + +If you're moving Indigo to a Mac with a different architecture, read on... + +## Moving an Indigo Installation to another Architecture +When you move your Indigo installation from one macOS architecture to another (for example from an Intel-based Mac to an M-series Mac) -- especially if you use Migration Assistant or Time Machine -- you will likely need to take additional steps because many Python libraries are compiled to the specific hardware they're installed on. One signal that this has become an issue is an error message like: + +```text +'/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/httptools/parser/parser.cpython-310-darwin.so' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64')) +``` + +If you see errors like that (*incompatible architecture*), can't get the login or license dialog to work, or you have other errors that keep Indigo from starting up, you may need to take a few extra steps: + +1. manually remove the `/Library/Frameworks/Python.framework/` directory, and +1. run the Indigo installer again to reinstall Python. + +Taking these additional steps should ensure that your Python installation is compiled for your new Mac and that all file permissions are properly set. diff --git a/reference/canonical/user/maintenance/uninstalling.md b/reference/canonical/user/maintenance/uninstalling.md new file mode 100644 index 0000000..0929ad1 --- /dev/null +++ b/reference/canonical/user/maintenance/uninstalling.md @@ -0,0 +1,96 @@ + + +# Uninstalling Indigo + +!!! abstract "In this guide" + This guide shows the steps to follow when uninstalling Indigo from your Mac, including the server application, the client application and the folder structure (including details that apply to a specific version of Indigo. + +## Uninstalling the Server +To uninstall the Indigo Server and all of its data and configuration files, first deactivate Indigo on your Mac by selecting the `Indigo {{ version }}->License Details...` menu item and clicking the `Deactivate License` button. You'll get the following warning dialog: + +![Deactivate Sheet Image](../../images/deactivate_sheet.png) + +Then make sure that you have the server and client completely shut down (select `Stop Server` from the `Indigo {{ version }}` menu if the server is still running before you quit the Indigo Mac Client). + +Then, delete the following files: + +- `/Library/Application Support/Perceptive Automation/Indigo {{ version }}/` +- `~(your user folder)/Library/LaunchAgents/com.perceptiveautomation.IndigoServer2.plist` +- *Optional* : If you don't use Python 3.11 for anything (other than Indigo {{ version }}), you can delete this folder: `/Library/Frameworks/Python.framework/Versions/3.11` and this file: `/Library/Frameworks/Python.framework/Versions/Current` Note: this will leave any other version of Python alone including any previous versions that older Indigo installs may have installed (if you plan on reverting to an older version). To completely remove all Python installations that any version of Indigo may have installed, just delete the entire Python framework: `/Library/Frameworks/Python.framework` + +## Uninstalling the Mac Client +To also uninstall the Indigo Mac Client delete the following files: + +- `/Applications/Indigo {{ version }}.app` +- `~(your user folder)/Library/Preferences/com.perceptiveautomation.indigo-2025-1.plist` +- `~(your user folder)/Library/Preferences/Indigo {{ version }} Client Prefs.indiPref` +- `~(your user folder)/Library/Preferences/Indigo {{ version }} Client Settings.indiPref` + +Note your Mac has two different Library folders. One is in your the home directory of the account Indigo runs under and the other is at the root level of the drive. In Mac OS X Lion and higher the user's home Library folder is hidden in the Finder so you'll have to use the `Go to Folder...` menu item in the Finder and type in the path (`~/Library/Preferences`) which will open a Finder window to the Preferences folder. + +If you remove the Mac client application before shutting down the server, then delete the rest of the files above and reboot. + +## Uninstalling Older Indigo Versions +To uninstall older versions but leave {{ version }} installed correctly, delete these: + +- Indigo 2025.1: + - `/Library/Application Support/Perceptive Automation/Indigo 2025.1/` + - `/Applications/Indigo 2025.1.app` + +- Indigo 2024.2: + - `/Library/Application Support/Perceptive Automation/Indigo 2024.2/` + - `/Applications/Indigo 2024.2.app` + +- Indigo 2024.1: + - `/Library/Application Support/Perceptive Automation/Indigo 2024.1/` + - `/Applications/Indigo 2024.1.app` + +- Indigo 2023.2: + - `/Library/Application Support/Perceptive Automation/Indigo 2023.2/` + - `/Applications/Indigo 2023.2.app` + +- Indigo 2023.1: + - `/Library/Application Support/Perceptive Automation/Indigo 2023.1/` + - `/Applications/Indigo 2023.1.app` + +- Indigo 2022.2: + - `/Library/Application Support/Perceptive Automation/Indigo 2022.2/` + - `/Applications/Indigo 2022.2.app` + +- Indigo 2022.1: + - `/Library/Application Support/Perceptive Automation/Indigo 2022.1/` + - `/Applications/Indigo 2022.1.app` + +- Indigo 2021.2: + - `/Library/Application Support/Perceptive Automation/Indigo 2021.2/` + - `/Applications/Indigo 2021.2.app` + +- Indigo 2021.1: + - `/Library/Application Support/Perceptive Automation/Indigo 2021.1/` + - `/Applications/Indigo 2021.1.app` + +- Indigo 7.5: + - `/Library/Application Support/Perceptive Automation/Indigo 7.5/` + - `/Applications/Indigo 7.5.app` + +- Indigo 7.4: + - `/Library/Application Support/Perceptive Automation/Indigo 7.4/` + - `/Applications/Indigo 7.4.app` + +- Indigo 7.3: + - `/Library/Application Support/Perceptive Automation/Indigo 7.3/` + - `/Applications/Indigo 7.3.app` + +- Indigo 7.2: + - `/Library/Application Support/Perceptive Automation/Indigo 7.2/` + - `/Applications/Indigo 7.2.app` + +- Indigo 7.0 and 7.1: + - `/Library/Application Support/Perceptive Automation/Indigo 7/` + - `/Applications/Indigo 7.app` + +- Indigo 6 and prior (substitute the previous version # for 6): + - `/Library/Application Support/Perceptive Automation/Indigo 6/` + - `/Applications/Indigo 6.app` + +Note that these (specifically the first item in each) serve as a backup in case you want to revert, so you might want to consider zipping up the folder (not the client app) and saving it off before deleting if you think you might want to revert for some reason. diff --git a/reference/canonical/user/maintenance/upgrading.md b/reference/canonical/user/maintenance/upgrading.md new file mode 100644 index 0000000..e929897 --- /dev/null +++ b/reference/canonical/user/maintenance/upgrading.md @@ -0,0 +1,221 @@ + + +# Upgrading Indigo + +!!! abstract "In this guide" + This guide provides detailed instructions on how to upgrade your Indigo software, including version-specific changes. + +## Upgrading from a Previous Version +The upgrade process is pretty straight-forward, but below you'll find the specifics for each older version. + +## Upgrading from Indigo 2021.1 or later +### Server Folder Change +For this release, we've changed the server install path to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/ + +and the Indigo Mac Client app is now named: + + /Applications/Indigo {{ version }}.app + +### Web Assets Folder Change +The installer moves customer-installed images and other files from these folders: + + /Library/Application Support/Perceptive Automation/Indigo 202x.y/Web Assets/ + +(depending on version of Indigo you were using) to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/ + +### Shared Python Modules Folder Change +Lastly, the [shared Python modules folder](../../scripting/tutorial.md#shared-classes-and-methods-in-python-files-python-modules) available during script execution is located here: + + /Library/Application Support/Perceptive Automation/Python3-includes + +If you have any existing Python modules/libraries in the old `Python2-includes` folder you should copy them to the new folder and **make sure** they are [Python 3 compatible](#python-script-changes-and-plugin-compatibility). + +### Troubleshooting Not Compatible Error +If you experience the error `This version of the Indigo client application is not compatible with the Indigo Server` when trying to launch Indigo then that means the Indigo client version being launched doesn't match the version of Indigo Server currently being run. This can occur when an older version of Indigo Server is still running or an older version of Indigo Client was launched by mistake. To fix this follow these steps: + +1. Shut down the Indigo Server by selecting the `Indigo 202x.y->Stop Server` menu item in the Mac client. This will shutdown the Indigo Server regardless of which version is running. +1. Quit the Mac client via the `Indigo 202x.y->Quit Indigo` menu item. +1. Open the `/Applications` folder on your Mac and launch the version of Indigo you wish to use. This will have it launch the correct version of the Indigo Server when it starts. + +Once you are sure you are ready to run the latest version of Indigo can delete (backup first!) the older Indigo Server install paths in `/Library/Application Support/Perceptive Automation/` and client applications in `/Applications`. + +## Upgrading from Legacy Versions of Indigo + +!!! abstract "In this guide" + Step-by-step instructions for upgrading from Indigo 6.x or 7.x to Indigo {{ version }}, including installer path changes, plugin migration, and database conversion steps. Review this before upgrading — particularly if you have scripts that may need updating for Python 3 compatibility. + +### Upgrading from Indigo 7.5 +For this release, we've changed the server install path to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/ + +and the Indigo Mac Client app is now named: + + /Applications/Indigo {{ version }}.app + +In addition to the automatic upgrade logic described below (for upgrades from Indigo 6 and earlier), the installer moves previously installed control page images and web server plugins to the new install location. Note the folder that contains Web server images, legacy Web plugins, etc. has been renamed from: + + /Library/Application Support/Perceptive Automation/Indigo 7.5/IndigoWebServer/ + +to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/ + +If you experience the error `This version of the Indigo client application is not compatible with the Indigo Server` when trying to launch Indigo then that means the Indigo client version being launched doesn't match the version of Indigo Server currently being run. This can occur when an older version of Indigo Server is still running or an older version of Indigo Client was launched by mistake. To fix this follow these steps: + +1. Shut down the Indigo Server by selecting the `Indigo 7.5->Stop Server` menu item in the Mac client. This will shut down the Indigo Server regardless of which version is running. +1. Quit the Mac client via the `Indigo 7.5->Quit Indigo` menu item. +1. Open the `/Applications` folder on your Mac and launch the version of Indigo you wish to use. This will have it launch the correct version of the Indigo Server when it starts. + +Once you are sure you are ready to run the latest version of Indigo can delete (backup first!) the older Indigo Server install paths in `/Library/Application Support/Perceptive Automation/` and client applications in `/Applications`. + +### Upgrading from Indigo 7.4 +For this release, we've changed the server install path to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/ + +and the Indigo Mac Client app is now named: + + /Applications/Indigo {{ version }}.app + +In addition to the automatic upgrade logic described below (for upgrades from Indigo 6 and earlier), the installer moves previously installed control page images and web server plugins to the new install location. Note the folder that contains Web server images, legacy Web plugins, etc. has been renamed from: + + /Library/Application Support/Perceptive Automation/Indigo 7.4/IndigoWebServer/ + +to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/ + +If you experience the error `This version of the Indigo client application is not compatible with the Indigo Server` when trying to launch Indigo then that means the Indigo client version being launched doesn't match the version of Indigo Server currently being run. This can occur when an older version of Indigo Server is still running or an older version of Indigo Client was launched by mistake. To fix this follow these steps: + +1. Shut down the Indigo Server by selecting the `Indigo 7.4->Stop Server` menu item in the Mac client. This will shut down the Indigo Server regardless of which version is running. +1. Quit the Mac client via the `Indigo 7.4->Quit Indigo` menu item. +1. Open the `/Applications` folder on your Mac and launch the version of Indigo you wish to use. This will have it launch the correct version of the Indigo Server when it starts. + +Once you are sure you are ready to run the latest version of Indigo can delete (backup first!) the older Indigo Server install paths in `/Library/Application Support/Perceptive Automation/` and client applications in `/Applications`. + +### Upgrading from Indigo 7.3 +For this release, we've changed the server install path to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/ + +and the Indigo Mac Client app is now named: + + /Applications/Indigo {{ version }}.app + +In addition to the automatic upgrade logic described below (for upgrades from Indigo 6 and earlier), the installer moves previously installed control page images and web server plugins to the new install location. Note the folder that contains Web server images, legacy Web plugins, etc. has been renamed from: + + /Library/Application Support/Perceptive Automation/Indigo 7.3/IndigoWebServer/ + +to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/ + +If you experience the error `This version of the Indigo client application is not compatible with the Indigo Server` when trying to launch Indigo then that means the Indigo client version being launched doesn't match the version of Indigo Server currently being run. This can occur when an older version of Indigo Server is still running or an older version of Indigo Client was launched by mistake. To fix this follow these steps: + +1. Shut down the Indigo Server by selecting the `Indigo 7.3->Stop Server` menu item in the Mac client. This will shut down the Indigo Server regardless of which version is running. +1. Quit the Mac client via the `Indigo 7.3->Quit Indigo` menu item. +1. Open the `/Applications` folder on your Mac and launch the version of Indigo you wish to use. This will have it launch the correct version of the Indigo Server when it starts. + +Once you are sure you are ready to run the latest version of Indigo can delete (backup first!) the older Indigo Server install paths in `/Library/Application Support/Perceptive Automation/` and client applications in `/Applications`. + +### Upgrading from Indigo 7.2 +For this release, we've changed the server install path to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/ + +and the Indigo Mac Client app is now named: + + /Applications/Indigo {{ version }}.app + +In addition to the automatic upgrade logic described below (for upgrades from Indigo 6 and earlier), the installer moves previously installed control page images and web server plugins to the new install location. Note the folder that contains Web server images, legacy Web plugins, etc. has been renamed from: + + /Library/Application Support/Perceptive Automation/Indigo 7.2/IndigoWebServer/ + +to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/ + +If you experience the error `This version of the Indigo client application is not compatible with the Indigo Server` when trying to launch Indigo then that means the Indigo client version being launched doesn't match the version of Indigo Server currently being run. This can occur when an older version of Indigo Server is still running or an older version of Indigo Client was launched by mistake. To fix this follow these steps: + +1. Shut down the Indigo Server by selecting the `Indigo 7.2->Stop Server` menu item in the Mac client. This will shut down the Indigo Server regardless of which version is running. +1. Quit the Mac client via the `Indigo 7.2->Quit Indigo` menu item. +1. Open the `/Applications` folder on your Mac and launch the version of Indigo you wish to use. This will have it launch the correct version of the Indigo Server when it starts. + +Once you are sure you are ready to run the latest version of Indigo can delete (backup first!) the older Indigo Server install paths in `/Library/Application Support/Perceptive Automation/` and client applications in `/Applications`. + +### Upgrading from Indigo 7, or 7.1 +For this release, we've changed the server install path to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/ + +and the Indigo Mac Client app is now named: + + /Applications/Indigo {{ version }}.app + +In addition to the automatic upgrade logic described below (for upgrades from Indigo 6 and earlier), the installer is now smarter and moves previously installed control page images and web server plugins to the new install location. Note the folder that contains Web server images, legacy Web plugins, etc. has been renamed from: + + /Library/Application Support/Perceptive Automation/Indigo 7/IndigoWebServer/ + +to: + + /Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/ + +If you experience the error `This version of the Indigo client application is not compatible with the Indigo Server` when trying to launch Indigo then that means the Indigo client version being launched doesn't match the version of Indigo Server currently being run. This can occur when an older version of Indigo Server is still running or an older version of Indigo Client was launched by mistake. To fix this follow these steps: + +1. Shut down the Indigo Server by selecting the `Indigo 7->Stop Server` menu item in the Mac client. This will shut down the Indigo Server regardless of which version is running. +1. Quit the Mac client via the `Indigo 7->Quit Indigo` menu item. +1. Open the `/Applications` folder on your Mac and launch the version of Indigo you wish to use. This will have it launch the correct version of the Indigo Server when it starts. + +Once you are sure you are ready to run the latest version of Indigo can delete (backup first!) the older Indigo Server install paths in `/Library/Application Support/Perceptive Automation/` and client applications in `/Applications`. + +### Upgrading from Indigo 6, 5, 4, 3, or 2 +First, run the Indigo {{ version }} installer. Then look through this list for any final actions. + +- We have moved to Python v3.x, so if you installed any shared scripts ([as outlined here](../../scripting/tutorial.md#shared-classes-and-methods-in-python-files-python-modules)) then you'll need to move them from: `/Library/Python/X.X/site-packages/` to `/Library/Python/3.11/site-packages/` +- Indigo will automatically copy your old preference file into the new location during the installation. +- Indigo will also copy over any enabled and disabled Plugins from Indigo 6 or 5. If a newer version of a plugin is included in Indigo, then it will automatically be installed and used on launch. +- Your old Indigo database file will automatically be converted to the new Indigo file format on first launch. A copy of your database will automatically be made before it is converted, but any changes made in Indigo to your database will not be available in older versions of Indigo. +- If you are **upgrading from Indigo 6**, you'll need to manually copy over any custom scripts, web server plugins, and/or custom control page images that you may have added. They can be found in the following directories: + - **Scripts**: `/Library/Application Support/Perceptive Automation/Indigo 6/Scripts/` + - **Control Page Images**: `/Library/Application Support/Perceptive Automation/Indigo 6/IndigoWebServer/images/` + - **Web Server Plugins**: `/Library/Application Support/Perceptive Automation/Indigo 6/IndigoWebServer/plugins/` +- If you are **upgrading from Indigo 5**, you'll need to manually copy over any custom scripts, web server plugins, and/or custom control page images that you may have added. They can be found in the following directories: + - **Scripts**: `/Library/Application Support/Perceptive Automation/Indigo 5/Scripts/` + - **Control Page Images**: `/Library/Application Support/Perceptive Automation/Indigo 5/IndigoWebServer/images/` + - **Web Server Plugins**: `/Library/Application Support/Perceptive Automation/Indigo 5/IndigoWebServer/plugins/` +- If you are **upgrading from Indigo 4**, you'll need to manually copy over any custom scripts, web server plugins, and/or custom control page images that you may have added. They can be found in the following directories: + - **Scripts**: `/Library/Application Support/Perceptive Automation/Indigo 4/Scripts/` + - **Control Page Images**: `/Library/Application Support/Perceptive Automation/Indigo 4/IndigoWebServer/images/` + - **Web Server Plugins**: `/Library/Application Support/Perceptive Automation/Indigo 4/IndigoWebServer/plugins/` +- If you are **upgrading from Indigo 3 or Indigo 2**, you'll need to manually copy over any custom scripts and/or custom control page images that you may have added. They can be found in the following directories: + - **Scripts**: `/Library/Application Support/Perceptive Automation/Indigo 2/Scripts/` + - **Control Page Images**: `/Library/Application Support/Perceptive Automation/Indigo 2/IndigoWebServer/images/` + +!!! warning "NOTE" + Do not replace the new Indigo versions of any file with your Indigo 6, 5, 4, 3, or 2 files. They have been modified to run optimally under the new version of Indigo. + +### Upgrading from Indigo 1.x + +- Indigo will automatically copy your old preference file into the new location on first launch. +- Your old Indigo database file will automatically be converted to the new Indigo file format on first launch. You will be prompted to save the new copy of the Indigo database file. The new Indigo file format is not compatible with Indigo 1.x. You should not replace or delete your older Indigo 1.x database file. Any changes made in Indigo to your database settings will not be available in older versions of Indigo. +- You will need to manually copy any of your custom script files. You only need to move the files from the Indigo 1.x location (`[~your user home folder]/Documents/Indigo User Data/Scripts/`) to the new folder specified above if you modified or added new script or script attachment files. + +!!! warning "NOTE" + Do not replace the new Indigo versions of any file with your Indigo 1.x files. They have been modified to run optimally under the new version of Indigo. + +## AppleScript after Upgrading +Indigo no longer supports AppleScripts that target the Indigo Server process. Check out the [AppleScript Integration Strategies](https://www.indigodomo.com/indigo/applescript.html) article for options on converting your AppleScripts. + +When Indigo first opens an Indigo 7.3 (or earlier) database, it will go through the database and identify items that will need changing and items you should look at to ensure that it will continue to function. The Event Log will contain the necessary information about where you can find those items. You can also select the `Help->Show AppleScript Usage in Event Log` menu item and Indigo will show you the list of those items in the Event Log window again. + +Embedded AppleScripts and AppleScript conditionals will need to be evaluated to best determine how to handle them. In those edit boxes in the UI, we've commented out the previous AppleScript for reference if you wish to convert them. Both of those script edit boxes now will only accept Python scripts. + +If you have [Execute Script](../concepts/actions.md#execute-script) actions that point to AppleScripts, those will continue to be run, though if the script contains a **tell "IndigoServer"** or **using terms from "IndigoServer"** they will fail. + +## Python Script Changes and Plugin Compatibility +All Indigo embedded and external Python scripts run in Python 3. If any of them aren't working, they may have been written for an older version of Python. Take a look at our [updating to Python 3 tips](https://github.com/IndigoDomotics/IndigoSDK/blob/main/Updating%20to%20API%20version%203.0%20(Python%203).md) document. You can also post your scripts on the [Help Converting to Python 3 forum](https://forums.indigodomo.com/viewforum.php?f=364) to get help with any conversion issues. diff --git a/reference/canonical/user/remote-access/reflector.md b/reference/canonical/user/remote-access/reflector.md new file mode 100644 index 0000000..f202909 --- /dev/null +++ b/reference/canonical/user/remote-access/reflector.md @@ -0,0 +1,125 @@ + + +# The Indigo Reflector Service + +!!! abstract "In this guide" + How to activate and use the Indigo Reflector Service for secure remote access to your Indigo server — no router port forwarding, static IP, or DynDNS account required. Covers reflector activation, the personalized remote URL, and how Indigo Touch automatically switches between local Bonjour and remote reflector access. + +## About Reflectors +[Indigo Reflectors](http://www.indigodomo.com/account/reflectors/) are a service that gives you secure (HTTPS) remote access from anywhere to your Indigo Server **with no network configuration needed.** This is particularly useful for those of us that have dynamic (vs. static) IP addresses at home, or that have routers or networks that are difficult to configure for remote access to your Mac running Indigo. + +![Reflector Flow Image](../../images/reflector_flow_image.png) + +Reflectors work by routing communication from [Indigo Touch for iOS](https://www.indigodomo.com/touch.html), [Domotics Pad for Android](https://play.google.com/store/apps/details?id=com.duncanware.domoPad), [Indigo Touch for Web browsers](https://www.indigodomo.com/touch.html), and from external services like [Amazon Alexa](../../plugins/alexa/index.md), through our hosted systems to your Indigo Server. We do this through a secure tunnel between our hosted systems and your Indigo Server (even we don't see the unencrypted traffic). + +Your purchase of Indigo includes an [Indigo Up-to-Date subscription](http://www.indigodomo.com/blog/2016/11/09/indigo-date/), which itself includes reflector access. If you have an active Up-to-Date subscription, you can have a reflector! + +Reflectors provide: + +- Personalized easy-to-remember URL when using [Indigo Touch](http://www.indigodomo.com/touch.html) for the Web +- [Indigo Touch](http://www.indigodomo.com/touch.html) for iOS (iPhone, iPad, etc.) and for the Web can access your Indigo Server from anywhere in the world +- [Indigo Touch](http://www.indigodomo.com/touch.html) for iOS enabled – automatic switching between local Bonjour access and remote reflector access +- 3rd party services like Amazon Alexa can get secure, authenticated access to your Indigo Server to open up a broad range of integration possibilities. +- Complete remote access solution (much more than just a dynamic IP address mapping service) +- Fully encrypted (256-bit) communication +- Hassle free setup: + - No firewall configuration needed + - No router port forwarding needed + - No static IP address or DynDNS account needed + - No non-standard port numbers to remember + - No reverse proxies to implement SSL/HTTPS + +## Activating your Reflector +Activating a reflector is fast and easy. First, make sure you are running Indigo version 7.0.0 or greater(both client and server -- check the About Box). Next: + +1. Choose the `Indigo->Start Local Server...` menu item. +1. Turn on the `Allow remote access` checkbox and enter a Username and good Password. You will *definitely* want password authentication on since you are about to enable access to the Indigo web server from the Internet. +1. Turn on the `Enable secure internet access via Indigo Reflector` checkbox. +1. Press the `Activate Reflector` button. + +A browser page will open to the http://www.indigodomo.com/account/codes/ page listing your registration codes. + +- If you already have an Indigo Account then log in (if necessary). You'll then be redirected to the registration codes page. +- If you don't have an Indigo Account then create one by clicking on the `Sign up` link below the login form. When you create an account, we'll send you an activation email that contains a link to activate your account. When you click that link, it will switch you back to your browser and open the reflectors page. If for some reason it doesn't, switch back to Indigo and click the `Activate Reflector` button again and it will. + +Once on the registration codes list page, you'll see a message to click the **Create Reflector** link next to your Indigo registration code. Click on that link and you'll switch to the Reflectors page with a form field to enter your reflector name. When you submit that we will create the reflector, activate it, and take you back to the codes page which will show your reflector activated. + +Lastly, switch back to the Indigo `Start Local Server...` dialog. It should now show that the reflector status is activated and will show a link to your new reflector URL. Press the `Start Server` button and that is it – Indigo will restart and automatically connect to your reflector! To access from the web, simply go to `https://YOUR-REFLECTOR-NAME.indigodomo.net/`. + +You can now access Indigo web pages from anywhere using your personalized URL. No firewall settings changes, router port forwarding, etc. is needed. And even if your IP address changes, Indigo will automatically make sure that a new connection is re-established within just a few minutes. + +Your reflector will be active as long as you maintain an active Indigo Up-to-Date subscription. + +## Reset Your Reflector's Activation { #reset-your-reflector-s-activation } +If you are switching to a different reflector that you've asked us to create for you, or you've been instructed by support to reset your current reflector's activation, then follow these steps: + +1. Shut down the Indigo Server (select `Indigo {{ version }}->Stop Server`) but don't quit the Indigo Client +1. Switch to your browser and [log out of your Indigo Account](http://www.indigodomo.com/account/logout/) +1. Go to the [reflector list](http://www.indigodomo.com/account/reflectors/) in your Indigo Account (you'll need to log back in) and click the `Reset` link beside your reflector's status (it should say *Activated* before your press *Reset*) +1. Switch back to the Indigo Client and click on the `Start Local Server` button + +You should now see an `Activate Reflector` button towards the bottom of the dialog. Click that, log in to your reflector account, and select the appropriate reflector. If the reflector you want to use doesn't show in the list of inactive reflectors, [contact us](http://www.indigodomo.com/#contact) with the name of the reflector you're trying to activate and what steps you've performed. + +### Manual Reset +If the procedure above doesn't work, and *​only* ​if instructed by support, follow these steps to manually reset your Indigo Client reflector settings: + +1. Shut down the Indigo Server (select `Indigo {{ version }}->Stop Server`) but don't quit the Indigo Client +1. Switch to your browser and [log out of your Indigo Account](http://www.indigodomo.com/account/logout/) +1. Go to the [reflector list](http://www.indigodomo.com/account/reflectors/) in your Indigo Account (you'll need to log back in) and click the `Reset` link beside your reflector's status (it should say *Activated* before your press *Reset*). If the reflector has already been deactivated that is fine – just skip this step. +1. In the Finder, select `Go->Go to Folder…` +1. In the resulting dialog, copy and paste the following: `/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Preferences/` +1. In the resulting Finder window, delete the folder named `PrismReflector` +1. Switch back to the Indigo Client and click on the `Start Local Server` button + +## Indigo Touch and Your Reflector +[Indigo Touch](http://www.indigodomo.com/touch.html) for iOS is transparently integrated with the Indigo Reflector service. When you use your iOS device (iPhone, iPad, etc.) to connect to Indigo while in your house (and on your local Wi-Fi network), Indigo Touch will automatically retrieve and remember your reflector address. You can press the settings (gear) icon on the top toolbar then find the `Reflector` item near the bottom to verify that it is working correctly. + +Once Indigo automatically detects your reflector address, it will seamlessly change between using the local Bonjour detected address and the remote reflector address. Just launch Indigo Touch and it works, no matter where you are! + +## Bandwidth Limits +Because using a reflector has to bounce all requested files to and from our server, monthly bandwidth usage cannot be unlimited. Reflectors that exceed an average bandwidth of approximately 200 MB per day may have temporary limitations or throttles imposed, but a vast majority of the time bandwidth is not an issue. There are a couple of things that can lead to excessive bandwidth usage. So please consider: + +- If you have a graphical Control Page in Indigo that uses the `Refreshing Image` control type then use a longer refresh duration (30 minutes or longer) for the image, especially if you plan to frequently access the page remotely. + +- Not leaving Indigo Touch or an Indigo web browser page running continuously while not viewing it. By closing the browser window or leaving Indigo Touch (home button), the requests through the reflector will stop which significantly reduces daily bandwidth usage. + +Note these usage suggestions only apply to connections when a reflector is being used. If you are directly connected to your Indigo Server on your home network or not using a reflector then the bandwidth isn't going through our servers and you can have Control Page images refreshed as frequently as you would like. + +## Troubleshooting +In this section you'll find information on troubleshooting any reflector errors/issues you may be experiencing. + +If you see any of the following errors in the Event Log window, do as described to resolve the issue. + +- failed to create reflector connection: reflector not active - try the steps above to [reset your reflector's activation](#reset-your-reflector-s-activation) +- reflector connection test failed: local server unreachable - check [this forum post](https://forums.indigodomo.com/viewtopic.php?f=131&t=27344) for the likely causes. +- Unable to authenticate with IndigoDomo.com (server might be down temporarily for maintenance) - you may be able to resolve the issue by: + 1. shutting down the Indigo Server, + 1. deleting the registration file located at *`/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Preferences/Indigo Registration.indiPref`*, + 1. restarting the Indigo Server, and + 1. when prompted, enter your Indigo Account information. + +Reflectors may also be affected by a bad entry in your *`/etc/hosts`* file. [Check this forum post for details](https://forums.indigodomo.com/viewtopic.php?t=27344). + +### Advanced Troubleshooting +If nothing else works or if directed by Indigo support, [create a new topic in the reflectors forum](https://forums.indigodomo.com/viewforum.php?f=10) detailing what you've tried and do the following: + +1. Launch the Terminal application (inside *`/Applications/Utilities/`*) + +2. Copy/paste each line below *individually* and hit the return key after each one: + + id + cd /Library/Application\ Support/Perceptive\ Automation + cd Indigo\ {{ version }}/IndigoServer.app/Contents/Resources/PlugIns/ + ps -axww | grep "Indigo" +3. Select the entire results of the Terminal window (CMD-A) and copy/paste into Code tags (the icon that looks like this: *``*). + +4. Copy/paste each line below *individually* into the Terminal window and hit the return key after each one: + + ./reflector_library_stub.py -m geturl -d + ./reflector_library_stub.py -m tunnel -d + +5. Wait 3 minutes. It can take a while for the network errors we are trying to catch to be reported. Then enter again: + + ps -axww | grep "Indigo" + +6. Select the entire contents of the Terminal window (CMD-A) again and copy/paste results into another section with Code tags. diff --git a/reference/canonical/user/remote-access/ssl-certificates.md b/reference/canonical/user/remote-access/ssl-certificates.md new file mode 100644 index 0000000..49e49b2 --- /dev/null +++ b/reference/canonical/user/remote-access/ssl-certificates.md @@ -0,0 +1,41 @@ + + +# Indigo Web Server Certificates + +!!! abstract "In this guide" + How to configure browsers and HTTP clients (such as Node-RED) to accept the Indigo Web Server's self-signed SSL certificate for local HTTPS connections. Covers locating the certificate files in the Web Assets folder and configuring TLS settings in third-party tools. + +## Node Red Example +The following example shows how to configure a Node Red flow that uses the Indigo Web Server (IWS) API to operate a lamp device. The example is only meant to show how to use a self-signed certificate and public key to enable the flow to connect to the IWS using `*https*` instead of `*http*` when using the IWS on a local network via `*10.0.1.123*`, `*127.0.0.1*`, or `*localhost*` (using the API via the Indigo Reflector Service uses a different CA-approved security certificate and the flow is configured the same as it would be using any API via `*https*`). + +![Noe Red Image](../../images/node_red_1_flow.png){ width=600 } + +Using the flow via `*https*` requires a few settings. Enter the preferred URL to point at the local IWS address `*10.0.1.123*`, `*127.0.0.1*`, or `*localhost*` with the URL: + +```text +https://:8176/v2/api/command/ +``` +for example, +```text +https://10.0.1.123:8176/v2/api/command/ +``` + +![Node Red 6 HTTP Request Node Image](../../images/node_red_6_http_request_node.png){ width=400 } + +select TLS, and use bearer authentication along with a valid token key (from your Indigo Account Authorizations). + +Then, use key and certificates from local files and point them to the certificate and public key files located in + +```text +/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/cert/ +``` + +![Node Red 7 HTTP Request Node Image](../../images/node_red_7_http_request_node_tls_config.png){ width=400 } + +Several other screenshots complete the example: +| ![Node Red Inject Node Turn On Image](../../images/node_red_2_inject_node_turn_on.png){ width=400 } | +| --- | --- | +| ![Node Red Inject Node Turn On JSON Image](../../images/node_red_3_inject_node_turn_on_json.png){ width=400 } | +| ![Node Red Inject Node Turn Off Image](../../images/node_red_4_inject_node_turn_off.png){ width=400 } | +| ![Node Red Inject Node Turn Off JSON Image](../../images/node_red_5_inject_node_turn_off_json.png){ width=400 } | +| ![Node Red HTTP Debug Node Image](../../images/node_red_8_http_debug_node.png){ width=400 } | diff --git a/reference/canonical/user/remote-access/touch-for-web.md b/reference/canonical/user/remote-access/touch-for-web.md new file mode 100644 index 0000000..d36123c --- /dev/null +++ b/reference/canonical/user/remote-access/touch-for-web.md @@ -0,0 +1,143 @@ + + +# Indigo Touch For Web + +!!! abstract "In this guide" + How to load and use Indigo Touch for Web (ITW), the browser-based control client built into Indigo. Covers local and reflector-based access URLs, the device/action/variable/pages tabs, and what functionality is available compared to the full Mac client. + +Indigo includes an [integrated web server](web-server.md) that allows you to serve your own custom content, and it also includes a web-based alternative to Indigo Touch for iOS called **Indigo Touch for Web** or ITW. ITW is a Single Page Application (SPA) that runs entirely in a browser. ITW is not meant to be a replacement for the Mac Client -- you can't configure devices or add variables for example -- however, the most common Indigo functions are available. These include turning on/off devices, controlling thermostats, changing variable values and so on. Available features are listed below, and we have plans to include more features in the future! + +![Indigo Touch Web Image](../../images/itw_tile_view_light.png){ width=800 } + +ITW works by establishing a bidirectional connection to the Indigo [Websocket API](../../api/index.md). ITW works on both desktop and mobile (mobile availability depends on configuration and whether you're connected locally via Wi-Fi or remotely via cellular). + +## Loading ITW +There are several ways to load ITW depending on your environment. The three most common being: + +1. the Indigo Reflector Service using your custom reflector address such as *`https://my_reflector.indigodomo.net`* via a secure *`https://`* connection (the reflector service requires an Indigo up-to-date subscription). +1. a local loop-back address such as *`http://localhost:8176`* or *`http://127.0.0.1:8176`* via an insecure *`http:`* connection. These connections are only valid when used on the same machine running the Indigo server (and obviously, won't work on mobile). +1. a direct IP address such as *`http://10.0.1.123:8176`* or *`http://192.168.0.123:8176`* via an insecure *`http:`* connection. + +Note that the custom port address (8176 above) may differ depending on the settings you use when launching the Indigo Server. + +When you use a bare address like the examples above, the server will redirect the request and load the ITW homepage *`index.html`* so -- depending on your browser -- the address field will show *`localhost:8176/index.html`* or *`http://localhost:8176/index.html`* or something similar. + +## Interface Controls +When ITW loads, you'll be presented with the main view which has five tabs to choose from -- Devices, Actions, Variables, Pages and Logs (Indigo schedules are not currently shown in ITW). + +### Tabs +#### Devices + +- The Devices tab shows the devices in the Indigo database. +- Only devices with *`Remote Display`* checked will be displayed. +- Many device controls are available in ITW, including: + - On/off + - Lock/unlock + - Dimming + - Thermostat + +Devices also have a special popup menu which is shown when you click the ellipsis icon *`...`* at the top (or on the right side) of the device tile. This displays a menu with up to four options (depending on the type of device): + +- Copy ID - This option will cause the device's ID to be copied to the clipboard. Due to the security of modern browsers, this feature will only work via *`https`* connections via the Indigo Reflector Service and via *`http`* when connecting using a local loopback address like *`localhost`* or *`127.0.0.1`*. +- Refresh from server - ITW objects update automatically when data are changed in Indigo, but sometimes you might want to force the data to refresh for a specific device. Selecting this option will cause the device data to be refreshed. +- Send status request - only available for devices that support the Send Status Request feature in the Indigo Client. +- Show device JSON - this option will cause a pop-up window to display the entire JSON payload for the device. + +#### Actions + +- The Actions tab shows the action groups in the Indigo database. +- Only actions with *`Remote Display`* checked will be displayed. +- Clicking a displayed action button will cause the action to be executed. + +#### Variables + +- The Variables tab shows all the variables in the Indigo database. +- Only variables with *`Remote Display`* checked will be displayed. +- You can change the value of any variable (with the sole exception of *`isDaylight`* which is read only). Clicking on a variable value will cause a dialog box to open where you can edit the value. +!!! note + **It's possible for the value to change on the Indigo server while you are editing it. In instances where this happens, the last write will take precedence. In other words, if you click save in ITW after the value has changed on the server, the ITW value will become the new value.** + +- For select boolean values, a toggle value button will be displayed in the editing dialog--similar to Indigo Touch. + +Variables also have a special popup menu which is shown when you click the ellipsis icon *`...`* on the right side of the variable tile. This displays a menu with two options: + +- Copy ID - This option will copy the variable's ID to the clipboard. +- Copy value - This option will copy the variable's value to the clipboard. + +Due to the security of modern browsers, these features will only work via https connections or via http when connecting using a local loopback address like localhost or 127.0.0.1. + +#### Triggers + +- The Triggers tab shows all the triggers in the Indigo database. +- Triggers don't have a *`Remote Display`* checkbox, so no triggers are hidden from view. +- Disabled triggers are shown with a red border. +- Clicking a displayed trigger button will cause the associated events to be executed. + +#### Schedules + +- The Schedules tab shows all the schedules in the Indigo database. +- Schedules don't have a *`Remote Display`* checkbox, so no schedules are hidden from view. +- Disabled schedules are shown with a red border. +- Clicking a displayed schedule button will cause the associated events to be executed. + +#### Pages + +- The Pages tab shows control pages in the Indigo database. +- Only control pages with *`Remote Display`* checked will be displayed. +- Clicking a displayed control page button will cause the page to be loaded in a separate window or tab. + +#### Logs + +- The Logs tab begins with the 25 most recent event log entries. +- New log messages will be displayed while the Logs tab is active. +- Debug, caution and warning messages will be colored appropriately. +- Long and multiline log messages will be truncated, and will appear with an ellipsis (...). Clicking on a truncated message will expand it. Click again to collapse it. + +## Search Tools +### In Folder +This dropdown list will list the folders appropriate to the tab selected. For example, the Actions tab will only display folders in your actions list in Indigo. Selecting a folder will filter the object list as it does in the Indigo client. + +### Name Contains +This text field allows you to filter the object list based on the object's name field. You can search by partial text -- for example, entering *`ext`* will show both "**Ext**erior" as well as "T**ext**". + +## Themes +ITW currently supports two themes -- light mode and dark mode. You can toggle between the two using the button at the top right of the screen. Your choice is saved locally via your browser's local storage, so the next time you visit, ITW will display using your theme preference. If you clear your browser's cache (including local storage), your preference choice will be erased. This setting is also browser specific so if you rotate among different browsers or have multiple users, each can have its own unique preference saved. + +| Light Mode | Dark Mode | | | +| --- | --- | --- | --- | +| ![Indigo Touch Web Image Light](../../images/itw_tile_view_light.png){ width=800 } | ![Indigo Touch Web Image Dark](../../images/itw_tile_view_dark.png){ width=800 } | + + +## Views +Indigo Touch Web supports two views--Tile view and List view. You can toggle between the two views using the view button located in the upper right corner. + +| Tile View | List View | | | +| --- | --- | --- | --- | +| ![Indigo Touch Web Tile View](../../images/itw_tile_view_light.png){ width=800 } | ![Indigo Touch Web List View](../../images/itw_list_view_light.png){ width=800 } | + + +Items in List view are collapsed by default. Clicking on the ">" next to an item will expand it to display things like additional controls and details. Click on the element's ">" again to collapse it. + +List view is available for all ITW tabs (except log entries). + +## Loading A Specific Tab +By default, ITW will show the Devices tab when it first loads. If you would like to begin with a different tab, you can add a URL query argument to the end of the target URL (**query arguments must be lowercase, and you must include *`index.html`* as a part of the URL for this feature to work**). + +Examples: + +| Tab | Target URL | Default | +| --- | --- | --- | +| Devices | *`http://localhost:8176/index.html?tab=devices`* | X | +| Actions | *`http://127.0.0.1:8176/index.html?tab=actions`* | | +| Variables | *`https://my_reflector.indigodomo.net/index.html?tab=variables`* | | +| Pages | *`http://192.168.0.123:8176/index.html?tab=pages`* | | +| Logs | *`http://10.0.1.123:8176/index.html?tab=logs`* | | + +## Troubleshooting +If you don't see the ITW web interface displayed in your browser, there are several things you can check. + +- be sure you're using the right URL security protocol: + - *`https://`* when accessing via the Indigo Reflector Service, and + - *`http://`* via the other available means. +- be sure you've entered the correct address for your Indigo server and the port number you specified when you started the server (the default is 8176). +- if the proper tab wasn't selected when you loaded the app, be sure your query arguments are lowercase... *`?tab=logs`* is valid, *`?tab=Logs`* is not. diff --git a/reference/canonical/user/remote-access/web-server.md b/reference/canonical/user/remote-access/web-server.md new file mode 100644 index 0000000..7807b8d --- /dev/null +++ b/reference/canonical/user/remote-access/web-server.md @@ -0,0 +1,210 @@ + + +# Indigo Web Server + +!!! abstract "In this guide" + How to configure and use the Indigo Web Server (IWS) to serve custom content locally or via the Indigo Reflector. Covers authentication methods, port settings, the Web Assets folder structure, plugin resource folders, and integration examples using Node-RED and JavaScript frameworks. + +The Indigo Server contains a fully-functioning web server that you can use to serve content locally or via the Indigo Reflector Service (the Reflector requires an active Indigo Up To Date subscription). You can use this functionality to make content available in a variety of ways. For example, Indigo users have created complex websites using JavaScript, [Vue](https://vuejs.org), and [Svelte](https://svelte.dev). See below for a fully-functional [example](#example). + +## Security Certificates +Displaying web content in a secure format using HTTPS requires a security certificate for the site your browser is connected to. These certificates are typically reviewed and signed by a third party authority to ensure they're legitimate. Indigo's certificate is “self-signed”, which means that it hasn't been reviewed by a third party. We must use a self-signed certificate because it isn't possible to have an authority-signed certificate for a local server name (localhost or 127.0.0.1) that doesn't have its own domain name. + +Appropriately, your browser will warn you that a security certificate is self-signed and require you to intervene in order to display the requested content. You can choose to respond to this warning each time it appears, or you can tell your browser to trust the certificate – which will typically silence these warnings. We have a [separate page](ssl-certificates.md) that describes various ways to handle self-signed certificates. + +## Advanced Web Server Settings +Select the `Indigo {{ version }}->Advanced Web Server Settings...` menu item and you'll get this dialog: + +![Web Server Settings Dialog](../../images/web_server_settings_2025_1.png){ width=700 } + +The menu has three options: + +1. Debug Logging: Enable this setting to show extra Web Server debugging information. +1. Hide Security Logging: Enable this setting to hide HTTP API connection attempts. Warning: enabling this will reduce the logging of incoming HTTP API requests. We recommend keeping these messages as they can help identify security issues. +1. Cache Controls: If you are having issues with cached API Keys (not Local Secrets), use the button to clear the key cache. This will force Indigo to connect to your Indigo Account to validate the next transaction which contains an API Key. + +## Web Assets Folder Structure +Indigo {{ version }} contains special folders that are accessible to the Indigo Web Server which are located in: +```text +/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/ +``` +There are four stock folders located under this parent folder: +```text +/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/images +/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/plugins +/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/public +/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Web Assets/static +``` + +As a convenience, you can access these folders under the Indigo Help menu: `Help` --> `Show Web Assets Folder` + +All assets you want to make available to the Indigo Web Server should be stored in these folders. + +### images folder +This folder is used to publish files and make them available in the Indigo UI for use in control pages (and for other purposes). More information on using this folder can be found in the [Custom Images on Control Pages](../concepts/control-pages.md#custom-images-on-control-pages) section. + +### plugins folder +With Indigo 2022.2, web server plugins are no longer supported. + +### public folder +This directory can be used to publish files from the Indigo Web Server that will be made available to anyone ****without any authentication****. If someone knows the URL of your reflector, they will have access to any files that are in this +directory, so use it wisely. + +For example: +```text +https://MYREFLECTOR.indigodomo.net/public/about.txt +http://10.0.1.2:8176/public/about.txt +http://localhost:8176/public/about.txt +``` + +Basic MIME types will be determined from file extensions. Subdirectories are also allowed so you can create hierarchy: +```text +https://MYREFLECTOR.indigodomo.net/public/somedirectory/somefile.html +https://MYREFLECTOR.indigodomo.net/public/images/somepic.jpg +``` + +Any files and/or directories in the /public/ folder will need to be moved over when you upgrade to a new major version (the installer WILL NOT move them automatically). The public folder was added with Indigo version 7.1. + +### static folder +This directory can be used to publish files from the Indigo Web Server that will be made available to anyone ****with authentication****. If someone knows the URL of your reflector, they will have access to any files that are in this directory once they have entered the appropriate authentication credentials for your reflector. + +For example: +```text +https://MYREFLECTOR.indigodomo.net/static/about.txt +http://10.0.1.2:8176/static/about.txt +http://localhost:8176/static/about.txt +``` + +Basic MIME types will be determined from file extensions. Subdirectories are also allowed so you can create hierarchy: +```text +https://MYREFLECTOR.indigodomo.net/static/somedirectory/somefile.html +https://MYREFLECTOR.indigodomo.net/static/images/somepic.jpg +``` + +### Authentication +#### API Keys +Information on Indigo Authentication options using API Keys can be found on the [Integration APIs](../../api/index.md) page under the authentication section. + +#### Local Secrets +In addition to authentication via API Keys and the Indigo Reflector (recommended), users can create their own local secrets (another type of key) that don't require an internet connection to validate. Users can create a JSON list of their own "secrets" that will be loaded whenever the web server is restarted. The secrets file is located in the install folder's *`/Preferences`* directory and is named //`secrets.json`//: + +*`/Library/Application Support/Perceptive Automation/Indigo {{ version }}/Preferences/secrets.json`* + +Those secrets can be used in both authorization headers and in the api-key query argument on URLs (exactly the same as API Keys). Example: + +```json +[ + "here-is-a-key", + "this*is*another*key" +] +``` + +Additionally, if the user wants to completely disable API Keys, they may add the string "do-not-use-api-keys" to their list of secrets. + +```json +[ + "here-is-a-key", + "this*is*another*key", + "do-not-use-api-keys" +] +``` + +The effect here is that only the first two will successfully authenticate API calls and nothing else. If the user only specifies this: + +```json +[ + "do-not-use-api-keys" +] +``` + +The effect would be the same as unchecking the "Enable OAuth and API Key authentication" checkbox in the Start Local Server dialog, but with different logging when an authentication try fails. While valid, this configuration is not recommended; instead, users should use the OAuth setting when the server is first started (to avoid confusion). + +You use the local secret(s) the same way you would use an API Key; for example, + +*`http:*localhost:8176/v2/api/indigo.devices/123456789?api-key=my-local-secret`// + +**Important!** - When making changes to the *`secrets.json`* file, you must restart the server for the changes to take effect (the server loads the secrets file at startup). + +### Custom Web Page Example { #example } +Using the Indigo Web Server and Web Assets folders is extremely easy. This example is for reference purposes and is not meant to be a primer on constructing Web content. There are many good tutorials online that you can refer to if needed. + +First, create your content. For example, websites often contain a `index.html` page. A simple `index.html` page looks like this: +```xml + + + + + Indigo Web Server + + +
+ Hello world. +
+ + +``` +Using a plain text editor, save this code as `index.html` within the `.../Web Assets/static` folder (to serve it with authentication) or within the `.../Web Assets/public` folder (to serve it without authentication). You can refer to assets located in other folders by referencing them with the `Web Assets` folder as the root. + +That's it! The Indigo Web Server will serve your web page via the appropriate method. + +## Troubleshooting +The Indigo Web Server is a complex piece of the Indigo ecosystem, but it rarely has issues. There are some things that have happened in the past, and we thought we'd outline some debugging steps here. + +### Websocket Failures +In rare circumstances, problems may arise that cause an inability to connect to Indigo's [Websocket API](../../api/websocket.md). This will often manifest as [Indigo Touch for Web](touch-for-web.md) hanging at the Loading page. Here are some troubleshooting tips that should get you back in business. + +#### Enable Diagnostic Tools +**Webserver Debug Options** + +In the Indigo client UI, go to Indigo > Advanced Web Server Settings... and enable **Debug Logging**. In rare circumstances you may need to enable **Cache Debug Logging** as well. This logging may provide some useful details. + +**Browser Debugging** + +Enable console debugging in your browser. The steps vary depending on the browser you're using, but in Safari go to Settings > Advanced > Show features for web developers. You should now see a Developer tab in settings and on the main Safari menu. Head to Develop and select Show JavaScript Console. Now trying to load Indigo Touch for Web and see if there are any errors shown in the console log (Indigo Touch for Web uses JavaScript to render the various pages). + +**Script Debugging** + +If you're having trouble getting a Python, JavaScript or other code to connect, it's best to add a lot of logging and error trapping to your code which will help to isolate any issues. You can always turn off or remove extra logging when you're done. + +#### Make Sure You Have the Right Websockets Version Installed +Each new version of Indigo is tested against a specific version of the websockets library and having a different websockets version can potentially cause problems. If you can't connect to the server using [Indigo Touch For Web](touch-for-web.md), the websockets library may be causing some trouble. To check which version of the websockets library you have installed, open a terminal window and run the following command: +```text +pip3 show websockets +``` +To see which version **should** be installed, head over to [Python Packages and Indigo](../../scripting/guides/python-packages.md) and follow the instructions there. Also, note that you may have multiple version of Python installed, so you'll want to make sure you're using the right pip by specifying the full version (pip3.11, pip3.13, etc). + +#### Make Sure You're Using the Right Security Layer +The security settings you chose when you started the Indigo Server affect how you connect to the web server. + +| Security | Protocols | +| --- | --- | +| HTTPS enabled | must use links that start with `https://` and `wws://` | +| HTTPS not enabled | must use links that start with `http://` and `ws://` | + + +#### Test With a Simple Script or Link +Another diagnostic tool you can try is to attempt to connect to the server using simple, known methods to try to isolate the issue. There are sample websocket scripts near the top of the [Integration APIs](../../api/index.md) page. These scripts will attempt to make a simple connection to the websocket API. + +#### Review Your Network Configuration +Some networking configurations can impact your ability to attach to the Indigo Server using the API endpoints. You should ensure that you're not blocking IPs or ports that you're trying to connect with. If you're running your traffic through a VPN, blocking or filtering traffic through applications like Little Snitch or PiHole, make sure these programs aren't blocking the traffic. Make sure that your Indigo Server and client are both on the same network (including subnet). Also check to ensure that nothing else is trying to use the port you're using with Indigo. + +### Other Potential Issues +There are other issues that may arise with the Indigo Web Server. If you are having issues outside the above, then you can use the next sections to help diagnose what might be causing them. + +#### Check Your Hosts File +Sometimes, hosts file settings can cause conflicts. Review your hosts file (do not make changes unless you know what you're doing) to see if anything looks like it might be rerouting your connection. The hosts file is typically located in `/etc/hosts`. It should only contain lines similar to this: + + 127.0.0.1 localhost + 255.255.255.255 broadcasthost + ::1 localhost + +If you have other declarations, especially for `localhost`, then that might be interfering with normal Web Server operation. We recommend commenting out any lines that are not the above lines to debug any issues you may have. + +#### Check Your Server's Network Connection and Settings +Assuming your server machine is able to connect to your network, check to ensure that the server machine isn't connecting with both wired and wireless connections. This can sometimes cause issues with network traffic. It's generally best to stick to one connection method. + +#### Try Local and Reflector Connections +If you can't connect locally, you still may be able to connect with the Indigo Reflector service. The reverse is also true. If you can connect via one method but not the other (both should work under normal circumstances) that may help you isolate the issue. + +#### Disable Firewalls and Virus Protection +Sometimes various firewall products (including macOS built-in firewall) can block different types of network connections. Virus Protection software can be especially bad about interfering with network traffic. While troubleshooting it's recommended to disable all such software on your Mac. diff --git a/reference/canonical/user/troubleshooting/powerline-signal-troubleshooting.md b/reference/canonical/user/troubleshooting/powerline-signal-troubleshooting.md new file mode 100644 index 0000000..ab73e14 --- /dev/null +++ b/reference/canonical/user/troubleshooting/powerline-signal-troubleshooting.md @@ -0,0 +1,77 @@ + + +# Insteon and X10 Troubleshooting Basics + +Insteon and X10 are both power line protocols that allow remote control and monitoring of modules through your existing home wiring. Insteon is a newer, more robust standard that provides improved performance and signal reliability. There are dozens of different Insteon and X10 [control modules](https://www.indigodomo.com/devices/) supported by Indigo which can be used to control lighting, appliances, hot tubs, sprinklers, thermostats (HVAC), and much more. These control modules listen for Insteon or X10 commands on your existing power lines, decode this information, and then control the device (light, appliance, thermostat, etc.). Indigo both listens and transmits to these control modules using a [home control computer interface](https://www.indigodomo.com/devices/interfaces). + +Insteon is also dual-band, which means that it sends signals both on the power line and wirelessly. Most Insteon devices that are not battery powered and have shipped since 2014 or so are dual-band. That is, they send and receive signals from both the power line and from RF. It's worth noting however that these dual-band devices often prioritize power line signals over RF. That means that if there is signal noise on the power line, the device may still fail to operate reliably even though it's dual-band. + +## Signal Troubleshooting +In some cases Insteon or X10 control modules fail to receive or properly decode the information sent over the power line. This typically happens because there is excessive noise on the power line caused by some other appliance, such as a power supply, surge protector strips, portable electronics charger, etc., or because the signal is not able to travel over that particular leg, or phase, of your household wiring. + +The most common symptom of a signal problem is when some Insteon or X10 modules are controllable, but others fail to respond to commands sent by Indigo. In extreme cases, the signal can fail to get to all modules. To troubleshoot modules that will not turn on/off from Indigo: + +### Bridge Your Home's 110V Power Legs +Every house has two 110V power legs that are electrically connected only at the street or alley transformer. Most Insteon devices that shipped over the past several years that aren't battery powered are dual-band, which means that they repeat over both the power line and RF. If you have older devices, then properly installing two [Insteon Range Extenders](https://www.smarthome.com/insteon-2992-222-range-extender.html) will also bridge all Insteon signals across both power legs. Dual-band devices (which includes the Range Extenders) are required to have a complete and reliable Insteon home network. Be sure and follow the instructions that come with the Range Extenders to ensure that they are plugged into outlets on opposite power legs. X10 customers will need to find an alternate device to bridge the power legs for X10 commands. + +**Important**: *The Insteon Range Extenders, AccessPoint RFs and SignaLinc RFs ONLY bridge Insteon signals.* + +### Change the Insteon / X10 Signal Path +Sometimes just changing the signal path from the transmitting computer interface (PowerLinc, CM11, etc.) to the destination module can help. Try the following, attempting to turn the module on/off after each step: + +- Plug the computer interface into a different outlet. If needed, use a short extension cord to reach another outlet. +- If the destination module is a plug-in type (LampLinc, ApplianceLinc, etc.), then temporarily plug it directly into the PowerLinc's passthrough outlet. If it works there, then this proves it is a signal problem. +- Insteon users can move their AccessPoint RF pair (or SignaLinc RF pair) to other outlets in the house. Per their instructions, be sure the new outlets are on opposite power legs. +- Insteon users can also plug one of the AccessPoint RFs directly into the PowerLinc's passthrough outlet. Per the AccessPoint instructions, the other AccessPoint must still be installed on the opposite power leg. This can help if there are severe signal problems on the same circuit as the PowerLinc. + +### Temporarily Remove or Filter "Signal Suckers" +Some electronics can significantly attenuate, or diminish, the strength of Insteon and X10 signals. Uninterruptible Power Supplies (UPSs) and high-end surge protector strips are notorious for attenuating both Insteon and X10 signals. Try temporarily unplugging all UPSs (just let them run off of battery for a couple of minutes) to see if that allows control of the module. If it does, then you can isolate the UPS so that it doesn't cause problems by plugging it into an [Insteon Noise Filter](https://www.smarthome.com/filterlinc-10-amp-plug-in-noise-filter.html). + +In addition to UPSs, try temporarily unplugging other electronics and surge protector strips that are on the same circuit as the PowerLinc. Potential problem devices include: + +- UPSs and surge protector power strips +- televisions and video game systems +- laptop and mobile phone chargers +- fax machines +- MIDI musical instruments + +If unplugging any of them helps, then you can isolate the problem device with an [Insteon Noise Filter](https://www.smarthome.com/filterlinc-10-amp-plug-in-noise-filter.html). + +**Important**: Although UPSs and other electronics on the same circuit as the PowerLinc are most often the culprit, it is possible for UPSs on other circuits or other parts of the house to cause signal problems. Try unplugging all UPSs if you don't see an improvement after removing devices on the same circuit as the PowerLinc. + +### Temporarily Remove or Filter Noisy Electronics +Some electronics can also introduce noise on the power lines that can cause problems for Insteon and X10 signal reliability. Try temporarily unplugging the following, especially if they are on the same power circuit as the home control computer interface (PowerLinc, CM11, etc.) or the module you are trying to control: + +- portable electronic chargers (laptop, mobile phone, tooth brushes, razors, etc.) +- CFL, LED, halogen and HID lighting +- fans, treadmills, and other appliances with motors + +If unplugging any of them helps, then you can isolate the problem device with an [Insteon Noise Filter](https://www.smarthome.com/filterlinc-10-amp-plug-in-noise-filter.html). + +### Identify Failing X10 (and Insteon) Devices +If you see traffic from X10 device addresses for which you don't have a corresponding device, it is possible that you have another X10 or Insteon device that's starting to fail and is erroneously broadcasting out garbage that looks to the interface like valid X10 traffic. The interface may become so busy trying to decipher these garbage transactions that it will not reliably send commands. You'll need to find the offending device and disable it. + +With plug-in modules that's simple, just unplug them all and start adding them back one at a time. It's a bit harder with devices that are in-wall. Some of these devices have the ability to be "air-gapped" which will completely remove power to them. Most SwitchLinc devices, for instance, can be air-gapped by pulling the LED pipe below the switch out until it clicks and stays pulled out. Other devices that don't have this ability will be harder to deal with. You can cut off circuit by circuit at your power panel until the problem ceases. That will give you a better clue where the problem device is located. + +### Increase the Insteon / X10 Signal Strength +Although we recommend making sure your power legs are bridged correctly (see above) and isolating problem electronics first (see above), if you still have unreliable operation with some modules then you can try increasing the signal strength with a signal repeater or booster. All Insteon modules are automatically repeaters (of Insteon commands only), so adding additional modules (LampLinc, ApplianceLinc, SwitchLinc, etc.) or additional AccessPoint RFs can help. + +X10 commands are only repeated by an active couple repeater, like the dryer SignaLinc Coupler Repeater. Another option besides repeating the command is to use a signal booster, like the BoosterLinc. Note the BoosterLinc only boosts X10 signals. + +## Signal Isolation Steps +When diagnosing issues, the most thorough practice is to isolate which circuit appears to have the most problems. As described above, changing the signal path may help you identify specific circuits that have issues. A more definitive approach is to check circuits individually. Start by turning off all circuits in your house except the one with your Mac and PowerLinc. Make sure that all devices on that circuit work correctly. Then, turn the circuits back on one by one and check all the devices on all active circuits. When you start experiencing failures (no acknowledgements with Insteon), then it's likely that the most recently turned on circuit has something that's causing the noise. You can then start unplugging/disabling devices (air-gap any in-wall switches — for Insteon switches this means pulling the LED pipe below the switch out until it clicks, thus completely removing the power) and other things plugged in until communication seems to improve. + +Repeat this process as necessary until you can isolate the problem areas and devices. + +## Getting More Help +Still having a problem? Perform the following troubleshooting steps and send the results to us in an email, or — to draw on the expertise of the entire Indigo community — post the results on our active [online forum](https://forums.indigodomo.com/). + +1. Choose the **Window → Event Log** menu item. +2. Press the **Clear Window** button at the top of the **Event Log** window. +3. Choose the **Interfaces → Insteon/X10 Power Line → Enable** menu item if it isn't already enabled. +4. From the Main Window select the Devices list and the Device you want to control, then press the **Turn On** and **Turn Off** buttons at the bottom of the window several times. +5. **Question**: Did the module turn on or off? +6. If the Device module is a plug-in type (LampLinc, ApplianceLinc, etc.), then plug it and its lamp/appliance directly into the PowerLinc's passthrough outlet. **Otherwise**, if the Device module is not a plug-in type, then plug the PowerLinc (or CM11) into a different outlet. If needed, use a short extension cord to reach another outlet. +7. From the Main Window select the Devices list and the Device you want to control, then press the **Turn On** and **Turn Off** buttons at the bottom of the window several times. +8. **Question**: Did the module turn on or off? +9. Select the Event Log window, then select all the logged text and copy/paste it into a [forum post](https://forums.indigodomo.com/) or email, along with a description of what occurred while following these steps. diff --git a/reference/canonical/user/troubleshooting/python-conflicts.md b/reference/canonical/user/troubleshooting/python-conflicts.md new file mode 100644 index 0000000..b88a144 --- /dev/null +++ b/reference/canonical/user/troubleshooting/python-conflicts.md @@ -0,0 +1,62 @@ + + +# Python Version Conflicts + +!!! abstract "In this guide" + This page explains why Python version and module conflicts occur when multiple Python installations coexist on your + Mac, and how to ensure scripts and packages use the correct Indigo-managed Python interpreter. + +Over the years, we've seen multiple reports of issues concerning Python modules, Python versions etc. We'd like to clear this up so that when people run across issues you can understand what's going on. + +## Indigo Python Installation +First and foremost - Indigo installs Python as part of the install process. We use the installers from python.org, which install here on your Indigo Server Mac: + +```text +/Library/Frameworks/Python.framework/ +``` + +Inside that directory are the versions that either we have installed (2.7, 3.10, 3.11 etc.) or which might have been installed by you if you downloaded a Python installer from python.org. Which ones are present is based on the Indigo release you're using. Since Indigo 2022.1, Indigo has been using Python 3. + +### Starting up the Python interpreter installed by Indigo +If you need to use the Python interpreter installed by Indigo directly from a command line (or shebang), it's always safest to be explicit in the path to the executable. There are tradeoffs though, so here are the various ways from most specific to least: + +1. `/Library/Frameworks/Python.framework/Versions/3.11/bin/python3` - this is the most explicit way to start up the 3.11 interpreter installed by Indigo. +1. `/usr/local/bin/python3.11` - this is a symlink to the above option, and has the same downside. In addition, though, since it's a symlink in a more public directory, it could get updated by something else entirely. +1. `/Library/Frameworks/Python.framework/Versions/Current/bin/python3` - the downside to this option is that if you (for some reason) install an older version, the installer might update that link to point to the older version. +1. `/usr/local/bin/python3` - this option is created/maintained by the Python installer as well, so it has the same benefits/issues of the last option, but also since it's a symlink it could get munged by some other installer (homebrew/macports). + +### Installing packages using the right pip3 +In the same way discussed above (using the right interpreter), you will find the same options for installing Python packages with **pip**. + +1. `/Library/Frameworks/Python.framework/Versions/3.11/bin/pip3` - this is the most explicit way to start up the 3.11 interpreter installed by Indigo. +1. `/usr/local/bin/pip3.11` - this is a symlink to the above option, and has the same downside. In addition, though, since it's a symlink in a more public directory, it could get updated by something else entirely. +1. `/Library/Frameworks/Python.framework/Versions/Current/bin/pip3` - the downside to this is that if you (for some reason) install an older version, the installer might update that link to point to the older version. +1. `/usr/local/bin/pip3` - this option is created/maintained by the Python installer as well, so it has the same benefits/issues of the last option, but also since it's a symlink it could get munged by some other installer (homebrew/macports). + +## Other Python Installs +So far, we've only discussed Python installations that are performed from the macOS installers available on python.org (which we use from our installer). Problems can arise when you (or some installer you run) installs a different 3rd party version of Python. The three most common sources of a 3rd party Python install are: homebrew, macports, and Xcode. Each will leave the existing Indigo-installed Pythons alone (so Indigo will continue to work), but they will insert themselves in unexpected ways, like by altering the **PATH** in your terminal sessions to point to other locations, unexpectedly replacing symlinks, or my installing into locations that are in your PATH variable before `/usr/local/bin` (making it very dangerous to just open a terminal window and typing in **python** or **pip3**). + +### Xcode +Xcode installs Python 3.9 (as of Xcode 14.2) inside the Xcode application bundle, and inserts these executables **/usr/bin/python3** and **/usr/bin/pip3**. Often times, **/usr/bin** is very early in the PATH so if you don't specify full paths you'll end up getting the wrong python or pip. This is especially troublesome in that if you don't have Xcode installed, and you type just **pip3** in a terminal, it will prompt you to install Xcode and Python 3.9. Buyer beware! + +### homebrew & macports +We believe homebrew and macports install their Python installs under a directory they create called opt (short for optional): + +```text +/opt/local/Library/Frameworks/Python.framework/ +``` + +so it's nice and separate, but it will also likely add items to your **PATH** which will point to these locations for **python3** and **pip3**, so again if you don't specify a full path you might not be getting the right one. + +## Troubleshooting +Each of the different installers mentioned above will do several things: + +They will insert paths into the various `.login`, `.profile`, `.bashrc` files such that their version of Python (and its executables) are found first when typing any of the Python commands from the shell without a full path. They set the **PYTHONPATH** (which is a list of file system paths that the Python interpreter looks in to find modules not part of the standard install like those installed by **pip3**) so that they look in their own site-packages directories + +Let's start with the second one first: they will add their own `site-packages` directories (i.e. `/opt/local/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages`) as well as the one from our Python install (`/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages`) to **PYTHONPATH**. This will, on the surface, make it seem that they're working OK because they're finding things that may have been installed prior to their installation. + +The problem is that when you install further modules using **pip3** (**the one they installed for you** since you didn't specify a full path), those modules will get installed into their site-packages directory rather than the one from our Python install (`/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages`). So anything new you install won't be accessible from the Python that Indigo installs and uses. But when you test from a shell script, using the **python** (*the one they installed for you* since you didn't specify a full path) command, it works. This is because that command isn't using our Python. This duality makes it very confusing to figure out what's going on because it appears to work from a shell but not from Indigo. + +It is possible that you can manage having multiple Python installs - you just have to remember which paths to executables you need to use to get modules installed in the correct place. + +We **highly** recommend that you do not install 3rd party Pythons. This will make sure that your Indigo experience is as painless as possible. diff --git a/tools/refresh_canonical.py b/tools/refresh_canonical.py index 1d3890d..07c369d 100644 --- a/tools/refresh_canonical.py +++ b/tools/refresh_canonical.py @@ -40,8 +40,10 @@ INDEX_URL = "https://docs.indigodomo.com/llms.txt" FULL_URL = "https://docs.indigodomo.com/llms-full.txt" -# Only these top-level doc trees are vendored — the surface the dev/api skills route into. -INCLUDE_PREFIXES = ("api", "plugin-dev", "scripting") +# Top-level doc trees to vendor. api/plugin-dev/scripting back the dev + api skills; +# user/plugins back the general /indigo:guide skill (concepts, interfaces incl. Z-Wave, +# remote access, and the bundled plugins). +INCLUDE_PREFIXES = ("api", "plugin-dev", "scripting", "user", "plugins") SECTION_RE = re.compile(r"^--- (?P.+?) \((?P<url>https?://\S+?)\) ---$") INDEX_LINK_RE = re.compile(r"^- \[(?P<title>[^\]]+)\]\((?P<url>https?://\S+?)\)(?::\s*(?P<desc>.*))?$") From 1cff7d40fbfbe7f45d8471a48ec30682a9963ce7 Mon Sep 17 00:00:00 2001 From: Simon Clark <simon@starmerclark.com> Date: Fri, 10 Jul 2026 07:54:01 +0100 Subject: [PATCH 2/3] feat(guide): add /indigo:guide skill + command for general usage questions New thin router over the vendored user guide + bundled-plugin docs, triggering on Indigo usage/concept/interface questions (Z-Wave associations, reflectors, control pages, triggers/schedules, Apple Shortcuts, SQL Logger, etc.) that the dev/api skills don't cover. Routes into reference/canonical/user/ and /plugins/, anchored to ${CLAUDE_PLUGIN_ROOT}; defers code questions to /indigo:dev and /indigo:api. Cross-link the most relevant pages from existing skills: api -> web-server + reflector (where local-secret/port auth actually lives); control-pages -> the user-facing control-page concept page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Arj5R66d73tc3PMPvHS65Z --- commands/guide.md | 56 ++++++++++++++++++++ skills/api/SKILL.md | 2 + skills/control-pages/SKILL.md | 1 + skills/guide/SKILL.md | 97 +++++++++++++++++++++++++++++++++++ 4 files changed, 156 insertions(+) create mode 100644 commands/guide.md create mode 100644 skills/guide/SKILL.md diff --git a/commands/guide.md b/commands/guide.md new file mode 100644 index 0000000..e2374a9 --- /dev/null +++ b/commands/guide.md @@ -0,0 +1,56 @@ +--- +name: guide +description: Indigo user-guide & concepts expert — devices, interfaces (Z-Wave/Insteon/X10), remote access, bundled plugins +--- + +# Indigo User Guide & Concepts + +**Plugin**: https://github.com/simons-plugins/indigo-claude-plugin +**Slash command**: `/indigo:guide` + +## Description + +Answers general "how does Indigo work" questions — concepts (triggers, schedules, action groups, +conditions, variables, control pages), device interfaces (Z-Wave, Insteon, X10, virtual devices), +remote access (reflectors, web server, SSL, Touch for Web), non-code automation (Apple Shortcuts, +substitutions, event data), install/upgrade/maintenance, and the bundled Indigo plugins. + +**Note**: This is for **using** Indigo. For **building** on it use `/indigo:dev` (plugins), +`/indigo:api` (client apps), or `/indigo:control-pages` (control-page XML). + +## CRITICAL: Context Optimization Strategy + +Reference docs are vendored verbatim from Indigo's published docs under `reference/canonical/` +(generated by `tools/refresh_canonical.py`, pinned to Indigo 2025.2). Load only the page a query +needs — never the whole tree. Start from `reference/canonical/INDEX.md` if unsure. All +`reference/canonical/…` paths are relative to `${CLAUDE_PLUGIN_ROOT}` (this plugin), not the user's project. + +## Query Routing Guide + +| User asks about | Read | +|-----------------|------| +| Triggers / schedules / action groups / conditions | `reference/canonical/user/concepts/{triggers,schedules,actions,conditions}.md` | +| Variables (concept) | `reference/canonical/user/concepts/variables.md` | +| What a control page is / how it works | `reference/canonical/user/concepts/control-pages.md` | +| Managing / installing plugins | `reference/canonical/user/concepts/plugins.md` | +| Z-Wave (pairing, associations, overview) | `reference/canonical/user/interfaces/z-wave.md` (+ `z-wave/{about,associations}.md`) | +| Insteon (devices, links/scenes, PowerLinc, FanLinc) | `reference/canonical/user/interfaces/insteon.md` (+ `insteon/` subpages) | +| X10 devices / RF | `reference/canonical/user/interfaces/x10.md` (+ `x10/rf-options.md`) | +| Virtual devices | `reference/canonical/user/interfaces/virtual-devices.md` | +| Remote access / reflector / web server / SSL | `reference/canonical/user/remote-access/{reflector,web-server,ssl-certificates,touch-for-web}.md` | +| Apple Shortcuts / substitutions / event data | `reference/canonical/user/automation/{apple-shortcuts,substitutions,event-data,get-contents-of-url}.md` | +| Install / upgrade / move / uninstall Indigo | `reference/canonical/user/getting-started.md`, `reference/canonical/user/maintenance/{upgrading,moving,uninstalling,license-transfer}.md` | +| Mac client UI (event log, home window, menus) | `reference/canonical/user/mac-client.md` (+ `mac-client/` subpages) | +| Python version conflicts / powerline signal | `reference/canonical/user/troubleshooting/{python-conflicts,powerline-signal-troubleshooting}.md` | +| A bundled plugin (SQL Logger, Email+, NOAA, Timers & Pesters, Alexa, Global Property Manager, Airfoil, EasyDAQ) | `reference/canonical/plugins/*.md` | + +## Routing notes + +- Repeated **SQL Logger** device-history errors → use `/indigo:debug-sqllogger` (guided fix), not just the reference page. +- Anything about *writing* code (plugin callbacks, the `indigo.*` object model, API command messages) → `/indigo:dev` or `/indigo:api`. + +## Related Commands + +- `/indigo:dev` — Plugin development +- `/indigo:api` — Client-side API integration +- `/indigo:control-pages` — Control page builder diff --git a/skills/api/SKILL.md b/skills/api/SKILL.md index 3f16d76..a941200 100644 --- a/skills/api/SKILL.md +++ b/skills/api/SKILL.md @@ -93,6 +93,8 @@ Vendored verbatim from Indigo's published docs. Read relative to `${CLAUDE_PLUGI | WebSocket API (feeds, refresh, patches) | `reference/canonical/api/websocket.md` | | Webhooks (receiving external events) | `reference/canonical/api/webhooks.md` | | Migrating from the old REST API | `reference/canonical/api/rest-migration.md` | +| Server auth setup: local secrets, ports, Start Local Server dialog | `reference/canonical/user/remote-access/web-server.md` | +| Reflector (remote access over the internet) | `reference/canonical/user/remote-access/reflector.md` | | Full canonical index (all pages) | `reference/canonical/INDEX.md` | ## Full Documentation diff --git a/skills/control-pages/SKILL.md b/skills/control-pages/SKILL.md index f9fcfd1..f093b03 100644 --- a/skills/control-pages/SKILL.md +++ b/skills/control-pages/SKILL.md @@ -81,6 +81,7 @@ For detailed guidance, read these files relative to `${CLAUDE_PLUGIN_ROOT}`: | Screen sizing | `docs/control-pages/layouts/sizing.md` | | Layout templates | `docs/control-pages/layouts/templates.md` | | Clipping export | `docs/control-pages/export/clipping-export.md` | +| Control pages — the user-facing concept | `reference/canonical/user/concepts/control-pages.md` | ## Full Documentation diff --git a/skills/guide/SKILL.md b/skills/guide/SKILL.md new file mode 100644 index 0000000..3e3e783 --- /dev/null +++ b/skills/guide/SKILL.md @@ -0,0 +1,97 @@ +--- +name: guide +description: >- + This skill should be used for general Indigo home-automation usage and concept + questions that are NOT about writing plugin or client code — e.g. "how do Z-Wave + associations work", "connect a Z-Wave / Insteon / X10 device", "set up a reflector", + "access Indigo remotely", "what is a control page", "how do triggers / schedules / + action groups / conditions / variables work", "use Apple Shortcuts with Indigo", + "variable substitutions", "upgrade Indigo", "move Indigo to a new Mac", or questions + about a bundled Indigo plugin (SQL Logger, Email+, NOAA Weather, Timers & Pesters, + Alexa, Global Property Manager). Routes into the vendored Indigo 2025.2 user guide and + bundled-plugin docs. For building plugins use /indigo:dev; for client API integration + use /indigo:api. +--- + +# Indigo User Guide & Concepts + +Answers general "how does Indigo work" questions from the **vendored canonical user guide and +bundled-plugin docs** under `reference/canonical/` (generated by `tools/refresh_canonical.py`, +pinned to Indigo 2025.2). Load only the page a question needs — `reference/canonical/INDEX.md` +lists every page. All paths below are relative to `${CLAUDE_PLUGIN_ROOT}`. + +This skill is for **using** Indigo. For **building** on it: plugins → `/indigo:dev`, client apps +(WebSocket/HTTP) → `/indigo:api`, control-page XML → `/indigo:control-pages`. + +## Core concepts (what things are and how they behave) + +| Topic | File | +|-------|------| +| Actions & action groups | `reference/canonical/user/concepts/actions.md` | +| Triggers | `reference/canonical/user/concepts/triggers.md` | +| Schedules | `reference/canonical/user/concepts/schedules.md` | +| Conditions | `reference/canonical/user/concepts/conditions.md` | +| Variables | `reference/canonical/user/concepts/variables.md` | +| Devices (user view) | `reference/canonical/user/concepts/devices.md` | +| Control pages (concept) | `reference/canonical/user/concepts/control-pages.md` | +| Managing plugins | `reference/canonical/user/concepts/plugins.md` | +| Deletion dependencies | `reference/canonical/user/concepts/deletion-dependencies.md` | +| Glossary | `reference/canonical/user/glossary.md` | + +## Device interfaces / protocols + +| Topic | File | +|-------|------| +| Z-Wave — managing devices | `reference/canonical/user/interfaces/z-wave.md` | +| Z-Wave — technology overview | `reference/canonical/user/interfaces/z-wave/about.md` | +| Z-Wave — association management | `reference/canonical/user/interfaces/z-wave/associations.md` | +| Insteon — managing devices | `reference/canonical/user/interfaces/insteon.md` (+ `insteon/` subpages: PowerLinc, FanLinc/KeypadLinc, links/scenes) | +| X10 — connecting interfaces | `reference/canonical/user/interfaces/x10.md` (+ `x10/rf-options.md`) | +| Virtual devices | `reference/canonical/user/interfaces/virtual-devices.md` | + +## Remote access + +| Topic | File | +|-------|------| +| Reflectors (remote access service) | `reference/canonical/user/remote-access/reflector.md` | +| Indigo Web Server (auth, local secrets, ports) | `reference/canonical/user/remote-access/web-server.md` | +| SSL certificates | `reference/canonical/user/remote-access/ssl-certificates.md` | +| Indigo Touch for Web | `reference/canonical/user/remote-access/touch-for-web.md` | + +## Automation & integration (non-code) + +| Topic | File | +|-------|------| +| Apple Shortcuts | `reference/canonical/user/automation/apple-shortcuts.md` | +| Event data passing | `reference/canonical/user/automation/event-data.md` | +| Substitutions (`%%v:…%%` etc.) | `reference/canonical/user/automation/substitutions.md` | +| Get Contents of URL | `reference/canonical/user/automation/get-contents-of-url.md` | + +## Install, maintain, upgrade + +| Topic | File | +|-------|------| +| Getting started / installation | `reference/canonical/user/getting-started.md` (+ `getting-started/` subpages) | +| Upgrading Indigo (breakage, Python) | `reference/canonical/user/maintenance/upgrading.md` | +| Moving to another Mac | `reference/canonical/user/maintenance/moving.md` | +| Uninstalling / license transfer | `reference/canonical/user/maintenance/{uninstalling,license-transfer}.md` | +| Mac client UI (event log, home window, menus) | `reference/canonical/user/mac-client.md` (+ `mac-client/` subpages) | +| Troubleshooting (Python conflicts, powerline signal) | `reference/canonical/user/troubleshooting/{python-conflicts,powerline-signal-troubleshooting}.md` | + +## Bundled plugins + +| Plugin | File | +|--------|------| +| SQL Logger | `reference/canonical/plugins/sql_logger.md` | +| Email+ | `reference/canonical/plugins/email.md` | +| NOAA Weather | `reference/canonical/plugins/noaaweather.md` | +| Timers & Pesters | `reference/canonical/plugins/timersandpesters.md` | +| Global Property Manager | `reference/canonical/plugins/globalpropertymanager.md` | +| Alexa (Smart Home / custom skill) | `reference/canonical/plugins/alexa.md` (+ `alexa/` subpages) | +| Airfoil Pro · EasyDAQ | `reference/canonical/plugins/{airfoilpro,easydaq_1}.md` | + +## Routing notes + +- Debugging repeated SQL Logger device-history errors specifically → use `/indigo:debug-sqllogger` (guided fix), not just the reference page. +- Anything about *writing* code (plugin callbacks, the `indigo.*` object model, API command messages) belongs in `/indigo:dev` or `/indigo:api`, not here. +- When unsure which page, scan `reference/canonical/INDEX.md` and open the single closest match. From f63539892facbb122802f63df17b943023bc650e Mon Sep 17 00:00:00 2001 From: Simon Clark <simon@starmerclark.com> Date: Fri, 10 Jul 2026 07:54:01 +0100 Subject: [PATCH 3/3] chore(release): bump to 2.1.0 Minor: new /indigo:guide skill + expanded canonical (user guide + bundled plugins). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Arj5R66d73tc3PMPvHS65Z --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 17ac612..ade69c9 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": "2.0.0", + "version": "2.1.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 d7b589f..40111d4 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "indigo", - "version": "2.0.0", + "version": "2.1.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" }