| 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. |
| |
| 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 |
| |
| 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-write] |
| |
| Value read from the remote Bluetooth device or from |
| the external application implementing GATT services. |
| |
| array{string} Flags [read-only, optional] |
| |
| 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" |
| |
| |
| 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 |
| |
| 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-write] |
| |
| Raw characteristic descriptor value read from the |
| remote Bluetooth device or from the external |
| application implementing GATT services. |
| |
| string Permissions [read-only]: To be defined |
| |
| Defines read/write authentication and authorization |
| requirements. |
| |
| 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 |
