[RFC PATCH BlueZ] LE Broadcaster/Observer API proposal

[RFC PATCH BlueZ] LE Broadcaster/Observer API proposal

[Anderson Lizardo]

Hi,

This patch contains an API proposal for implementing LE Broadcaster/Observer
roles in BlueZ. These roles allow to transfer data unidirectionally (from
Broadcaster to Observer) in a connectionless setup. See Core spec Vol 3, Part
C, section 9.1 for more details.

The API consists on extending the Adapter API to support Observer/Broadcaster
procedures. These are implemented as methods separate from Discovery, given
that Broadcaster devices are non-connectable and non-discoverable.

Multiple D-Bus clients can register for Observer mode, as well as for
Broadcaster. BlueZ is thus responsible for constructing the Adv. Data (in
Broadcaster mode) or routing the broadcast data (in Observer mode) to the
applications.

On Broadcaster, multiple applications cannot broadcast the same Adv. data type.
On Observer, the application(s) register(s) a callback that will be called only
when the specified Adv. types are present on the received advertising event.

We considered using signals for broadcast data, but it turns out it can cause
too much D-Bus traffic given that all registered applications will receive the
signals. The callback approach allows to ignore broadcasts which have no
information relevant to an application.

Note that this proposal does not describe the necessary mgmt API changes. This
will come once we agree on the higher level D-Bus API. But it should be
expected that new commands for enabling/disabling observer/broadcaster modes
and setting adv. data will be necessary, as well as modifying the current
kernel code that ignores non-connectable advertising (which are used by
Observers).

Comments and suggestions are welcome.

Anderson Lizardo (1):
  doc: Document Broadcaster/Observer API

 doc/adapter-api.txt |   56 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 56 insertions(+), 0 deletions(-)

-- 
1.7.5.4

--
Anderson Lizardo
Instituto Nokia de Tecnologia - INdT
Manaus - Brazil

[RFC PATCH BlueZ] doc: Document Broadcaster/Observer API

[Anderson Lizardo]

---
 doc/adapter-api.txt |   56 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 56 insertions(+), 0 deletions(-)

diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
index 20cef03..67f9f62 100644
--- a/doc/adapter-api.txt
+++ b/doc/adapter-api.txt
@@ -181,6 +181,48 @@ Methods		dict GetProperties()
 
 			Possible errors: org.bluez.Error.DoesNotExist
 
+		void RegisterBroadcaster(dict values)
+
+			Set Advertising data for broadcast. Different
+			applications can register different Adv. data types,
+			and they are all concatenated to form the Adv. data.
+			Broadcasting is enabled as soon as the first
+			RegisterBroadcaster() call is made.
+
+			Use UnregisterBroadcaster() to release Adv. data for
+			the application. Advertising data is also released when
+			application exits, and once the last Broadcaster exits,
+			advertising is disabled.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
+
+		void UnregisterBroadcaster()
+
+			This method will release any previously set Advertising
+			data.
+
+			Note that a broadcast procedure is shared between all
+			sessions, thus calling UnregisterBroadcaster() will
+			only release a single session.
+
+			Possible errors: org.bluez.Error.Failed
+
+		void RegisterObserver(object agent, array{byte} data_types)
+
+			Registers an observer agent to monitor broadcasts. This
+			agent will be notified whenever a broadcast is received
+			that contains any of selected Advertising data types.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+
+		void UnregisterObserver(object agent)
+
+			Unregisters an observer. Broadcasts will not be
+			notified to this agent anymore.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+
 Signals		PropertyChanged(string name, variant value)
 
 			This signal indicates a changed value of the given
@@ -284,3 +326,17 @@ Properties	string Address [readonly]
 
 			List of 128-bit UUIDs that represents the available
 			local services.
+
+
+Observer hierarchy
+==================
+
+Service		unique name
+Interface	org.bluez.Observer
+Object path	freely definable
+
+Methods		void BroadcastReceived(string address, byte data_type,
+								variant value)
+
+			This callback gets called when a broadcast data has
+			arrived with selected Advertising Data type.
-- 
1.7.5.4

RE: [RFC PATCH BlueZ] doc: Document Broadcaster/Observer API

[Ganir, Chen]

Lizardo,

