Plugin Developer Documenter Plugin

Posted on
Thu May 28, 2015 10:23 am
RogueProeliator offline
User avatar
Posts: 1852
Joined: Nov 13, 2012
Location: Baton Rouge, LA

Plugin Developer Documenter Plugin

Quick Download: Plugin

Introducing the Plugin Developer Documenter Plugin
This Indigo 6.0+ plugin allows plugin developers to examine and follow the lifecycle of calls that are available when developing an Indigo Plugin. The plugin is meant as a demonstration and learning tool for both new and experienced developers alike -- I learned a few new things just in doing this exercise, as was the point.

I have tried to thoroughly document the plugin's code so that you may easily follow what is going on and how to use a feature/callback in your own plugin should you find the need. I have attempted to document in the code where you must be sure to call the base class implementation lest you inadvertently break the lifecycle.

Usage
The plugin, by default, will simply log each function call / event that is executed within the plugin. To see the order of events simply use the plugin - create a new plugin device, open/close dialogs, press buttons within the dialogs, etc. This level of logging is fairly low since, as long as you are not actively using the plugin and devices, there are not many function calls.

If you want more details, you may turn on additional logging options in the plugin configuration dialog -- such as the parameter values for each of those function calls. Be warned, though, this will dump a LOT of data to your log when things such as devices are passed in to routines. You will want to use this when learning/debugging and then shut it off for normal use.

The plugin also demonstrates, and logs, the calls that you may receive when other Indigo objects (outside of your plugin) change, such as variables. These options may be turned on and off from the plugin configuration dialog as well. There is no way to unsubscribe to these changes, so when you are ready to stop subscribing to, say, all Indigo Variable changes, you will need to uncheck this box, save the change and then reload the plugin.

Plugin Devices / Dialogs
The plugin defines a single, custom device type and a nonsense device configuration just to demonstrate the various options that affect the lifecycle of the plugin. You will want to create one of these in order to view the lifecycle of calls around creation, starting, configuring, etc. a device. This device supports a couple of actions, again meant to allow you to trace the lifecycle that occurs when a plugin action executes.

A single event is also available that will allow you to examine how to create, register and execute custom Events and what that lifecycle entails.

Review / Improvement / Modification
If anyone sees anything missing from the documentation and plugin, some incorrectly documented information or has any other suggestions for improvement then please let me know! I will leave this thread open for discussion since I don't anticipate announcements of changes being a particularly big deal for this due to its intended audience.

I fully expect developers to take this plugin and change it to their needs or even use it as a basis of other plugins when learning or trying out new features... feel free to do so!

UPDATES
v1.1 - 5/29/2015
  • Added population of the Address column in the device listing
  • Added line numbers to debug output
  • Added a Queue to handle asynchronous command / communication with the background thread

Posted on
Thu May 28, 2015 10:33 am
jay (support) offline
Site Admin
User avatar
Posts: 13623
Joined: Mar 19, 2008
Location: Austin, Texas

Re: Plugin Developer Documenter Plugin

Cool!

Jay (Indigo Support)
Twitter | Facebook | LinkedIn

Posted on
Thu May 28, 2015 10:36 am
howartp offline
Posts: 2963
Joined: Jan 09, 2014
Location: West Yorkshire, UK

Re: Plugin Developer Documenter Plugin

Thanks Adam - will play tonight!

Posted on
Thu May 28, 2015 12:36 pm
kw123 offline
User avatar
Posts: 5144
Joined: May 12, 2013
Location: dallas, tx

Re: Plugin Developer Documenter Plugin

great overview... one question:

what does "super(Plugin, self)....." do? .. and how would you do this without the super constructor? shows my python limits..


Karl

Posted on
Thu May 28, 2015 12:47 pm
howartp offline
Posts: 2963
Joined: Jan 09, 2014
Location: West Yorkshire, UK

Re: Plugin Developer Documenter Plugin

It's gives one a good congratulatory feeling?

self.plugin = super...?

Posted on
Thu May 28, 2015 1:19 pm
RogueProeliator offline
User avatar
Posts: 1852
Joined: Nov 13, 2012
Location: Baton Rouge, LA

Re: Plugin Developer Documenter Plugin

what does "super(Plugin, self)....." do? .. and how would you do this without the super constructor? shows my python limits..

The super function is not a constructor, it is a function that returns the super class (the base class) of the given class. This allows you to call the same function that you are defining but in the base class.

There are other ways to get at the base class, but this is the best IMHO; I wouldn't try to use others as they gain you nothing and slightly increase maintenance in that you are required to specify the type of the base class.

Posted on
Thu May 28, 2015 2:22 pm
autolog offline
Posts: 2137
Joined: Sep 10, 2013
Location: West Sussex

Re: Plugin Developer Documenter Plugin

Hi Adam,
Can I complement you on your Documentation Plugin - It is an excellent piece of work and I have already learnt quite a few new things just by looking at the plugin source. :D

