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.

		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.ReadNotPermitted
					 org.bluez.Error.NotAuthorized
					 org.bluez.Error.NotPaired
					 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.WriteNotPermitted
					 org.bluez.Error.InvalidValueLength
					 org.bluez.Error.NotAuthorized
					 org.bluez.Error.NotPaired
					 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.ReadNotPermitted
					 org.bluez.Error.NotAuthorized
					 org.bluez.Error.NotPaired
					 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.WriteNotPermitted
					 org.bluez.Error.InvalidValueLength
					 org.bluez.Error.NotAuthorized
					 org.bluez.Error.NotPaired
					 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.


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