what is a good way to get started writing a plugin for a complete beginner?

[TeleFragger]

this may be me also....

well I tapped Moskus on the shoulder about a flow document.. that would help..

if I knew what files i never have to touch and which I do.. Id know what I am looking for....

[mrhappy]

They ain't easy, but they are not impossible! It took me (as a largely brain dead police officer who has never worked in IT, holds a college level IT qualification that long since has any meaningful value, has no .net training and is not truly interested in learning new things) some time to figure it out but at some point it does just 'click' (if you pardon the pun). If I can impart any wisdom out of 10-15 HS2/HS3 plugins (the vast majority I would never release) that I have written, all of which have been a struggle, then it would be do not underestimate the debug statements, at every step have the ability to see whether the function was called, then see what is passed to it, then see what you are doing with it etc. If you don't you will just chase yourself around when something does not work.

The beauty of HS3 is the remote running of plugins and the fact they are separate programs from the HS core. If you wrote a bad HS2 one (which I could easily do) then you could very easily tie up your entire HS system and cause global issues. Now it is just a case of killing the plugin.

TeleFragger - have you looked at the webinar I have linked to? It's got some good information in and if you look at 1:28:15 you will see a little bit of a flow chart of the trigger system. In reality it may not really have a flow chart because if your plugin does nothing then you will find that only InitIO is called when the plugin loads. If you did nothing with HS and your plugin did nothing then that is all that it would do. Things for triggers/actions get called when you start going into the events page and creating events. SetIOMulti gets called when you actually go to control a device etc.

[Moskus]

Remember there's A LOT going on in a plugin!
I've started creating a "flow chart", but I'm having difficulty with it. I think it's easier to break it down into smaller pieces, and then we can have a look at it together. So this is the first piece in a larger puzzle!

I'm going to assume a couple of things:
1. You've installed some version of Visual Studio.
2. You have added the required DLL files as described in my post
3. And you have successfully opened the .vbproj or .sln file.

Open HSPI_MoskusSample and read this carefully:


You'll find the "Plugin.vb" file in the Solution Explorer (usually to the right), and open it (double click).



Press "CTRL + M, L" (hold down CTRL, press M and release, and then press L and release) until everything is collapsed down to a few, grey lines.

Click on the + next to the text "Public Class CurrentPlugin...", and this is what you see:


The first line is my settings class, you can see what it does by opening "Settings.vb". I wrote this class for easier access to settings we need and for easier saving of said settings. The Timer just takes care of updating our random number (which is stored in "lastRandomNumber").

The rest we are not going to bother with at the moment.

Futher down, click on the + next to "Init...", and also expand the <summary> and "Public Function InitIO(ByVal port As String) As String..."

Here's where the magic happens! After the plugin has started, and connected to HS3 (have a look in "Main.vb" if you want, but you seriously don't have to at this point), the plugin initialization takes place, and it's all happening in "InitIO".



This is basically it. Everything the plugin does is defined here (almost).

First it loads the settings (the first line is just the global variable making it accessible for all functions and subs in "Plugin.vb")

Then the plugin registers two web pages in the HS3 web server (accessable under Plugins -> "MoskusSample Config" and just "MoskusSample")

It then adds all triggers, subtriggers and actions.

After that it Checks if our predefined devices exist, and creates them if not. That sub ("CheckAndCreateDevices()") is absolutely worth checking out (right-click on it, and select "Go To Definition..." or just press F12).



CheckAndCreateDevices() is broken down in to several smaller functions, to hopefully make it easier to read. I actually think that this sub reads really well, so it should be failry easy to sort out what's going on. But give me a hint if you're stuck!




Last, it starts the time that will create a new random number every 30 seconds or what ever you have set that setting to. What happens when the Timer triggers is defined in UpdateRandomValue and that may seem overwhelming at first. BUT it's really not, but it requires a bit knowledge about how Events work.

1. It creates the new random number between 0 and 100.


2. It then gets all triggers belonging to the plugin ("callback.GetTriggers(Me.Name)").

3. Each trigger has a key value named "SomeValue" (I needed a unique name and that fit). This is where the value selected by the user who set up the trigger or condition on the Events page set, like "I want my random number to be lower than... err... 42". "SomeValue" is then 42 for that particular trigger.

For each trigger to check, there is a ".TANumber". If you look above in InitIO, you will see we added two triggers. First here:

        'Adding a trigger 
        triggers.Add(CObj(Nothing), "Random value is lower than")

... and then here (after defining some subtriggers):

        '... and then the trigger with the subtriggers
        triggers.Add(subtriggers, "Random value is...")

The ".TANumber" is "1" for the first trigger we added, and "2" for the second, and we can use that to determine which trigger was used. I made an Enum of them that makes it easier to remember what the trigger was, and I use that to compare for ".TANumber" and ".SubTANumber" (see lines 529 and 538 in "Plugin.vb", CTRL+G is Goto Line)

    Private Enum TriggerTypes
        WithoutSubtriggers = 1
        WithSubtriggers = 2
    End Enum

    Private Enum SubTriggerTypes
        LowerThan = 1
        EqualTo = 2
        HigherThan = 3
    End Enum

It's then just a matter of getting the trigger value, select compare type (lower, equal higher) and the new random number to see if the random number should trigger the event or not. If it should, then just execute:

TriggerFire(t)

... where t is the particual trigger we are checking.


4. It checks all "Basic" devices and update their value with the new random value.

(The sample also handles something in the "Advanced" devices. In this device you can save a string, so the sample shows you how to retrieve it. Perhaps you want to do something cool with it?)

5. ???

6. Profit. (No, seriously, we're done! At least until the Timer fires again.)





When you shut down HS3 or shut down the plugin, ShutdownIO() is called.

... as with InitIO() handles startup, this handles exiting the plugin, so we Save our settings, we stop the timer from trigging, and save all devices to the HS database ("hs.SaveEventsDevices()")


... and this is the most important parts. If you don't want to use triggers and actions, you don't have to, you just comment the "triggers.Add..." lines out They are a but cumbersome to set up and understand, but it's much easier if you just toy around with the sample running in HS3, and see what happens. You'll recognize the text, and then it's easier to see what happens when.


All Subs and Functions have a <summary> which explains what this sub/function is doing. All subs/functions are also commented alot (I've gone through the Plugin SDK and copied in the descriptions for easier access, but you'll see that the SDK does have some holes in it).

[jeanv]

Simply fantastic!!! This was SO SO SO helpful as compared to the HS3 SDK help and samples.... Moskus, you are AWESOME!!!

[Robin Hayman]

Thanks Raptor. At least something to look at. I am wondering about multiple identical endpoints with just different names. More ...

I have logged in and tried to find a development toolkit leading to a HS4 plug-in that we would bundle inclusive with new endpoint hardware we are building. The plug in would have no use on other hardware.
I downloaded the three HomeSeer sample applications but saw they are written in VB script.
Do we really have to use VB. Are there any similar examples in C#.Net?
Would we have to sign some NDA for HS4 prototype sample code?
How do you sign up for that?
I presume new plug would implement discovery, naming, endpoint configuration on HS4 start up. The events to and from endpoint to HS.
Note https://homeseer.com/developer-support/ only leads to page with revisions listed but no content when selecting PLUG-IN-SDK.
How to do multiple instances.
Help!