[RFC BlueZ] mgmt-api: Broadcaster/Observer management API

[RFC BlueZ] mgmt-api: Broadcaster/Observer management API

[Anderson Lizardo]

Hi,

This is a proposal for new Management API commands to allow implementing
Broadcaster/Observer roles in BlueZ. It can also be used to add information to
EIR on BR/EDR controllers.

Comments and suggestions are welcome. If anyone has a better name for the "Set
Controller Data" and "Remove Controller Data" commands (that are not LE
specific), let us know.


Anderson Lizardo (1):
  mgmt-api: Broadcaster/Observer management API

 doc/mgmt-api.txt |   70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

-- 
1.7.9.5

[RFC BlueZ] mgmt-api: Broadcaster/Observer management API

[Anderson Lizardo]

Add new management commands for enabling or disabling broadcasting and
observation modes, as defined by the Observer and Broadcaster GAP roles
on the Core specification 4.0.

The commands can also be used for adding information to EIR on BR/EDR
controllers. For a list of all available AD/EIR types, see the Core
Specification Suplement (CSS) document.

Note that some AD/EIR types are managed internally by the kernel and are
not available thhrough these new commands.
---
 doc/mgmt-api.txt |   70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 51c9b46..1841434 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -139,6 +139,8 @@ Read Controller Information Command
 		8	Basic Rate/Enhanced Data Rate
 		9	High Speed
 		10	Low Energy
+		11	Broadcaster
+		12	Observer
 
 	This command generates a Command Complete event on success or
 	a Command Status event on failure.
@@ -845,6 +847,74 @@ Set Device ID Command
 	a Command Status event on failure.
 
 
+Set Broadcaster Command
+=======================
+
+	Command Code:		0x0029
+	Controller Index:	<controller id>
+	Command Parameters:	Broadcaster (1 Octet)
+	Return Parameters:	Current_Settings (4 Octets)
+
+	This command generates a Command Complete event on success or
+	a Command Status event on failure.
+
+
+Set Observer Command
+====================
+
+	Command Code:		0x002A
+	Controller Index:	<controller id>
+	Command Parameters:	Observer (1 Octet)
+	Return Parameters:	Current_Settings (4 Octets)
+
+	This command generates a Command Complete event on success or
+	a Command Status event on failure.
+
+
+Set Controller Data Command
+===========================
+
+	Command Code:		0x002B
+	Controller Index:	<controller id>
+	Command Parameters:	Flags (1 Octet)
+				Data_Type (1 Octet)
+				Data_Length (1 Octet)
+				Data (0-255 Octets)
+	Return Parameters:
+
+	This command can be used to set AD for LE capable controllers or EIR
+	for BR/EDR controllers. Multiple AD/EIR types can be configured by
+	calling this command multiple times. If the data does not fit on a
+	single AD/EIR on the controller, it will be rotated based on the "High
+	priority" flag, so data with this flag set will stay longer over the
+	air than those with this flag cleared.
+
+	Data_Type is the AD Type or EIR data type related to the provided data.
+
+	The following bits are defined for the Flags parameter:
+		0	High priority
+		1	Add to LE advertising data
+		2	Add to BR/EDR EIR
+
+	This command generates a Command Complete event on success or
+	a Command Status event on failure.
+
+
+Remove Controller Data Command
+==============================
+
+	Command Code:		0x002C
+	Controller Index:	<controller id>
+	Command Parameters:	Data_Type (1 Octet)
+	Return Parameters:
+
+	Remove the AD/EIR information identified by Data_Type, so it will not
+	be broadcasted anymore.
+
+	This command generates a Command Complete event on success or
+	a Command Status event on failure.
+
+
 Command Complete Event
 ======================
 
-- 
1.7.9.5

Re: [RFC BlueZ] mgmt-api: Broadcaster/Observer management API

[Johan Hedberg]

Hi Lizardo,

On Wed, Jul 11, 2012, Anderson Lizardo wrote:
> +Set Controller Data Command
> +===========================
> +
> +	Command Code:		0x002B
> +	Controller Index:	<controller id>
> +	Command Parameters:	Flags (1 Octet)
> +				Data_Type (1 Octet)
> +				Data_Length (1 Octet)
> +				Data (0-255 Octets)
> +	Return Parameters:
> +

