| 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 |
| 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} Includes [read-only, optional] |
| |
| 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 |
| Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY |
| |
| Methods array{byte} ReadValue(dict options) |
| |
| Issues a request to read the value of the |
| characteristic and returns the value if the |
| operation was successful. |
| |
| Possible options: "offset": uint16 offset |
| "device": Object Device (Server only) |
| |
| Possible Errors: org.bluez.Error.Failed |
| 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) |
| |
| Issues a request to write the value of the |
| characteristic. |
| |
| Possible options: "offset": Start offset |
| "device": Device path (Server only) |
| "link": Link type (Server only) |
| "prepare-authorize": boolean Is prepare |
| authorization |
| request |
| |
| 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 |
| |
| fd, uint16 AcquireWrite(dict options) [optional] |
| |
| Acquire file descriptor and MTU for writing. Usage of |
| WriteValue will be locked causing it to return |
| NotPermitted error. |
| |
| 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: "device": Object Device (Server only) |
| "MTU": Exchanged MTU (Server only) |
| "link": Link type (Server only) |
| |
| Possible Errors: org.bluez.Error.Failed |
| org.bluez.Error.NotSupported |
| |
| fd, uint16 AcquireNotify(dict options) [optional] |
| |
| Acquire file descriptor and MTU for notify. Usage of |
| StartNotify will be locked causing it to return |
| NotPermitted error. |
| |
| For server the MTU returned shall be equal or smaller |
| than the negotiated MTU. |
| |
| Only works with characteristic that has NotifyAcquired |
| 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: "device": Object Device (Server only) |
| "MTU": Exchanged MTU (Server only) |
| "link": Link type (Server only) |
| |
| Possible Errors: org.bluez.Error.Failed |
| 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.NotPermitted |
| 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 |
| |
| void Confirm() [optional] (Server only) |
| |
| This method doesn't expect a reply so it is just a |
| confirmation that value was received. |
| |
| 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 characteristic |
| 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 WriteAcquired [read-only, optional] |
| |
| True, if this characteristic has been acquired by any |
| client using AcquireWrite. |
| |
| 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] |
| |
| True, if this characteristic has been acquired by any |
| client using AcquireNotify. |
| |
| 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] |
| |
| 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" |
| "secure-read" (Server only) |
| "secure-write" (Server only) |
| "authorize" |
| |
| Characteristic Descriptors hierarchy |
| ==================================== |
| |
| Local or remote GATT characteristic descriptors hierarchy. |
| |
| Service org.bluez |
| Interface org.bluez.GattDescriptor1 |
| Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ |
| |
| Methods array{byte} ReadValue(dict flags) |
| |
| Issues a request to read the value of the |
| characteristic and returns the value if the |
| operation was successful. |
| |
| Possible options: "offset": Start offset |
| "device": Device path (Server only) |
| "link": Link type (Server only) |
| |
| 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, dict flags) |
| |
| Issues a request to write the value of the |
| characteristic. |
| |
| Possible options: "offset": Start offset |
| "device": Device path (Server only) |
| "link": Link type (Server only) |
| "prepare-authorize": boolean Is prepare |
| authorization |
| request |
| |
| 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 characteristic 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" |
| "secure-read" (Server Only) |
| "secure-write" (Server Only) |
| "authorize" |
| |
| GATT Profile hierarchy |
| ===================== |
| |
| 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 |
| 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. |
| |
| Properties array{string} UUIDs [read-only] |
| |
| 128-bit GATT service UUIDs to auto connect. |
| |
| |
| 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 |
| | - org.freedesktop.DBus.ObjectManager |
| | |
| -> /com/example/service0 |
| | | - 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.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. |
| |
| Examples: |
| - Client |
| test/example-gatt-client |
| client/bluetoothctl |
| - Server |
| test/example-gatt-server |
| tools/gatt-service |
| |
| |
| Service org.bluez |
| Interface org.bluez.GattManager1 |
| Object path [variable prefix]/{hci0,hci1,...} |
| |
| Methods void RegisterApplication(object application, dict options) |
| |
| Registers a local GATT services hierarchy as described |
| above (GATT Server) and/or GATT profiles (GATT Client). |
| |
| The application object path together with the D-Bus |
| system bus connection ID define the identification of |
| the application registering a GATT based |
| service or profile. |
| |
| Possible errors: org.bluez.Error.InvalidArguments |
| org.bluez.Error.AlreadyExists |
| |
| void UnregisterApplication(object application) |
| |
| This unregisters the services 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 |