| 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. |
| |
| 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" |
| |
| 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. |
| |
| |
| Service Manager hierarchy |
| ============================= |
| |
| Service Manager allows external applications to register GATT based |
| services. Services must follow the API for Service and Characteristic |
| described above. |
| |
| Local GATT services, characteristics and characteristic descriptors are |
| discovered automatically using the D-Bus Object Manager interface. |
| |
| Service org.bluez |
| Interface org.bluez.GattManager1 [Experimental] |
| Object path /org/bluez |
| |
| Methods RegisterService(object service, dict options) |
| |
| Registers remote application service exported under |
| interface GattService1. Characteristic objects must |
| be hierarchical to their service and must use the |
| interface GattCharacteristic1. D-Bus Object Manager |
| is used to fetch the exported objects. |
| |
| "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 |
| |
| 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 |
