Pushover 3P Plugin

This plugin enables HomeSeer HS3 to send push notifications to Pushover.net (http://www.pushover.net), Pushover have two clients available, one for iOS and one for Android. This enables you to send a wide variety of different messages to your mobile devices, Pushover support a system of different priorities and different message tones. This plugin for HS3 enables you to send these notification messages from HomeSeer to Pushover meaning that you can warn about a variety of different events in HomeSeer. The plugin is very simple, it has one web page for configuration and a handful of simple event actions.

Setting up Pushover

1) Go to http://www.pushover.net and press ‘Login or Signup’ in the top right corner.

2) Fill out an email address and password to sign up for an account.

3) You should then eventually get a dashboard page that looks like this:

4) The user key in the top right is used in this plugin and it is time to copy this down.

5) On that page scroll down to the section marked ‘Your Applications’, there should be nothing in this page and you need to click ‘Register an Application’.

6) You will then get a page looking like this:

7) Fill out the details on the page, you can call the application HomeSeer as long as you do not make it public and then fill out the rest of the page, you can also give it a suitable icon. After completing that page click ‘Create Application’

8) Next page will look like this:

Please note down the API Token/Key from here as it is also used in the plugin. That completes setting up the Pushover side of things.

Setting up your devices

1) Download the Pushover client from the app store.

2) After it installs launch it and enter your username/password you used to sign up for Pushover before.

3) You then need to give your device a suitable name, this is used in the plugin if you want to send alerts to a specific device.

Setting up HomeSeer

1) Inside the HSPI_PUSHOVER.zip file you should find the HSPI_PUSHOVER.exe file, this is the only file you need and please place this file in the root HomeSeer directory.

2) Under the ‘Plug-Ins’ drop down of the HS web interface you will have a menu for Pushover, there is only one webpage and that will be to the configuration page.

3) Enter your User Key and API Token in the top of the configuration page in the relevant fields and press save.

4) If you wish to set up any specific devices (you do not have to do this, if you don’t then the plugin will always send the messages to all of the devices linked to your Pushover account) then scroll down to the next table.

In this example I have two devices set up, an iPhone and a Nexus 7, their client names are the iphone and nexus7 (these are the device names you specify when you install the Pushover client on your device). If you just want to add a device then fill out the first box and press ‘Add Device/Group’, after that it should update the current devices table.

If you want to set up a delivery group (which is a group of different Pushover users rather than a group of devices on one account) then you need to complete both fields. You need to give the delivery group a name and then you need to give the group key which you get from Pushover when you set up the group in this screen:

5) You will then need to set up at least one application, you can have any number of applications and this may be useful to filter out the origin of the messages. Earlier you should’ve taken down the application key, in this section you can specify a name for the application in HomeSeer (this can be the same as the name in Pushover or different) and you also need to add a key for that application.

Ensure that the application is added and appears in the box.

Once you have specified the keys and if required the devices you should then be in a position to start creating events. Create a new event to test the plugin, when you create an event there should be a single new action to send a Pushover message. Click that action and a screen looking like the following should appear:

The fields are relatively self explanatory, the first is a drop down list box of device names and groups that are currently in the configuration page. Leave as ‘All Clients’ if you want to broadcast to all clients.

Message Title and Message Body are as they say, they also support HomeSeer replacement variables, so an event action like this:

Will produce a Pushover message similar to this:

The Message Priority is best described on the Pushover website here https://pushover.net/api#priority , messages can be any of those priorities.

The Message Sound drop down is populated by downloading a list of sounds from the Pushover website when the plugin starts.