> -----Original Message-----
> From: linux-bluetooth-owner@vger.kernel.org [mailto:linux-bluetooth-
> owner@vger.kernel.org] On Behalf Of Anderson Lizardo
> Sent: Thursday, April 12, 2012 4:04 AM
> To: linux-bluetooth@vger.kernel.org
> Cc: Anderson Lizardo
> Subject: [RFC PATCH BlueZ] doc: Document Broadcaster/Observer API
> 
> ---
>  doc/adapter-api.txt |   56
> +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 56 insertions(+), 0 deletions(-)
> 
> diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
> index 20cef03..67f9f62 100644
> --- a/doc/adapter-api.txt
> +++ b/doc/adapter-api.txt
> @@ -181,6 +181,48 @@ Methods		dict GetProperties()
> 
>  			Possible errors: org.bluez.Error.DoesNotExist
> 
> +		void RegisterBroadcaster(dict values)
> +
> +			Set Advertising data for broadcast. Different
> +			applications can register different Adv. data types,
> +			and they are all concatenated to form the Adv. data.
> +			Broadcasting is enabled as soon as the first
> +			RegisterBroadcaster() call is made.
> +
> +			Use UnregisterBroadcaster() to release Adv. data for
> +			the application. Advertising data is also released
> when
> +			application exits, and once the last Broadcaster
> exits,
> +			advertising is disabled.
> +
> +			Possible Errors: org.bluez.Error.InvalidArguments
> +					 org.bluez.Error.Failed
> +
What if the data changes? What if I register for Service Data, and the service data changes? Do I need to RegisterBroadcaster again?

> +		void UnregisterBroadcaster()
> +
> +			This method will release any previously set
> Advertising
> +			data.
> +
> +			Note that a broadcast procedure is shared between all
> +			sessions, thus calling UnregisterBroadcaster() will
> +			only release a single session.
> +
> +			Possible errors: org.bluez.Error.Failed
> +
> +		void RegisterObserver(object agent, array{byte} data_types)
> +
> +			Registers an observer agent to monitor broadcasts.
> This
> +			agent will be notified whenever a broadcast is
> received
> +			that contains any of selected Advertising data types.
> +
> +			Possible errors: org.bluez.Error.InvalidArguments
> +
Will this automatically start the scanning for advertising? How will you combine this with the device search for dual mode devices?


> +		void UnregisterObserver(object agent)
> +
> +			Unregisters an observer. Broadcasts will not be
> +			notified to this agent anymore.
> +
> +			Possible errors: org.bluez.Error.InvalidArguments
Will unregistering ALL observers stop the scan for advertising ?

> +
>  Signals		PropertyChanged(string name, variant value)
> 
>  			This signal indicates a changed value of the given
> @@ -284,3 +326,17 @@ Properties	string Address [readonly]
> 
>  			List of 128-bit UUIDs that represents the available
>  			local services.
> +
> +
> +Observer hierarchy
> +==================
> +
> +Service		unique name
> +Interface	org.bluez.Observer
> +Object path	freely definable
> +
> +Methods		void BroadcastReceived(string address, byte
> data_type,
> +								variant value)
> +
> +			This callback gets called when a broadcast data has
> +			arrived with selected Advertising Data type.
> --
> 1.7.5.4
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-
> bluetooth" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html


Thanks,
Chen Ganir

Re: [RFC PATCH BlueZ] doc: Document Broadcaster/Observer API

[Anderson Lizardo]

Hi Chen,

On Mon, Apr 16, 2012 at 4:07 AM, Ganir, Chen <chen.ganir@ti.com> wrote:
>> +             void RegisterBroadcaster(dict values)
>> +
>> +                     Set Advertising data for broadcast. Different
>> +                     applications can register different Adv. data types,
>> +                     and they are all concatenated to form the Adv. data.
>> +                     Broadcasting is enabled as soon as the first
>> +                     RegisterBroadcaster() call is made.
>> +
>> +                     Use UnregisterBroadcaster() to release Adv. data for
>> +                     the application. Advertising data is also released
>> when
>> +                     application exits, and once the last Broadcaster
>> exits,
>> +                     advertising is disabled.
>> +
>> +                     Possible Errors: org.bluez.Error.InvalidArguments
>> +                                      org.bluez.Error.Failed
>> +
> What if the data changes? What if I register for Service Data, and the service data changes? Do I need to RegisterBroadcaster again?

In this API, it needs to be called again. We need to clarify more
these cases here. Will do for next version.

