Proposed/revised API for org.bluez.audio.control (AVRCP)

["David Stockwell" <dstockwell@frequency-one.com>]

[-- Attachment #1.1: Type: text/plain, Size: 1614 bytes --]

I have revised and updated the AVRCP API proposal, submitted in March.

I agree that the previous version was too complicated, and have encapsulated everything having to do with UnitInfo and SubUnitInfo into the internals (most of those elements are fixed anyway, and can be set in the audio.conf file).

With regards to the rest, I propose to provide two ways to handle Passthrough messages received; by uinput for integration with GStreamer and the like, and by signal, which will pass not only the keystroke itself, but the vendor dependent data allowed for in the spec (AVRCP with Metadata Transfer, published by the BT SIG).

I propose to handle Metadata as a sub-class or specialization of VendorDependent, without taking away the ability to create one's own VendorDependent messages.  I am thinking that to send a batch of Metadata, one would create it as a string-variant dict, with the string being a key to identify what the thing to be transmitted is (and hence how to interpret/translate it, per the spec).  The internal plumbing will take care of batching all of it into a VendorDependent and shipping it off.

With respect to handling basic Passthrough and Metadata, this should cover it, and provide very good functionality for most applications.

The spec also provides for numerous events and responses; I am still reviewing them to see how or if these can or should be implemented.  It does appear that some of these would require a greater level of integration with the overall "playing" application to handle these within this module, which IMHO is not a good idea.

David Stockwell

[-- Attachment #1.2: Type: text/html, Size: 2146 bytes --]

[-- Attachment #2: avrcp-api-v0.1.txt --]
[-- Type: text/plain, Size: 3039 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:
	dict	GetProperties()
		GHashTable with named properties and variant values.

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

	void	ConnectResponse(boolean response)
		Respond to ConnectedRequested from remote device.
		Respond TRUE if granting connection request.

	void	Disconnect()
		Disconnect from remote device.

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

	boolean SendVendorDependent(uint16 sizeof_op_data, const void * op_data)
		Called to send VendorDependent commands, other than Metadata.

	void *	FetchVendorDependent(uint16 sizeof_op_data)
		Called to retrieve VendorDependent commands, other than Metadata.

	void	SendMetadata(uint8 pdu_id, dict meta_data)
		Called to send Metadata commands (a subset of the
		VendorDependent message). Multiple key/element pairs.

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

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

		ConnectRequested(string address)
		Sent when a remote device wishes to connect.  Return value is BT address
		of connecting device (might be Device path instead...)

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

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

		VendorDependentReceived(uint16 sizeof_op_data, const void * op_data)
		Called when VendorDependent message is received from connected device
		(except for Metadata).

		MetadataReceived(dict metadata)
		Called when Metadata is received from connected device.  May be multiple
		meta attribute/element pairs.

Properties:
	string	Address [readonly]
		Bluetooth Device Address of the connected device.

	string	Name [readonly]
		The Bluetooth "friendly name" from the connected device.

	uint8	SubUnitID [readonly]
		The three-bit Subunit ID from the connected device (per the spec).

	uint8	SubUnitType [readonly]
		The five-bit Subunit Type from the connected device (per the spec).

	array{uint} CompanyIDs [readonly]
		List of three-byte Company IDs (OUI) from the connected device.

	array{uint8} Capabilities [readonly]
		List of Capabilities provided by the connected device.

Note that many of the items supporting AVRCP and the Metadata Extension are essentially
fixed from the standpoint of the application running in the Linux box.  To simplify the
API, these are best handled by setting them up statically in the audio.conf file.

A list of these attributes and possible settings will be submitted in the very near future.

[-- Attachment #3: audio.conf --]
[-- Type: application/octet-stream, Size: 1476 bytes --]

# Configuration file for the audio service

# This section contains options which are not specific to any
# particular interface
[General]

# Switch to master role for incoming connections (defaults to true)
#Master=true

# If we want to disable support for specific services
# Defaults to supporting all implemented services
#Disable=Control,Source
Disable=Headset,Gateway,Sink,Source
Enable=Control

# SCO routing. Either PCM or HCI (in which case audio is routed to/from ALSA)
# Defaults to HCI
#SCORouting=PCM

# Headset interface specific options (i.e. options which affect how the audio
# service interacts with remote headset devices)
[Headset]

# Set to true to support HFP (in addition to HSP only which is the default)
# Defaults to false
HFP=false

# HFP Gateway features
# Defaults to false
3WayCalling=false
EchoCancelNoiseCancel=false
VoiceRecognition=false
InBandRingtone=false
VoiceTags=false
RejectingCalls=false
EnhancedCallStatus=false
EnhancedCallControl=false
ExtendedErrorResultCodes=false

# Just an example of potential config options for the other interfaces
#[A2DP]
#SBCSources=1
#MPEG12Sources=0

# Configuration for Control/AVRCP Implementation
[Control]
Role=Target  # Role of Bluez server.  Other options: Controller, Both
Company=FFFFFF # For Metadata transfer, BT SIG 001958 is assumed/standard
SubunitID=0
SubunitType=9
PassthroughUinput=false
PassthroughSignal=true
EnableMetadata=true
#