Avviso is a collection of Arduino and Processing libraries and examples to send push notifications to an iOS device via Prowl. Arduinos with Ethernet shields work best, but USB Arduinos connected to a computer with Processing work, too. The rest of this file describes how to setup and use Avviso. These instructions are similar to those for my iOS app, Ciao.

Avviso requires the Prowl app and a Prowl API key. Install the Prowl app on your iOS device and paste your Prowl API key into the appropriate place in your Arduino or Processing sketch. If you know how to install Arduino or Processing libraries, you’re all set. Read on for the installation details.

You don’t need an Arduino to use Avviso. You can demo it with a stand-alone Processing sketch.

1. Download Processing and install it.

2. Copy the included Processing/libraries/avviso/ folder into Processing’s libraries/ folder. The default folder on Mac OS X is:

    ~/Documents/Processing/libraries/

Create the libraries/ folder if it doesn’t exist. Consult the instructions on how to install a contributed library for help finding Processing’s libraries/ folder.

3. Launch Processing or restart it if it was already running. Select the sample Avviso app: RingTheRedPhone. Find it in the menu:

File > Sketchbook > libraries > avviso > examples

After opening it, click “Run”.

4. Type a message and hit return.

5. Prowl will push the message to your iOS device.

If you don’t have an Ethernet shield, you may use your computer and a Processing sketch to connect your Arduino to your network.

1. Follow all the instructions above to install Processing and the Avviso Processing library. Make sure that you can communicate with Processing to the Prowl app on your iOS device using the RingTheRedPhone example.

2. Copy all five folders (Avviso/, AvvisoUSB/, EthernetDHCP/, EthernetDNS/, and HTTPClient/) in the included Arduino/libraries/ folder into your Arduino’s libraries/ folder. The default folder on Mac OS X is:

    ~/Documents/Arduino/libraries/

Create the libraries/ folder if it doesn’t exist. Consult the Arduino documentation on libraries for help finding the libraries folder. There’s more on libraries in the reference section.

Once you copy the folders, the structure should look like this:

    ~/Documents/Arduino/libraries/Avviso/
    ~/Documents/Arduino/libraries/AvvisoUSB/
    ...

and so on.

3. Launch the Arduino IDE or restart it if it was already running. Load the AvvisoUSB (not Avviso) sketch named RingTheRedPhone. Find it the menu:

File > Examples > AvvisoUSB > RingTheRedPhone

4. Paste in your API key and load the sketch onto your Arduino.

5. Launch Processing and load the AvvisoArduino example:

File > Sketchbook > libraries > avviso > examples > AvvisoArduino

and click “Run”.

6. Prowl will push the message to your iOS device.

You rock. This is the setup Avviso was designed for and where it works best. Setup is the easiest, too.

1. Just like step 2 in the section above, load everything in the included Arduino/libraries/ folder into:

    ~/Documents/Arduino/libraries/

see the Arduino documentation on libraries if you need help.

2. Load the Avviso (not AvvisoUSB) RingTheRedPhone example sketch from here:

File > Examples > Avviso > RingTheRedPhone

3. Paste in your API key and load the sketch onto your Arduino.

4. Prowl will push the message to your iOS device.

Once you’ve gotten started and tested the example sketches, make a copy one of them to modify for your own sketch. The Arduino API has only four methods. Three of them are for use in setup(), and the fourth one is for pushing the message.

Don’t forget to call

    Avviso.begin();

in the setup() method of your sketch. In the Ethernet version of Avviso, this method looks up the IP address of api.prowlapp.com in order to send push notifications.

Without a valid 40-byte API key in the call to Avviso.setApiKey(), the Prowl server will return a 401 HTTP error code. Replace the dummy code with your Prowl API key here:

    Avviso.setApiKey("0123456789012345678901234567890123456789");

Call Avviso.setApiKey() in setup().

The application name is part of the Prowl API, and it shows up first in the push notifications.

    Avviso.setApplicationName("Monitoring system");

Call Avviso.setApplicationName() in setup().

Call Avviso.push() in setup() or loop() after you have set the API key and application name. Every call to Avviso.push() will send a new push notification to your iOS device. The call takes three parameters:

    Avviso.push("Event name", "Message body/description", intPriorityValue);

The event, description, and priority are part of the Prowl API, and they will show up in the app. You may refer to the Prowl API page for size limits, but they’re all reasonable, so you probably won’t exceed them on a memory-constrained device like an Arduino.

Avviso doesn’t support the Prowl 1.2 url parameter. If you’d really like to have it, contact me or make a fork with the change.

Thank you very much to the authors of these projects, which are distributed with the Avviso libraries:

Avviso proudly uses EthernetDHCP on Ethernet Arduinos to acquire an IP address. It’s not strictly required, but it generally should be. The only reason I could accept not to use it is size, but even then you better have a good reason why the rest of your sketches size can’t accommodate EthernetDHCP.

Avviso also uses EthernetDNS to do a DNS lookup of api.prowlapp.com. In 2011 and beyond, if you’re putting the IP address of a remote site into your sketch, you’re officially doing it wrong.

Avviso required a slight change to HTTPClient, so the link is to my fork of the otherwise great library from Interactive Matter. The Prowl API is not RESTful, but in general use HTTPClient when dealing with a REST-based web service. It handles details your shouldn’t re-implement yourself, including URL encoding.

The Processing sketches use an unmodified copy of jProwlAPI. In fact, the Processing file Avviso.java is a very thin wrapper around jProwlAPI.