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