doc/advertising-api.txt

   1 BlueZ D-Bus LE Advertising API Description
   2 ******************************************
   3
   4 Advertising packets are structured data which is broadcast on the LE Advertising
   5 channels and available for all devices in range.  Because of the limited space
   6 available in LE Advertising packets (32 bytes), each packet's contents must be
   7 carefully controlled.
   8
   9 BlueZ acts as a store for the Advertisement Data which is meant to be sent.
  10 It constructs the correct Advertisement Data from the structured
  11 data and configured the kernel to send the correct advertisement.
  12
  13 Advertisement Data objects are registered freely and then referenced by BlueZ
  14 when constructing the data sent to the kernel.
  15
  16 LE Advertisement Data hierarchy
  17 ===============================
  18
  19 Specifies the Advertisement Data to be broadcast and some advertising
  20 parameters.  Properties which are not present will not be included in the
  21 data.  Required advertisement data types will always be included.
  22 All UUIDs are 128-bit versions in the API, and 16 or 32-bit
  23 versions of the same UUID will be used in the advertising data as appropriate.
  24
  25 Service         org.bluez
  26 Interface       org.bluez.LEAdvertisement1
  27 Object path     freely definable
  28
  29 Methods         void Release() [noreply]
  30
  31                         This method gets called when the service daemon
  32                         removes the Advertisement. A client can use it to do
  33                         cleanup tasks. There is no need to call
  34                         UnregisterAdvertisement because when this method gets
  35                         called it has already been unregistered.
  36
  37 Properties      string Type
  38
  39                         Determines the type of advertising packet requested.
  40
  41                         Possible values: "broadcast" or "peripheral"
  42
  43                 array{string} ServiceUUIDs
  44
  45                         List of UUIDs to include in the "Service UUID" field of
  46                         the Advertising Data.
  47
  48                 dict ManufacturerData
  49
  50                         Manufactuer Data fields to include in
  51                         the Advertising Data.  Keys are the Manufacturer ID
  52                         to associate with the data.
  53
  54                 array{string} SolicitUUIDs
  55
  56                         Array of UUIDs to include in "Service Solicitation"
  57                         Advertisement Data.
  58
  59                 dict ServiceData
  60
  61                         Service Data elements to include. The keys are the
  62                         UUID to associate with the data.
  63
  64                 bool IncludeTxPower
  65
  66                         Includes the Tx Power in the advertising packet.
  67                         If missing, the Tx Power is not included.
  68
  69
  70 LE Advertising Manager hierarchy
  71 ================================
  72
  73 The Advertising Manager allows external applications to register Advertisement
  74 Data which should be broadcast to devices.  Advertisement Data elements must
  75 follow the API for LE Advertisement Data described above.
  76
  77 Service         org.bluez
  78 Interface       org.bluez.LEAdvertisingManager1 [Experimental]
  79 Object path     /org/bluez/{hci0,hci1,...}
  80
  81 Methods         RegisterAdvertisement(object advertisement, dict options)
  82
  83                         Registers an advertisement object to be sent over the LE
  84                         Advertising channel.  The service must be exported
  85                         under interface LEAdvertisement1. InvalidArguments
  86                         indicates that the object has invalid or conflicting
  87                         properties.  InvalidLength indicates that the data
  88                         provided generates a data packet which is too long.
  89                         The properties of this object are parser when it is
  90                         registered, and any changes are ignored.
  91                         Currently only one advertisement at a time is supported,
  92                         attempting to register two advertisements will result in
  93                         an AlreadyExists error.
  94
  95                         Possible errors: org.bluez.Error.InvalidArguments
  96                                          org.bluez.Error.AlreadyExists
  97                                          org.bluez.Error.InvalidLength
  98
  99                 UnregisterAdvertisement(object advertisement)
 100
 101                         This unregisters an advertisement that has been
 102                         prevously registered.  The object path parameter must
 103                         match the same value that has been used on registration.
 104
 105                         Possible errors: org.bluez.Error.InvalidArguments
 106                                          org.bluez.Error.DoesNotExist