Sending Push Notifications From A Raspberry Pi With Prowl

Push notifications are the instantaneous way that apps send messages or links to a phone.  If you receive breaking news alerts or something similar, then you know what I am talking about.  Push messages are sent over data, not over the cell network, meaning that they are free.  Being free and nearly instantaneous makes them a very attractive way to send information from a Raspberry Pi to a phone.

However, push messages are tied to apps, so if you want to send a message you will need to develop an app to take advantage of them.  This is where the Prowl app for iOS comes in.  Prowl is a $3 app that receives custom notifications.  All you have to do is purchase Prowl on your phone, setup an account and then go to Prowl’s website and create and API key, which serves as your password and ID.

The easiest way I have found to send notifications with Prowl is its official command line interface.  Prowl’s CLI is a Perl script which you can check out here: http://www.prowlapp.com/static/prowl.pl.

In my experience, these notifications can be delayed anywhere from 3 seconds to 15 seconds from when the command is executed, to when the notification is received.  

Setup & Installation

./prowl.pl -application="Application" -event="Event" -notification="Notification" -apikey="[insert your API key here]"

First will need to install prowl.pl’s dependencies:

sudo apt-get install libwww-perl -y

Next you need to install the LWP Perl bundle.

sudo perl -MCPAN -e 'install Bundle::LWP'

You will be prompted with a few questions, just hit enter to accept the default settings.  Once you have answered the questions, it may take up to half an hour to install the bundle.

Lastly, you need to download the prowl.pl script and make it executable:

wget http://www.prowlapp.com/static/prowl.pl
chmod +x prowl.pl

Usage

Here is the script’s usage synopsis:

prowl.pl [options] event_information

 Options:
 -help Display all help information.
 -apikey=... Your Prowl API key.
 -apikeyfile=... A file containing your Prowl API key.
 -providerkey=... Your provider key (optional)

 Event information:
 -application=... The name of the application.
 -event=... The name of the event.
 -notification=... The text of the notification.
 -priority=... The priority of the notification.
 An integer in the range [-2, 2].
 -url=... The URL to attach to the notification, and possibly redirect to.

The required options are:

• -apikey=”Place your api key here”
• -application=”The Name of the App, Max 256 Characters”
• -event=”The Notification’s Title, Max 1024 Characters”
• -notification=”Notification text, max 10,000 characters.”

Aside from the API key, the other three required fields have no right or wrong answer.  You can place whatever text you would like in them; the different fields simply control the order in which the text will display:

Here are two non required options that you might use:

• -priority= – This is a number, either -2, -1, 0, 1, 2, that is used to prioritize the notifications.  Each priority level can be given a unique ringtone.  This may be useful if you want different ring tones for different kinds of notification.  A notification with a priority 2 notification can be set to bypass the app’s built in “Quiet Hours.”  In the app, the priority numbers correspond with Very Low (-2), Moderate (-1), Normal (0), High (1), Emergency (2).
• -url=”http://…” – This specifies a URL to redirect to if the notification is opened.  If your Raspberry Pi has an html server on it, Prowl can be used to redirect you to a webpage on the Pi with more information or an image from the Raspberry Pi camera.

Examples

Here is an example of a basic command:

./prowl.pl -apikey="insert your API key here" -application="Application" -event="Event" -notification="Notification"

Here is a command with all options:

./prowl.pl -apikey="insert your API key here" -application="Application" -event="Event" -notification="Notification" -priority=2 -url="https://www.makingyouthink.com"

The above would bypass quiet hours (priority 2) and redirect you to this website.

Sometimes you may want to send a push notification if a command fails, here is a quick and easy way to do that.  Just place this line on the line directly after the command:

some command...
[ $? -gt 0 ] && ./prowl.pl -apikey="Place your api key here" -application="Raspberry Pi" -event="Command failed" -notification="This command failed to execute '[previous command here]'" -priority=2

This checks to see if the previous command’s exit code ($?) is greater than 0, which usually means that an error occurred.  If it is, then a notification is sent.

Got a favorite Prowl notification usage?  Leave a comment!