doc/attribute-api.txt

BlueZ D-Bus Attribute API description
*************************************

Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>

Service details
---------------

All characteristics are presented as object paths in a single, flat list. Each
object has a "ServiceUUID" property which contains the 128-bit UUID of the
service that contains it, so clients can identify the correct characteristic if
multiple services contain the same characteristic.

This API is used for both local (added to the BlueZ GATT server) and remote
(found by GATT discovery) services.

Device Characteristic hierarchy
===============================

Service		org.bluez
Interface	org.bluez.Characteristic
Object path	freely definable

For local characteristics, it is recommended (for readability and debugging
purposes) to have the object path prefix as "[freely definable]/[busid]" where
"[busid]" is the application's D-Bus address. For remote characteristics, the
device address is added to the prefix. E.g.:

[freely definable]/[busid]/characteristic_1803_2A06 (local)
[freely definable]/dev_XX_XX_XX_XX_XX_XX/characteristic_1803_2A06 (remote)

Methods		void SetValue(array{byte} value)

			Update characteristic value.

			For a remote characteristic, this method triggers a
			GATT characteristic value write procedure setting a new
			value for this characteristic. The GATT sub-procedure
			is automatically selected based on the characteristic
			properties and value length.

		dict GetValue()

			Read characteristic value and descriptors. The returned
			dictionary has the following format:

			{
				"value": array{byte},
				"formatted value": string,
				// Optional descriptors
				"client configuration": uint16,
				"server configuration": uint16,
				"extended properties": uint16,
				"user description": string,
				// For unknown descriptors, use 128-bit UUID
				// as key
				"uuid": array{byte},
			}

Properties	string UUID [readonly]

			128-bit UUID of this characteristic.

		string ServiceUUID [readonly]

			128-bit UUID of the service which includes this
			characteristic.

		boolean Read [readonly]

			Characteristic value can be read.

		boolean WriteWithoutResponse [readonly]

			Characteristic value can be written using GATT Write
			Without Response sub-procedure.

		boolean Write [readonly]

			Characteristic value can be written using GATT Write
			Characteristic Value sub-procedures.

		boolean Notify [readonly]

			Characteristic value can be notified.

		boolean Indicate [readonly]

			Characteristic value can be indicated.

		boolean AuthenticatedSignedWrites [readonly]

			Characteristic value can be written using GATT Signed
			Write Without Response sub-procedure.

		boolean ExtendedProperties [readonly]

			Characteristic contains additional properties defined
			on the Extended Properties descriptor.

Characteristic Watcher hierarchy
===============================

Service		unique name
Interface	org.bluez.Watcher
Object path	freely definable

Methods		void ValueChanged(object characteristic, dict value)

			The value dictionary contains the new value for the
			Characteristic. The format is the same returned by
			Characteristic.GetValue().

			This method is only called when the "raw" setting is
			disabled on Adapter.RegisterCharacteristicsWatcher().

		void RawValueChanged(object characteristic, array{byte} value)

			New raw Characteristic value.

			This method is only called when the "raw" setting is
			enabled on Adapter.RegisterCharacteristicsWatcher().