[Bluez-devel] Proposed API for org.bluez.audio.control (AVRCP)

[Bluez-devel] Proposed API for org.bluez.audio.control (AVRCP)

[David Stockwell]

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

Marcel, Johan, Brad, et al:

As promised, I have laid out a first draft interface for .control, which is 
largely based on AVRCP support provided by CSR.

It appears that the *-api.txt documents are created with groff (or something 
like that); this document I just quickly hacked together in KWrite (similar 
to MS Notepad).

Any and all comments will be appreciated.

-- 
David Stockwell
Frequency One

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

org.bluez.audio.Control interface

This interface is available for remote devices which implement support for an
AVRCP controller and target.

Object path(s)	/org/bluez/audio/device*

Methods:
	void	Connect(uint8 role)
		Request connection between this node and remote device.
		Role is role of THIS node in the connection, {CT|TG|CT&TG}.

	void	Disconnect()
		Disconnect from the remote device.

	boolean IsConnected()
		Returns TRUE if connected with the remote device.

	boolean GetUnitInfo()
		Sends UnitInfo command to target of connection

	boolean SendUnitInfo(boolean accepted,
			uint8 avc_subunit_type, uint16 unit, uint32 company_id)
		Called to send UnitInfo (in response to a UnitInfoRequested signal).
		NOTE:	Once this is set, should it be possible to auto-respond to
			future UnitInfoRequested signals?

	boolean GetSubUnitInfo(uint8 page)
		Sends UnitInfo command to target of connection

	boolean SendSubUnitInfo(boolean accepted, uint8 page,
			const uint8 * page_data)
		Called to send a page of SubUnitInfo (in response to a
		SubUnitInfoRequested signal).

	boolean SendPassthrough(uint8 avc_subunit_type,
			uint8 avc_subunit_id, boolean state, avc_operation_id key,
			uint16 sizeof_op_data, const uint8 * op_data)
		Called to send Passthrough commands.

	boolean SendVendorDependent(uint8 avc_subunit_type,
			uint8 avc_subunit_id, uint8 ctype, uint32 company_id,
			uint16 sizeof_op_data, const uint8 * op_data)
		Called to send VendorDependent commands (also used internally for
		Metadata).

	void	SendMetadata(uint8 avc_subunit_type,
			uint8 avc_subunit_id, uint8 ctype,
			{uint16 meta_attr, const char * meta_element})
		Called to send Metadata commands (a subset of the
		VendorDependent message). May be multiple meta attribute/element pairs.

Signals:
	void	Connected()
		Sent when a successful connection has been made to the remote device.

	void	Disconnected()
		Sent when a connection to the remote device has been disconnected.

	void	ConnectRequested(string address, uint8 role)
		Sent when a remote device wishes to connect.

	void	DisconnectRequested()
		Sent when a connected remote device wishes to disconnect.

	void	UnitInfoRequested()
		Received when another connected device requests UnitInfo.

	void	UnitInfoReceived(boolean accepted,
			uint8 avc_subunit_type, uint16 unit, uint32 company_id)
		Called when response to GetUnitInfo is received from connected
		device.

	void	SubUnitInfoRequested(uint8 page)
		Received when another connected device requests SubUnitInfo

	void	SubUnitInfoReceived(boolean accepted, uint8 page,
			const uint8 * page_data)
		Called when response to GetSubUnitInfo is received from connected device.

	void	PassthroughReceived(uint8 avc_subunit_type,
			uint8 avc_subunit_id, boolean state, avc_operation_id key,
			uint16 sizeof_op_data, const uint8 * op_data)
		Called when Passthrough command is received from connected device.

	void	VendorDependentReceived(uint8 avc_subunit_type,
			uint8 avc_subunit_id, uint8 ctype, uint32 company_id,
			uint16 sizeof_op_data, const uint8 * op_data)
		Called when VendorDependent message is received from connected device
		(except for Metadata).

	void	MetadataReceived(uint8 avc_subunit_type,
			uint8 avc_subunit_id, uint8 ctype,
			{uint16 meta_attr, const char * meta_element})
		Called when Metadata is received from connected device.  May be multiple
		meta attribute/element pairs.

