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 [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" "encrypt-read" "encrypt-write" "encrypt-authenticated-read" "encrypt-authenticated-write" 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. 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" Profile hierarcy ================ 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 Interface org.bluez.GattProfile1 [Experimental] Object path 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. 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 | -> /com/example/service0 | | - org.freedesktop.DBus.ObjectManager | | - 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.ObjectManager | - 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. Service org.bluez Interface org.bluez.GattManager1 [Experimental] Object path [variable prefix]/{hci0,hci1,...} Methods void RegisterService(object service, dict options) Registers a local GATT service hierarchy as described above. "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 void 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 void RegisterProfile(object profile, array{string} UUIDs, dict options) Registers a GATT (client role) profile exported under interface GattProfile1. The array of UUIDs specifies the mandatory set of remote service UUIDs that should all be available for the remote device to match this profile. Matching devices will be added to the auto-connection list and connected whenever available. Possible errors: org.bluez.Error.InvalidArguments org.bluez.Error.AlreadyExists void UnregisterProfile(object profile) This unregisters the profile 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