The return parameters should include the Flags and Data_Type so that
user space can distinguish which Set Controller Data command completed
or failed (in the case of multiple pending commands). Same goes for the
Remove Controller Data command.

> +	This command can be used to set AD for LE capable controllers or EIR
> +	for BR/EDR controllers. Multiple AD/EIR types can be configured by
> +	calling this command multiple times. If the data does not fit on a
> +	single AD/EIR on the controller, it will be rotated based on the "High
> +	priority" flag, so data with this flag set will stay longer over the
> +	air than those with this flag cleared.

I'm still struggling to see the usefulness or even the feasibility of a
meaningful rotation of data. Is there actually some place in the core
spec that implies or recommends that this be done? More importantly, is
there some place that states that the content of multiple different AD
packets from the same remote device should be considered in an
aggregated manner instead of considering each of them as a
unique/complete state of the remote device? If there's no such mention
there's nothing stopping devices from using the latter interpretation
and in such a case any kind of rotation could mess things up. Also the
fact that there exists short/incomplete variants of many AD types
(UUIDs, device name) seems to indicate that if any kind of compromising
mechanism should be used when trying to fit data, this is it.

Johan

Re: [RFC BlueZ] mgmt-api: Broadcaster/Observer management API

[Anderson Lizardo]

Hi Johan,

On Tue, Jul 17, 2012 at 4:44 AM, Johan Hedberg <johan.hedberg@gmail.com> wrote:
> Hi Lizardo,
>
> On Wed, Jul 11, 2012, Anderson Lizardo wrote:
>> +Set Controller Data Command
>> +===========================
>> +
>> +     Command Code:           0x002B
>> +     Controller Index:       <controller id>
>> +     Command Parameters:     Flags (1 Octet)
>> +                             Data_Type (1 Octet)
>> +                             Data_Length (1 Octet)
>> +                             Data (0-255 Octets)
>> +     Return Parameters:
>> +
>
> The return parameters should include the Flags and Data_Type so that
> user space can distinguish which Set Controller Data command completed
> or failed (in the case of multiple pending commands). Same goes for the
> Remove Controller Data command.

Ok, will add on next revision.

>
>> +     This command can be used to set AD for LE capable controllers or EIR
>> +     for BR/EDR controllers. Multiple AD/EIR types can be configured by
>> +     calling this command multiple times. If the data does not fit on a
>> +     single AD/EIR on the controller, it will be rotated based on the "High
>> +     priority" flag, so data with this flag set will stay longer over the
>> +     air than those with this flag cleared.
>
> I'm still struggling to see the usefulness or even the feasibility of a
> meaningful rotation of data. Is there actually some place in the core
> spec that implies or recommends that this be done? More importantly, is
> there some place that states that the content of multiple different AD
> packets from the same remote device should be considered in an
> aggregated manner instead of considering each of them as a
> unique/complete state of the remote device? If there's no such mention
> there's nothing stopping devices from using the latter interpretation
> and in such a case any kind of rotation could mess things up. Also the
> fact that there exists short/incomplete variants of many AD types
> (UUIDs, device name) seems to indicate that if any kind of compromising
> mechanism should be used when trying to fit data, this is it.

Rotation gives the ability to broadcast multiple sets of information
easily (when the information sets are known beforehand), without
requiring to have a timer on userspace and multiple mgmt API calls.
Given that LE advertising is inherently unreliable, it is up to the
application to add some sort of checksum or account for data that may
never arrive. In other words, it is a best effort communication
channel (IMHO).

Remember that this API is only useful for AD Types which are not
managed by BlueZ or kernel internally, i.e. service data and
manufaturer specific data currently (more may come on future Core
Specification Supplement document revisions). These information are
not necessarily device state, and applications have the freedom do
manage the information as they find necessary. E.g. some sort of
sequence numbering, CRC, or even Message Authentication (although
tricky to fit into <31 bytes adv. packets, it is still possible).

That said, I believe that even if the kernel does not rotate the
information as described above, it is still possible to broadcast the
same sets of information, but with performance penalty because of
multiple set/remove controller data commands.

Best Regards,
-- 
Anderson Lizardo
Instituto Nokia de Tecnologia - INdT
Manaus - Brazil