[-- Attachment #3: Type: text/plain, Size: 278 bytes --]

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace

[-- Attachment #4: Type: text/plain, Size: 164 bytes --]

_______________________________________________
Bluez-devel mailing list
Bluez-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/bluez-devel

Re: [Bluez-devel] Proposed API for org.bluez.audio.control (AVRCP)

[Marcel Holtmann]

Hi David,

> As promised, I have laid out a first draft interface for .control,  
> which is
> largely based on AVRCP support provided by CSR.

I think it is a little bit too complex. Lets make this easier and put  
the logic and intelligence into the daemon. Please write down what you  
really do need by this API and don't try to export everything.

> It appears that the *-api.txt documents are created with groff (or  
> something
> like that); this document I just quickly hacked together in KWrite  
> (similar
> to MS Notepad).

It is free from :)

Regards

Marcel


-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace
_______________________________________________
Bluez-devel mailing list
Bluez-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/bluez-devel

Re: [Bluez-devel] Proposed API for org.bluez.audio.control (AVRCP)

[David Stockwell]

Marcel,

Thank you for your brief critique.

I believe a couple of message exchanges that could be buried into the daemon is the UnitInfo and SubUnitInfo, at least from the TG 
side, because the information for these is constant for any application (perhaps in a .conf file).  There is probably no need for 
the application to receive a signal indicating that something has requested Unit- or SubUnitInfo, and no need to construct and send 
that response.

However, a TG application may need to query and receive Unit and SubUnitInfo; this could be buried into the establishment of the 
link, which as far as I can tell takes place when opening the Device; I am still digging through the code.

I expressed a need (in a Connect method) to select whether the application running in "this" box, connecting to "this" side of the 
DBus is CT, TG, or both.  If only one-sided, it makes no sense to add both CT and TG records to SDP.  This is also constant for the 
application.

As far as other requirements go from my standpoint, I need full access to sending Metadata from TG to a remote CT using the 
VendorDependent message.  I did propose two methods: SendVendorDependent and SendMetadata (specifically for metadata).

I also need full access to Passthrough for receiving messages from a remote CT.  With respect to Passthrough, I believe receiving a 
signal is the better way to go (not just the key pressed, but also the vendor dependent operation_data_field).  I know the current 
implementation converts a subset of the messages received to simple "keystrokes" sent with /dev/uinput.  Maybe Johan could inform us 
of what he intended: his requirements, advantages, limitations, etc.

As far as my approach goes, there are obviously things that will be moved around, deleted, and rethought.  For now I intend to use 
the document I submitted as initial guidance and as a checklist until I have a complete working model: it's usually easier to cut 
out than to add later.

Incidentally, one of the other things that I have to think about when dealing with metadata is internationalization: displayable 
character set, passing non-Western character data, etc.

Thanks again for your comments.

All the best,

David Stockwell

----- Original Message ----- 
From: "Marcel Holtmann" <marcel@holtmann.org>
To: <dstockwell@frequency-one.com>; "BlueZ development" <bluez-devel@lists.sourceforge.net>
Sent: Sunday, March 30, 2008 10:19 PM
Subject: Re: [Bluez-devel] Proposed API for org.bluez.audio.control (AVRCP)


Hi David,

> As promised, I have laid out a first draft interface for .control,
> which is
> largely based on AVRCP support provided by CSR.

I think it is a little bit too complex. Lets make this easier and put
the logic and intelligence into the daemon. Please write down what you
really do need by this API and don't try to export everything.

> It appears that the *-api.txt documents are created with groff (or
> something
> like that); this document I just quickly hacked together in KWrite
> (similar
> to MS Notepad).

It is free from :)

Regards

Marcel

Re: [Bluez-devel] Proposed API for org.bluez.audio.control (AVRCP)

[Johan Hedberg]

Hi David,

On Apr 2, 2008, at 17:02, David Stockwell wrote:
>
> I expressed a need (in a Connect method) to select whether the  
> application running in "this" box, connecting to "this" side of the
> DBus is CT, TG, or both.  If only one-sided, it makes no sense to  
> add both CT and TG records to SDP.  This is also constant for the
> application.

In a multi-application environment where e.g. volume-up/down messages  
can be sent to the headset (which implies CT role) with the help of D- 
Bus method calls, you can't really know if some application is going  
to use those methods or not. They might even come from a different  
application than the one that called Connect and the two applications  
might not know about each other. However, if you have some really  
embedded system with full control over what can and what cannot happen  
we can of course add the possibility to disable TG or CT service  
records and interfaces through an audio.conf option.

> As far as other requirements go from my standpoint, I need full  
> access to sending Metadata from TG to a remote CT using the
> VendorDependent message.  I did propose two methods:  
> SendVendorDependent and SendMetadata (specifically for metadata).

The idea so-far regarding metadata is that it could be communicated  
over the unix socket from the client (alsa/gstreamer/pulse/something  
else) to the audio service. As I've understood it, gstreamer even has  
some native support for this so you could get a "works out of the box"  
experience with existing gstreamer based players. However, if you have  
clear requirements where this is not enough (btw, it'd help if you  
could give some more details of your requirements and usecases), I'm  
sure we can add an interface to fulfill them.

> I also need full access to Passthrough for receiving messages from a  
> remote CT.  With respect to Passthrough, I believe receiving a
> signal is the better way to go (not just the key pressed, but also  
> the vendor dependent operation_data_field).  I know the current
> implementation converts a subset of the messages received to simple  
> "keystrokes" sent with /dev/uinput.  Maybe Johan could inform us
> of what he intended: his requirements, advantages, limitations, etc.

The use of uinput was simply a consensus reached at a BlueZ developer  
meeting some time (1 year?) ago. The idea was that as many  
applications as possible could benefit of AVRCP with very small or no  
changes to their code. I.e. the appllications don't even have to know  
that there exists something called bluetooth or AVRCP. E.g. right now  
you can hack most X based media players to work with AVRCP on Linux.  
However, at no point has it been ruled out that other interfaces for  
AVRCP TG role could be added too if necessary and if you come up with  
a nice interface and a valid set of use cases/requirements it fulfills  
I'm sure we can integrate it to BlueZ.

Johan

-------------------------------------------------------------------------
Check out the new SourceForge.net Marketplace.
It's the best place to buy or sell services for
just about anything Open Source.
http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace
_______________________________________________
Bluez-devel mailing list
Bluez-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/bluez-devel