I'm soliciting RFCs for this approach to defining the LE Advertising Data for
broadcast. This has a number of advantages over the previous method including
flexibility, ability for multiple advertisements, specifying the advertising
type, and the address to be used for advertisement.
Using the comments on the last RFC for LE Advertising, I've incorporated it
into the ServiceManager API next to the custom service registration, and removed
the advertising data types which are not used in practice.
Michael Janssen (1):
doc: Add LE Advertisements to Service Manager
doc/gatt-api.txt | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 85 insertions(+), 4 deletions(-)
--
2.2.0.rc0.207.ga3a616c
Updates the documentation defining a service hierarchy which can be used
for defining LE Advertisement data, and register these advertisements
to be broadcast.
---
doc/gatt-api.txt | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 85 insertions(+), 4 deletions(-)
diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt
index bfeaf6d..7fa9883 100644
--- a/doc/gatt-api.txt
+++ b/doc/gatt-api.txt
@@ -205,18 +205,77 @@ Properties string UUID [read-only]
which a PropertiesChanged signal will be emitted.
+LE Advertisement Data hierarchy
+===============================
+
+Advertisement Data to be broadcast and parameters for such. Properties which
+are not present will not be included. Required advertisement data types will
+always be included.
+
+Service org.bluez
+Interface org.bluez.LEAdvertisement1
+Object path [variable prefix]/{hci0,hci1,...}/ad_XX_XX_XX_XX_XX_XX
+
+Properties string AdvertisingType
+
+ Determines the type of advertising packet requested.
+ Must be one of "connectable", "scannable", or
+ "nonconnectable".
+
+ array{string} ServiceUUIDs
+
+ List of UUIDs to include in the "Service UUID" field of
+ the Advertising Data. These will be compressed to 16-bit
+ or 32-bit addresses if appropriate to save space.
+
+ bool IncludeLocalName
+
+ If present and true, the local name will be included in
+ the Advertising Data. A partial name will be included if
+ enough space is not available
+
+ array{struct(uint16,array{byte})} ManufacturerSpecificData
+
+ Array of Manufactuer Specific Data fields to include in
+ the Advertising Data. Each struct includes the
+ Manufacturer ID and the raw bytes to include.
+
+ bool IncludePower
+
+ If present and true, the TX Power Level will be included
+ in the Advertising Data.
+
+ array{string} SolicitUUIDs
+
+ Array of UUIDs to include in "Service Solicitation"
+ Advertisement Data. These will be compressed to 16-bit
+ or 32-bit addresses if appropriate to save space.
+
+ array{struct(string,array{byte})} ServiceData
+
+ Array of Service Data to include. The string is the
+ UUID to include with the data, and will be compressed to
+ 16 or 32 bit length if applicable.
+
+ bool IncludeAppearance
+
+ If present and true, the Appearance will be included
+ in the Advertising Data.
+
+
Service Manager hierarchy
=============================
-Service Manager allows external applications to register GATT based
-services. Services must follow the API for Service and Characteristic
-described above.
+The Service Manager allows external applications to register GATT based
+services and LE Advertisements. Services must follow the API for Service
+and Characteristic described above. LE Advertisements must follow the API
+for LE Advertisement Data described above.
Local GATT services, characteristics and characteristic descriptors are
discovered automatically using the D-Bus Object Manager interface.
Service org.bluez
-Interface org.bluez.GattManager1 [Experimental]
+Interface org.bluez.ServiceManager1 [Experimental]
Object path /org/bluez
Methods RegisterService(object service, dict options)
@@ -243,3 +302,25 @@ Methods RegisterService(object service, dict options)
Possible errors: org.bluez.Error.InvalidArguments
org.bluez.Error.DoesNotExist
+
+ RegisterAdvertisement(object advertisement, dict options)
+
+ Registers an advertisement object to be sent over the LE
+ Advertising channel. The service must be exported
+ under interface LEAdvertisement1. The last segment of
+ the object path determines the advertiser's address used
+ and is assumed to be a random address unless it matches
+ the public address.
+
+ Possible errors: org.bluez.Error.InvalidArguments
+ org.bluez.Error.AlreadyExists
+ org.bluez.Error.InvalidLength
+
+ UnregisterAdvertisement(object advertisement)
+
+ This unregisters the advertisement that has been
+ prevously registered. The object path parameter must
+ match the same value that has been used on registration.
+
+ Possible errors: org.bluez.Error.InvalidArguments
+ org.bluez.Error.DoesNotExist
--
2.2.0.rc0.207.ga3a616c
Hi Michael,
On Mon, Feb 2, 2015 at 11:11 AM, Luiz Augusto von Dentz
<[email protected]> wrote:
> Hi Michael,
>
> On Fri, Jan 30, 2015 at 9:53 PM, Michael Janssen <[email protected]> wrote:
>> Updates the documentation defining a service hierarchy which can be used
>> for defining LE Advertisement data, and register these advertisements
>> to be broadcast.
>> ---
>> doc/gatt-api.txt | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
>> 1 file changed, 85 insertions(+), 4 deletions(-)
>>
>> diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt
>> index bfeaf6d..7fa9883 100644
>> --- a/doc/gatt-api.txt
>> +++ b/doc/gatt-api.txt
>> @@ -205,18 +205,77 @@ Properties string UUID [read-only]
>> which a PropertiesChanged signal will be emitted.
>>
>>
>> +LE Advertisement Data hierarchy
>> +===============================
>> +
>> +Advertisement Data to be broadcast and parameters for such. Properties which
>> +are not present will not be included. Required advertisement data types will
>> +always be included.
>> +
>> +Service org.bluez
>> +Interface org.bluez.LEAdvertisement1
>> +Object path [variable prefix]/{hci0,hci1,...}/ad_XX_XX_XX_XX_XX_XX
>> +
>> +Properties string AdvertisingType
>> +
>> + Determines the type of advertising packet requested.
>> + Must be one of "connectable", "scannable", or
>> + "nonconnectable".
I was chatting with Johan regarding AdvertisingType and perhaps we
could do try to figure the packet type implicitly, if there is a GATT
service it should probably became connectable. Also for SolicitUUIDs
there is the following restriction:
"The Peripheral device should be in the undirected connectable mode
and in one of the discoverable modes."
Also if we have conflicts, such as one app want to be connectable but
another does want nonconnectable bluetoothd will need to resolve this
anyway
>> + array{string} ServiceUUIDs
>> +
>> + List of UUIDs to include in the "Service UUID" field of
>> + the Advertising Data. These will be compressed to 16-bit
>> + or 32-bit addresses if appropriate to save space.
>> +
>> + bool IncludeLocalName
>> +
>> + If present and true, the local name will be included in
>> + the Advertising Data. A partial name will be included if
>> + enough space is not available
Name is another thing that could conflict, Id say we can probably
leave this out for now.
>> + array{struct(uint16,array{byte})} ManufacturerSpecificData
>> +
>> + Array of Manufactuer Specific Data fields to include in
>> + the Advertising Data. Each struct includes the
>> + Manufacturer ID and the raw bytes to include.
>> +
>> + bool IncludePower
>> +
>> + If present and true, the TX Power Level will be included
>> + in the Advertising Data.
Another thing that could conflict.
>> + array{string} SolicitUUIDs
>> +
>> + Array of UUIDs to include in "Service Solicitation"
>> + Advertisement Data. These will be compressed to 16-bit
>> + or 32-bit addresses if appropriate to save space.
>> +
>> + array{struct(string,array{byte})} ServiceData
>> +
>> + Array of Service Data to include. The string is the
>> + UUID to include with the data, and will be compressed to
>> + 16 or 32 bit length if applicable.
>> +
>> + bool IncludeAppearance
>> +
>> + If present and true, the Appearance will be included
>> + in the Advertising Data.
And this one as well.
So in essence the API should not let application to interfere with
others services/advertisements, including bluetoothd and kernel.
>
>
> This looks much better, but I want to point out that most complex
> structs you have can actually be map to dict, the key element don't
> actually need to be a string:
>
> 'The restrictions are: it occurs only as an array element type; it has
> exactly two single complete types inside the curly braces; the first
> single complete type (the "key") must be a basic type rather than a
> container type.'
>
> So the key element just need to be a basic type, therefore you can use
> in ManufacturerData (I prefer it sorter like this) and in ServiceData
> as well. Another thing is that the UUID compression seems to be
> unaligned with the rest of the API which has always used 128 bits for
> client facing APIs such as D-Bus, while this can take more space I
> believe it might be simpler to handle in the clients.
>
>> Service Manager hierarchy
>> =============================
>>
>> -Service Manager allows external applications to register GATT based
>> -services. Services must follow the API for Service and Characteristic
>> -described above.
>> +The Service Manager allows external applications to register GATT based
>> +services and LE Advertisements. Services must follow the API for Service
>> +and Characteristic described above. LE Advertisements must follow the API
>> +for LE Advertisement Data described above.
>>
>> Local GATT services, characteristics and characteristic descriptors are
>> discovered automatically using the D-Bus Object Manager interface.
>>
>> Service org.bluez
>> -Interface org.bluez.GattManager1 [Experimental]
>> +Interface org.bluez.ServiceManager1 [Experimental]
>> Object path /org/bluez
>>
>> Methods RegisterService(object service, dict options)
>> @@ -243,3 +302,25 @@ Methods RegisterService(object service, dict options)
>>
>> Possible errors: org.bluez.Error.InvalidArguments
>> org.bluez.Error.DoesNotExist
>> +
>> + RegisterAdvertisement(object advertisement, dict options)
>> +
>> + Registers an advertisement object to be sent over the LE
>> + Advertising channel. The service must be exported
>> + under interface LEAdvertisement1. The last segment of
>> + the object path determines the advertiser's address used
>> + and is assumed to be a random address unless it matches
>> + the public address.
The address to be used could also conflict, furthermore we should
never encode anything like that in the object path. The kernel should
be able to generate random addresses and do the proper privacy, we
should never let a user process control this.
>> + Possible errors: org.bluez.Error.InvalidArguments
>> + org.bluez.Error.AlreadyExists
>> + org.bluez.Error.InvalidLength
>> +
>> + UnregisterAdvertisement(object advertisement)
>> +
>> + This unregisters the advertisement that has been
>> + prevously registered. The object path parameter must
>> + match the same value that has been used on registration.
>> +
>> + Possible errors: org.bluez.Error.InvalidArguments
>> + org.bluez.Error.DoesNotExist
>> --
>> 2.2.0.rc0.207.ga3a616c
>>
>> --
>> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
>> the body of a message to [email protected]
>> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
>
>
> --
> Luiz Augusto von Dentz
--
Luiz Augusto von Dentz
Hi Michael,
On Fri, Jan 30, 2015 at 9:53 PM, Michael Janssen <[email protected]> wrote:
> Updates the documentation defining a service hierarchy which can be used
> for defining LE Advertisement data, and register these advertisements
> to be broadcast.
> ---
> doc/gatt-api.txt | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 85 insertions(+), 4 deletions(-)
>
> diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt
> index bfeaf6d..7fa9883 100644
> --- a/doc/gatt-api.txt
> +++ b/doc/gatt-api.txt
> @@ -205,18 +205,77 @@ Properties string UUID [read-only]
> which a PropertiesChanged signal will be emitted.
>
>
> +LE Advertisement Data hierarchy
> +===============================
> +
> +Advertisement Data to be broadcast and parameters for such. Properties which
> +are not present will not be included. Required advertisement data types will
> +always be included.
> +
> +Service org.bluez
> +Interface org.bluez.LEAdvertisement1
> +Object path [variable prefix]/{hci0,hci1,...}/ad_XX_XX_XX_XX_XX_XX
> +
> +Properties string AdvertisingType
> +
> + Determines the type of advertising packet requested.
> + Must be one of "connectable", "scannable", or
> + "nonconnectable".
> +
> + array{string} ServiceUUIDs
> +
> + List of UUIDs to include in the "Service UUID" field of
> + the Advertising Data. These will be compressed to 16-bit
> + or 32-bit addresses if appropriate to save space.
> +
> + bool IncludeLocalName
> +
> + If present and true, the local name will be included in
> + the Advertising Data. A partial name will be included if
> + enough space is not available
> +
> + array{struct(uint16,array{byte})} ManufacturerSpecificData
> +
> + Array of Manufactuer Specific Data fields to include in
> + the Advertising Data. Each struct includes the
> + Manufacturer ID and the raw bytes to include.
> +
> + bool IncludePower
> +
> + If present and true, the TX Power Level will be included
> + in the Advertising Data.
> +
> + array{string} SolicitUUIDs
> +
> + Array of UUIDs to include in "Service Solicitation"
> + Advertisement Data. These will be compressed to 16-bit
> + or 32-bit addresses if appropriate to save space.
> +
> + array{struct(string,array{byte})} ServiceData
> +
> + Array of Service Data to include. The string is the
> + UUID to include with the data, and will be compressed to
> + 16 or 32 bit length if applicable.
> +
> + bool IncludeAppearance
> +
> + If present and true, the Appearance will be included
> + in the Advertising Data.
> +
This looks much better, but I want to point out that most complex
structs you have can actually be map to dict, the key element don't
actually need to be a string:
'The restrictions are: it occurs only as an array element type; it has
exactly two single complete types inside the curly braces; the first
single complete type (the "key") must be a basic type rather than a
container type.'
So the key element just need to be a basic type, therefore you can use
in ManufacturerData (I prefer it sorter like this) and in ServiceData
as well. Another thing is that the UUID compression seems to be
unaligned with the rest of the API which has always used 128 bits for
client facing APIs such as D-Bus, while this can take more space I
believe it might be simpler to handle in the clients.
> Service Manager hierarchy
> =============================
>
> -Service Manager allows external applications to register GATT based
> -services. Services must follow the API for Service and Characteristic
> -described above.
> +The Service Manager allows external applications to register GATT based
> +services and LE Advertisements. Services must follow the API for Service
> +and Characteristic described above. LE Advertisements must follow the API
> +for LE Advertisement Data described above.
>
> Local GATT services, characteristics and characteristic descriptors are
> discovered automatically using the D-Bus Object Manager interface.
>
> Service org.bluez
> -Interface org.bluez.GattManager1 [Experimental]
> +Interface org.bluez.ServiceManager1 [Experimental]
> Object path /org/bluez
>
> Methods RegisterService(object service, dict options)
> @@ -243,3 +302,25 @@ Methods RegisterService(object service, dict options)
>
> Possible errors: org.bluez.Error.InvalidArguments
> org.bluez.Error.DoesNotExist
> +
> + RegisterAdvertisement(object advertisement, dict options)
> +
> + Registers an advertisement object to be sent over the LE
> + Advertising channel. The service must be exported
> + under interface LEAdvertisement1. The last segment of
> + the object path determines the advertiser's address used
> + and is assumed to be a random address unless it matches
> + the public address.
> +
> + Possible errors: org.bluez.Error.InvalidArguments
> + org.bluez.Error.AlreadyExists
> + org.bluez.Error.InvalidLength
> +
> + UnregisterAdvertisement(object advertisement)
> +
> + This unregisters the advertisement that has been
> + prevously registered. The object path parameter must
> + match the same value that has been used on registration.
> +
> + Possible errors: org.bluez.Error.InvalidArguments
> + org.bluez.Error.DoesNotExist
> --
> 2.2.0.rc0.207.ga3a616c
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
> the body of a message to [email protected]
> More majordomo info at http://vger.kernel.org/majordomo-info.html
--
Luiz Augusto von Dentz