MisterHouse is an open source home automation program. It's fun, it's free, and it's entirely geeky. Written in Perl, it fires events based on time, web, socket, voice, and serial data. It currently runs on Windows 95 or newer and on most Unix based platforms, including Linux and Mac OSX.

Pushsafer.pm

• Pushsafer
  • SYNOPSIS
  • CONFIGURATION
  • DESCRIPTION
  • INHERITS
  • DEPENDENCIES
  • METHODS
  • AUTHOR
  • MODIFICATIONS
  • SEE ALSO
  • LICENSE

Pushsafer

SYNOPSIS

This module allows MisterHouse to send notification messages to Pushsafer.com clients. See https://www.pushsafer.com/ for details of the service and API.

CONFIGURATION

Configure the required pushsafer settings in your mh.private.ini file:

  Pushsafer_k           = <Private or Alias key from Pushsafer.com account> 
  Pushsafer_t           = "MisterHouse" Default title for messages if none provided 
  Pushsafer_d           = <Default device or device group id to send notifications to>
  Pushsafer_i           = <Default icon>
  Pushsafer_s           = <Default sound>
  Pushsafer_v           = <Default vibration>
  Pushsafer_disable = 1  Disable notifications.  Messages will still be logged

Create a pushsafer instance in the .mht file, or in user code:

.mht file:

  CODE, require Pushsafer; #noloop 
  CODE, my $push = new Pushsafer(); #noloop

A user code file overriding parameters normally specified in mh.private.ini. All of the parameters are optional if properly configured in the ini file.

    use Pushsafer;
    my $push = new Pushsafer({
                                        k => '1234qwer1234qewr1234qwer',
                                        t => 'Home Notification',
                                        d => '111',
                                        i => '11',
                                        s => '5',
                                        v => '1',
                      });

In user code send a message. The only required parameter is the first, the message text. Any of the parameters provided when initializing the Pushsafer instance may also be provided on the message send. They will be merged with and override the default values provided on initialization. See the method documentation for below more details.

  $push->notify( "Some important message", { t => 'Security Alert', i => 11 });

DESCRIPTION

The Pushsafer instance establishes the defaults for messages and acts as a rudimentary rate limiter for notifications.

The rate limiting kicks in if an identical message is sent within a 10 second threshold. (Identical meaning the same message, title and device.) Identical messages will be logged but not sent to the pushsafer service. This will minimize excessive use of message credits if a configuration error causes looping notifications.

It's important to exclude the Pushsafer initialization from the loop, so that rate limiting thresholds can be detected and pending acknowledgments are not lost.

INHERITS

NONE

DEPENDENCIES

  Data::Dumper:     Used for error reporting and debugging
  LWP::UserAgent:   Implements HTTPS for interaction with Pushsafer.net
  Digest::MD5:      Calculates hash for rate limiting duplicate messages
  JSON:             Decodes responses from Pushsafer.net

METHODS

new(p_self, p_parameter_hash)

Creates a new Pushsafer object. The parameter hash is optional. Defaults will be taken from the mh.private.ini file or are hardcoded.

This must be excluded from the primary misterhouse loop, or the acknowledgment checking and duplicate message rate limiting will be lost

  my $push = Pushsafer->new( {
                        k       => "xxxx...",           # Set the Private or Alias Key
                        t       => "Some title",        # Set default title for messages
                        d       => "111",                       # Set the target device or device group (leaving this unset goes to all devices)
                        i       => "5",                         # Set the icon to be displayed
                        s       => "3",                         # Set the sound to be played
                        v       => "1",                         # Set the vibration to be played
                        speak   => 1,                           # Enable or disable speak of notifications and acknowledgment
        });

Any of these parameters may be specified in mh.private.ini by prefixing them with "Pushsafer_"

notify(p_self, p_message, p_paramater_hash)

This is the primary method of the Pushsafer object. The message text is the only mandatory parameter.

The optional parameter hash can be used to override defaults, or specify additional information for the notification. The list is not exclusive. Additional parameters will be passed in the POST to Pushsafer.com. This allows support of any API parameter as defined at https://pushsafer.net/api

        $push->notify("Some urgent message", {
                        k   => "xxxx...",      # Override the Private or Alias Key
            t   => "Some title",   # Override title of message
            d   => "1111"                       # Device or device-group id 
        });

Notify will record the last message sent along with a timestamp. If the duplicate message is sent within a 10 second window, the message will be logged and dropped. A duplicate message is one with identical message text, title and device. Although this permits a message to be sent to multiple users using repeated notify commands, it is preferable to define a group ID on the Pushsafer.com site to minimize traffic.

AUTHOR

George Clark

MODIFICATIONS

2016/09/30 Kevin Siml Pushsafer.com

SEE ALSO

http://www.pushsafer.com/

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Pushsafer.pm