mirror of
https://git.kernel.org/pub/scm/bluetooth/bluez.git
synced 2024-11-28 14:44:39 +08:00
fe2cf29b3b
This adds Flags property to GattDescriptor so the server can define permissions and authentication requirements for descriptors.
357 lines
11 KiB
Plaintext
357 lines
11 KiB
Plaintext
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 <application dependent>
|
|
Interface org.bluez.GattProfile1 [Experimental]
|
|
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.
|
|
|
|
|
|
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
|