Indigo Extensibility and Python

Indigo has a very rich set of functionality: flexible scheduling and triggering, broad device support, an excellent UI abstraction (if we do say so ourselves). However, because we're just the software that glues all of these hardware devices (and, in fact, other software) together, it's impossible for us to support every device, every protocol, natively and in a timely manner. That's why we created a mechanism for 3rd party developers to build sophisticated plugins to integrate other products and services. So there are often plugins available that will solve many scenarios that aren't covered directly in Indigo.

However, we know that even this level of extensibility won't cover all user scenarios, so we provide a very sophisticated scripting environment. Indigo uses the Python programming language (v2.7 currently) for scripting and plugin development. We chose Python because it's widely used (3rd most used programming language on the planet at the time of this writing) and therefore there are a lot of resources for people using it: quality tutorials, easy to find answers to questions, and a boatload of packages (Python speak for libraries) to do a very wide variety of things.

Because Indigo is a client/server application, you won't be scripting the client, as you might expect (i.e. AppleScript with other apps) - rather, you'll be scripting the Indigo server (which is a faceless background application). Scripts will be executed by the Indigo server and will have access to the objects that the server presents (devices, variables, etc). For example, you can use scripts to create variables, get/set properties, delete devices, control objects (turn lights on/off, enable/disable triggers and time/date actions), etc. Why? Because we'll never be able to anticipate your every need, nor should we even try. Using Python and the Indigo Object Model, you can solve problems in ways that we've never considered.

If you have experience with some other programming language, then you've got a leg up. If you've only used AppleScript before, then you'll likely want to get some help with the basics of Python. We recommend this as a learning order for writing scripts:

1. If you want an overview of Python concepts and syntax (recommended), do a Python tutorial (like this one) - there are many out on the internet
2. Next, check out the Indigo Scripting Tutorial, which will get you doing neat things with Indigo very quickly
3. Once you're familiar with the basics, check out the full Indigo Object Model Reference for the details on how to do more complex scripts

Many of our customers are familiar with AppleScript, but are less familiar with Python. With AppleScript, you normally use the Script Editor app that ships with macOS to edit AppleScripts. With Python, you can use any app that allows you to edit simple plain text files (text with no markup). The TextEdit app will do this, though to start a new text-only document you should create a new document in TextEdit then immediately select the Format→Make Plain Text menu item before you save it. This will make sure the script is just simple text that can be propertly executed.

Most users, however, will opt for a Mac-based text editor that is created specifically to write scripts/programs. There are a variety out there, but these are the most popular:

• BBEdit - this editor has been the most popular editor on the Mac for 25+ years. There is a very capable free version, with a commercial version ($50) that adds power-user features.
• Sublime Text - another great editing option, though there isn't a free version ($80). There is a trial however.
• PyCharm - this is actually a full-blown Integrated Development Environment (IDE) which is great for developing plugins (Professional Edition). However, there is a free Community Edition which will work for just writing scripts, just note that it's a bit more complex to use because it's a full IDE and not just text editor.

There are others out there as well - the most important point is that the file must be a “plain text” file - i.e. no markup or special formatting (like a Word doc). The same applies if you're editing your script from Windows (or Linux, or somewhere else).

In Indigo, you can have either embedded scripts, where the script code goes directly into the Mac UI, or run as a script file, where you point the Mac UI to the python script file (always end python scripts in .py, i.e. my_script.py) that you want to be executed. Often, the latter method is better since embedded scripts have some constraints (they can't run longer than 10 seconds) that scripts executed as files don't have (they can run forever).

TODO

Another thing that AppleScript users may be familiar with are Attachment Scripts. This allows a script writer to share AppleScript handlers between scripts. You can do the same with Python. Python functions and classes may be shared between your scripts easily because Python has a well defined way of making scripts and the objects they define available to other scripts, and Indigo (v7.4.1+) provides a simple location for you to place scripts that define functions and other objects that you want to share across your scripts:

/Library/Application Support/Perceptive Automation/Python2-includes/

Any Python file that you put in this directory will be available to any Python script executed by Indigo.