table of contents
ORG.BLUEZ.GATTCHARACTERISTIC(5) | Linux System Administration | ORG.BLUEZ.GATTCHARACTERISTIC(5) |
NAME¶
org.bluez.GattCharacteristic - BlueZ D-Bus GattCharacteristic API documentation
DESCRIPTION¶
GATT local/server and remote/client characteristic attribute representation share the same high-level D-Bus API.
Local/Server refers to GATT based characteristics exported by a plugin or an external application.
Remote/Client refers to GATT characteristics exported by the peer.
INTERFACE¶
Client¶
- Service
- org.bluez
- Interface
- org.bluez.GattCharacteristic1
- Object path
- [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY
Server¶
- Service
- unique name
- Interface
- org.bluez.GattCharacteristic1
- Object path
- freely definable
Methods¶
array{byte} ReadValue(dict options)¶
Possible options:
- uint16_t offset
- Read start offset in bytes.
- uint16_t mtu (server only)
- Exchange MTU in bytes.
- object device (server only)
- Device object.
Possible Errors:
- org.bluez.Error.Failed
- Possible values: string 0x80 - 0x9f
- org.bluez.Error.InProgress
- org.bluez.Error.NotPermitted
- org.bluez.Error.NotAuthorized
- org.bluez.Error.InvalidOffset
- org.bluez.Error.NotSupported
void WriteValue(array{byte} value, dict options)¶
Possible options:
- uint16 offset
- Write start offset in bytes.
- string type
- Possible values:
- "command"
- Use Write without response procedure.
- "request"
- Use Write with response procedure.
- "reliable"
- Use Reliable Write procedure.
- uint16 mtu
- Exchanged MTU (Server only).
- object device
- Device path (Server only).
- string link
- Link type (Server only).
Possible values:
- "BR/EDR"
- "LE"
- boolean prepare-authorize
- True if prepare authorization request.
Possible Errors:
fd, uint16 AcquireWrite(dict options) [optional]¶
For server the MTU returned shall be equal or smaller than the negotiated MTU.
For client it only works with characteristic that has WriteAcquired property which relies on write-without-response Flag.
To release the lock the client shall close the file descriptor, a HUP is generated in case the device is disconnected.
Note: the MTU can only be negotiated once and is symmetric therefore this method may be delayed in order to have the exchange MTU completed, because of that the file descriptor is closed during reconnections as the MTU has to be renegotiated.
Possible options:
- object device
- Object Device (Server only).
- uint16 mtu
- Exchanged MTU (Server only).
- string link
- Link type (Server only).
Possible values:
- "BR/EDR"
- "LE"
Possible Errors:
fd, uint16 AcquireNotify(dict options) [optional]¶
Usage of StartNotify will be locked causing it to return org.bluez.Error.NotPermitted.
For server the MTU returned shall be equal or smaller than the negotiated MTU.
Only works with characteristic that has NotifyAcquired property which relies on "notify" Flag and no other client have called StartNotify().
Notification are enabled during this procedure so StartNotify() shall not be called, any notification will be dispatched via file descriptor therefore the Value property is not affected during the time where notify has been acquired.
To release the lock the client shall close the file descriptor, a HUP is generated in case the device is disconnected.
Note: the MTU can only be negotiated once and is symmetric therefore this method may be delayed in order to have the exchange MTU completed, because of that the file descriptor is closed during reconnections as the MTU has to be renegotiated.
Possible options:
- object device
- Object Device (Server only).
- uint16 mtu
- Exchanged MTU (Server only).
- string link
- Link type (Server only).
Possible values:
- "BR/EDR"
- "LE"
Possible Errors:
void StartNotify()¶
Possible Errors:
void StopNotify()¶
Note that notifications from a characteristic are shared between sessions thus calling StopNotify will release a single session.
Possible Errors:
void Confirm() [noreply, optional] (Server only)¶
Possible Errors:
org.bluez.Error.Failed
Properties¶
string UUID [read-only]¶
object Service [read-only]¶
array{byte} Value [read-only, optional]¶
boolean WriteAcquired [read-only, optional]¶
For client properties is ommited in case 'write-without-response' flag is not set.
For server the presence of this property indicates that AcquireWrite is supported.
boolean NotifyAcquired [read-only, optional]¶
For client this properties is ommited in case 'notify' flag is not set.
For server the presence of this property indicates that AcquireNotify is supported.
boolean Notifying [read-only, optional]¶
array{string} Flags [read-only]¶
The "x-notify" and "x-indicate" flags restrict access to notifications and indications by imposing write restrictions on a characteristic's client characteristic configuration descriptor.
Possible values:
- "broadcast"
- "read"
- "write-without-response"
- "write"
- "notify"
- "indicate"
- "authenticated-signed-writes"
- "extended-properties"
- "reliable-write"
- "writable-auxiliaries"
- "encrypt-read"
- "encrypt-write"
- "encrypt-notify" (Server only)
- "encrypt-indicate" (Server only)
- "encrypt-authenticated-read"
- "encrypt-authenticated-write"
- "encrypt-authenticated-notify" (Server only)
- "encrypt-authenticated-indicate" (Server only)
- "secure-read" (Server only)
- "secure-write" (Server only)
- "secure-notify" (Server only)
- "secure-indicate" (Server only)
- "authorize"
uint16 Handle [read-only] (Client Only)¶
uint16 Handle [read-write, optional] (Server Only)¶
uint16 MTU [read-only]¶
October 2023 | BlueZ |