>> +             void UnregisterBroadcaster()
>> +
>> +                     This method will release any previously set
>> Advertising
>> +                     data.
>> +
>> +                     Note that a broadcast procedure is shared between all
>> +                     sessions, thus calling UnregisterBroadcaster() will
>> +                     only release a single session.
>> +
>> +                     Possible errors: org.bluez.Error.Failed
>> +
>> +             void RegisterObserver(object agent, array{byte} data_types)
>> +
>> +                     Registers an observer agent to monitor broadcasts.
>> This
>> +                     agent will be notified whenever a broadcast is
>> received
>> +                     that contains any of selected Advertising data types.
>> +
>> +                     Possible errors: org.bluez.Error.InvalidArguments
>> +
> Will this automatically start the scanning for advertising?

Not sure yet :). It will depend on how the underlying mgmt API will
work. There is a clear conflict/dependency here with BR/EDR/LE
discovery.

> How will you combine this with the device search for dual mode devices?

One possibility if for RegisterObserver() to trigger a LE only
discovery (using the existing mgmt API), then when some application
triggers the dual mode discovery, it just switches to BR/EDR/LE. I
suppose this is fully supported by current mgmt discovery API.

(note that I'm ignoring the scan parameters here for now; as explained
on previous e-mail, it needs a broader discussion.)

>> +             void UnregisterObserver(object agent)
>> +
>> +                     Unregisters an observer. Broadcasts will not be
>> +                     notified to this agent anymore.
>> +
>> +                     Possible errors: org.bluez.Error.InvalidArguments
> Will unregistering ALL observers stop the scan for advertising ?

If there is no pending BR/EDR/LE discovery, yes. But I think this
"detail" can be left out from the documentation. After unregister, the
application will not receive any new broadcast information on the
agent.

Thanks for your comments, we will fill the missing information and
send a new version soon.

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

RE: [RFC PATCH BlueZ] doc: Document Broadcaster/Observer API

[Ganir, Chen]

Lizardo,

> -----Original Message-----
> From: Anderson Lizardo [mailto:anderson.lizardo@openbossa.org]
> Sent: Monday, April 16, 2012 3:11 PM
> To: Ganir, Chen
> Cc: linux-bluetooth@vger.kernel.org
> Subject: Re: [RFC PATCH BlueZ] doc: Document Broadcaster/Observer API
> 
> Hi Chen,
> 
> On Mon, Apr 16, 2012 at 4:07 AM, Ganir, Chen <chen.ganir@ti.com> wrote:
> >> +             void RegisterBroadcaster(dict values)
> >> +
> >> +                     Set Advertising data for broadcast. Different
> >> +                     applications can register different Adv. data
> types,
> >> +                     and they are all concatenated to form the Adv.
> data.
> >> +                     Broadcasting is enabled as soon as the first
> >> +                     RegisterBroadcaster() call is made.
> >> +
> >> +                     Use UnregisterBroadcaster() to release Adv.
> data for
> >> +                     the application. Advertising data is also
> released
> >> when
> >> +                     application exits, and once the last
> Broadcaster
> >> exits,
> >> +                     advertising is disabled.
> >> +
> >> +                     Possible Errors:
> org.bluez.Error.InvalidArguments
> >> +                                      org.bluez.Error.Failed
> >> +
> > What if the data changes? What if I register for Service Data, and
> the service data changes? Do I need to RegisterBroadcaster again?
> 
> In this API, it needs to be called again. We need to clarify more
> these cases here. Will do for next version.
> 
I would suggest adding a new API, called UpdateBroadcastData() which will be used by a registered broadcaster to update it's broadcasting data. Using the same RegisterBroadcaster() will cause inconsistency between the regiseter/unregister functions which will break the logic - you may see many registerBroadcaster calls, but only one unregister call.

