|
Packit Service |
8264ee |
BlueZ D-Bus GATT API description
|
|
Packit Service |
8264ee |
********************************
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
GATT local and remote services share the same high-level D-Bus API. Local
|
|
Packit Service |
8264ee |
refers to GATT based service exported by a BlueZ plugin or an external
|
|
Packit Service |
8264ee |
application. Remote refers to GATT services exported by the peer.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
BlueZ acts as a proxy, translating ATT operations to D-Bus method calls and
|
|
Packit Service |
8264ee |
Properties (or the opposite). Support for D-Bus Object Manager is mandatory for
|
|
Packit Service |
8264ee |
external services to allow seamless GATT declarations (Service, Characteristic
|
|
Packit Service |
8264ee |
and Descriptors) discovery. Each GATT service tree is required to export a D-Bus
|
|
Packit Service |
8264ee |
Object Manager at its root that is solely responsible for the objects that
|
|
Packit Service |
8264ee |
belong to that service.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Releasing a registered GATT service is not defined yet. Any API extension
|
|
Packit Service |
8264ee |
should avoid breaking the defined API, and if possible keep an unified GATT
|
|
Packit Service |
8264ee |
remote and local services representation.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Service hierarchy
|
|
Packit Service |
8264ee |
=================
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
GATT remote and local service representation. Object path for local services
|
|
Packit Service |
8264ee |
is freely definable.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
External applications implementing local services must register the services
|
|
Packit Service |
8264ee |
using GattManager1 registration method and must implement the methods and
|
|
Packit Service |
8264ee |
properties defined in GattService1 interface.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Service org.bluez
|
|
Packit Service |
8264ee |
Interface org.bluez.GattService1
|
|
Packit Service |
8264ee |
Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Properties string UUID [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
128-bit service UUID.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
boolean Primary [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Indicates whether or not this GATT service is a
|
|
Packit Service |
8264ee |
primary service. If false, the service is secondary.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
object Device [read-only, optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Object path of the Bluetooth device the service
|
|
Packit Service |
8264ee |
belongs to. Only present on services from remote
|
|
Packit Service |
8264ee |
devices.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
array{object} Includes [read-only, optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Array of object paths representing the included
|
|
Packit Service |
8264ee |
services of this service.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
uint16 Handle [read-write, optional] (Server Only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Service handle. When available in the server it
|
|
Packit Service |
8264ee |
would attempt to use to allocate into the database
|
|
Packit Service |
8264ee |
which may fail, to auto allocate the value 0x0000
|
|
Packit Service |
8264ee |
shall be used which will cause the allocated handle to
|
|
Packit Service |
8264ee |
be set once registered.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Characteristic hierarchy
|
|
Packit Service |
8264ee |
========================
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For local GATT defined services, the object paths need to follow the service
|
|
Packit Service |
8264ee |
path hierarchy and are freely definable.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Service org.bluez
|
|
Packit Service |
8264ee |
Interface org.bluez.GattCharacteristic1
|
|
Packit Service |
8264ee |
Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Methods array{byte} ReadValue(dict options)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Issues a request to read the value of the
|
|
Packit Service |
8264ee |
characteristic and returns the value if the
|
|
Packit Service |
8264ee |
operation was successful.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible options: "offset": uint16 offset
|
|
Packit Service |
8264ee |
"mtu": Exchanged MTU (Server only)
|
|
Packit Service |
8264ee |
"device": Object Device (Server only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
org.bluez.Error.InProgress
|
|
Packit Service |
8264ee |
org.bluez.Error.NotPermitted
|
|
Packit Service |
8264ee |
org.bluez.Error.NotAuthorized
|
|
Packit Service |
8264ee |
org.bluez.Error.InvalidOffset
|
|
Packit Service |
8264ee |
org.bluez.Error.NotSupported
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
void WriteValue(array{byte} value, dict options)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Issues a request to write the value of the
|
|
Packit Service |
8264ee |
characteristic.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible options: "offset": Start offset
|
|
Packit Service |
8264ee |
"type": string
|
|
Packit Service |
8264ee |
Possible values:
|
|
Packit Service |
8264ee |
"command": Write without
|
|
Packit Service |
8264ee |
response
|
|
Packit Service |
8264ee |
"request": Write with response
|
|
Packit Service |
8264ee |
"reliable": Reliable Write
|
|
Packit Service |
8264ee |
"mtu": Exchanged MTU (Server only)
|
|
Packit Service |
8264ee |
"device": Device path (Server only)
|
|
Packit Service |
8264ee |
"link": Link type (Server only)
|
|
Packit Service |
8264ee |
"prepare-authorize": True if prepare
|
|
Packit Service |
8264ee |
authorization
|
|
Packit Service |
8264ee |
request
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
org.bluez.Error.InProgress
|
|
Packit Service |
8264ee |
org.bluez.Error.NotPermitted
|
|
Packit Service |
8264ee |
org.bluez.Error.InvalidValueLength
|
|
Packit Service |
8264ee |
org.bluez.Error.NotAuthorized
|
|
Packit Service |
8264ee |
org.bluez.Error.NotSupported
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
fd, uint16 AcquireWrite(dict options) [optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Acquire file descriptor and MTU for writing. Only
|
|
Packit Service |
8264ee |
sockets are supported. Usage of WriteValue will be
|
|
Packit Service |
8264ee |
locked causing it to return NotPermitted error.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For server the MTU returned shall be equal or smaller
|
|
Packit Service |
8264ee |
than the negotiated MTU.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For client it only works with characteristic that has
|
|
Packit Service |
8264ee |
WriteAcquired property which relies on
|
|
Packit Service |
8264ee |
write-without-response Flag.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
To release the lock the client shall close the file
|
|
Packit Service |
8264ee |
descriptor, a HUP is generated in case the device
|
|
Packit Service |
8264ee |
is disconnected.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Note: the MTU can only be negotiated once and is
|
|
Packit Service |
8264ee |
symmetric therefore this method may be delayed in
|
|
Packit Service |
8264ee |
order to have the exchange MTU completed, because of
|
|
Packit Service |
8264ee |
that the file descriptor is closed during
|
|
Packit Service |
8264ee |
reconnections as the MTU has to be renegotiated.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible options: "device": Object Device (Server only)
|
|
Packit Service |
8264ee |
"mtu": Exchanged MTU (Server only)
|
|
Packit Service |
8264ee |
"link": Link type (Server only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
org.bluez.Error.NotSupported
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
fd, uint16 AcquireNotify(dict options) [optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Acquire file descriptor and MTU for notify. Only
|
|
Packit Service |
8264ee |
sockets are support. Usage of StartNotify will be locked
|
|
Packit Service |
8264ee |
causing it to return NotPermitted error.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For server the MTU returned shall be equal or smaller
|
|
Packit Service |
8264ee |
than the negotiated MTU.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Only works with characteristic that has NotifyAcquired
|
|
Packit Service |
8264ee |
which relies on notify Flag and no other client have
|
|
Packit Service |
8264ee |
called StartNotify.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Notification are enabled during this procedure so
|
|
Packit Service |
8264ee |
StartNotify shall not be called, any notification
|
|
Packit Service |
8264ee |
will be dispatched via file descriptor therefore the
|
|
Packit Service |
8264ee |
Value property is not affected during the time where
|
|
Packit Service |
8264ee |
notify has been acquired.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
To release the lock the client shall close the file
|
|
Packit Service |
8264ee |
descriptor, a HUP is generated in case the device
|
|
Packit Service |
8264ee |
is disconnected.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Note: the MTU can only be negotiated once and is
|
|
Packit Service |
8264ee |
symmetric therefore this method may be delayed in
|
|
Packit Service |
8264ee |
order to have the exchange MTU completed, because of
|
|
Packit Service |
8264ee |
that the file descriptor is closed during
|
|
Packit Service |
8264ee |
reconnections as the MTU has to be renegotiated.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible options: "device": Object Device (Server only)
|
|
Packit Service |
8264ee |
"mtu": Exchanged MTU (Server only)
|
|
Packit Service |
8264ee |
"link": Link type (Server only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
org.bluez.Error.NotSupported
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
void StartNotify()
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Starts a notification session from this characteristic
|
|
Packit Service |
8264ee |
if it supports value notifications or indications.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
org.bluez.Error.NotPermitted
|
|
Packit Service |
8264ee |
org.bluez.Error.InProgress
|
|
Packit Service |
8264ee |
org.bluez.Error.NotSupported
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
void StopNotify()
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
This method will cancel any previous StartNotify
|
|
Packit Service |
8264ee |
transaction. Note that notifications from a
|
|
Packit Service |
8264ee |
characteristic are shared between sessions thus
|
|
Packit Service |
8264ee |
calling StopNotify will release a single session.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
void Confirm() [optional] (Server only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
This method doesn't expect a reply so it is just a
|
|
Packit Service |
8264ee |
confirmation that value was received.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Properties string UUID [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
128-bit characteristic UUID.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
object Service [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Object path of the GATT service the characteristic
|
|
Packit Service |
8264ee |
belongs to.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
array{byte} Value [read-only, optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
The cached value of the characteristic. This property
|
|
Packit Service |
8264ee |
gets updated only after a successful read request and
|
|
Packit Service |
8264ee |
when a notification or indication is received, upon
|
|
Packit Service |
8264ee |
which a PropertiesChanged signal will be emitted.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
boolean WriteAcquired [read-only, optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
True, if this characteristic has been acquired by any
|
|
Packit Service |
8264ee |
client using AcquireWrite.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For client properties is ommited in case
|
|
Packit Service |
8264ee |
'write-without-response' flag is not set.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For server the presence of this property indicates
|
|
Packit Service |
8264ee |
that AcquireWrite is supported.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
boolean NotifyAcquired [read-only, optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
True, if this characteristic has been acquired by any
|
|
Packit Service |
8264ee |
client using AcquireNotify.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For client this properties is ommited in case 'notify'
|
|
Packit Service |
8264ee |
flag is not set.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
For server the presence of this property indicates
|
|
Packit Service |
8264ee |
that AcquireNotify is supported.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
boolean Notifying [read-only, optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
True, if notifications or indications on this
|
|
Packit Service |
8264ee |
characteristic are currently enabled.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
array{string} Flags [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Defines how the characteristic value can be used. See
|
|
Packit Service |
8264ee |
Core spec "Table 3.5: Characteristic Properties bit
|
|
Packit Service |
8264ee |
field", and "Table 3.8: Characteristic Extended
|
|
Packit Service |
8264ee |
Properties bit field". Allowed values:
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
"broadcast"
|
|
Packit Service |
8264ee |
"read"
|
|
Packit Service |
8264ee |
"write-without-response"
|
|
Packit Service |
8264ee |
"write"
|
|
Packit Service |
8264ee |
"notify"
|
|
Packit Service |
8264ee |
"indicate"
|
|
Packit Service |
8264ee |
"authenticated-signed-writes"
|
|
Packit Service |
8264ee |
"extended-properties"
|
|
Packit Service |
8264ee |
"reliable-write"
|
|
Packit Service |
8264ee |
"writable-auxiliaries"
|
|
Packit Service |
8264ee |
"encrypt-read"
|
|
Packit Service |
8264ee |
"encrypt-write"
|
|
Packit Service |
8264ee |
"encrypt-authenticated-read"
|
|
Packit Service |
8264ee |
"encrypt-authenticated-write"
|
|
Packit Service |
8264ee |
"secure-read" (Server only)
|
|
Packit Service |
8264ee |
"secure-write" (Server only)
|
|
Packit Service |
8264ee |
"authorize"
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
uint16 Handle [read-write, optional] (Server Only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Characteristic handle. When available in the server it
|
|
Packit Service |
8264ee |
would attempt to use to allocate into the database
|
|
Packit Service |
8264ee |
which may fail, to auto allocate the value 0x0000
|
|
Packit Service |
8264ee |
shall be used which will cause the allocated handle to
|
|
Packit Service |
8264ee |
be set once registered.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Characteristic Descriptors hierarchy
|
|
Packit Service |
8264ee |
====================================
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Local or remote GATT characteristic descriptors hierarchy.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Service org.bluez
|
|
Packit Service |
8264ee |
Interface org.bluez.GattDescriptor1
|
|
Packit Service |
8264ee |
Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Methods array{byte} ReadValue(dict flags)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Issues a request to read the value of the
|
|
Packit Service |
8264ee |
characteristic and returns the value if the
|
|
Packit Service |
8264ee |
operation was successful.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible options: "offset": Start offset
|
|
Packit Service |
8264ee |
"device": Device path (Server only)
|
|
Packit Service |
8264ee |
"link": Link type (Server only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
org.bluez.Error.InProgress
|
|
Packit Service |
8264ee |
org.bluez.Error.NotPermitted
|
|
Packit Service |
8264ee |
org.bluez.Error.NotAuthorized
|
|
Packit Service |
8264ee |
org.bluez.Error.NotSupported
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
void WriteValue(array{byte} value, dict flags)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Issues a request to write the value of the
|
|
Packit Service |
8264ee |
characteristic.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible options: "offset": Start offset
|
|
Packit Service |
8264ee |
"device": Device path (Server only)
|
|
Packit Service |
8264ee |
"link": Link type (Server only)
|
|
Packit Service |
8264ee |
"prepare-authorize": boolean Is prepare
|
|
Packit Service |
8264ee |
authorization
|
|
Packit Service |
8264ee |
request
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible Errors: org.bluez.Error.Failed
|
|
Packit Service |
8264ee |
org.bluez.Error.InProgress
|
|
Packit Service |
8264ee |
org.bluez.Error.NotPermitted
|
|
Packit Service |
8264ee |
org.bluez.Error.InvalidValueLength
|
|
Packit Service |
8264ee |
org.bluez.Error.NotAuthorized
|
|
Packit Service |
8264ee |
org.bluez.Error.NotSupported
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Properties string UUID [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
128-bit descriptor UUID.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
object Characteristic [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Object path of the GATT characteristic the descriptor
|
|
Packit Service |
8264ee |
belongs to.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
array{byte} Value [read-only, optional]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
The cached value of the descriptor. This property
|
|
Packit Service |
8264ee |
gets updated only after a successful read request, upon
|
|
Packit Service |
8264ee |
which a PropertiesChanged signal will be emitted.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
array{string} Flags [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Defines how the descriptor value can be used.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible values:
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
"read"
|
|
Packit Service |
8264ee |
"write"
|
|
Packit Service |
8264ee |
"encrypt-read"
|
|
Packit Service |
8264ee |
"encrypt-write"
|
|
Packit Service |
8264ee |
"encrypt-authenticated-read"
|
|
Packit Service |
8264ee |
"encrypt-authenticated-write"
|
|
Packit Service |
8264ee |
"secure-read" (Server Only)
|
|
Packit Service |
8264ee |
"secure-write" (Server Only)
|
|
Packit Service |
8264ee |
"authorize"
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
uint16 Handle [read-write, optional] (Server Only)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Characteristic handle. When available in the server it
|
|
Packit Service |
8264ee |
would attempt to use to allocate into the database
|
|
Packit Service |
8264ee |
which may fail, to auto allocate the value 0x0000
|
|
Packit Service |
8264ee |
shall be used which will cause the allocated handle to
|
|
Packit Service |
8264ee |
be set once registered.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
GATT Profile hierarchy
|
|
Packit Service |
8264ee |
=====================
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Local profile (GATT client) instance. By registering this type of object
|
|
Packit Service |
8264ee |
an application effectively indicates support for a specific GATT profile
|
|
Packit Service |
8264ee |
and requests automatic connections to be established to devices
|
|
Packit Service |
8264ee |
supporting it.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Service <application dependent>
|
|
Packit Service |
8264ee |
Interface org.bluez.GattProfile1
|
|
Packit Service |
8264ee |
Object path <application dependent>
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Methods void Release()
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
This method gets called when the service daemon
|
|
Packit Service |
8264ee |
unregisters the profile. The profile can use it to
|
|
Packit Service |
8264ee |
do cleanup tasks. There is no need to unregister the
|
|
Packit Service |
8264ee |
profile, because when this method gets called it has
|
|
Packit Service |
8264ee |
already been unregistered.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Properties array{string} UUIDs [read-only]
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
128-bit GATT service UUIDs to auto connect.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
GATT Manager hierarchy
|
|
Packit Service |
8264ee |
======================
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
GATT Manager allows external applications to register GATT services and
|
|
Packit Service |
8264ee |
profiles.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Registering a profile allows applications to subscribe to *remote* services.
|
|
Packit Service |
8264ee |
These must implement the GattProfile1 interface defined above.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Registering a service allows applications to publish a *local* GATT service,
|
|
Packit Service |
8264ee |
which then becomes available to remote devices. A GATT service is represented by
|
|
Packit Service |
8264ee |
a D-Bus object hierarchy where the root node corresponds to a service and the
|
|
Packit Service |
8264ee |
child nodes represent characteristics and descriptors that belong to that
|
|
Packit Service |
8264ee |
service. Each node must implement one of GattService1, GattCharacteristic1,
|
|
Packit Service |
8264ee |
or GattDescriptor1 interfaces described above, based on the attribute it
|
|
Packit Service |
8264ee |
represents. Each node must also implement the standard D-Bus Properties
|
|
Packit Service |
8264ee |
interface to expose their properties. These objects collectively represent a
|
|
Packit Service |
8264ee |
GATT service definition.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
To make service registration simple, BlueZ requires that all objects that belong
|
|
Packit Service |
8264ee |
to a GATT service be grouped under a D-Bus Object Manager that solely manages
|
|
Packit Service |
8264ee |
the objects of that service. Hence, the standard DBus.ObjectManager interface
|
|
Packit Service |
8264ee |
must be available on the root service path. An example application hierarchy
|
|
Packit Service |
8264ee |
containing two separate GATT services may look like this:
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
-> /com/example
|
|
Packit Service |
8264ee |
| - org.freedesktop.DBus.ObjectManager
|
|
Packit Service |
8264ee |
|
|
|
Packit Service |
8264ee |
-> /com/example/service0
|
|
Packit Service |
8264ee |
| | - org.freedesktop.DBus.Properties
|
|
Packit Service |
8264ee |
| | - org.bluez.GattService1
|
|
Packit Service |
8264ee |
| |
|
|
Packit Service |
8264ee |
| -> /com/example/service0/char0
|
|
Packit Service |
8264ee |
| | - org.freedesktop.DBus.Properties
|
|
Packit Service |
8264ee |
| | - org.bluez.GattCharacteristic1
|
|
Packit Service |
8264ee |
| |
|
|
Packit Service |
8264ee |
| -> /com/example/service0/char1
|
|
Packit Service |
8264ee |
| | - org.freedesktop.DBus.Properties
|
|
Packit Service |
8264ee |
| | - org.bluez.GattCharacteristic1
|
|
Packit Service |
8264ee |
| |
|
|
Packit Service |
8264ee |
| -> /com/example/service0/char1/desc0
|
|
Packit Service |
8264ee |
| - org.freedesktop.DBus.Properties
|
|
Packit Service |
8264ee |
| - org.bluez.GattDescriptor1
|
|
Packit Service |
8264ee |
|
|
|
Packit Service |
8264ee |
-> /com/example/service1
|
|
Packit Service |
8264ee |
| - org.freedesktop.DBus.Properties
|
|
Packit Service |
8264ee |
| - org.bluez.GattService1
|
|
Packit Service |
8264ee |
|
|
|
Packit Service |
8264ee |
-> /com/example/service1/char0
|
|
Packit Service |
8264ee |
- org.freedesktop.DBus.Properties
|
|
Packit Service |
8264ee |
- org.bluez.GattCharacteristic1
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
When a service is registered, BlueZ will automatically obtain information about
|
|
Packit Service |
8264ee |
all objects using the service's Object Manager. Once a service has been
|
|
Packit Service |
8264ee |
registered, the objects of a service should not be removed. If BlueZ receives an
|
|
Packit Service |
8264ee |
InterfacesRemoved signal from a service's Object Manager, it will immediately
|
|
Packit Service |
8264ee |
unregister the service. Similarly, if the application disconnects from the bus,
|
|
Packit Service |
8264ee |
all of its registered services will be automatically unregistered.
|
|
Packit Service |
8264ee |
InterfacesAdded signals will be ignored.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Examples:
|
|
Packit Service |
8264ee |
- Client
|
|
Packit Service |
8264ee |
test/example-gatt-client
|
|
Packit Service |
8264ee |
client/bluetoothctl
|
|
Packit Service |
8264ee |
- Server
|
|
Packit Service |
8264ee |
test/example-gatt-server
|
|
Packit Service |
8264ee |
tools/gatt-service
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Service org.bluez
|
|
Packit Service |
8264ee |
Interface org.bluez.GattManager1
|
|
Packit Service |
8264ee |
Object path [variable prefix]/{hci0,hci1,...}
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Methods void RegisterApplication(object application, dict options)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Registers a local GATT services hierarchy as described
|
|
Packit Service |
8264ee |
above (GATT Server) and/or GATT profiles (GATT Client).
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
The application object path together with the D-Bus
|
|
Packit Service |
8264ee |
system bus connection ID define the identification of
|
|
Packit Service |
8264ee |
the application registering a GATT based
|
|
Packit Service |
8264ee |
service or profile.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible errors: org.bluez.Error.InvalidArguments
|
|
Packit Service |
8264ee |
org.bluez.Error.AlreadyExists
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
void UnregisterApplication(object application)
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
This unregisters the services that has been
|
|
Packit Service |
8264ee |
previously registered. The object path parameter
|
|
Packit Service |
8264ee |
must match the same value that has been used
|
|
Packit Service |
8264ee |
on registration.
|
|
Packit Service |
8264ee |
|
|
Packit Service |
8264ee |
Possible errors: org.bluez.Error.InvalidArguments
|
|
Packit Service |
8264ee |
org.bluez.Error.DoesNotExist
|