Indigo Pro and AppleScript

Update: AppleScript that targets the Indigo Server (tell IndigoServer) is no longer supported in Indigo 7.4 and beyond. To write scripts that interact with Indigo objects, you must use Python. The best place to start is with the Indigo and Python wiki page.

The rest of this article is left here for users of Indigo 7.3 and earlier.

Note: This article was written before Indigo 5 so there is no mention of Python Scripting. While all of the information in this article still applies to Indigo 5 and beyond, if you're new to Indigo we recommend learning Python Scripting instead as it is more full-featured - see the Python Scripting Tutorial for more information. If you need to communicate with other Mac applications then AppleScript is probably still the best way to go.

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. So, allowing Indigo Pro to be scripted via AppleScript (Mac OS X's native scripting language), allowing Indigo Pro to be extended via attachment scripts, and allowing Indigo Pro to execute AppleScripts gives users the ability to fill in functionality that they need for their particular environment. If you're interested in learning more about AppleScript, we'd suggest AppleScript: The Definitive Guide, 2nd Edition by Matt Neuburg. It's a very good overview and reference in one book. If you're new to AppleScript, some of the descriptions below may be foreign to you, but we've tried to make this description as high-level as possible while offering the information thats necessary to start scripting Indigo Pro.

First, let's talk about scripting Indigo Pro. Because Indigo is a client/server application, you won't be scripting the client - rather, you'll be scripting the Indigo server application, called appropriately enough “IndigoServer”. That will be the target of your tell statements. Almost everything you can do in the Mac client UI can be done through AppleScript. One look at the AppleScript dictionary and you'll see pretty much everything is there. And, what's not there will most likely be added as soon as we hear someone needs that functionality. So, you can use scripts to create objects, get/set object properties and delete objects, 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 AppleScript, you can solve problems in ways that we've never considered.

Next, let's talk a little about attachment scripts. AppleScript functions, called handlers, can be defined as standalone functions that are available to any script that's talking to Indigo. So, for instance, we include a script called “iTunes attachment.scpt”. This is an attachment script: it defines a bunch of handlers that allow Indigo to talk to and control to iTunes. So, if you want to define a trigger on a button press that toggles iTunes play/pause, you can just type “iTunesPlayPause()” into the Embedded: field in the Actions: tab (or an Action Group) when the Type: is Execute AppleScript. When that button is pressed, iTunes will either play or pause based on it's current state. If you take a look at that attachment script, you'll see that it does a bunch of work under the hood for you: it maintains state, it wraps all the calls to iTunes in timeouts so that the server isn't impacted if iTunes is having an issue or is busy (see the next section for a description of that), etc. And, other people can create attachment scripts and share them via the user contribution library - there are already quite a few there. Scripts that are placed in the /Library/Application Support/Perceptive Automation/Indigo 5/Scripts/Attachments/ folder will automatically be loaded when the IndigoServer starts up.

Finally, there are 2 ways to have Indigo Pro execute an AppleScript: embedded or external. Both have advantages and disadvantages, so we'll describe them in some detail here. Embedded AppleScripts are scripts that are typed in to the Embedded: field in the Actions: tab (or an Action Group) when the Type: is Execute AppleScript. Scripts typed in here are stored within the current database file, and are executed within the IndigoServer itself. This makes them pretty much encapsulated, so you don't have to worry about moving script files around, etc. The downside is that the architecture of AppleScript requires scripts to be executed in the main thread of the application - this means that if an AppleScript takes a long time to execute, NOTHING else in the server will process until it's finished. That's why we've taken considerable care when crafting timeout values in the iTunes attachment script (and others that talk to resources outside of Indigo) - if iTunes becomes unresponsive (for instance, if it's trying to rip a CD), then any script thats trying to talk to it might hang up until it becomes free. This would effectively stop the IndigoServer from doing any other processing. Our recommendation is that you try to avoid running scripts that talk to other applications as embedded scripts unless you're sure that appropriate “with timeout” statements are in place.

The other way for Indigo Pro to execute an AppleScript is as an external script. When you select the File: radio button in the Actions: tab (or an Action Group) when the Type: is Execute AppleScript, you'll be able to choose an AppleScript file. This file must reside on the server machine, and be saved in the compiled script format (the default format for Apple's Script Editor). When this action is executed, IndigoServer will start the script up in a separate process - this allows scripts to do pretty much anything they want - the “iTunes Sync.scpt” file loops forever - every 3 seconds it queries iTunes for it's current state and puts those value into Indigo variables for use by anything else in Indigo, and display on control pages, etc. And, because it's running in another process, the fact that the script never finishes executing doesn't effect the server at all. The only interaction is when the script tells the IndigoServer to update the variable values, and that happens very quickly. The downside is that the script files are separate and must be managed and edited outside of Indigo.

Check out the AppleScript Snippit page for bits of code that others have found useful.