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
 152                 array{object} Descriptors [read-only]
 153
 154                         Array of object paths representing the descriptors
 155                         of this service. This property is set only when the
 156                         descriptor discovery has been completed, however the
 157                         descriptor objects will become available via
 158                         ObjectManager as soon as they get discovered.
 159
 160
 161 Characteristic Descriptors hierarchy
 162 ====================================
 163
 164 Local or remote GATT characteristic descriptors hierarchy.
 165
 166 Service         org.bluez
 167 Interface       org.bluez.GattDescriptor1 [Experimental]
 168 Object path     [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ
 169
 170 Methods         array{byte} ReadValue()
 171
 172                         Issues a request to read the value of the
 173                         characteristic and returns the value if the
 174                         operation was successful.
 175
 176                         Possible Errors: org.bluez.Error.Failed
 177                                          org.bluez.Error.InProgress
 178                                          org.bluez.Error.NotPermitted
 179                                          org.bluez.Error.NotAuthorized
 180                                          org.bluez.Error.NotSupported
 181
 182                 void WriteValue(array{byte} value)
 183
 184                         Issues a request to write the value of the
 185                         characteristic.
 186
 187                         Possible Errors: org.bluez.Error.Failed
 188                                          org.bluez.Error.InProgress
 189                                          org.bluez.Error.NotPermitted
 190                                          org.bluez.Error.InvalidValueLength
 191                                          org.bluez.Error.NotAuthorized
 192                                          org.bluez.Error.NotSupported
 193
 194 Properties      string UUID [read-only]
 195
 196                         128-bit descriptor UUID.
 197
 198                 object Characteristic [read-only]
 199
 200                         Object path of the GATT characteristc the descriptor
 201                         belongs to.
 202
 203                 array{byte} Value [read-only, optional]
 204
 205                         The cached value of the descriptor. This property
 206                         gets updated only after a successful read request, upon
 207                         which a PropertiesChanged signal will be emitted.
 208
 209
 210 Profile hierarcy
 211 ================
 212
 213 Local profile (GATT client) instance. By registering this type of object
 214 an application effectively indicates support for a specific GATT profile
 215 and requests automatic connections to be established to devices
 216 supporting it.
 217
 218 Service         <application dependent>
 219 Interface       org.bluez.GattProfile1 [Experimental]
 220 Object path     <application dependent>
 221
 222 Methods         void Release()
 223
 224                         This method gets called when the service daemon
 225                         unregisters the profile. The profile can use it to
 226                         do cleanup tasks. There is no need to unregister the
 227                         profile, because when this method gets called it has
 228                         already been unregistered.
 229
 230
 231 GATT Manager hierarchy
 232 ======================
 233
 234 GATT Manager allows external applications to register GATT services and
 235 profiles.
 236
 237 Registering a profile allows applications to subscribe to *remote* services.
 238 These must implement the GattProfile1 interface defined above.
 239
 240 Registering a service allows applications to publish a *local* GATT service,
 241 which then becomes available to remote devices. A GATT service is represented by
 242 a D-Bus object hierarchy where the root node corresponds to a service and the
 243 child nodes represent characteristics and descriptors that belong to that
 244 service. Each node must implement one of GattService1, GattCharacteristic1,
 245 or GattDescriptor1 interfaces described above, based on the attribute it
 246 represents. Each node must also implement the standard D-Bus Properties
 247 interface to expose their properties. These objects collectively represent a
 248 GATT service definition.
 249
 250 To make service registration simple, BlueZ requires that all objects that belong
 251 to a GATT service be grouped under a D-Bus Object Manager that solely manages
 252 the objects of that service. Hence, the standard DBus.ObjectManager interface
 253 must be available on the root service path. An example application hierarchy
 254 containing two separate GATT services may look like this:
 255
 256 -> /com/example
 257   |
 258   -> /com/example/service0
 259   | |   - org.freedesktop.DBus.ObjectManager
 260   | |   - org.freedesktop.DBus.Properties
 261   | |   - org.bluez.GattService1
 262   | |
 263   | -> /com/example/service0/char0
 264   | |     - org.freedesktop.DBus.Properties
 265   | |     - org.bluez.GattCharacteristic1
 266   | |
 267   | -> /com/example/service0/char1
 268   |   |   - org.freedesktop.DBus.Properties
 269   |   |   - org.bluez.GattCharacteristic1
 270   |   |
 271   |   -> /com/example/service0/char1/desc0
 272   |       - org.freedesktop.DBus.Properties
 273   |       - org.bluez.GattDescriptor1
 274   |
 275   -> /com/example/service1
 276     |   - org.freedesktop.DBus.ObjectManager
 277     |   - org.freedesktop.DBus.Properties
 278     |   - org.bluez.GattService1
 279     |
 280     -> /com/example/service1/char0
 281         - org.freedesktop.DBus.Properties
 282         - org.bluez.GattCharacteristic1
 283
 284 When a service is registered, BlueZ will automatically obtain information about
 285 all objects using the service's Object Manager. Once a service has been
 286 registered, the objects of a service should not be removed. If BlueZ receives an
 287 InterfacesRemoved signal from a service's Object Manager, it will immediately
 288 unregister the service. Similarly, if the application disconnects from the bus,
 289 all of its registered services will be automatically unregistered.
 290 InterfacesAdded signals will be ignored.
 291
 292 Service         org.bluez
 293 Interface       org.bluez.GattManager1 [Experimental]
 294 Object path     [variable prefix]/{hci0,hci1,...}
 295
 296 Methods         void RegisterService(object service, dict options)
 297
 298                         Registers a local GATT service hierarchy as described
 299                         above.
 300
 301                         "service" object path together with the D-Bus system
 302                         bus connection ID define the identification of the
 303                         application registering a GATT based service.
 304
 305                         Possible errors: org.bluez.Error.InvalidArguments
 306                                          org.bluez.Error.AlreadyExists
 307
 308                 void UnregisterService(object service)
 309
 310                         This unregisters the service that has been
 311                         previously registered. The object path parameter
 312                         must match the same value that has been used
 313                         on registration.
 314
 315                         Possible errors: org.bluez.Error.InvalidArguments
 316                                          org.bluez.Error.DoesNotExist
 317
 318                 void RegisterProfile(object profile, array{string} UUIDs,
 319                                      dict options)
 320
 321                         Registers a GATT (client role) profile exported
 322                         under interface GattProfile1. The array of UUIDs
 323                         specifies the mandatory set of remote service
 324                         UUIDs that should all be available for the
 325                         remote device to match this profile. Matching
 326                         devices will be added to the auto-connection
 327                         list and connected whenever available.
 328
 329                         Possible errors: org.bluez.Error.InvalidArguments
 330                                          org.bluez.Error.AlreadyExists
 331
 332                 void UnregisterProfile(object profile)
 333
 334                         This unregisters the profile that has been
 335                         previously registered. The object path parameter
 336                         must match the same value that has been used
 337                         on registration.
 338
 339                         Possible errors: org.bluez.Error.InvalidArguments
 340                                          org.bluez.Error.DoesNotExist
 341 #ifdef __TIZEN_PATCH__
 342                 GetService(string uuid)
 343
 344                         This Reads the service, characterstics and descriptors
 345                         that has been previously registered. The string uuid parameter
 346                         must match the same value that has been used
 347                         on registration.
 348
 349                         The return values includes,
 350                         Key               objectpath
 351                         ----              -----------
 352                         Service           /serviceX
 353                         CharacteristicsX  /serviceX/CharacterisitcX
 354                         DescriptorX       /serviceX/CharacterisitcX/DescriptorX
 355
 356                         Possible errors: org.bluez.Error.InvalidArguments
 357 #endif