I posted this question and since it didn't receive any replies, I had to figure it out for myself. Here is what I learned: I'll describe both what "mute-agent.py" does and an *error* in the default Bluetooth configuration that prevents it from working properly.
BlueZ is the preferred Bluetooth stack implementation included in Linux 2.6. (
http://www.bluez.org/). To "pair" with a bluetooth computer, a little program that prompts the user for permission is required. This program is a bluetooth pincode "agent." In many Linux distributions this program is called /usr/bin/simple-agent.py. (Here's a pretty good explanation of it:
http://wiki.openmoko.org/wiki/Manually_using_Bluetooth).
The Plug doesn't have a default window environment, so there isn't a standard way to prompt a user for permission. Instead, the development Plug has a simplified agent that accepts pairing with anyone and offers a fixed pincode of "0000." This type of bluetooth agent has been described here:
http://it-result.me/bluetooth-network-on-linux/Summary: in most Linux distributions the Bluetooth agent is called "simple-agent.py" Our Plug distribution with fixed pincode and no prompting for permission is called "mute-agent.py."
These two articles helped me to understand what the agent was supposed to do. However, once understanding this I was still unable to "pair" with the Plug. If I initiated pairing from a Mac I observed the following error in /var/log/syslog.
Aug 31 16:26:24 debian hcid[1609]: Agent replied with an error: org.freedesktop.DBus.Error.AccessDenied, Rejected send message, 1 matched rules; type="method_call", sender=":1.0" (uid=0 pid=1609 comm="/usr/sbin/hcid -x -s ") interface="org.bluez.Agent" member="RequestPinCode" error name="(unset)" requested_reply=0 destination=":1.1" (uid=0 pid=1768 comm="/usr/bin/python /usr/bin/mute-agent "))For some reason, the mute-agent was not given permission by dbus.
Upon more reading, I found some information about configuring permissions for dbus. The file /etc/dbus-1/system.d/bluetooth.conf grants permissions for specific interfaces. Our mute-agent is using the interface "org.bluez.Agent" and it was not granted permission in the distributed bluetooth.conf. (I'm guessing that in other versions of BlueZ utilities, the agent is named "PasskeyAgent" or "AuthorizationAgent". Ours is named "Agent" and is not granted.) I added the line below marked with
!!!!. The I restarted the Plug.
/etc/dbus-1/system.d/bluetooth.conf
<policy user="root">
<allow own="org.bluez"/>
<allow send_destination="org.bluez"/>
<!-- allow root to send to agents -->
<allow send_interface="org.bluez.PasskeyAgent"/>
<allow send_interface="org.bluez.Agent"/> !!!!
<allow send_interface="org.bluez.AuthorizationAgent"/>
</policy>
Hope this helps someone else new to working with Bluetooth on Linux.
-T
