I've decided that rather than hack up more applescript to help control my pool system, the right way to do this would be to create a plugin and then I can have all of the pool equipment set up as devices and report their states, etc...

Given that it's a simple serial device, and there's already a script for controlling some sort of serial relays, I figure this will be as hard as taking that old script, setting it up to send and receive a different set of commands, having it interface with Indigo slightly differently, and then a whole bunch of text parsing in between to make it work (Is this obvious programmer noob talk?). I'm sure in practice it will be much trickier than that, particularly since my 'programming experience' currently consists of some simple Applescripts.

Now my question: I saw in the Serial Bridge/Jandy thread where Jay says that basically a plugin is just a bundle full of text files that are XML and python code and you can edit it with any text editor. Is there a simpler guide than this? Is there a place that says what file does what, and also, is there some sort of environment where I can test code, check its syntax, log outputs etc... (I'm thinking of something analogous to AppleScript Editor here. without having that thing log a bunch of intermediate steps and stuff I never would have been able to debug and get my current scripts working).

Thanks.

Swancoat wrote:I saw in the Serial Bridge/Jandy thread where Jay says that basically a plugin is just a bundle full of text files that are XML and python code and you can edit it with any text editor. Is there a simpler guide than this? Is there a place that says what file does what, and also, is there some sort of environment where I can test code, check its syntax, log outputs etc... (I'm thinking of something analogous to AppleScript Editor here. without having that thing log a bunch of intermediate steps and stuff I never would have been able to debug and get my current scripts working).

That post you read of mine was an answer to a specific question about editing a plugin - I didn't mean to imply that's all there was in terms of documentation. There is a TON of documentation on how to script using the Python IOM as well as how to build a Server Plugin at the bottom of the Documetation page.

Also, by selecting "Open Scripting Shell" from the "Plugins" menu, you'll have a terminal window opened on an interactive Python shell that has full access to Indigo (which is also discussed in the scripting tutorial). In that shell, you can try pretty much any IOM object or command interactively. The tutorial, while not nearly complete yet, should be a great way to get started experimenting.

Swancoat wrote:Given that it's a simple serial device, and there's already a script for controlling some sort of serial relays, I figure this will be as hard as taking that old script, setting it up to send and receive a different set of commands, having it interface with Indigo slightly differently, and then a whole bunch of text parsing in between to make it work (Is this obvious programmer noob talk?). I'm sure in practice it will be much trickier than that, particularly since my 'programming experience' currently consists of some simple Applescripts.

Here's a suggestion, first read up on Python....

This is the Python v2.54 tutorial, which I highly recommend... I wouldn't start with later versions, simply because v2.5x is the version Indigo is designed to work with...

http://docs.python.org/release/2.5.4/tut/tut.html

Get comfortable with Python, and then read the Indigo 5 Scripting Tutorial...

http://www.perceptiveautomation.com/wik ... g_tutorial

That covers basic Python coding in the Interactive Script Window.

If you decide that you want to progress into developing your own plugins, the Indigo Plugin Developer's Guide covers everything you have asked about... What are the XML files, and the structure of a plugin, etc...

http://www.perceptiveautomation.com/wik ... ugin_guide

While there are "Fix Me!" tags in the Documentation, most of the big issues have been expanded on and revised at this point.
The main issue here, is since the application is still in Beta, there still sections that might change... But as they get closer to general release, the odds of this go way down...

I'm plowing ahead with this thing. So far, I'm just looking at config boxes, etc...

If I write the PluginConfig.xml part of my plugin, how exactly to I see how that's going to look? Right now I'm thinking: Save it. Drop a copy into Indigo's Disabled Plugins, and then head into Indigo to enable it and see what comes up?

Is this as risky/foolish as it sounds? Is anything really going to blow up here if I don't create a device or anything?

On one hand it certainly seems unwise to just 'test it' by trying it out live in my Indigo setup, but on the other hand... there's no actual *code* in there that I'm calling on...

You don't really even need to disable it - just put it in the plugins folder. If it can't load it propertly it will just toss errors into the event log. You can edit it in place (while it's in the Plugins folder) then just do a Reload which will force it to completely reload. It won't do anything to the rest of the server since plugins run in their own process space.

SWEET!, so even when I start mucking with Python code, I can basically: Save. Reload. and see what happens?

Worst case scenario is some 'process' crashes?

Yep, it's pretty safely sandboxed.

I suppose if you created a tight loop where it was querying the server repeatedly you could cause the server to become unresponsive - but thats less likely than, say, creating an infinite loop in an embedded AppleScript.

Sorry for all the noob questions (Hopefully they become less frequent)...

I'm trying to use the visible binding ID to have a bunch of fields hidden by default, but if I uncheck a checkbox, they show up. Unfortunately, they just don't show up, regardless of what I do with the checkbox.

Is this set up right?

Code: Select all

   <Field type="checkbox" id="factorydefaults" defaultValue="yes">
      <Label>Factory Default Command Characters:</Label>
      <Description>(Recommended)</Description>
   </Field>
   
   <Field type="label" id="factorydefaultsdesc" visibleBindingId="factorydefaults" visibleBindingValue="0">
      <Label>If the command character set on your Protocol Interface Adapter has been altered from factory defaults for any reason, you can set the values here to match the altered settings.</Label>
   </Field>

Sorry, the docs are wrong. Use "true" or "false" for the visibleBindingValue rather than 0 or 1. In fact, the defaultValue for a checkbox can also be "true" or "false".

I'm still reading up on how to do this. Between some Python tutorials, the Indigo Plugin Guide and the Python code for the EasyDAQ, I think it's slowly sinking in, but I've got some questions.

The first thing I did was get the PluginConfig.xml and Devices.xml written (relatively straightforward. I'll probably have to change them in the future, but I currently don't feel 'mystified' about what's going on here). I don't have anything for Actions.xml or MenuItems.xml, but from what I can tell, they're not really necessary.

So on to the plugin.py piece. I'm suspicious that the EasyDAQ isn't the best for learning, because it's a bit more complex and has a recursive element that lets you modify the device config pages, but ultimately, it controls a serial device, which is what I want to do so that's where I started.

First of all, I notice that the EasyDAQ module also has easydaq.py which is referenced in plugin.py. Is there any particular reason for this (my reasoning is that it just breaks the complexity into smaller pieces)? Any reason why it couldn't just be one file?

Secondly, is there some sort of 'dev' class that has things like pluginProps and stuff like that in it. I see it referenced in the easydaq.py, and it appears it uses ids from devices.xml, but I guess I don't really understand where the connection comes from. Is there a missing piece of documentation? Or do I just have more learning to do?

The EasyDAQ plugin should be a good example for you. The only thing that is a bit custom for it is the Actions panel XML UI is dynamically generated at runtime instead of being stored statically in the .xml file. But if you ignore getActionConfigUiXml() and the methods it calls (_xmlAddHiddenDescField, _xmlAddStaticLabelForInput, _xmlAddMenuFieldForOutput, _xmlAddListOptionItems) then it should be a good base example.

Swancoat wrote:First of all, I notice that the EasyDAQ module also has easydaq.py which is referenced in plugin.py. Is there any particular reason for this (my reasoning is that it just breaks the complexity into smaller pieces)? Any reason why it couldn't just be one file?

There is no reason it had to be broken into multiple files. I just wanted all of the hardware specific communication to be in its own file (easydaq.py).

Swancoat wrote:Secondly, is there some sort of 'dev' class that has things like pluginProps and stuff like that in it. I see it referenced in the easydaq.py, and it appears it uses ids from devices.xml, but I guess I don't really understand where the connection comes from. Is there a missing piece of documentation? Or do I just have more learning to do?

In most places in the source "dev" is just a local argument/variable that is pointing to a specific device instance object that is representing the Indigo EasyDAQ device being operated on. Meaning, it is just an instance like you would get if you did:

Code: Select all

dev = indigo.devices[someDeviceID]

So all of the attributes/methods called on it (like pluginProps, name, deviceTypeId, etc.) should be defined in the Indigo Object Model documentation for devices. If you find something missing, then let us know and we'll get it documented for you.

Ok, I've read thy EasyDAQ example many many times, and I think I've started to turn the corner. I think I'm following the basic logic at this point. In my view, part of the complexity comes from the fact that for the Plugin, each 'device' is a separate piece of hardware running on its own serial port, and can be one of several models (each with several possible inputs or outputs) all adding to the complexity.

Given that my pool automation interface is one piece of hardware (and my 'devices' will just be variations of commands on it) I figure I can open/close the serial port under runConcurrentThread. (Tell me if I'm getting off track here).

As for the main process, I figure I'd set a loop that reads from the serial port, parses the output and passes it to whatever device, and then moves on to check if there's anything in a waiting 'command queue', and if there is, sends it and restarts the loop. I *think* this is what you guys are doing too... but this is where I'm getting lost.

How does Indigo talk to the plugin. i.e. If I turn a device on from my computer, how does that command hit the plugin so I can add it to the queue?

(Also, what the heck is with the 'Queue' module you guys import. I figure I can do it with just a list, but seeing a separate module makes me think it can get a lot more complex than that...)

Should I start a separate Pentair Pool thread for this? I've basically decided I'm going to do it at this point...

Thanks!

Hmm. I'm not sure I'm following your design. In the case of the EasyDAQ, each physical board corresponds to an Indigo device - one of the properties of the device is the serial port it's connected to, but there is a 1:1 mapping.

There are other examples where that mapping doesn't make sense, but we believe those are the minority. So, I'm not sure what you mean by "Given that my pool automation interface is one piece of hardware (and my 'devices' will just be variations of commands on it)". Unless your pool interface can support multiple different devices I'm not sure that's the approach you want to take.

Seems more like your pool interface is just a single device, with multiple states (lights, pump, etc) and commands which operate on the iterface (turn on/off the lights, turn on/off the pump, etc). Maybe I'm not seeing the full capability of the interface though. If, for instance, the interface supports a variable number of lights (each of which can be identified individually somehow), then perhaps your method is better. Determining this will definitely effect how you implement it.

If you go with your current design (a single interface with multiple devices) then your approach is about right. When your plugin starts up, it will get the serial port from the plugin settings (since there will be only a single port that every device defined by the plugin uses) and open it. Then, in the runConcurrentThread method, you'd loop as you describe reading from the serial port and writing commands.

Note - this is not how the EasyDAQ plugin works because it takes the other approach - a 1:1 mapping of serial port to device. Each device executes in it's own thread (and has yet another thread to handle the actual serial communication). It does use roughly the same loop methodology - get bytes from the port and do stuff then check the outgoing Queue for commands. The Queue object is a thread-safe queueing mechanism - so one thread is adding to the Queue and a different thread is removing stuff from the Queue. If the thing that's adding to the list is running in the same thread as the thing that's consuming the things on the list then you don't need a Queue.

Some clarification on the pool controller:

The pool controller is a big box with a serial connection. It controls the pool pump, the water feature pump, the pool lights, a yard light, and outdoor fireplace (and can control more things with more relays). I would like to consider the yard light a 'device' in my interface as opposed to a state of the pool controller as a whole. This also makes sense to me in that it's conceivable that you may connect more than one EasyDAQ (and hence need to configure the serial port at the device level), but it's unlikely you'll have more than one pool controller per Indigo setup (so one serial port config at the plugin level is not going to constrain anyone).

Basically, the serial commands are simple enough that turning on the yard light looks like #AUX5=1 ( =0 to turn off). My intent is to have the user select which AUX circuit when they configure their device. Similarly the controller reports states of various things back to the serial port. So if I turn on the water feature using the pool controller's built-in control, it will return something like !00 AUX8=1 which I will then read, parse and pass to Indigo.

I think I'm going to need to read more about this Queue module I think I will be adding and removing from the queue in different threads (although to be frank, I barely understand what a 'thread' really means). Is there some documentation on this?

Now how do commands get INTO the queue? When you change a device state in Indigo does it call a method of some sort? (I see the documentation for deviceUpdated, but I'm unclear for if that's a device merely having its state changed, or if it's actually being reconfigured in some way - as you can see, I'm really only understanding the very basic flow of the plugin right now. I need to do a LOT of work to understand the details.

Thanks for all the help!

So, right - given this arrangement I think I'd take the 1:1 approach - the plugin talks to 1 pool controller (since it's highly unlikely you'd have multiple). So you'd configure the serial connection in the Plugin's ConfigUI. You'd do the serial communication through some queueing mechanism in the runConcurrentThread loop. At least, off the top of my head, that's probably what I'd do.

The runConcurrentThread loop would do 2 things. First, it would probably cycle through some list/queue of commands to send out to each device. These commands would be received from the Indigo server. When you define Actions in your plugin, you specify a method that's called for that action. Inside that method, you would add the command to the Queue of commands to execute the next time the run loop gets to that point. Then, in the run loop, you'd cycle through all the commands in that Queue and send the appropriate serial commands (and, as a optimization, update the state on the server - see below).

The second thing it would do would be to poll each device to see if the state changed (if you updated the state on the server as mentioned above you might could skip those devices). When you get the current state(s) of each device, you'd update any changed states on the server (pool pump changed to off, lights went on, etc.) using updateStateOnServer(). A description of that is found in the discussion of Custom Device States.