Common Cynical Plugin Features

Common Cynical Plugin Features #

The Cynical Plugins are built on a shared foundation (a Python module called cyin). They therefore share a set of common features and behaviors that are consistent across them all. This is where we document them.

Plugin Configuration #

Configuration Settings #

Setting Value Description
Debug checkbox Enable verbose logging in a plugin.
Debug Modules string Enable debug features in the named submodules.

Cynical plugins are fairly reserved when it comes to writing to Indigo’s log. You will see error messages and messages explicitly put there by your code, but that’s about it. If you want your plugin to be chatty and provide a running commentary on its function, then the Debug checkbox is for you.

Once you checked Debug, the Debug Modules configuration setting appears. If you report a problem, I may give you a magical string to put there to generate more logging to help me solve your problem. Otherwise, you should probably leave this alone. If you’re curious, it’s a comma-separated list of Python module names with DEBUG hooks. Don’t worry; putting something silly there won’t hurt.

Keepalive #

Under normal circumstances, Cynical plugins won’t talk to your devices unless they have something to say. This means that if you don’t ask Indigo to do anything to a device, we may not talk to it for hours on end. This is usually a good thing, because there’s no point in clogging up your network for no good reason. But it also means that if your network fails, or the device gets into trouble and stops communicating, we won’t find out until we actually try to talk to it again. (This often happens first thing in the morning when you’re in a hurry.) If the plugin does notice a problem, it will always attempt to reset the connection and restart the device, and you will see error messages in the Indigo log saying so.

Many Cynical devices have a Keepalive checkbox in their configuration. If you enable this feature, the plugin will make sure to talk to its hardware once in a while (typically every 10 minutes) even if it only says, “Hi, how are you?” This means that mysterious disconnects will be detected soon after they happen, and the device will have been reset and hopefully be ready for you by the time you actually want something from it.

Keepalive isn’t just for network connections, either. Even serial line protocols can benefit from this as long as the serial protocol has a way to request a reset of the connection (say, a break condition or reset command). The same general ideas apply equally.

Do Script Action #

This action runs some arbitrary Python code. It functions similarly to Indigo’s standard Execute Script action.

Configuration Settings #

Setting Value Description
Script string The Python code to execute.
Device device A device that becomes the device variable available in the code.

Why not just use Indigo’s native run script action, then? After all, it offers a multi-line input field (which sadly plugins cannot have at this time). It is a difference in perspective. An Indigo script action runs in the context of the Indigo Plugin Host, which is essentially a separate plugin. It has access to Indigo and its state, but no specific knowledge or access to any particular plugin. The Do Script action of a Cynical Plugin, on the other hand, runs inside the plugin and has direct access to the internals of a plugin - it executes a plugin formula .

This action will accept arbitrarily long scripts. If you need to type more than a line or two, you will want to write it elsewhere and then paste it into the sad single-line field that is the only text input means Indigo provides for plugins at the moment. Please, feel free to complain about that to the Indigo maintainers.

The optional Device field lets you choose any device managed by the plugin you send this action to (and only those), and that device becomes directly accessible to the script under the name device.