Interfaces to Growl, Howl, and Boxcar notification systems ========================================================== Alexander Kasprzyk and Dan Roozemond * Summary * Requirements * How to Install * Growl * Howl * Boxcar * Sending Growl Notifications over a Network * Using curl with Howl and Boxcar * Customising Howl * Boxcar and the "No application/event defined" error Summary ------- Growl is a popular notification system on Mac OS X. We provide a Magma intrinsic for sending Growl notifications to your computer. Howl and Boxcar are two popular notification apps on iOS devices such as the iPhone, iPod Touch, and iPad. If you have signed up for a Howl or Boxcar account, and have the relevant app installed on your device, you can use the intrinsics we provide to send a notification from within Magma to your iOS device. Requirements ------------ * Magma V2.18-4 or higher, installed on a platform capable of executing the Pipe command (currently this excludes Microsoft Windows). To send Growl notifications: * For receiving Growl notifications, Growl must be installed on your computer. This can be downloaded from http://growl.info/. * In the "Extras" folder of the Growl installer (http://growl.info/) is "growlnotify". This MUST be installed on your computer in order for Magma to send messages to Growl. * For sending Growl notifications over the network, you will need either growlnotify, PHP, or Python installed on each machine you want to send messages from. * growlnotify is for Mac OS X machines only, and comes as part of the Growl installer (http://growl.info/). * PHP and Python come as standard on most UNIX-type systems, so you probably don't need to worry about installing them yourself. To send Howl or Boxcar notifications: * For sending Howl notifications to your iOS devices (iPhone, iPad, etc.), you must have a Howl account (sign-up for free at http://howlapp.com/) and have installed the Howl app on each device you want to receive messages on. * For sending Boxcar notifications to your iOS devices (iPhone, iPad, etc.), you must have a Boxcar account (sign-up for free at http://boxcar.io/) and have installed the Boxcar app on each device you want to receive messages on. Before you send your first notification, you must register your Boxcar e-mail address to receive notifications from Magma. This is described in the Boxcar section below. * In order to send messages to Howl or Boxcar, the computer you are running Magma on must have the curl command line tool installed (standard, or easily installed, on most UNIX-type systems) and a working internet connection. How to Install -------------- * Download the "Growl.tar.gz" archive and unpack it. We will assume that you have saved it to /path/to/Growl (a sensible location might be in a "magma" directory in your home directory). * From within Magma, load the files via: > AttachSpec("/path/to/Growl/growl.spec"); * This will provide you with five new intrinsics: Growl HowlInit Howl BoxcarInit Boxcar If you use this package regularly, you could put the AttachSpec command in your Magma startup file (usually ~/.magmarc). If you're using Howl or Boxcar, the appropriate HowlInit or BoxcarInit command could be added to that file as well. Growl ----- Growl (http://growl.info/) is a popular notification system for Mac OS X that allows applications to send you messages. It provides a unified, non-obtrusive way to be informed about activity on your system. To send a Growl notification from within Magma, simply call: > Growl("Title", "Message"); Howl ---- Howl (http://howlapp.com/) extends Growl notifications to iOS devices such as the iPhone and iPad. Using "push notifications", Howl allows you to send messages to your iPhone, iPod touch, or iPad, from any computer that has access to the internet. At the start of each Magma session you must set your Howl username and password: > HowlInit("Username", "Password"); (Note: You only need to call HowlInit once per Magma session.) Once you've done that, a Howl notification can be issued at any time via: > Howl("Title", "Message"); Boxcar ------ Boxcar (http://boxcar.io/) takes the idea of Growl and extends it to iOS devices such as the iPhone and iPad. Once you've registered Magma with your Boxcar account, you'll be able to send messages to your iOS device from any copy of Magma that has access to the internet. IMPORTANT: Before you can send messages from Magma to Boxcar, you MUST REGISTER Magma with Boxcar. You only need to do this once per Boxcar account. To do this, run the "boxcar_register" script (located in the same directory as this README.txt file) ./boxcar_register you@email.address using the e-mail address associated with your Boxcar account. At the start of each Magma session you must set your Boxcar e-mail address: > BoxcarInit("me@example.com"); (Note: You only need to call BoxcarInit once per Magma session.) Once you've done that, a Boxcar notification can be issued at any time via: > Boxcar("Message"); (Note: Unlike Growl and Howl, the Boxcar interface does not allow you to set a title for your message.) Sending Growl Notifications over a Network ------------------------------------------ If you want to receive notifications from machines other than your own computer, you will need to enable network notifications and registration. The settings are in System Preferences... -> Growl, under the "Network" tab. Note that you MUST set a nonempty password for the network notifications to work. If you're running a firewall, your machine will need to be able to receive data over TCP port 23052 and UDP port 9887. Growl notifications can be sent over the network from any machine that has either Python or PHP installed. Within Magma, you can specify the target address and password via two optional parameters: > Growl("Title", "Message" : address="192.168.0.3", password:="secret"); You can also specify the address and password via the environment variables MAGMAGROWL_ADDRESS and MAGMAGROWL_PASSWORD. Using curl with Howl and Boxcar ------------------------------- Both Howl and Boxcar require the command line tool "curl" to access the internet. If necessary, you can specify the path to curl via the environment variable CURL_PATH. Customising Howl ---------------- The Howl intrinsic supports a number of parameters to allow you to customise your notification. These are: application - The name of the application sending the notification (default: "Magma"). name - The name of the notification (default: "howl"). icon - The named icon to use (default: "warning"). hostname - The hostname to use (default: the machine's hostname). A list of named icons are available from the Howl web site at: http://howlapp.com/interface-icons.html Boxcar and the "E-mail address is not registered with this provider" error -------------------------------------------------------------------------- Before Magma can send notifications to your Boxcar account, you must grant it permission. You only need to do this once per Boxcar account. To register Magma with your Boxcar account, run the "boxcar_register" script (located in the same directory as this README.txt file). You will need to pass the e-mail address associated with your Boxcar account: ./boxcar_register you@email.address