> >> +             void UnregisterBroadcaster()
> >> +
> >> +                     This method will release any previously set
> >> Advertising
> >> +                     data.
> >> +
> >> +                     Note that a broadcast procedure is shared
> between all
> >> +                     sessions, thus calling UnregisterBroadcaster()
> will
> >> +                     only release a single session.
> >> +
> >> +                     Possible errors: org.bluez.Error.Failed
> >> +
> >> +             void RegisterObserver(object agent, array{byte}
> data_types)
> >> +
> >> +                     Registers an observer agent to monitor
> broadcasts.
> >> This
> >> +                     agent will be notified whenever a broadcast is
> >> received
> >> +                     that contains any of selected Advertising data
> types.
> >> +
> >> +                     Possible errors:
> org.bluez.Error.InvalidArguments
> >> +
> > Will this automatically start the scanning for advertising?
> 
> Not sure yet :). It will depend on how the underlying mgmt API will
> work. There is a clear conflict/dependency here with BR/EDR/LE
> discovery.
> 
> > How will you combine this with the device search for dual mode
> devices?
> 
> One possibility if for RegisterObserver() to trigger a LE only
> discovery (using the existing mgmt API), then when some application
> triggers the dual mode discovery, it just switches to BR/EDR/LE. I
> suppose this is fully supported by current mgmt discovery API.
> 
> (note that I'm ignoring the scan parameters here for now; as explained
> on previous e-mail, it needs a broader discussion.)
> 
> >> +             void UnregisterObserver(object agent)
> >> +
> >> +                     Unregisters an observer. Broadcasts will not
> be
> >> +                     notified to this agent anymore.
> >> +
> >> +                     Possible errors:
> org.bluez.Error.InvalidArguments
> > Will unregistering ALL observers stop the scan for advertising ?
> 
> If there is no pending BR/EDR/LE discovery, yes. But I think this
> "detail" can be left out from the documentation. After unregister, the
> application will not receive any new broadcast information on the
> agent.
> 
> Thanks for your comments, we will fill the missing information and
> send a new version soon.
> 
> Best Regards,
> --
> Anderson Lizardo
> Instituto Nokia de Tecnologia - INdT
> Manaus - Brazil


Thanks,
Chen Ganir

RE: [RFC PATCH BlueZ] LE Broadcaster/Observer API proposal

[Ganir, Chen]

Lizardo,

> -----Original Message-----
> From: linux-bluetooth-owner@vger.kernel.org [mailto:linux-bluetooth-
> owner@vger.kernel.org] On Behalf Of Anderson Lizardo
> Sent: Thursday, April 12, 2012 4:04 AM
> To: linux-bluetooth@vger.kernel.org
> Cc: Anderson Lizardo
> Subject: [RFC PATCH BlueZ] LE Broadcaster/Observer API proposal
> 
> Hi,
> 
> This patch contains an API proposal for implementing LE
> Broadcaster/Observer
> roles in BlueZ. These roles allow to transfer data unidirectionally
> (from
> Broadcaster to Observer) in a connectionless setup. See Core spec Vol
> 3, Part
> C, section 9.1 for more details.
> 
> The API consists on extending the Adapter API to support
> Observer/Broadcaster
> procedures. These are implemented as methods separate from Discovery,
> given
> that Broadcaster devices are non-connectable and non-discoverable.
> 
> Multiple D-Bus clients can register for Observer mode, as well as for
> Broadcaster. BlueZ is thus responsible for constructing the Adv. Data
> (in
> Broadcaster mode) or routing the broadcast data (in Observer mode) to
> the
> applications.
> 
> On Broadcaster, multiple applications cannot broadcast the same Adv.
> data type.

This looks a bit problematic. What if two applications wish to broadcast services ? Or Service Solicitation ? or Service Data ? This could lead to problems.

In addition, what about TX Power, or Flags - which module is responsible for sending this data ? Will it be public for any application, or will you have some kind of allowed Advertising packets for external application, and some reserved for system ?

Are you planning to support duplicate filtering ?

What are you planning to do if the Advertising data exceeds the MAX ADV Data size ? Will you split the data somehow to multiple advertising packets ? What is the logic behind such a split ?

How will you allow a user to select whether the data is to be sent over Advertising or Scan Response ?

How will you allow a user or system to configure scan parameters for observer or advertising parameters for broadcasters ?

I'm guessing you will need to add more D-BUS Api's, or at least allow setting those parameters in the main.conf file ?

> On Observer, the application(s) register(s) a callback that will be
> called only
> when the specified Adv. types are present on the received advertising
> event.
> 
> We considered using signals for broadcast data, but it turns out it can
> cause
> too much D-Bus traffic given that all registered applications will
> receive the
> signals. The callback approach allows to ignore broadcasts which have
> no
> information relevant to an application.
> 
I agree with that.


