RFC: New Handsfree Client Role API

RFC: New Handsfree Client Role API

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 702 bytes --]

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

[-- Attachment #2: hfp-api.txt --]
[-- Type: text/plain, Size: 2314 bytes --]

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.

Re: RFC: New Handsfree Client Role API

[Johan Hedberg]

Hi Denis,

On Thu, Nov 05, 2009, Denis Kenzior wrote:
> Properties	boolean Connected [readonly]
> 
> 			Indicates if there is an active connection to the
> 			AG service on the remote device.

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).

> 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.

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

Re: RFC: New Handsfree Client Role API

[Luiz Augusto von Dentz]

Hi Denis,

On Thu, Nov 5, 2009 at 2:42 PM, Denis Kenzior <denkenz@gmail.com> wrote:
> 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.

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.

> 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.

Pretty good, fd seems to fit very nicely here.

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

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

Re: RFC: New Handsfree Client Role API

[Denis Kenzior]

[-- Attachment #1: Type: text/plain, Size: 854 bytes --]

Hi Johan,

> > Properties	boolean Connected [readonly]
> >
> > 			Indicates if there is an active connection to the
> > 			AG service on the remote device.
>
> 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).

Sure, updated.

>
> 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).

Yep, good catch.

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

Regards,
-Denis

[-- Attachment #2: hfp-api.txt --]
[-- Type: text/plain, Size: 2297 bytes --]

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.

Re: RFC: New Handsfree Client Role API

[João Paulo Rechi Vita]

On Thu, Nov 5, 2009 at 17:22, Denis Kenzior <denkenz@gmail.com> wrote:
> Hi Johan,
>
>> > Properties  boolean Connected [readonly]
>> >
>> >                     Indicates if there is an active connection to the
>> >                     AG service on the remote device.
>>
>> 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).
>
> Sure, updated.
>

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/

Re: RFC: New Handsfree Client Role API

[Luiz Augusto von Dentz]

Hi,

2010/1/11 João Paulo Rechi Vita <jprvita@gmail.com>:
> On Thu, Nov 5, 2009 at 17:22, Denis Kenzior <denkenz@gmail.com> wrote:
>> Hi Johan,
>>
>>> > Properties  boolean Connected [readonly]
>>> >
>>> >                     Indicates if there is an active connection to the
>>> >                     AG service on the remote device.
>>>
>>> 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).
>>
>> Sure, updated.
>>
>
> 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/
>

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