From: Luiz Augusto von Dentz <[email protected]>
Updates the documentation defining a service hierarchy which can be used
for defining LE Advertisement data and registering these advertisements
to be broadcast.
Note: Ive made some modifications since the last proposal taking away a
good number of properties that could conflict if advertisement would be
combined, in case we cannot use different random addresses for each AD.
Also I include the intention to use the same interface for
central/client role so the interface would be exposed in the device
path.
---
doc/advertising-api.txt | 90 +++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 90 insertions(+)
create mode 100644 doc/advertising-api.txt
diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt
new file mode 100644
index 0000000..3ab4691
--- /dev/null
+++ b/doc/advertising-api.txt
@@ -0,0 +1,90 @@
+BlueZ D-Bus LE Advertising API Description
+******************************************
+
+Advertising packets are structured data which is broadcast on the LE Advertising
+channels and available for all devices in range. Because of the limited space
+available in LE Advertising packets (32 bytes) , each packet's contents must be
+controllable.
+
+BlueZ acts as a store for the multiple sets of Advertisement Data which is meant
+to be sent. It constructs the correct Advertisement Data from the structured
+data and communicates the sets of data to the kernel, where it is
+multiplexed.
+
+Advertisement Data objects are registered freely and then referenced by BlueZ
+when constructing the data sent to the kernel.
+
+LE Advertisement Data hierarchy
+===============================
+
+Specifies the Advertisement Data to be broadcast and some advertising
+parameters. Properties which are not present will not be included in the
+data. Required advertisement data types will always be included.
+All UUIDs are 128-bit versions in the API, and 16 or 32-bit
+versions of the same UUID will be used in the advertising data as appropriate.
+
+Service org.bluez
+Interface org.bluez.LEAdvertisement1
+Object path freely definable or
+ /org/bluez/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Properties string Type
+
+ Determines the type of advertising packet requested.
+
+ Possible values: "broadcaster" or "peripheral"
+
+ array{string} ServiceUUIDs [Optional]
+
+ List of UUIDs to include in the "Service UUID" field of
+ the Advertising Data.
+
+ dict ManufacturerData [Optional]
+
+ Array of Manufactuer Specific Data fields to include in
+ the Advertising Data. Each dictionary entry includes
+ the Manufacturer ID and the raw bytes to include.
+
+ array{string} SolicitUUIDs [Optional]
+
+ Array of UUIDs to include in "Service Solicitation"
+ Advertisement Data.
+
+ dict ServiceData [Optional]
+
+ Array of Service Data to include. The keys are the
+ UUID to associate with the data.
+
+LE Advertising Manager hierarchy
+================================
+
+The Advertising Manager allows external applications to register Advertisement
+Data which should be broadcast to devices. Advertisement Data elements must
+follow the API for LE Advertisement Data described above.
+
+Service org.bluez
+Interface org.bluez.LEAdvertisementManager1 [Experimental]
+Object path /org/bluez/{hci0,hci1,...}
+
+Methods 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. InvalidArguments
+ indicates that the object has invalid or conflicting
+ properties. InvalidLength indicates that the data
+ provided generates a data packet which is too long.
+
+ 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.1.0
Hi Luiz,
> On Mon, Mar 9, 2015 at 10:44 AM, Luiz Augusto von Dentz <[email protected]> wrote:
> Hi Arman,
>
> On Mon, Mar 9, 2015 at 7:36 PM, Arman Uguray <[email protected]> wrote:
>> Hi Luiz,
>>
>>> On Mon, Mar 9, 2015 at 5:26 AM, Luiz Augusto von Dentz <[email protected]> wrote:
>>> From: Luiz Augusto von Dentz <[email protected]>
>>>
>>> Updates the documentation defining a service hierarchy which can be used
>>> for defining LE Advertisement data and registering these advertisements
>>> to be broadcast.
>>>
>>> Note: Ive made some modifications since the last proposal taking away a
>>> good number of properties that could conflict if advertisement would be
>>> combined, in case we cannot use different random addresses for each AD.
>>> Also I include the intention to use the same interface for
>>> central/client role so the interface would be exposed in the device
>>> path.
>>
>> This is good, though should Michael maintain authorship of this commit
>> since it was his proposal?
>
> I have no problem either way.
>
>>> ---
>>> doc/advertising-api.txt | 90 +++++++++++++++++++++++++++++++++++++++++++++++++
>>> 1 file changed, 90 insertions(+)
>>> create mode 100644 doc/advertising-api.txt
>>>
>>> diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt
>>> new file mode 100644
>>> index 0000000..3ab4691
>>> --- /dev/null
>>> +++ b/doc/advertising-api.txt
>>> @@ -0,0 +1,90 @@
>>> +BlueZ D-Bus LE Advertising API Description
>>> +******************************************
>>> +
>>> +Advertising packets are structured data which is broadcast on the LE Advertising
>>> +channels and available for all devices in range. Because of the limited space
>>> +available in LE Advertising packets (32 bytes) , each packet's contents must be
>>> +controllable.
>>> +
>>> +BlueZ acts as a store for the multiple sets of Advertisement Data which is meant
>>> +to be sent. It constructs the correct Advertisement Data from the structured
>>> +data and communicates the sets of data to the kernel, where it is
>>> +multiplexed.
>>> +
>>> +Advertisement Data objects are registered freely and then referenced by BlueZ
>>> +when constructing the data sent to the kernel.
>>> +
>>> +LE Advertisement Data hierarchy
>>> +===============================
>>> +
>>> +Specifies the Advertisement Data to be broadcast and some advertising
>>> +parameters. Properties which are not present will not be included in the
>>> +data. Required advertisement data types will always be included.
>>> +All UUIDs are 128-bit versions in the API, and 16 or 32-bit
>>> +versions of the same UUID will be used in the advertising data as appropriate.
>>> +
>>> +Service org.bluez
>>> +Interface org.bluez.LEAdvertisement1
>>> +Object path freely definable or
>>> + /org/bluez/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
>>> +
>>> +Properties string Type
>>> +
>>> + Determines the type of advertising packet requested.
>>> +
>>> + Possible values: "broadcaster" or "peripheral"
>>> +
>>> + array{string} ServiceUUIDs [Optional]
>>> +
>>> + List of UUIDs to include in the "Service UUID" field of
>>> + the Advertising Data.
>>> +
>>> + dict ManufacturerData [Optional]
>>> +
>>> + Array of Manufactuer Specific Data fields to include in
>>> + the Advertising Data. Each dictionary entry includes
>>> + the Manufacturer ID and the raw bytes to include.
>>> +
>>> + array{string} SolicitUUIDs [Optional]
>>> +
>>> + Array of UUIDs to include in "Service Solicitation"
>>> + Advertisement Data.
>>> +
>>> + dict ServiceData [Optional]
>>> +
>>> + Array of Service Data to include. The keys are the
>>> + UUID to associate with the data.
>>> +
>>> +LE Advertising Manager hierarchy
>>> +================================
>>> +
>>> +The Advertising Manager allows external applications to register Advertisement
>>> +Data which should be broadcast to devices. Advertisement Data elements must
>>> +follow the API for LE Advertisement Data described above.
>>> +
>>> +Service org.bluez
>>> +Interface org.bluez.LEAdvertisementManager1 [Experimental]
>>> +Object path /org/bluez/{hci0,hci1,...}
>>> +
>>> +Methods 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. InvalidArguments
>>> + indicates that the object has invalid or conflicting
>>> + properties. InvalidLength indicates that the data
>>> + provided generates a data packet which is too long.
>>
>> Will this also cause the controller to start advertising? Or would we
>> want a separate Adapter1 API for this, e.g. StartAdvertising? We need
>> a good story for switching between central/scanner and
>> peripheral/broadcaster roles in general.
>
> I guess we could do that following similar design as discovery, with
> Advertising property, etc. We then should probably return an error if
> a discovering session is ongoing and vice versa.
>
Yes, we would also need to return an error if we're already connected
to a remote peripheral for example.
>>> +
>>> + 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.1.0
>>>
>>> --
>>> 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
>>
>> Thanks,
>> Arman
>
>
>
> --
> Luiz Augusto von Dentz
Arman
Hi Arman,
On Mon, Mar 9, 2015 at 7:36 PM, Arman Uguray <[email protected]> wrote:
> Hi Luiz,
>
>> On Mon, Mar 9, 2015 at 5:26 AM, Luiz Augusto von Dentz <[email protected]> wrote:
>> From: Luiz Augusto von Dentz <[email protected]>
>>
>> Updates the documentation defining a service hierarchy which can be used
>> for defining LE Advertisement data and registering these advertisements
>> to be broadcast.
>>
>> Note: Ive made some modifications since the last proposal taking away a
>> good number of properties that could conflict if advertisement would be
>> combined, in case we cannot use different random addresses for each AD.
>> Also I include the intention to use the same interface for
>> central/client role so the interface would be exposed in the device
>> path.
>
> This is good, though should Michael maintain authorship of this commit
> since it was his proposal?
I have no problem either way.
>> ---
>> doc/advertising-api.txt | 90 +++++++++++++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 90 insertions(+)
>> create mode 100644 doc/advertising-api.txt
>>
>> diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt
>> new file mode 100644
>> index 0000000..3ab4691
>> --- /dev/null
>> +++ b/doc/advertising-api.txt
>> @@ -0,0 +1,90 @@
>> +BlueZ D-Bus LE Advertising API Description
>> +******************************************
>> +
>> +Advertising packets are structured data which is broadcast on the LE Advertising
>> +channels and available for all devices in range. Because of the limited space
>> +available in LE Advertising packets (32 bytes) , each packet's contents must be
>> +controllable.
>> +
>> +BlueZ acts as a store for the multiple sets of Advertisement Data which is meant
>> +to be sent. It constructs the correct Advertisement Data from the structured
>> +data and communicates the sets of data to the kernel, where it is
>> +multiplexed.
>> +
>> +Advertisement Data objects are registered freely and then referenced by BlueZ
>> +when constructing the data sent to the kernel.
>> +
>> +LE Advertisement Data hierarchy
>> +===============================
>> +
>> +Specifies the Advertisement Data to be broadcast and some advertising
>> +parameters. Properties which are not present will not be included in the
>> +data. Required advertisement data types will always be included.
>> +All UUIDs are 128-bit versions in the API, and 16 or 32-bit
>> +versions of the same UUID will be used in the advertising data as appropriate.
>> +
>> +Service org.bluez
>> +Interface org.bluez.LEAdvertisement1
>> +Object path freely definable or
>> + /org/bluez/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
>> +
>> +Properties string Type
>> +
>> + Determines the type of advertising packet requested.
>> +
>> + Possible values: "broadcaster" or "peripheral"
>> +
>> + array{string} ServiceUUIDs [Optional]
>> +
>> + List of UUIDs to include in the "Service UUID" field of
>> + the Advertising Data.
>> +
>> + dict ManufacturerData [Optional]
>> +
>> + Array of Manufactuer Specific Data fields to include in
>> + the Advertising Data. Each dictionary entry includes
>> + the Manufacturer ID and the raw bytes to include.
>> +
>> + array{string} SolicitUUIDs [Optional]
>> +
>> + Array of UUIDs to include in "Service Solicitation"
>> + Advertisement Data.
>> +
>> + dict ServiceData [Optional]
>> +
>> + Array of Service Data to include. The keys are the
>> + UUID to associate with the data.
>> +
>> +LE Advertising Manager hierarchy
>> +================================
>> +
>> +The Advertising Manager allows external applications to register Advertisement
>> +Data which should be broadcast to devices. Advertisement Data elements must
>> +follow the API for LE Advertisement Data described above.
>> +
>> +Service org.bluez
>> +Interface org.bluez.LEAdvertisementManager1 [Experimental]
>> +Object path /org/bluez/{hci0,hci1,...}
>> +
>> +Methods 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. InvalidArguments
>> + indicates that the object has invalid or conflicting
>> + properties. InvalidLength indicates that the data
>> + provided generates a data packet which is too long.
>
> Will this also cause the controller to start advertising? Or would we
> want a separate Adapter1 API for this, e.g. StartAdvertising? We need
> a good story for switching between central/scanner and
> peripheral/broadcaster roles in general.
I guess we could do that following similar design as discovery, with
Advertising property, etc. We then should probably return an error if
a discovering session is ongoing and vice versa.
>> +
>> + 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.1.0
>>
>> --
>> 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
>
> Thanks,
> Arman
--
Luiz Augusto von Dentz
Hi Luiz,
> On Mon, Mar 9, 2015 at 5:26 AM, Luiz Augusto von Dentz <[email protected]> wrote:
> From: Luiz Augusto von Dentz <[email protected]>
>
> Updates the documentation defining a service hierarchy which can be used
> for defining LE Advertisement data and registering these advertisements
> to be broadcast.
>
> Note: Ive made some modifications since the last proposal taking away a
> good number of properties that could conflict if advertisement would be
> combined, in case we cannot use different random addresses for each AD.
> Also I include the intention to use the same interface for
> central/client role so the interface would be exposed in the device
> path.
This is good, though should Michael maintain authorship of this commit
since it was his proposal?
> ---
> doc/advertising-api.txt | 90 +++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 90 insertions(+)
> create mode 100644 doc/advertising-api.txt
>
> diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt
> new file mode 100644
> index 0000000..3ab4691
> --- /dev/null
> +++ b/doc/advertising-api.txt
> @@ -0,0 +1,90 @@
> +BlueZ D-Bus LE Advertising API Description
> +******************************************
> +
> +Advertising packets are structured data which is broadcast on the LE Advertising
> +channels and available for all devices in range. Because of the limited space
> +available in LE Advertising packets (32 bytes) , each packet's contents must be
> +controllable.
> +
> +BlueZ acts as a store for the multiple sets of Advertisement Data which is meant
> +to be sent. It constructs the correct Advertisement Data from the structured
> +data and communicates the sets of data to the kernel, where it is
> +multiplexed.
> +
> +Advertisement Data objects are registered freely and then referenced by BlueZ
> +when constructing the data sent to the kernel.
> +
> +LE Advertisement Data hierarchy
> +===============================
> +
> +Specifies the Advertisement Data to be broadcast and some advertising
> +parameters. Properties which are not present will not be included in the
> +data. Required advertisement data types will always be included.
> +All UUIDs are 128-bit versions in the API, and 16 or 32-bit
> +versions of the same UUID will be used in the advertising data as appropriate.
> +
> +Service org.bluez
> +Interface org.bluez.LEAdvertisement1
> +Object path freely definable or
> + /org/bluez/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
> +
> +Properties string Type
> +
> + Determines the type of advertising packet requested.
> +
> + Possible values: "broadcaster" or "peripheral"
> +
> + array{string} ServiceUUIDs [Optional]
> +
> + List of UUIDs to include in the "Service UUID" field of
> + the Advertising Data.
> +
> + dict ManufacturerData [Optional]
> +
> + Array of Manufactuer Specific Data fields to include in
> + the Advertising Data. Each dictionary entry includes
> + the Manufacturer ID and the raw bytes to include.
> +
> + array{string} SolicitUUIDs [Optional]
> +
> + Array of UUIDs to include in "Service Solicitation"
> + Advertisement Data.
> +
> + dict ServiceData [Optional]
> +
> + Array of Service Data to include. The keys are the
> + UUID to associate with the data.
> +
> +LE Advertising Manager hierarchy
> +================================
> +
> +The Advertising Manager allows external applications to register Advertisement
> +Data which should be broadcast to devices. Advertisement Data elements must
> +follow the API for LE Advertisement Data described above.
> +
> +Service org.bluez
> +Interface org.bluez.LEAdvertisementManager1 [Experimental]
> +Object path /org/bluez/{hci0,hci1,...}
> +
> +Methods 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. InvalidArguments
> + indicates that the object has invalid or conflicting
> + properties. InvalidLength indicates that the data
> + provided generates a data packet which is too long.
Will this also cause the controller to start advertising? Or would we
want a separate Adapter1 API for this, e.g. StartAdvertising? We need
a good story for switching between central/scanner and
peripheral/broadcaster roles in general.
> +
> + 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.1.0
>
> --
> 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
Thanks,
Arman