> Note that this proposal does not describe the necessary mgmt API
> changes. This
> will come once we agree on the higher level D-Bus API. But it should be
> expected that new commands for enabling/disabling observer/broadcaster
> modes
> and setting adv. data will be necessary, as well as modifying the
> current
> kernel code that ignores non-connectable advertising (which are used by
> Observers).
I also think you need to add PropertyChanged for Broadcasting, since you will need to stop broadcasting when connecting to a device, or when the power is turned off for example. In addition, you will need to figure out a way to synchronize all the GAP LE roles, according to what is allowed or disallowed.

> 
> Comments and suggestions are welcome.
> 
> Anderson Lizardo (1):
>   doc: Document Broadcaster/Observer API
> 
>  doc/adapter-api.txt |   56
> +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 56 insertions(+), 0 deletions(-)
> 
> --
> 1.7.5.4
> 
> --
> Anderson Lizardo
> Instituto Nokia de Tecnologia - INdT
> Manaus - Brazil
> --
> To unsubscribe from this list: send the line "unsubscribe linux-
> bluetooth" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html



Thanks,
Chen Ganir

Re: [RFC PATCH BlueZ] LE Broadcaster/Observer API proposal

[Anderson Lizardo]

Hi Chen,

On Mon, Apr 16, 2012 at 4:03 AM, Ganir, Chen <chen.ganir@ti.com> wrote:
>> On Broadcaster, multiple applications cannot broadcast the same Adv.
>> data type.
>
> This looks a bit problematic. What if two applications wish to broadcast services ? Or Service Solicitation ? or Service Data ? This could lead to problems.

Ok, we will clarify this on the document. Actually the "single
instance" verification is only applied to some AD types. It is not a
general rule.

> In addition, what about TX Power, or Flags - which module is responsible for sending this data ? Will it be public for any application, or will you have some kind of allowed Advertising packets for external application, and some reserved for system ?

As described on the Observer API, an application can filter which adv.
it is interested on, and its callback will only be called when that AD
type is present on the received adv. data. I don't think there is a
need currently to prevent certain AD types from being "observable".

> Are you planning to support duplicate filtering ?

Yes, but this cannot be enabled while device is in Observer mode. But
it is very useful for Central role to avoid overhead of adv. data
flood to userspace.

> What are you planning to do if the Advertising data exceeds the MAX ADV Data size ? Will you split the data somehow to multiple advertising packets ? What is the logic behind such a split ?

For now, there will be no split, the API will return some error if the
adv. data field is full. We can either pre-calculate the necessary
space for the data as it is registered by the Broadcaster application
(easier), or let the mgmt API return error if it cannot append more
data.

I think it is hard to build this logic inside BlueZ. I can't find any
reference on the Core spec how to properly do this split. So for now
applications will need to do this (e.g. using timers).

> How will you allow a user to select whether the data is to be sent over Advertising or Scan Response ?

We can have a separate boolean "BroadcasterScannable" adapter property
to handle this. It can be boolean because Broadcasters can only use
scannable (0x02) or non-connectable (0x03) adv. types.

Maybe it is interesting to add a new "bool scannable" parameter to
RegisterBroadcaster as well, this way, some application can quickly
alternate between scannable/non-scannable adv. by just toggling the
BroadcasterScannable property. What do you think?

> How will you allow a user or system to configure scan parameters for observer or advertising parameters for broadcasters ?

Some parameters can be inferred. Others will need adapter properties.
We need to verify case by case. New properties can be proposed as
necessary.

But I think this is a broader topic, because it is also a missing
feature for Central role as well. We need a separate discussion just
for the scan/advertising parameters topic. For instance, currently we
don't have a way to switch from the "fast connection" parameters
currently hard coded on the kernel.

> I'm guessing you will need to add more D-BUS Api's, or at least allow setting those parameters in the main.conf file ?

Yes. The selection between main.conf or Adapter properties needs to be
on a case by case. This initial proposal is to outline the base
architecture.

>> Note that this proposal does not describe the necessary mgmt API
>> changes. This
>> will come once we agree on the higher level D-Bus API. But it should be
>> expected that new commands for enabling/disabling observer/broadcaster
>> modes
>> and setting adv. data will be necessary, as well as modifying the
>> current
>> kernel code that ignores non-connectable advertising (which are used by
>> Observers).
> I also think you need to add PropertyChanged for Broadcasting, since you will need to stop broadcasting when connecting to a device, or when the power is turned off for example. In addition, you will need to figure out a way to synchronize all the GAP LE roles, according to what is allowed or disallowed.

Yes, we will add a few more information on this on the next version.

