Plugin Update Checker Module

[travisc]

Plugin Update Checker Module

I've created an update checker module that can be easily included in any indigo plugin. I started with berkinet's versionCheck method, which worked great, but then my imagination got the best of me.

I wanted to have a version checking module that would meet the following requirements:

1. Have the option to email a user once for each new version release.

• Maybe it's just me, but I rarely check my logs unless something is wrong. Email's the only reliable notification option for me. I've also had a few of my plugins break after an Indigo update (usually something I did wrong). It's not always obvious to the user that there's a problem. It would be nice to have a facility where I can notify the users of an important update. The plugin saves the version number last emailed to the user so they're only notified once per version.

2. The email subject and body can be controlled by the author for each update.

• This way the user can be notified of what's changed without them having to go looking in the forums. A download link can optionally be added into the body of the email.

3. Really easy to add to any plugin.

• I was aiming for two or three lines of code. One line to create the instance and setup the module. One more to allow it to see if it's time to check for an update. Then one more if you want to force an update manually, like from a menu action. The plugin handles all the config checking and state saving on its own.

Other than those points, the basic concept is the same as berkinet's versionCheck method. The module checks a master file on a server somewhere that lists the most current version number. If the version number on the server is higher, the user is first notified by a note in the log. If the file on the server also contains an email subject and body, those are emailed to the user using Indigo's built-in email feature. For emails to work, the user must have email sending setup in Indigo's preferences.

Using indigoPluginUpdateChecker

1. You can download the module here.

2. Put the module in your plugin's Server Plugin folder, and import the module at the top of your plugin.py:

Code: Select all

import indigoPluginUpdateChecker

3. Create the instance and setup the module in your plugin's __Init__ method:

Code: Select all

self.updater = indigoPluginUpdateChecker.updateChecker(self, versionFileUrl [,daysBetweenChecks])

where:

• - versionFileUrl is the url for the location of your update info file. The url must be formatted like "http://www.domain.com/folder/versionInfoFile.html"
  - daysBetweenChecks is optional and defaults to 1. This controls how often the module will check for updates automatically. They can always be checked for manually by running self.updater.checkVersionNow()

4. Call the poller in your runConcurrentThread so the module can see if it's time to check for an update. It doesn't matter how often this method is called, it will only actually check for updates once a day (unless daysBetweenChecks was overridden).

If you've already got a runConcurrentThread that loops, just add the line below:

Code: Select all

self.updater.checkVersionPoll()

If you don't have a runConcurrentThread then a simple example is below:

Code: Select all

def runConcurrentThread(self):
	# While Indigo hasn't told us to shutdown
	while self.shutdown is False:
		self.updater.checkVersionPoll()
		self.sleep(1)

 def stopConcurrentThread(self):
	self.shutdown = True

To force the module to check for updates you can use the following method:

Code: Select all

self.updater.checkVersionNow()

PluginConfig.xml
If you'd like to use the email feature, you need to have at least a text box for an email address in your plugin's config. You can also optionally have a checkbox that's used to enable/disable email notifications. Regardless of either of these settings the module will always check the server at the set interval and make a note in the log.

Code: Select all

<!-- Do NOT change the ids -->
<Field id="updaterEmail" type="textfield">
	<Label>Email:</Label>
</Field>
<Field id="updaterEmailNote" type="label" fontColor="darkgray" fontSize="small" alignWithControl="true">
	<Label>Email sending must be configured in Indigo's preferences.</Label>
</Field>

<!-- Optionally a checkbox can also be used. -->
<Field id="updaterEmailsEnabled" type="checkbox" defaultValue="true">
	<Label>Email Update Notifications:</Label>
</Field>

Some values are automatically saved in the plugin's prefs file for use by the updater:

• 'updaterLastCheck' = Last time an update check was performed (epoch time)
  'updaterLastVersionEmailed' = The last version emailed to the user

Checking Manually
If you want to have a Check for Updates option in the plugin's menu.

MenuItems.xml:

Code: Select all

<?xml version="1.0"?>
<MenuItems>
    <MenuItem id="menu1">
        <Name>Check for Updates</Name>
        <CallbackMethod>checkForUpdates</CallbackMethod>
    </MenuItem>
</MenuItems>

Then the following method in your plugin.py:

Code: Select all

def checkForUpdates(self):
	indigo.server.log(u"Manually checking for updates")
	self.updater.checkVersionNow()

Sample Server Version Info File
Below is a template for the version file that must reside on a server. The only mandatory line is the first one. That will cause a note to be displayed in the Indigo log. If you don't want a notification emailed to the user then don't include the EmailSubject: or EmailBody:.

Code: Select all

Version: 1.3.1
EmailSubject: DSC Alarm Indigo Plugin Update
EmailBody: The DSC Alarm Plugin you are using with Indigo has been updated to version 1.3.1.

The changes are:
- Change 1
- Change 2

The update can be downloaded at the link below.
http://www.domain.com/plugins/plugin.zip

This email was sent to you by Indigo at the request of the plugin.  You will only be emailed once per release.  To disable these emails see the plugin's config.

[matt (support)]

Great idea and implementation -- thanks for sharing it, Travis!

[nlagaros]

Travis - I just implemented your module in my Sonos plugin. The directions were excellent. Thank you.

[travisc]

Travis - I just implemented your module in my Sonos plugin. The directions were excellent. Thank you.

Your welcome!

[nsheldon]

I just added this to my new Energy EAGLE plugin too. It works perfectly. I plan on adding it to all my other plugins as well. Great work Travis!

[Dewster35]

This is something I've been kind of wishing for for quite a while! Thanks guys! A slight suggestion... is it possible to have the plugin just use a default email addy? For someone who has accumulated quite a few third party plugins, entering the notification email addy over and over again becomes quite redundant.

[travisc]

This is something I've been kind of wishing for for quite a while! Thanks guys! A slight suggestion... is it possible to have the plugin just use a default email addy? For someone who has accumulated quite a few third party plugins, entering the notification email addy over and over again becomes quite redundant.

That would be nice, but I don't think that's possible right now. To my knowledge Indigo doesn't have a preference for an email address.

[midd]

There is an email setting in Indigo preferences.

[jay (support)]

There is no default To address and those settings aren't available to plugins in any event.