The Message URL and Message URL Title are in case you wish to put a link in the messages, the link will appear when you click on the message and can be a link to anything you want. Pushover also support Open URL’s (http://handleopenurl.com/ for iOS) so it is possible if you put “tel:0031204637000” in the URL and clicked on it then it would link to the dialer for that phone number. Both fields also will support replacement variables from HomeSeer.

Triggers

The plugin supports two triggers for priority message status. One trigger is for when a priority message is acknowledged and the other is for when a priority message expires. Please note that these triggers will only fire on the basis of the last priority message sent and it cannot be used to query older messages. These triggers are evaluated every ten seconds post message so there may be anything up to a ten second delay from acknowledging the message to the trigger firing.

Untitled.jpg

Devices

Version 1.0.0.8 introduces a set of devices to the plugin, by default five devices will be created as per the below image. The root device has no function and is just used to identify a base device for the plugin, the next device enables you to disable or enable the sending of messages. If this is set to disabled then no messages will be sent by the plugin no matter what is tried, this is handy if you wish for no messages to be sent to devices because you are at home for example.

The next device enables you to resend the last message sent to a client, when you send a message this device will be populated and clicking the ‘Resend Message’ button will make an attempt to resend the last message.

Device four enables you to disable low priority messages from being sent, if this device is set to true then only emergency messages will be sent. This device relies on the master enabled/disabled device (device two) being set to enabled, if device two is disabled then no message will be sent regardless of the status of device four. The last device will show how many messages remain for the month for the application you used last (please be aware of this), the default amount is 7,500 messages per month per application. This device could be used in an event to set a warning if a low number of messages remain.

Note: If you do not want the devices then open up the Pushover.ini configuration file in the \Config directory and add WantDevices=False under the [Settings] key. Delete the devices if they have already been created and then restart the plugin, the devices should not be created.

Scripting

The scripting calls have changed in HS3. To send a message from a script please pass an object array in the following order to the plugin function 'PushScript'. All array elements should be sent even if they are optional, if they are optional please send 'Nothing'. This function will return a boolean value of true/false depending on whether or not the message was successful:

Index(0)

Device Name (Required - “All Clients” to send to all devices, separate multiple clients with the ASCII character 124 - | - String)

Index(1)

Message Body (Required - String)

Index(2)

Message Title (Optional - String)

Index(3)

Message Priority (Optional - normal/low/emergency/high - String)

Index(4)

Message Sound (Optional - 'pushover' etc, from the sound list - String)

Index(5)

Message URL (Optional - String)

Index(6)

Message URL Title (Optional - String)

Index(7)

API String (Optional - Same as in the configuration page - String)

Index(8)

Attachment Path (Optional - full file path to the attachment - String)

NEW:

If you wish to send a newer “Glance Message” (described below) by scripting then there is an additional scripting call to make, this should be to the plugin function ‘GlanceScript’ and you should pass it the following data, if they are optional please send 'Nothing' .

Index(0)

Device Name (Required - “All Clients” to send to all devices - String)

Index(1)

Message Body (Optional - String)

Index(2)

Message Title (Optional - String)

Index(3)

Message Subtext (Optional - String)

Index(4)

Message Count (Optional - Integer)

Index(4)

Message Percentage (Optional - Integer - 0-100)

NEW 28/01/18:

With Pushover version 3.0 (the application version, not this plugin version) Pushover now has the option to send messages with an image attachment. When creating an event action then if you specify the path to a file then it will make an attempt to send that image to your Pushover client. Please note the larger the file the longer it will take and this may tie up the plugin, my advice is to keep the images sizes small so they will be sent in a reasonable time. Also PLEASE note that the scripting function will now have an additional parameter and your scripts may need amendment to deal with this.

Return Properties

There are three properties you can call if you need information from the plugin (using the hs.PluginPropertyGet call), these are;

All are fairly self explanatory, they do not need any parameters and will all return a string array of either devices, applications or sounds.

HTML Strings

As of the 27/02/15 the Pushover application supports a limited set of HTML tags, they are detailed and exampled here https://pushover.net/api#html but amount to:

If you wish to use this please check the above link for examples and include them in the message body like this:

Untitled.png

Please remember to close the tag and be aware that this will render the same in the HomeSeer Events page.

Custom Replacement Variables

As of version .23 there are now some custom replacement variables supported, these variables are similar in nature to HS replacement variables however return some information that is at present unavailable in the HS replacement variable set. To use these add the following syntax to either the message title, body or URL:

%ShortTime%

This will report the system short time format, depending on your regional settings

%LongTime%

Same but for the long time format

%ShortDate%

Same but for the short date format

%LongDate%

Same but for the long date format

%HSUptime%

This is the same return as the scripting call for hs.uptime

%HSWanIP%

This is the same as the call http://checkip.homeseer.com:8245/

Flood Control

As of version .24 the plugin now has some in built ability to stop you flood your devices with messages, this could be used if you have an errant device that causes an event to run repeatedly and in turn send a series of messages to the clients. This is enabled by default and the basis of this function is every minute a timer will run and count how many messages have been sent over the last minute. If over 100 messages have been sent, which is likely to be indicative of a fault then the plugin will disable the ability to send messages. If you have the HS devices enabled then the master device ‘Enabled/Disabled’ will change to disabled. If you do not have the devices then the plugin will need to be restarted in the plugin interfaces page. If you do not wish for this function then please add the following entry to the INI file under the [Settings] key.

DisableFlood

Set to ‘True’ to disable the checking timer, false to leave it enabled.

FloodNumber

Optional - set to a number if you want a number other than 100 to check against

Glance Messages

As of one of the later betas for Pushover (and version .26 of the plugin) has included the facility to have messages displayed on the background of smart watches. This functionality is in beta and described here - https://pushover.net/api/glances . This is different to push messages in that you send a bit of data to the server and a widget on the watch will update, because it is different from push messages these are not designed for instant messaging and should be seen as a little bit of data that you might want to look at, say a temperature or such like.

There is one single event action for this and it will look like the following:

Untitled.png 

One difference between this approach and previous approaches is that you must select which bits of data you wish to send, some widgets will support a combination of data and as such if you want to send just the percentage you need to just select the percentage check box.

This functionality is still subject to testing, please check to see how it suits your purpose. Please note that you can only send a message every twenty minutes, this is documented on the Pushover website. If your messages do not arrive then please check the HS log for suggestion as to what might be the problem.

If you find any bugs please post them here: http://forums.homeseer.com/showthread.php?t=163974