Thanks for your comments!
-- 
Anderson Lizardo
Instituto Nokia de Tecnologia - INdT
Manaus - Brazil

RE: [RFC PATCH BlueZ] LE Broadcaster/Observer API proposal

[Ganir, Chen]

Lizardo,

> -----Original Message-----
> From: Anderson Lizardo [mailto:anderson.lizardo@openbossa.org]
> Sent: Monday, April 16, 2012 2:52 PM
> To: Ganir, Chen
> Cc: linux-bluetooth@vger.kernel.org
> Subject: Re: [RFC PATCH BlueZ] LE Broadcaster/Observer API proposal
> 
> Hi Chen,
> 
> On Mon, Apr 16, 2012 at 4:03 AM, Ganir, Chen <chen.ganir@ti.com> wrote:
> >> On Broadcaster, multiple applications cannot broadcast the same Adv.
> >> data type.
> >
> > This looks a bit problematic. What if two applications wish to
> broadcast services ? Or Service Solicitation ? or Service Data ? This
> could lead to problems.
> 
> Ok, we will clarify this on the document. Actually the "single
> instance" verification is only applied to some AD types. It is not a
> general rule.
> 
I suppose you need to specify exactly what types of advertising is supported, and how many advertisers may advertise the same data, and appropriate error code for a scenario when a user tries to advertise information which is already advertised by someone else.


> > In addition, what about TX Power, or Flags - which module is
> responsible for sending this data ? Will it be public for any
> application, or will you have some kind of allowed Advertising packets
> for external application, and some reserved for system ?
> 
> As described on the Observer API, an application can filter which adv.
> it is interested on, and its callback will only be called when that AD
> type is present on the received adv. data. I don't think there is a
> need currently to prevent certain AD types from being "observable".
> 
I was talking about the broadcaster role here. Flags AD is a GAP LE advertising which is supposed to be advertised in the Advertising data by the system (the flags should be set according to the system properties). In addition, you have the name (short/long), or TX Power, or Services or Manufacturer data, which usually describe the system and not a specific profile. We may have to split the functionality between the Broadcaster API (Profile specific advertising) and Adapter (GAP LE System advertising).

> > Are you planning to support duplicate filtering ?
> 
> Yes, but this cannot be enabled while device is in Observer mode. But
> it is very useful for Central role to avoid overhead of adv. data
> flood to userspace.
This is also very useful as observer role. Let's say you are observing for a sensor value. You would wither like to know the exact value periodically or would like to see only changed advertising. You may want to add this functionality to the API.

> 
> > What are you planning to do if the Advertising data exceeds the MAX
> ADV Data size ? Will you split the data somehow to multiple advertising
> packets ? What is the logic behind such a split ?
> 
> For now, there will be no split, the API will return some error if the
> adv. data field is full. We can either pre-calculate the necessary
> space for the data as it is registered by the Broadcaster application
> (easier), or let the mgmt API return error if it cannot append more
> data.
> 
> I think it is hard to build this logic inside BlueZ. I can't find any
> reference on the Core spec how to properly do this split. So for now
> applications will need to do this (e.g. using timers).
> 
I did not find this kind of logic in the specs as well. What if we build a splitting mechanism, and see how it works in IOP Tests? Maybe we need to get more feedback from the SIG or other LE peripheral/Broadcasters developers?

> > How will you allow a user to select whether the data is to be sent
> over Advertising or Scan Response ?
> 
> We can have a separate boolean "BroadcasterScannable" adapter property
> to handle this. It can be boolean because Broadcasters can only use
> scannable (0x02) or non-connectable (0x03) adv. types.
> 
What I meant here is that the user can select if the name of the device should appear in the advertising data, or in the scan response data, but the user can not select which advertising method is used. The only way to invoke the SCAN RSP is by an observer/central doing active scanning.

> Maybe it is interesting to add a new "bool scannable" parameter to
> RegisterBroadcaster as well, this way, some application can quickly
> alternate between scannable/non-scannable adv. by just toggling the
> BroadcasterScannable property. What do you think?
> 
Look above. The user has no control over this, and he does not need to know the details of the advertising method.

> > How will you allow a user or system to configure scan parameters for
> observer or advertising parameters for broadcasters ?
> 
> Some parameters can be inferred. Others will need adapter properties.
> We need to verify case by case. New properties can be proposed as
> necessary.
> 
> But I think this is a broader topic, because it is also a missing
> feature for Central role as well. We need a separate discussion just
> for the scan/advertising parameters topic. For instance, currently we
> don't have a way to switch from the "fast connection" parameters
> currently hard coded on the kernel.
> 
I agree. This needs more discussion and needs to be more flexible.

