doc/gatt-api.txt - vendor/opensource/bluez - Git at Google

 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
 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} 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
 Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY

 Methods		array{byte} ReadValue(dict options)

 			Issues a request to read the value of the
 			characteristic and returns the value if the
 			operation was successful.

 			Possible options: "offset": uint16 offset
 					  "device": Object Device (Server only)

 			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, dict options)

 			Issues a request to write the value of the
 			characteristic.

 			Possible options: "offset": Start offset
 					  "device": Device path (Server only)

 			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 characteristic
 			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, optional]

 			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"
 				"secure-read" (Server only)
 				"secure-write" (Server only)

 Characteristic Descriptors hierarchy
 ====================================

 Local or remote GATT characteristic descriptors hierarchy.

 Service		org.bluez
 Interface	org.bluez.GattDescriptor1
 Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ

 Methods		array{byte} ReadValue(dict flags)

 			Issues a request to read the value of the
 			characteristic and returns the value if the
 			operation was successful.

 			Possible options: "offset": Start offset
 					  "device": Device path (Server only)

 			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, dict flags)

 			Issues a request to write the value of the
 			characteristic.

 			Possible options: "offset": Start offset
 					  "device": Device path (Server only)

 			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 characteristic 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"
 				"secure-read" (Server Only)
 				"secure-write" (Server Only)

 GATT Profile hierarchy
 =====================

 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
 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.

 Properties	array{string} UUIDs [read-only]

 			128-bit GATT service UUIDs to auto connect.


 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
   |   - org.freedesktop.DBus.ObjectManager
   |
   -> /com/example/service0
   | |   - 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.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.

 Examples:
 	- Client
 		test/example-gatt-client
 		client/bluetoothctl
 	- Server
 		test/example-gatt-server
 		tools/gatt-service


 Service		org.bluez
 Interface	org.bluez.GattManager1
 Object path	[variable prefix]/{hci0,hci1,...}

 Methods		void RegisterApplication(object application, dict options)

 			Registers a local GATT services hierarchy as described
 			above (GATT Server) and/or GATT profiles (GATT Client).

 			The application object path together with the D-Bus
 			system bus connection ID define the identification of
 			the application registering a GATT based
 			service or profile.

 			Possible errors: org.bluez.Error.InvalidArguments
 					 org.bluez.Error.AlreadyExists

 		void UnregisterApplication(object application)

 			This unregisters the services 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
	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
	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} 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
	Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY

	Methods array{byte} ReadValue(dict options)

	Issues a request to read the value of the
	characteristic and returns the value if the
	operation was successful.

	Possible options: "offset": uint16 offset
	"device": Object Device (Server only)

	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, dict options)

	Issues a request to write the value of the
	characteristic.

	Possible options: "offset": Start offset
	"device": Device path (Server only)

	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 characteristic
	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, optional]

	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"
	"secure-read" (Server only)
	"secure-write" (Server only)

	Characteristic Descriptors hierarchy
	====================================

	Local or remote GATT characteristic descriptors hierarchy.

	Service org.bluez
	Interface org.bluez.GattDescriptor1
	Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ

	Methods array{byte} ReadValue(dict flags)

	Issues a request to read the value of the
	characteristic and returns the value if the
	operation was successful.

	Possible options: "offset": Start offset
	"device": Device path (Server only)

	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, dict flags)

	Issues a request to write the value of the
	characteristic.

	Possible options: "offset": Start offset
	"device": Device path (Server only)

	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 characteristic 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"
	"secure-read" (Server Only)
	"secure-write" (Server Only)

	GATT Profile hierarchy
	=====================

	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
	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.

	Properties array{string} UUIDs [read-only]

	128-bit GATT service UUIDs to auto connect.


	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
	\| - org.freedesktop.DBus.ObjectManager
	\|
	-> /com/example/service0
	\| \| - 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.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.

	Examples:
	- Client
	test/example-gatt-client
	client/bluetoothctl
	- Server
	test/example-gatt-server
	tools/gatt-service


	Service org.bluez
	Interface org.bluez.GattManager1
	Object path [variable prefix]/{hci0,hci1,...}

	Methods void RegisterApplication(object application, dict options)

	Registers a local GATT services hierarchy as described
	above (GATT Server) and/or GATT profiles (GATT Client).

	The application object path together with the D-Bus
	system bus connection ID define the identification of
	the application registering a GATT based
	service or profile.

	Possible errors: org.bluez.Error.InvalidArguments
	org.bluez.Error.AlreadyExists

	void UnregisterApplication(object application)

	This unregisters the services 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