path: root/doc/gatt-api.txt

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"

		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.


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
#ifdef __TIZEN_PATCH__
		GetService(string uuid)

			This Reads the service, characterstics and descriptors
			that has been previously registered. The string uuid parameter
			must match the same value that has been used
			on registration.

			The return values includes,
			Key               objectpath
			----              -----------
			Service           /serviceX
			CharacteristicsX  /serviceX/CharacterisitcX
			DescriptorX       /serviceX/CharacterisitcX/DescriptorX

			Possible errors: org.bluez.Error.InvalidArguments
#endif