1ORG.BLUEZ.GATTCHARACTERISTILCi(n5u)x System AdministrOaRtGi.oBnLUEZ.GATTCHARACTERISTIC(5)
2
3
4

NAME

6       org.bluez.GattCharacteristic - BlueZ D-Bus GattCharacteristic API docu‐
7       mentation
8

DESCRIPTION

10       GATT local/server and remote/client characteristic attribute  represen‐
11       tation share the same high-level D-Bus API.
12
13       Local/Server  refers to GATT based characteristics exported by a plugin
14       or an external application.
15
16       Remote/Client refers to GATT characteristics exported by the peer.
17

INTERFACE

19   Client
20       Service
21              org.bluez
22
23       Interface
24              org.bluez.GattCharacteristic1
25
26       Object path
27              [variable     prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/ser‐
28              viceXX/charYYYY
29
30   Server
31       Service
32              unique name
33
34       Interface
35              org.bluez.GattCharacteristic1
36
37       Object path
38              freely definable
39
40   Methods
41   array{byte} ReadValue(dict options)
42          Issues a request to read the value of the characteristic and returns
43          the value if the operation was successful.
44
45          Possible options:
46
47          uint16_t offset
48                 Read start offset in bytes.
49
50          uint16_t mtu (server only)
51                 Exchange MTU in bytes.
52
53          object device (server only)
54                 Device object.
55
56          Possible Errors:
57
58          org.bluez.Error.Failed
59                 Possible values: string 0x80 - 0x9f
60
61          org.bluez.Error.InProgress
62
63          org.bluez.Error.NotPermitted
64
65          org.bluez.Error.NotAuthorized
66
67          org.bluez.Error.InvalidOffset
68
69          org.bluez.Error.NotSupported
70
71   void WriteValue(array{byte} value, dict options)
72          Issues a request to write the value of the characteristic.
73
74          Possible options:
75
76          uint16 offset
77                 Write start offset in bytes.
78
79          string type
80                 Possible values:
81
82                 "command"
83                        Use Write without response procedure.
84
85                 "request"
86                        Use Write with response procedure.
87
88                 "reliable"
89                        Use Reliable Write procedure.
90
91          uint16 mtu
92                 Exchanged MTU (Server only).
93
94          object device
95                 Device path (Server only).
96
97          string link
98                 Link type (Server only).
99
100                 Possible values:
101
102                 "BR/EDR"
103
104                 "LE"
105
106          boolean prepare-authorize
107                 True if prepare authorization request.
108
109          Possible Errors:
110
111          org.bluez.Error.Failed
112                 Possible values: string 0x80 - 0x9f
113
114          org.bluez.Error.InProgress
115
116          org.bluez.Error.NotPermitted
117
118          org.bluez.Error.InvalidValueLength
119
120          org.bluez.Error.NotAuthorized
121
122          org.bluez.Error.NotSupported
123
124   fd, uint16 AcquireWrite(dict options) [optional]
125          Acquire file descriptor and MTU for writing. Only sockets  are  sup‐
126          ported.   Usage  of  WriteValue  will be locked causing it to return
127          NotPermitted error.
128
129          For server the MTU returned shall be equal or smaller than the nego‐
130          tiated MTU.
131
132          For  client it only works with characteristic that has WriteAcquired
133          property which relies on write-without-response Flag.
134
135          To release the lock the client shall close the  file  descriptor,  a
136          HUP is generated in case the device is disconnected.
137
138          Note: the MTU can only be negotiated once and is symmetric therefore
139          this method may be delayed in order to have the  exchange  MTU  com‐
140          pleted,  because of that the file descriptor is closed during recon‐
141          nections as the MTU has to be renegotiated.
142
143          Possible options:
144
145          object device
146                 Object Device (Server only).
147
148          uint16 mtu
149                 Exchanged MTU (Server only).
150
151          string link
152                 Link type (Server only).
153
154                 Possible values:
155
156                 "BR/EDR"
157
158                 "LE"
159
160          Possible Errors:
161
162          org.bluez.Error.Failed
163
164          org.bluez.Error.NotSupported
165
166   fd, uint16 AcquireNotify(dict options) [optional]
167          Acquire file descriptor and MTU for notify. Only  sockets  are  sup‐
168          port.
169
170          Usage   of   StartNotify   will  be  locked  causing  it  to  return
171          org.bluez.Error.NotPermitted.
172
173          For server the MTU returned shall be equal or smaller than the nego‐
174          tiated MTU.
175
176          Only  works  with  characteristic  that  has NotifyAcquired property
177          which relies on "notify" Flag and no other client have called Start‐
178          Notify().
179
180          Notification  are  enabled  during  this  procedure so StartNotify()
181          shall not be called, any notification will be  dispatched  via  file
182          descriptor  therefore  the Value property is not affected during the
183          time where notify has been acquired.
184
185          To release the lock the client shall close the  file  descriptor,  a
186          HUP is generated in case the device is disconnected.
187
188          Note: the MTU can only be negotiated once and is symmetric therefore
189          this method may be delayed in order to have the  exchange  MTU  com‐
190          pleted,  because of that the file descriptor is closed during recon‐
191          nections as the MTU has to be renegotiated.
192
193          Possible options:
194
195          object device
196                 Object Device (Server only).
197
198          uint16 mtu
199                 Exchanged MTU (Server only).
200
201          string link
202                 Link type (Server only).
203
204                 Possible values:
205
206                 "BR/EDR"
207
208                 "LE"
209
210          Possible Errors:
211
212          org.bluez.Error.Failed
213
214          org.bluez.Error.NotSupported
215
216          org.bluez.Error.NotPermitted
217
218   void StartNotify()
219          Starts a notification session from this characteristic  if  it  sup‐
220          ports value notifications or indications.
221
222          Possible Errors:
223
224          org.bluez.Error.Failed
225
226          org.bluez.Error.NotPermitted
227
228          org.bluez.Error.InProgress
229
230          org.bluez.Error.NotConnected
231
232          org.bluez.Error.NotSupported
233
234   void StopNotify()
235          Stops or cancel session previously created by StartNotify().
236
237          Note  that  notifications  from  a characteristic are shared between
238          sessions thus calling StopNotify will release a single session.
239
240          Possible Errors:
241
242          org.bluez.Error.Failed
243
244   void Confirm() [noreply, optional] (Server only)
245          Confirms value was received.
246
247          Possible Errors:
248
249          org.bluez.Error.Failed
250
251   Properties
252   string UUID [read-only]
253          128-bit characteristic UUID.
254
255   object Service [read-only]
256          Object path of the GATT service the characteristic belongs to.
257
258   array{byte} Value [read-only, optional]
259          The cached value of the characteristic. This property  gets  updated
260          only  after a successful read request and when a notification or in‐
261          dication is received, upon which a PropertiesChanged signal will  be
262          emitted.
263
264   boolean WriteAcquired [read-only, optional]
265          True,  if  this characteristic has been acquired by any client using
266          AcquireWrite.
267
268          For client properties is ommited  in  case  'write-without-response'
269          flag is not set.
270
271          For server the presence of this property indicates that AcquireWrite
272          is supported.
273
274   boolean NotifyAcquired [read-only, optional]
275          True, if this characteristic has been acquired by any  client  using
276          AcquireNotify.
277
278          For  client  this properties is ommited in case 'notify' flag is not
279          set.
280
281          For server the presence of this property indicates  that  AcquireNo‐
282          tify is supported.
283
284   boolean Notifying [read-only, optional]
285          True,  if  notifications  or  indications on this characteristic are
286          currently enabled.
287
288   array{string} Flags [read-only]
289          Defines how the characteristic value can be used. See Core spec "Ta‐
290          ble 3.5: Characteristic Properties bit field", and "Table 3.8: Char‐
291          acteristic Extended Properties bit field".
292
293          The "x-notify" and "x-indicate" flags restrict access  to  notifica‐
294          tions and indications by imposing write restrictions on a character‐
295          istic's client characteristic configuration descriptor.
296
297          Possible values:
298
299          "broadcast"
300
301          "read"
302
303          "write-without-response"
304
305          "write"
306
307          "notify"
308
309          "indicate"
310
311          "authenticated-signed-writes"
312
313          "extended-properties"
314
315          "reliable-write"
316
317          "writable-auxiliaries"
318
319          "encrypt-read"
320
321          "encrypt-write"
322
323          "encrypt-notify" (Server only)
324
325          "encrypt-indicate" (Server only)
326
327          "encrypt-authenticated-read"
328
329          "encrypt-authenticated-write"
330
331          "encrypt-authenticated-notify" (Server only)
332
333          "encrypt-authenticated-indicate" (Server only)
334
335          "secure-read" (Server only)
336
337          "secure-write" (Server only)
338
339          "secure-notify" (Server only)
340
341          "secure-indicate" (Server only)
342
343          "authorize"
344
345   uint16 Handle [read-only] (Client Only)
346          Characteristic handle.
347
348   uint16 Handle [read-write, optional] (Server Only)
349          Characteristic handle. When available in the server it would attempt
350          to  use  to allocate into the database which may fail, to auto allo‐
351          cate the value 0x0000 shall be used which will cause  the  allocated
352          handle to be set once registered.
353
354   uint16 MTU [read-only]
355          Characteristic  MTU,  this  is valid both for ReadValue() and Write‐
356          Value() but either method can use long procedures when supported.
357
358
359
360
361BlueZ                            October 2023  ORG.BLUEZ.GATTCHARACTERISTIC(5)