doc/gatt-api.txt

   1 BlueZ D-Bus GATT API description
   2 ********************************
   3
   4 GATT local and remote services share the same high-level D-Bus API. Local
   5 refers to GATT based service exported by a BlueZ plugin or an external
   6 application. Remote refers to GATT services exported by the peer.
   7
   8 BlueZ acts as a proxy, translating ATT operations to D-Bus method calls and
   9 Properties (or the opposite). Support for D-Bus Object Manager is mandatory for
  10 external services to allow seamless GATT declarations (Service, Characteristic
  11 and Descriptors) discovery. Each GATT service tree is required to export a D-Bus
  12 Object Manager at its root that is solely responsible for the objects that
  13 belong to that service.
  14
  15 Releasing a registered GATT service is not defined yet. Any API extension
  16 should avoid breaking the defined API, and if possible keep an unified GATT
  17 remote and local services representation.
  18
  19 Service hierarchy
  20 =================
  21
  22 GATT remote and local service representation. Object path for local services
  23 is freely definable.
  24
  25 External applications implementing local services must register the services
  26 using GattManager1 registration method and must implement the methods and
  27 properties defined in GattService1 interface.
  28
  29 Service         org.bluez
  30 Interface       org.bluez.GattService1 [Experimental]
  31 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX
  32
  33 Properties      string UUID [read-only]
  34
  35                         128-bit service UUID.
  36
  37                 boolean Primary [read-only]
  38
  39                         Indicates whether or not this GATT service is a
  40                         primary service. If false, the service is secondary.
  41
  42                 object Device [read-only, optional]
  43
  44                         Object path of the Bluetooth device the service
  45                         belongs to. Only present on services from remote
  46                         devices.
  47
  48                 array{object} Characteristics [read-only]
  49
  50                         Array of object paths representing the characteristics
  51                         of this service. This property is set only when the
  52                         characteristic discovery has been completed, however the
  53                         characteristic objects will become available via
  54                         ObjectManager as soon as they get discovered.
  55
  56                 array{object} Includes [read-only]: Not implemented
  57
  58                         Array of object paths representing the included
  59                         services of this service.
  60
  61
  62 Characteristic hierarchy
  63 ========================
  64
  65 For local GATT defined services, the object paths need to follow the service
  66 path hierarchy and are freely definable.
  67
  68 Service         org.bluez
  69 Interface       org.bluez.GattCharacteristic1 [Experimental]
  70 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY
  71
  72 Methods         array{byte} ReadValue()
  73
  74                         Issues a request to read the value of the
  75                         characteristic and returns the value if the
  76                         operation was successful.
  77
  78                         Possible Errors: org.bluez.Error.Failed
  79                                          org.bluez.Error.InProgress
  80                                          org.bluez.Error.NotPermitted
  81                                          org.bluez.Error.NotAuthorized
  82                                          org.bluez.Error.NotSupported
  83
  84                 void WriteValue(array{byte} value)
  85
  86                         Issues a request to write the value of the
  87                         characteristic.
  88
  89                         Possible Errors: org.bluez.Error.Failed
  90                                          org.bluez.Error.InProgress
  91                                          org.bluez.Error.NotPermitted
  92                                          org.bluez.Error.InvalidValueLength
  93                                          org.bluez.Error.NotAuthorized
  94                                          org.bluez.Error.NotSupported
  95
  96                 void StartNotify()
  97
  98                         Starts a notification session from this characteristic
  99                         if it supports value notifications or indications.
 100
 101                         Possible Errors: org.bluez.Error.Failed
 102                                          org.bluez.Error.InProgress
 103                                          org.bluez.Error.NotSupported
 104
 105                 void StopNotify()
 106
 107                         This method will cancel any previous StartNotify
 108                         transaction. Note that notifications from a
 109                         characteristic are shared between sessions thus
 110                         calling StopNotify will release a single session.
 111
 112                         Possible Errors: org.bluez.Error.Failed
 113
 114 Properties      string UUID [read-only]
 115
 116                         128-bit characteristic UUID.
 117
 118                 object Service [read-only]
 119
 120                         Object path of the GATT service the characteristc
 121                         belongs to.
 122
 123                 array{byte} Value [read-only, optional]
 124
 125                         The cached value of the characteristic. This property
 126                         gets updated only after a successful read request and
 127                         when a notification or indication is received, upon
 128                         which a PropertiesChanged signal will be emitted.
 129
 130                 boolean Notifying [read-only]
 131
 132                         True, if notifications or indications on this
 133                         characteristic are currently enabled.
 134
 135                 array{string} Flags [read-only]
 136
 137                         Defines how the characteristic value can be used. See
 138                         Core spec "Table 3.5: Characteristic Properties bit
 139                         field", and "Table 3.8: Characteristic Extended
 140                         Properties bit field". Allowed values:
 141
 142                                 "broadcast"
 143                                 "read"
 144                                 "write-without-response"
 145                                 "write"
 146                                 "notify"
 147                                 "indicate"
 148                                 "authenticated-signed-writes"
 149                                 "reliable-write"
 150                                 "writable-auxiliaries"
 151                                 "encrypt-read"
 152                                 "encrypt-write"
 153                                 "encrypt-authenticated-read"
 154                                 "encrypt-authenticated-write"
 155
 156                 array{object} Descriptors [read-only]
 157
 158                         Array of object paths representing the descriptors
 159                         of this service. This property is set only when the
 160                         descriptor discovery has been completed, however the
 161                         descriptor objects will become available via
 162                         ObjectManager as soon as they get discovered.
 163
 164 #ifdef __TIZEN_PATCH__
 165                 string Unicast [read-only]
 166
 167                         12:34:56:78:9A:BC remote device address, if address is set then
 168                         notifications or indications shall be sent to only "XX_XX_XX_XX_XX_XX"
 169                         device otherwise notification or indication shall be multicasted.
 170 #endif
 171
 172 Characteristic Descriptors hierarchy
 173 ====================================
 174
 175 Local or remote GATT characteristic descriptors hierarchy.
 176
 177 Service         org.bluez
 178 Interface       org.bluez.GattDescriptor1 [Experimental]
 179 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ
 180
 181 Methods         array{byte} ReadValue()
 182
 183                         Issues a request to read the value of the
 184                         characteristic and returns the value if the
 185                         operation was successful.
 186
 187                         Possible Errors: org.bluez.Error.Failed
 188                                          org.bluez.Error.InProgress
 189                                          org.bluez.Error.NotPermitted
 190                                          org.bluez.Error.NotAuthorized
 191                                          org.bluez.Error.NotSupported
 192
 193                 void WriteValue(array{byte} value)
 194
 195                         Issues a request to write the value of the
 196                         characteristic.
 197
 198                         Possible Errors: org.bluez.Error.Failed
 199                                          org.bluez.Error.InProgress
 200                                          org.bluez.Error.NotPermitted
 201                                          org.bluez.Error.InvalidValueLength
 202                                          org.bluez.Error.NotAuthorized
 203                                          org.bluez.Error.NotSupported
 204
 205 Properties      string UUID [read-only]
 206
 207                         128-bit descriptor UUID.
 208
 209                 object Characteristic [read-only]
 210
 211                         Object path of the GATT characteristc the descriptor
 212                         belongs to.
 213
 214                 array{byte} Value [read-only, optional]
 215
 216                         The cached value of the descriptor. This property
 217                         gets updated only after a successful read request, upon
 218                         which a PropertiesChanged signal will be emitted.
 219
 220                 array{string} Flags [read-only]
 221
 222                         Defines how the descriptor value can be used.
 223
 224                         Possible values:
 225
 226                                 "read"
 227                                 "write"
 228                                 "encrypt-read"
 229                                 "encrypt-write"
 230                                 "encrypt-authenticated-read"
 231                                 "encrypt-authenticated-write"
 232
 233 Profile hierarcy
 234 ================
 235
 236 Local profile (GATT client) instance. By registering this type of object
 237 an application effectively indicates support for a specific GATT profile
 238 and requests automatic connections to be established to devices
 239 supporting it.
 240
 241 Service         <application dependent>
 242 Interface       org.bluez.GattProfile1 [Experimental]
 243 Object path     <application dependent>
 244
 245 Methods         void Release()
 246
 247                         This method gets called when the service daemon
 248                         unregisters the profile. The profile can use it to
 249                         do cleanup tasks. There is no need to unregister the
 250                         profile, because when this method gets called it has
 251                         already been unregistered.
 252
 253
 254 GATT Manager hierarchy
 255 ======================
 256
 257 GATT Manager allows external applications to register GATT services and
 258 profiles.
 259
 260 Registering a profile allows applications to subscribe to *remote* services.
 261 These must implement the GattProfile1 interface defined above.
 262
 263 Registering a service allows applications to publish a *local* GATT service,
 264 which then becomes available to remote devices. A GATT service is represented by
 265 a D-Bus object hierarchy where the root node corresponds to a service and the
 266 child nodes represent characteristics and descriptors that belong to that
 267 service. Each node must implement one of GattService1, GattCharacteristic1,
 268 or GattDescriptor1 interfaces described above, based on the attribute it
 269 represents. Each node must also implement the standard D-Bus Properties
 270 interface to expose their properties. These objects collectively represent a
 271 GATT service definition.
 272
 273 To make service registration simple, BlueZ requires that all objects that belong
 274 to a GATT service be grouped under a D-Bus Object Manager that solely manages
 275 the objects of that service. Hence, the standard DBus.ObjectManager interface
 276 must be available on the root service path. An example application hierarchy
 277 containing two separate GATT services may look like this:
 278
 279 -> /com/example
 280   |   - org.freedesktop.DBus.ObjectManager
 281   |
 282   -> /com/example/service0
 283   | |   - org.freedesktop.DBus.Properties
 284   | |   - org.bluez.GattService1
 285   | |
 286   | -> /com/example/service0/char0
 287   | |     - org.freedesktop.DBus.Properties
 288   | |     - org.bluez.GattCharacteristic1
 289   | |
 290   | -> /com/example/service0/char1
 291   |   |   - org.freedesktop.DBus.Properties
 292   |   |   - org.bluez.GattCharacteristic1
 293   |   |
 294   |   -> /com/example/service0/char1/desc0
 295   |       - org.freedesktop.DBus.Properties
 296   |       - org.bluez.GattDescriptor1
 297   |
 298   -> /com/example/service1
 299     |   - org.freedesktop.DBus.Properties
 300     |   - org.bluez.GattService1
 301     |
 302     -> /com/example/service1/char0
 303         - org.freedesktop.DBus.Properties
 304         - org.bluez.GattCharacteristic1
 305
 306 When a service is registered, BlueZ will automatically obtain information about
 307 all objects using the service's Object Manager. Once a service has been
 308 registered, the objects of a service should not be removed. If BlueZ receives an
 309 InterfacesRemoved signal from a service's Object Manager, it will immediately
 310 unregister the service. Similarly, if the application disconnects from the bus,
 311 all of its registered services will be automatically unregistered.
 312 InterfacesAdded signals will be ignored.
 313
 314 Service         org.bluez
 315 Interface       org.bluez.GattManager1 [Experimental]
 316 Object path     [variable prefix]/{hci0,hci1,...}
 317
 318 Methods         void RegisterApplication(object application, dict options)
 319
 320                         Registers a local GATT services hierarchy as described
 321                         above.
 322
 323                         The application object path together with the D-Bus
 324                         system bus connection ID define the identification of
 325                         the application registering a GATT based service.
 326
 327                         Possible errors: org.bluez.Error.InvalidArguments
 328                                          org.bluez.Error.AlreadyExists
 329
 330                 void UnregisterApplication(object application)
 331
 332                         This unregisters the services that has been
 333                         previously registered. The object path parameter
 334                         must match the same value that has been used
 335                         on registration.
 336
 337                         Possible errors: org.bluez.Error.InvalidArguments
 338                                          org.bluez.Error.DoesNotExist
 339
 340                 void RegisterProfile(object profile, array{string} UUIDs,
 341                                      dict options)
 342
 343                         Registers a GATT (client role) profile exported
 344                         under interface GattProfile1. The array of UUIDs
 345                         specifies the mandatory set of remote service
 346                         UUIDs that should all be available for the
 347                         remote device to match this profile. Matching
 348                         devices will be added to the auto-connection
 349                         list and connected whenever available.
 350
 351                         Possible errors: org.bluez.Error.InvalidArguments
 352                                          org.bluez.Error.AlreadyExists
 353
 354                 void UnregisterProfile(object profile)
 355
 356                         This unregisters the profile that has been
 357                         previously registered. The object path parameter
 358                         must match the same value that has been used
 359                         on registration.
 360
 361                         Possible errors: org.bluez.Error.InvalidArguments
 362                                          org.bluez.Error.DoesNotExist
 363 #ifdef __TIZEN_PATCH__
 364                 GetService(string uuid)
 365
 366                         This Reads the service, characterstics and descriptors
 367                         that has been previously registered. The string uuid parameter
 368                         must match the same value that has been used
 369                         on registration.
 370
 371                         The return values includes,
 372                         Key               objectpath
 373                         ----              -----------
 374                         Service           /serviceX
 375                         CharacteristicsX  /serviceX/CharacterisitcX
 376                         DescriptorX       /serviceX/CharacterisitcX/DescriptorX
 377
 378                         Possible errors: org.bluez.Error.InvalidArguments
 379 #endif