RFC: New Handsfree Client Role API

Hi Everyone,

As you know we're currently working to add support for Handsfree Profile (HFP) as another possible backend for oFono. The missing piece is audio integration which is done in BlueZ.

Proposed is an API for such integration between BlueZ and an AT engine that will implement the Handsfree Profile Client role. The API will replace the current org.bluez.HeadsetGateway interface, if accepted.

An interesting thing to note here is that the API will utilize DBus 1.3+ capability for file-descriptor passing to pass the RFCOMM socket from bluetoothd to oFono.

This API has passed first round of review, but further comments, suggestions and refinements are welcome.

Regards,
-Denis

Gateway hierarchy
========================

Service org.bluez
Interface org.bluez.Gateway
Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX

This interface is available for remote devices which can function in the Audio Gateway role of the HFP profiles. It is intended to be used with external telephony stacks / handlers of the HFP protocol.

Methods void Connect()

Connect to the AG service on the remote device.

void Disconnect()

Disconnect from the AG service on the remote device

dict GetProperties()

Returns all properties for the interface. See the properties section for available properties.

Signals PropertyChanged(string name, variant value)

This signal indicates a changed value of the given property.

Properties boolean Connected [readonly]

Indicates if there is an active connection to the AG service on the remote device.

HandsfreeManager hierarchy
===============

Service org.bluez
Interface org.bluez.HandsfreeManager
Object path [variable prefix]/{hci0,hci1,...}

This interface is available on adapters which support audio related profiles. It can be used to register Handsfree agents with the system.

Methods void RegisterHandsfreeAgent(object path)

The object path defines the path the of the agent that will be called when a new Handsfree connection is established.

If an application disconnects from the bus all of its registered agents will be removed.

void UnregisterHandsfreeAgent(object path)

This unregisters the agent that has been previously registered. The object path parameter must match the same value that has been used on registration.

HandsfreeAgent hierarchy
===============

Service         unique name
Interface       org.bluez.HandsfreeAgent
Object path     freely definable

Methods void NewConnection(object device, filedescriptor fd)

This method gets called whenever a new handsfree connection has been established. The objectpath contains the object path of the remote device. This method assumes that DBus daemon with file descriptor passing capability is being used.

Possible Errors: org.bluez.Error.InvalidArguments
org.bluez.Error.Failed

void Release()

This method gets called whenever the service daemon unregisters the agent.

Hi Denis,

In addition to (or instead of) this property we could also have a string State property which would also communicate the "connecting" and "playing" states. This is what we have for some other interfaces and it has proved to be useful there (not sure if that'll be equally true for this new interface but it's still worth considering).

As discussed on the #ofono channel, you might want to add here that the assumption is that the agent responds to this method only after it has completed the establishment of the SLC (or when it chooses to reject the connection).

Johan

Hi Johan,

Sure, updated.

Yep, good catch.

Here's the updated API based on more discussion on #ofono.

Regards,
-Denis

Gateway hierarchy
========================

Service org.bluez
Interface org.bluez.HandsfreeGateway
Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX

This interface is available for remote devices which can function in the Audio Gateway role of the HFP profiles. It is intended to be used with external telephony stacks / handlers of the HFP protocol.

Methods void Connect()

Connect to the AG service on the remote device.

void Disconnect()

Disconnect from the AG service on the remote device

dict GetProperties()

Returns all properties for the interface. See the properties section for available properties.

void RegisterAgent(object path)

The object path defines the path the of the agent that will be called when a new Handsfree connection is established.

If an application disconnects from the bus all of its registered agents will be removed.

void UnregisterAgent(object path)

This unregisters the agent that has been previously registered. The object path parameter must match the same value that has been used on registration.

Signals PropertyChanged(string name, variant value)

This signal indicates a changed value of the given property.

Properties string Connected [readonly]

Indicates the state of the connection. Possible values are:
"disconnected"
"connecting"
"connected"
"playing"

HandsfreeAgent hierarchy
===============

Service         unique name
Interface       org.bluez.HandsfreeAgent
Object path     freely definable

Methods void NewConnection(filedescriptor fd)

This method gets called whenever a new handsfree connection has been established. The objectpath contains the object path of the remote device. This method assumes that DBus daemon with file descriptor passing capability is being used.

The agent should only return successfully once the establishment of the service level connection (SLC) has been completed. In the case of Handsfree this means that BRSF exchange has been performed and necessary initialization has been done.

Possible Errors: org.bluez.Error.InvalidArguments
org.bluez.Error.Failed

void Release()

This method gets called whenever the service daemon unregisters the agent.

I guess you forgot to update the property name to "State", making it consistent with the audio API. BTW, is this the latest version of the API spec so far, or there were further discussions on that on IRC?

João Paulo Rechi Vita
http://jprvita.wordpress.com/

Hi,

2010/1/11 João Paulo Rechi Vita <[email protected]>:

What about merging part of this spec with Media spec, that would mean we not only can register endpoints that implements MediaEndpoint, but also MediaControlEndpoint or both.

This also means org.bluez.HandsfreeGateway doesn't need to register its own agents and the transport can be acquired via MediaControlTransport interface. The only real difference is that the endpoint registration is per adapter instead of per device as HandsfreeGateway is, but maybe this is no big deal.

Luiz Augusto von Dentz
Engenheiro de Computação

Hi Denis,

I wonder if we couldn't create something more generic for telephony as SAP could use the same agent, although SAP doesn't use AT commands there are some overlap between handsfree Profile and Sim Access. Also I prefer just RegisterAgent and UnregisterAgent, the interface already has Handsfree in its name.

Pretty good, fd seems to fit very nicely here.

In general I prefer this Agent based (runtime) mechanism rather than having those telephony drivers in BlueZ (buildtime), even for server role, it is much easier to test (no rebuild and restart) and also very convenient if e.g. the platform needs to talk to something (telepathy) in session bus, in that case the agent process just need to connect to both system and session bus but the driver can't do that since we don't know about session.

Luiz Augusto von Dentz
Engenheiro de Computação