# vim:ts=4:et:tw=72
# $Id: README,v 1.5 2007/02/24 22:54:42 jcs Exp $

blueping
------------------------------------------------------------------------
by joshua stein <jcs@jcs.org>                            http://jcs.org/

blueping is a simple command-line utility for mac os x (>=10.4) that
"pings" a bluetooth device in a loop, optionally executing programs when
the device is reachable (within range) and/or not reachable (out of
range).

blueping is released under a bsd license.

the following options are available:

    -d MAC  (required) the mac address of the device, in the format
            01-23-45-67-89-01 or 012345678901.  can be found by opening
            the system bluetooth preferences and locating the "device
            address" of the device.

            the device must be paired and configured prior to using it
            with blueping.

    -e PROG (optional) a string to execute when the device enters range
            and is reachable.  passed directly to sh(1).

    -i NUM  (optional) the interval, in seconds, to ping the device.
            the default is 15 seconds.  not recommended to be under 5
            seconds.

    -v      (optional) be verbose and log to STDOUT.  specify this
            option twice to be even more verbose.

    -x PROG (optional) a string to execute when the device exits range
            and is no longer reachable.  passed directly to sh(1).

examples of usage:

    when i walk away carrying my cell phone, lock the screen:

        blueping -d 00-14-9a-d8-10-18 -v -x "/System/Library/Frameworks/ScreenSaver.framework/Resources/ScreenSaverEngine.app/Contents/MacOS/ScreenSaverEngine"

    when my cell phone comes into range, run a helper script that checks
    the last time that iSync completed and if it has been over a certain
    amount of days, launch iSync and auto-synchronize:

        blueping -d 00-14-9a-d8-10-18 -v -e "/Users/jcs/bin/blueping-isync"

    when i walk away carrying my cell phone, pause itunes, then unpause
    it when i return:

        blueping -d 00-14-9a-d8-10-18 -v \
            -e "osascript -e 'tell application "'"iTunes"'" to play'" \
            -x "osascript -e 'tell application "'"iTunes"'" to pause'"