Avviso is a collection of Arduino and Processing libraries and examples to send push notifications to an iOS device via Prowl or an Android device via Notify My Android. 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.
For iOS, 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.
For Android, Avviso requires Notify My Android and a Notify My Android API key. Install the Notify My Android app on your Android device and paste your Notify My Android API key into the appropriate place in your Arduino or Processing sketch. The Arduino or Processing sketches default to using Prowl, so follow the comments in the sketches to switch them to use Notify My Android instead. It’s a simple one-line change.
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/Notify My Android will push the message to your iOS/Android 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 push a notification to your 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/Notify My Android will push the message to your iOS/Android 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/Notify My Android will push the message to your iOS/Android 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 (default) or www.notifymyandroid.com (see the begin() call below) in order to send push notifications.
To use Notify My Android, use this form:
Avviso.begin(NOTIFY_MY_ANDROID);Without a valid API key in the call to Avviso.setApiKey(), the push notification will fail. Replace the dummy code with your Prowl or Notify My Android API key here:
Avviso.setApiKey("0123456789012345678901234567890123456789");Call Avviso.setApiKey() in setup().
The application name is part of the push notification 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 push notification API, and they will show up in the app. You may refer to the Prowl API page or Notify My Android 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. It also doesn’t support the Notify My Android developerkey or content-type parameters. 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 requires the great HTTPClient 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 copies of jProwlAPI and NMAClientLib. In fact, the Processing file Avviso.java is a very thin wrapper around these libraries.