> > I'm guessing you will need to add more D-BUS Api's, or at least allow
> setting those parameters in the main.conf file ?
> 
> Yes. The selection between main.conf or Adapter properties needs to be
> on a case by case. This initial proposal is to outline the base
> architecture.
> 
Ok.

> >> Note that this proposal does not describe the necessary mgmt API
> >> changes. This
> >> will come once we agree on the higher level D-Bus API. But it should
> be
> >> expected that new commands for enabling/disabling
> observer/broadcaster
> >> modes
> >> and setting adv. data will be necessary, as well as modifying the
> >> current
> >> kernel code that ignores non-connectable advertising (which are used
> by
> >> Observers).
> > I also think you need to add PropertyChanged for Broadcasting, since
> you will need to stop broadcasting when connecting to a device, or when
> the power is turned off for example. In addition, you will need to
> figure out a way to synchronize all the GAP LE roles, according to what
> is allowed or disallowed.
> 
> Yes, we will add a few more information on this on the next version.
> 
> Thanks for your comments!


> --
> Anderson Lizardo
> Instituto Nokia de Tecnologia - INdT
> Manaus - Brazil



Thanks,
Chen Ganir

[PATCH RFC BlueZ v2 0/1] LE Broadcaster/Observer API proposal

[Anderson Lizardo]

Hi,

Changes since v1:

