1 BlueZ D-Bus GATT API description
2 ********************************
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.
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.
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.
22 GATT remote and local service representation. Object path for local services
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.
30 Interface org.bluez.GattService1 [Experimental]
31 Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX
33 Properties string UUID [read-only]
37 boolean Primary [read-only]
39 Indicates whether or not this GATT service is a
40 primary service. If false, the service is secondary.
42 object Device [read-only, optional]
44 Object path of the Bluetooth device the service
45 belongs to. Only present on services from remote
48 array{object} Characteristics [read-only]
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.
56 array{object} Includes [read-only]: Not implemented
58 Array of object paths representing the included
59 services of this service.
62 Characteristic hierarchy
63 ========================
65 For local GATT defined services, the object paths need to follow the service
66 path hierarchy and are freely definable.
69 Interface org.bluez.GattCharacteristic1 [Experimental]
70 Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY
72 Methods array{byte} ReadValue()
74 Issues a request to read the value of the
75 characteristic and returns the value if the
76 operation was successful.
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
84 void WriteValue(array{byte} value)
86 Issues a request to write the value of the
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
98 Starts a notification session from this characteristic
99 if it supports value notifications or indications.
101 Possible Errors: org.bluez.Error.Failed
102 org.bluez.Error.InProgress
103 org.bluez.Error.NotSupported
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.
112 Possible Errors: org.bluez.Error.Failed
114 Properties string UUID [read-only]
116 128-bit characteristic UUID.
118 object Service [read-only]
120 Object path of the GATT service the characteristc
123 array{byte} Value [read-only, optional]
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.
130 boolean Notifying [read-only]
132 True, if notifications or indications on this
133 characteristic are currently enabled.
135 array{string} Flags [read-only]
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:
144 "write-without-response"
148 "authenticated-signed-writes"
150 "writable-auxiliaries"
153 "encrypt-authenticated-read"
154 "encrypt-authenticated-write"
156 array{object} Descriptors [read-only]
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.
164 #ifdef __TIZEN_PATCH__
165 string Unicast [read-only]
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.
172 Characteristic Descriptors hierarchy
173 ====================================
175 Local or remote GATT characteristic descriptors hierarchy.
178 Interface org.bluez.GattDescriptor1 [Experimental]
179 Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ
181 Methods array{byte} ReadValue()
183 Issues a request to read the value of the
184 characteristic and returns the value if the
185 operation was successful.
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
193 void WriteValue(array{byte} value)
195 Issues a request to write the value of the
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
205 Properties string UUID [read-only]
207 128-bit descriptor UUID.
209 object Characteristic [read-only]
211 Object path of the GATT characteristc the descriptor
214 array{byte} Value [read-only, optional]
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.
220 array{string} Flags [read-only]
222 Defines how the descriptor value can be used.
230 "encrypt-authenticated-read"
231 "encrypt-authenticated-write"
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
241 Service <application dependent>
242 Interface org.bluez.GattProfile1 [Experimental]
243 Object path <application dependent>
245 Methods void Release()
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.
254 GATT Manager hierarchy
255 ======================
257 GATT Manager allows external applications to register GATT services and
260 Registering a profile allows applications to subscribe to *remote* services.
261 These must implement the GattProfile1 interface defined above.
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.
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:
280 | - org.freedesktop.DBus.ObjectManager
282 -> /com/example/service0
283 | | - org.freedesktop.DBus.Properties
284 | | - org.bluez.GattService1
286 | -> /com/example/service0/char0
287 | | - org.freedesktop.DBus.Properties
288 | | - org.bluez.GattCharacteristic1
290 | -> /com/example/service0/char1
291 | | - org.freedesktop.DBus.Properties
292 | | - org.bluez.GattCharacteristic1
294 | -> /com/example/service0/char1/desc0
295 | - org.freedesktop.DBus.Properties
296 | - org.bluez.GattDescriptor1
298 -> /com/example/service1
299 | - org.freedesktop.DBus.Properties
300 | - org.bluez.GattService1
302 -> /com/example/service1/char0
303 - org.freedesktop.DBus.Properties
304 - org.bluez.GattCharacteristic1
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.
315 Interface org.bluez.GattManager1 [Experimental]
316 Object path [variable prefix]/{hci0,hci1,...}
318 Methods void RegisterApplication(object application, dict options)
320 Registers a local GATT services hierarchy as described
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.
327 Possible errors: org.bluez.Error.InvalidArguments
328 org.bluez.Error.AlreadyExists
330 void UnregisterApplication(object application)
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
337 Possible errors: org.bluez.Error.InvalidArguments
338 org.bluez.Error.DoesNotExist
340 void RegisterProfile(object profile, array{string} UUIDs,
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.
351 Possible errors: org.bluez.Error.InvalidArguments
352 org.bluez.Error.AlreadyExists
354 void UnregisterProfile(object profile)
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
361 Possible errors: org.bluez.Error.InvalidArguments
362 org.bluez.Error.DoesNotExist
363 #ifdef __TIZEN_PATCH__
364 GetService(string uuid)
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
371 The return values includes,
375 CharacteristicsX /serviceX/CharacterisitcX
376 DescriptorX /serviceX/CharacterisitcX/DescriptorX
378 Possible errors: org.bluez.Error.InvalidArguments