It is good to have all the interactions documented in one place and not only that but in a real "live" plugin example. :)

I can see that I am going to have to make more Indigo improvement suggestions if it is going to elicit a response like this :wink:

Well done again and thanks! :D

Posted on
Thu May 28, 2015 6:45 pm
jblackburn offline
Posts: 58
Joined: Dec 11, 2013
Location: Quebec, Canada

Re: Plugin Developer Documenter Plugin

A very good piece of software!

Thanks!

Joël

NOTE1: In the next version, add standard pluginProps name who interract with different function of the software. E.g. 'address' to set-up address column in the home windows, ...
NOTE2: Add a number in the debugLog method to easily find the line number.

Posted on
Thu May 28, 2015 7:54 pm
RogueProeliator offline
User avatar
Posts: 1852
Joined: Nov 13, 2012
Location: Baton Rouge, LA

Re: Plugin Developer Documenter Plugin

NOTE1: In the next version, add standard pluginProps name who interract with different function of the software. E.g. 'address' to set-up address column in the home windows, ...
NOTE2: Add a number in the debugLog method to easily find the line number.

Thanks for the suggestions, I'll make a note of those... definitely could use to show some of the other features such as Address column population; I might should scour the developer forum(s) to get an idea of some of the questions whose answer wasn't in the documentation or not obvious but which Matt & Jay cleared up.

Also, thought about making a bare-bones plugin from the example that could be used as a "framework" for anyone to start with; they would just customize specific parts or something.

Adam

Posted on
Thu May 28, 2015 8:10 pm
matt (support) offline
Site Admin
User avatar
Posts: 18174
Joined: Jan 27, 2003
Location: Texas

Re: Plugin Developer Documenter Plugin

Hi Adam,

This is really useful – thanks a ton for putting this together.

Image

Posted on
Fri May 29, 2015 2:05 am
Chameleon offline
Posts: 611
Joined: Oct 04, 2014

Re: Plugin Developer Documenter Plugin

Adam

Just found out about this from Karl and Jon - what a great idea :D

Mike

Posted on
Fri May 29, 2015 6:29 am
kw123 offline
User avatar
Posts: 5144
Joined: May 12, 2013
Location: dallas, tx

Re: Plugin Developer Documenter Plugin

Yes. Adding address column and comment field should be included. I am not home ... Can't write anything lengthy now.


Also how to process callback commands synchronously in the main loop. Set self.newcommand=xxx in the callback and check self.newcommand in the main loop :
if self.newcommand!="" :
execute xxx
Self.newcommand=""






Sent from my iPhone using Tapatalk

Posted on
Fri May 29, 2015 7:38 am
RogueProeliator offline
User avatar
Posts: 1852
Joined: Nov 13, 2012
Location: Baton Rouge, LA

Re: Plugin Developer Documenter Plugin

Also how to process callback commands synchronously in the main loop. Set self.newcommand=xxx in the callback and check self.newcommand in the main loop :
if self.newcommand!="" :
execute xxx
Self.newcommand=""

I thought about adding that in as well, but I might add that your example is not a great way to do it -- primarily, that is not thread safe, and secondly could potentially drop commands if multiple new commands came in before being processed. :-) It wouldn't take much to show how to do it, though, so I will see about adding that in to the example.

Posted on
Fri May 29, 2015 9:43 am
kw123 offline
User avatar
Posts: 5144
Joined: May 12, 2013
Location: dallas, tx

Re: Plugin Developer Documenter Plugin

yes I agree, here how I do it :

1. init
self.newc=[]

2. add command in callbacks etc:
self.newc.append(xxx) #what ever you want to get executed

3. execute in main loop
if len(self.newc) >0:
for i in range(len(self.newc)): ## can't do " for cmd in self.newc :' as we will delete elements in newc
cmd= self.newc[0]
"execute cmd" ## put your code here to execute "xxx"
del self.newc[0]


karl

Posted on
Fri May 29, 2015 9:59 am
RogueProeliator offline
User avatar
Posts: 1852
Joined: Nov 13, 2012
Location: Baton Rouge, LA

Re: Plugin Developer Documenter Plugin

That should work and is basically what I use except that I use a queue construct which makes the code a bit tidier and easier to read/understand. In practice, it accomplishes the same thing; however, Queues were built in Python to be a thread-safe way to communicate between threads and protect programmers against several common mistakes that can happen with using lists in your manner. When I put up an example in the plugin I'll use that as a best-practice technique.

As as aside, if one wanted to get super fancy, the Queue can act as a Priority Queue, the advantage being that you could assign a priority to a task in order to execute "must do now" tasks in response to user actions first and let background tasks, such as status polling, happen after that (even if they were in the Queue first). I've thought of implementing that for my A/V based plugins that poll and accept user interaction.

Who is online

Users browsing this forum: No registered users and 1 guest