User Tools

Site Tools


Sidebar

tutorials:prowl

Sending PROWL iPhone Alerts from XTension

Prowl is an excellent iPhone app that acts as a receiver for remote notifications. It comes with a plugin for Growl, so if you're already using that you can plug directly into it. I've never had too much luck getting Growl to reliably alert me due to it's interesting networking model so the real value to me in Prowl is that it has a direct API that we can talk to in XTension without ever having to go through Growl, or even having to have it installed.

app store link to purchase Prowl You'll first need to purchase the prowl app. XTension is not affiliated directly with Prowl we just love the app. Once you have the app installed you need to setup an account on his server. iPhone popup alerts require that they go through a centralized server and you use of the prowl server is included in the price of the app. Next you'll need to create an “API Key” that XTension can use to directly contact your iPhone which you can do on the prowl site's settings page

SO now you have a program that can receive the alert, a server through whom you can sent the alert, now you just need something in XTension that can start the process off. There are a couple of extra steps involved here to make sure that XTension isn't held out or slowed down by an unresponsive server or a slow network or a cable modem that someone unplugged. In order to make sure that no matter what XTension keeps going we need to offload the actual request to the server to a separate applescript applet. This is just an applescript program that runs as a separate app and not inside of XTension like the rest of the scripts.

UPDATE 5/28/14 it is no longer necessary to use the external separate app. As of XTension version 854 I’ve added the “loadurl” command which will do the calling in the background and not interrupt XTension. So you can just cut and past this script text into a global script named “Prowl”.

UPDATE 3/31/16 Recently the older notification server address was replaced. Where the original script sent alerts to “https://prowl.weks.net/publicapi/add” the new server address is “https://api.prowlapp.com/publicapi/add” and just changing that in the loadURL command in the script will get things working again. I have updated the script below to reflect this change.

--prowl helper script to send prowl notifications to iPhone
 
on SendProwlNotification(ThePriority, TheDescription, TheEvent)
 
	-- PROWL HELPER APP *\
	-- for XTension to send notifications to iPhone via prowl *\
	-- prowl is an app for iPhone available from prowl.weks.net *\
	-- this script by James Sentman james@sentman.com *\
	-- version 1.0 8/5/09 
	-- version 2.0 5/28/14 *\
        -- version 2.1 3/31/16 (new notification server address)
 
	write log "sending prowl notification " & TheEvent & ": " & TheDescription
 
 
	--generate your own API key from https://prowl.weks.net/settings.php
 
	set MyAPIKey toput your Prowl API code here!"
	set MyApplicationName to "XTension"
	--
	--  ThePriority: -2 to 2
	--  TheEventName: short string description i.e. "preimeter alarm"
	--  TheDescription: longer description i.e. "Front Door Open"
 
	--build the form elemenets to pass as a list to the loadURL command
	set MyParams to {"apikey=" & MyAPIKey, ¬
		"priority=" & ThePriority, ¬
		"application=" & MyApplicationName, ¬
		"event=" & TheEvent, ¬
		"description=" & TheDescription}
 
 
	loadurl "https://api.prowlapp.com/publicapi/add" post data MyParams ¬
		callback script (thisScript) callback handler "gotresult" timeout 90
 
 
 
 
end SendProwlNotification
 
on gotresult(replyCode, replyText)
	if "success" is in replyText then
 
		write log "Prowl Notification Sent"
 
 
	else
 
 
		write log "ERROR FROM PROWL: (" & replyCode & ") " & MyReply
 
 
	end if
 
end gotresult

if you are using an older version of XTension then you can use this separate app:

prowl_helper.zip

To see the source just drag and drop it onto the script editor. You will need to cut and paste your API code you received from the settings page into this script. Where to put it should be clearly marked at the top of the code. Then just re-save the app. for the older method use this as the global script “Prowl” code.

--prowl helper script to send prowl notifications to iPhone
 
on SendProwlNotification(ThePriority, TheEvent, TheDescription)
 
 
    --check the global switch before we do anything
 
    if (status of "Send Prowl Alerts") is false then
 
      --you've turned off alerts, so nothing will be sent, but we'll log it anyway
 
      write log "Prowl alert not sent: " & TheEvent & ": " & TheDescription
      return
    end if
 
 
 
 
	write log "sending prowl notification " & TheEvent & ": " & TheDescription
 
	ignoring application responses
		tell application "Prowl Helper"
			SendIntProwlNotification(ThePriority, TheEvent, TheDescription)
		end tell
	end ignoring
 
end SendProwlNotification

All other code and methods here are the same regardless of your using the new or the old method.

Make a global switch to turn it on and off

Now you need a global switch to turn prowl notifications on and off. Perhaps you'll create a schedule to turn this off at 11pm or whenever you run your going to bed script, except when you're on vacation or away from the house or something like that. In any case it is very helpful to be able to turn them off easily without having to edit a script. I created a new pseudo unit and called it “Send Prowl Alerts”. The global script we're going to create in the next step checks that status before doing anything.

Now actually send the alert

The simplest way to actually generate an alert is to call that script from the ON script or any motion sensor or any door or window or other sensor logging an event you want to send an alert for. For example in the ON script of the front door sensor you might put

tell xGLobalScript "prowl" to SendProwlNotification( 2, "Front Door Open", (current date) as text)

and at some time later, either almost immediately or quite a bit later depending on how backed up Apples servers are you'll get the tone, buzz and a message on your iPhone! In the case of this test alert it took almost 4 minutes to appear, but it's often almost instant. I hope Apple or AT&T or whoever is responsible for the slowdowns to get their infrastructure fixed up. I have the same problem when experimenting with other apps that serve up alerts so it's not limited to just Prowl.

Improvements for easy scripting, use a Group

The best way to manage lists of units or devices that send various alerts is via a group. This way units can easily be added or removed without having to mess with the scripts themselves. A group's ON script receives an event you can use anytime any of the units in the group change their value.

You can even customize the script to look up the current label assigned to the unit, so if you've assigned “open” and “closed” to the window/door units and motion, safe for the motion units they can send the appropriate text to the alert.

Create a group called “Prowl Perimeter Alerts” or whatever makes sense to you. Then in the ON script add a handler like:

  on GroupMemberChanged(TheUnit, TheValue)
 
	--only report ON's
 
	if (TheValue is greater than 0) then
            tell xGlobalScript "Prowl" to SendProwlNotification( 2, TheUnit, "was opened at " & ((current date) as text)
       	end if
 
end GroupMemberChanged

More Information

If you're more attached to Twitter than Growl or want to be able to follow your house remotely via a twitter client please have a look at Gordon Meyer's excellent article Twittering Your Home where he talks about getting his XTension system talking directly to twitter.

It is very important to let the prowl app load up once in a while. If you don't load it and let it log in every so often you'll eventually stop receiving alerts.

UPGRADING

I’ve noticed a problem with this, and other applescript saved as applications, when upgrading a MacOS machine. If you’re getting a new machine and upgrading from an old PPC to an Intel machine you may not be able to run them. The problem is that the previous OS saved the application as a PPC app if it was a PPC computer and with Lion now you can no longer run PPC applications. Luckily the fix is simple. Just drag the un-runnable applescript application onto the script editor and it will open. Then save it again as an application and make sure the “stay open” checkbox is checked and the “startup screen” is NOT checked. The new system will re-create it as an intel app and all will be well again.

tutorials/prowl.txt · Last modified: 2016/03/31 12:34 (external edit)