Return-Path: MIME-Version: 1.0 In-Reply-To: <1425903978-24536-1-git-send-email-luiz.dentz@gmail.com> References: <1425903978-24536-1-git-send-email-luiz.dentz@gmail.com> Date: Mon, 9 Mar 2015 10:36:01 -0700 Message-ID: Subject: Re: [RFC BlueZ] doc: Add LE Advertisement Manager From: Arman Uguray To: Luiz Augusto von Dentz Cc: BlueZ development Content-Type: text/plain; charset=UTF-8 Sender: linux-bluetooth-owner@vger.kernel.org List-ID: Hi Luiz, > On Mon, Mar 9, 2015 at 5:26 AM, Luiz Augusto von Dentz wrote: > From: Luiz Augusto von Dentz > > 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 majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html Thanks, Arman