* Add UpdateBroadcastData() (suggested by Chen Ganir)
* Add Broadcasting/Observing adapter properties (based on Chen's suggestion)


This patch contains an API proposal for implementing LE Broadcaster/Observer
roles in BlueZ. These roles allow to transfer data unidirectionally (from
Broadcaster to Observer) in a connectionless setup. See Core spec Vol 3, Part
C, section 9.1 for more details.

The API consists on extending the Adapter API to support Observer/Broadcaster
procedures. These are implemented as methods separate from Discovery, given
that Broadcaster devices are non-connectable and non-discoverable.

Multiple D-Bus clients can register for Observer mode, as well as for
Broadcaster. BlueZ is thus responsible for constructing the Adv. Data (in
Broadcaster mode) or routing the broadcast data (in Observer mode) to the
applications.

On Broadcaster, each application registers the values to be broadcast. Note
that some advertising types cannot be registered by multiple applications (they
can only appear once on the Adv. data), and thus a second registration attempt
will fail with a proper error message. Some advertising data types are also
managed internally by BlueZ and are not available for external applications.

On Observer, the application(s) register(s) a callback that will be called only
when the specified Adv. types are present on the received advertising event.

We considered using signals for broadcast data, but it turns out it can cause
too much D-Bus traffic given that all registered applications will receive the
signals. The callback approach allows to ignore broadcasts which have no
information relevant to an application.

These are the currently known adv. data types (as listed on the Core
Specification Supplement v1):

* 1.1 Service UUID: managed internally by BlueZ as LE services are registered
  (same as BR/EDR)
* 1.2 Local Name: managed internally by BlueZ (same as BR/EDR)
* 1.3 Flags: managed internally by BlueZ based on discovery status
* 1.4 Manufacturer Specific Data: this is freely defined, and can be registered
  by multiple applications
* 1.5 TX Power Level: managed internally by BlueZ (application can enable
  broadcast, but cannot control the value)
* 1.6, 1.7, 1.8 (not applicable for AD or EIR)
* 1.9 Slave Connection Interval Range: managed internally by BlueZ (once we
  support dynamic connection parameters)
* 1.10 Service Solicitation: managed internally by BlueZ as LE services are
  registered
* 1.11 Service Data: this is freely defined per-service data. Not sure if it is
  interesting to be available for external applications
* 1.12 Appearance: managed internally by BlueZ
* 1.13 Public Target Address: managed internally by BlueZ (useful for
  notifications/indications)
* 1.14 Random Target Address: managed internally by BlueZ (useful for
  notifications/indications)

Therefore, only "Manufacturer specific data" (and maybe "Service data") are
currently available for external Broadcaster applications. In future, other
Broadcaster/Observer based profiles may add new adv. types, so we need a
extensible solution.

Note that this proposal does not describe the necessary mgmt API changes. This
will come once we agree on the higher level D-Bus API. But it should be
expected that new commands for enabling/disabling observer/broadcaster modes
and setting adv. data will be necessary, as well as modifying the current
kernel code that ignores non-connectable advertising (which are used by
Observers).

A few open topics:

* It is still not clear when actual scanning (for Observer) or advertising (for
  Broadcaster) will start. It cannot conflict with any ongoing Discovery
  session on the Observer side. We may want to check the supported LE states on
  the kernel side.
* Duplicate filtering affects Broadcaster role. So it is interesting to be able
  to enable/disable it as necessary.
* Given that maximum Adv. data size is very limited (31 bytes), we may want to
  implement some algorithm to "split" or "interleave" advertising data. We
  could not find any references to this on the Core specifications. Suggestions
  or ideas how to handle this are welcome.
* Adv. data can appear either on adv. reports or in scan responses (sent when
  Observer does a active scan), but usually not in both. We may want to have a
  way to set which adv. types will go on each case. Note that some adv. types
  may not be allowed in either adv. reports or scan responses.
* Scan and advertising parameters are not covered on this proposal. We expect
  to have a common setting mechanism which may be used for Central/Peripheral
  roles (e.g. LE HID will probably need configurable scan parameters as well),
  so it will be discussed in a separate proposal.

Comments and suggestions are welcome.

Anderson Lizardo (1):
  doc: Document Broadcaster/Observer API

 doc/adapter-api.txt |   71 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 71 insertions(+), 0 deletions(-)

-- 
1.7.5.4

[PATCH RFC BlueZ v2 1/1] doc: Document Broadcaster/Observer API

[Anderson Lizardo]

---
 doc/adapter-api.txt |   71 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 71 insertions(+), 0 deletions(-)

diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
index 0cded8c..346e7c3 100644
--- a/doc/adapter-api.txt
+++ b/doc/adapter-api.txt
@@ -181,6 +181,55 @@ Methods		dict GetProperties()
 
 			Possible errors: org.bluez.Error.DoesNotExist
 
+		void RegisterBroadcaster(dict values)
+
+			Set Advertising data for broadcast. Different
+			applications can register different Adv. data types,
+			and they are all concatenated to form the Adv. data.
+			Broadcasting is enabled as soon as the first
+			RegisterBroadcaster() call is made.
+
+			Use UnregisterBroadcaster() to release Adv. data for
+			the application. Advertising data is also released when
+			application exits, and once the last Broadcaster exits,
+			advertising is disabled.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.Failed
+
+		void UpdateBroadcastData(dict values)
+
+			Replace Advertising data for broadcast. This method can
+			only be called after RegisterBroadcaster().
+
+			Possible errors: org.bluez.Error.Failed
+
+		void UnregisterBroadcaster()
+
+			This method will release any previously set Advertising
+			data.
+
+			Note that a broadcast procedure is shared between all
+			sessions, thus calling UnregisterBroadcaster() will
+			only release a single session.
+
+			Possible errors: org.bluez.Error.Failed
+
+		void RegisterObserver(object agent, array{byte} data_types)
+
+			Registers an observer agent to monitor broadcasts. This
+			agent will be notified whenever a broadcast is received
+			that contains any of selected Advertising data types.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+
+		void UnregisterObserver(object agent)
+
+			Unregisters an observer. Broadcasts will not be
+			notified to this agent anymore.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+
 Signals		PropertyChanged(string name, variant value)
 
 			This signal indicates a changed value of the given
@@ -276,6 +325,14 @@ Properties	string Address [readonly]
 
 			Indicates that a device discovery procedure is active.
 
+		boolean Broadcasting [readonly]
+
+			Indicates that a broadcast procedure is active.
+
+		boolean Observing [readonly]
+
+			Indicates that an observation procedure is active.
+
 		array{object} Devices [readonly]
 
 			List of device object paths.
@@ -284,3 +341,17 @@ Properties	string Address [readonly]
 
 			List of 128-bit UUIDs that represents the available
 			local services.
+
+
+Observer hierarchy
+==================
+
+Service		unique name
+Interface	org.bluez.Observer
+Object path	freely definable
+
+Methods		void BroadcastReceived(string address, byte data_type,
+								variant value)
+
+			This callback gets called when a broadcast data has
+			arrived with selected Advertising Data type.
-- 
1.7.5.4