[RFC BlueZ 0/7] Generic GATT API changes

[RFC BlueZ 0/7] Generic GATT API changes

[Anderson Lizardo]

Hi,

This series contains the latest updates to the Generic GATT API planned for
the next major BlueZ release. It was based on the discussions on the last BlueZ
meeting, plus a few tweaks to the signature of some methods. For instance, the
Register() method of the Service interface contains an optional "id" setting,
which could allow to load the correct storage for registered GATT services when
BlueZ daemon is restarted.

While reviewing these patches, please keep in mind that the plan is to allow to
use the same API (or, more likely, a subset) when implementing external GATT
services. This avoids creating another "asymmetric" API just for service
registration. This approach has been already successfully adopted by other
(audio related?) profiles in BlueZ.

Comments and suggestions are welcome.

Anderson Lizardo (6):
  attrib-api: Remove local service hierarchy
  attrib-api: Update introduction text
  attrib-api: Remove GATT service hierarchy
  attrib-api: Update Characteristic interface
  attrib-api: Update Watcher interface methods
  attrib-api: Add RegisterWatcher/UnregisterWatcher methods

Claudio Takahasi (1):
  doc: Add Register/Unregister GATT based services

 doc/attribute-api.txt |  195 ++++++++++++++++++++-----------------------------
 doc/service-api.txt   |   54 ++++++++++++++
 2 files changed, 134 insertions(+), 115 deletions(-)

-- 
1.7.9.5

[RFC BlueZ 1/7] attrib-api: Remove local service hierarchy

[Anderson Lizardo]

Local GATT services will now share the same interface as remote
services.
---
 doc/attribute-api.txt |   13 -------------
 1 file changed, 13 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 98d7f30..5f4209d 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -24,19 +24,6 @@ A service consists of some generic service information and a set of
 characteristics. All characteristic are presented as object path as well.
 
 
-Local Service hierarchy
-=======================
-
-Service		org.bluez
-Interface	org.bluez.Service
-		org.bluez.Characteristic
-Object path	[prefix]/{hci0}/{service0, service1, ...}
-
-Methods
-
-Properties
-
-
 Device Service hierarchy
 ========================
 
-- 
1.7.9.5

[RFC BlueZ 2/7] attrib-api: Update introduction text

[Anderson Lizardo]

We do not have service objects anymore.
---
 doc/attribute-api.txt |   20 ++++----------------
 1 file changed, 4 insertions(+), 16 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 5f4209d..6560b53 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -6,22 +6,10 @@ Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
 Service details
 ---------------
 
-One service object path for every remote SDP record or service in the
-attribute database. One service object path for every local SDP record
-or service from attribute database.
-
-Local services are children of the adapter object path. Remote services
-are children of the remote device object path. This doesn't solve the
-problem where local attributes can have different instances based on
-the remote device.
-
-In general the idea is to also represent SDP records as services so that
-new style application can just use the service interfaces to retrieve the
-needed information. That way the usage of SDP and GATT would be mostly
-fully transparent and a differentiation becomes unimportant in the future.
-
-A service consists of some generic service information and a set of
-characteristics. All characteristic are presented as object path as well.
+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.
 
 
 Device Service hierarchy
-- 
1.7.9.5

[RFC BlueZ 3/7] attrib-api: Remove GATT service hierarchy

[Anderson Lizardo]

---
 doc/attribute-api.txt |   54 -------------------------------------------------
 1 file changed, 54 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 6560b53..4c29f66 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -12,60 +12,6 @@ service that contains it, so clients can identify the correct characteristic if
 multiple services contain the same characteristic.
 
 
-Device Service hierarchy
-========================
-
-Service		org.bluez
-Interface	org.bluez.Characteristic
-Object path	[prefix]/{hci0}/{device0}/{service0, service1, ...}
-		[prefix]/{hci0}/{device1}/{service0, service1, ...}
-
-Methods 	dict GetProperties()
-
-			Returns all properties for the interface. See the
-			Properties section for the available properties.
-
-		array{object} DiscoverCharacteristics()
-
-			Discover all characteristics that belongs in this service.
-			When it returns all the characteristics paths will be
-			already registered. It will return the characteristics paths
-			as soon as they are discovered. After that it will try to
-			read all values.
-
-		RegisterCharacteristicsWatcher(object agent)
-
-			Register a watcher to monitor characteristic changes.
-
-			A watcher will be registered for this service and will
-			notify about any changed characteristics in the service.
-			This also notifies about any included characteristics.
-
-		UnregisterCharacteristicsWatcher(object agent)
-
-			Unregister a watcher.
-
-Properties	string Name (mandatory) [readonly]
-
-			General name of service
-
-		string Description (optional) [readonly]
-
-			Description of service
-
-		string UUID (mandatory) [readonly]
-
-			UUID of service. Service class value for SDP and GATT
-			UUID for attribute based services.
-
-		array{object} Characteristics [readonly]
-
-			This list contains the characteristics owned by this
-			specific service and other characteristics from service
-			includes. That way no complicated service includes array
-			is needed.
-
-
 Device Characteristic hierarchy
 ===============================
 
-- 
1.7.9.5

[RFC BlueZ 4/7] attrib-api: Update Characteristic interface

[Anderson Lizardo]

---
 doc/attribute-api.txt |   97 +++++++++++++++++++++++++++++++------------------
 1 file changed, 61 insertions(+), 36 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 4c29f66..4f7dd40 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -11,67 +11,92 @@ 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	[prefix]/{hci0}/{device0}/{service0}/{characteristic0,...}
-		[prefix]/{hci0}/{device0}/{service1}/{characteristic0,...}
+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:
 
-Methods		dict GetProperties()
+			{
+				"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},
+			}
 
-			Returns all properties for the characteristic. See the
-			properties section for available properties.
+Properties	string UUID [readonly]
 
-		void SetProperty(string name, variant value)
+			128-bit UUID of this characteristic.
 
-			Changes the value of the specified property. Only
-			read-write properties can be changed. On success
-			this will emit a PropertyChanged signal.
+		string ServiceUUID [readonly]
 
-			Possible Errors: org.bluez.Error.InvalidArguments
+			128-bit UUID of the service which includes this
+			characteristic.
 
-Properties 	string UUID [readonly]
+		boolean Read [readonly]
 
-			UUID128 of this characteristic.
+			Characteristic value can be read.
 
-		string Name [readonly]
+		boolean WriteWithoutResponse [readonly]
 
-			Optional field containing a friendly name for the
-			Characteristic UUID.
+			Characteristic value can be written using GATT Write
+			Without Response sub-procedure.
 
-		string Description [readonly]
+		boolean Write [readonly]
 
-			Textual optional characteristic descriptor describing
-			the Characteristic Value.
+			Characteristic value can be written using GATT Write
+			Characteristic Value sub-procedures.
 
-		struct Format [readonly]
+		boolean Notify [readonly]
 
-			Optional Characteristic descriptor which defines the
-			format of the Characteristic Value. For numeric
-			values, the actual value can be value * 10^Exponent.
-			NameSpace and Description are defined on the Assigned
-			Number Specification.
+			Characteristic value can be notified.
 
-			  uint8  | Format: format of the value
-			  uint8  | Exponent: Field to determine how the value is
-			         | further formatted.
-			  uint16 | Unit: unit of the characteristic
-			  uint8  | NameSpace: Name space of description.
-			  uint16 | Description: Description of the characteristic defined
-			         | in a high layer profile.
+		boolean Indicate [readonly]
 
-		array{byte} Value [readwrite]
+			Characteristic value can be indicated.
 
-			Raw value of the Characteristic Value attribute.
+		boolean AuthenticatedSignedWrites [readonly]
 
-		string Representation (of the binary Value) [readonly]
+			Characteristic value can be written using GATT Signed
+			Write Without Response sub-procedure.
 
-			Friendly representation of the Characteristic Value
-			based on the format attribute.
+		boolean ExtendedProperties [readonly]
 
+			Characteristic contains additional properties defined
+			on the Extended Properties descriptor.
 
 Characteristic Watcher hierarchy
 ===============================
-- 
1.7.9.5

[RFC BlueZ 5/7] attrib-api: Update Watcher interface methods

[Anderson Lizardo]

There are now two different methods for the interface. Only one method
is called, based on the "raw" setting being enabled or not when
registering the watcher.
---
 doc/attribute-api.txt |   16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 4f7dd40..4b392b9 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -105,6 +105,18 @@ Service		unique name
 Interface	org.bluez.Watcher
 Object path	freely definable
 
-Methods		void ValueChanged(object characteristic, array{byte})
+Methods		void ValueChanged(object characteristic, dict value)
 
-			New raw value of the Characteristic Value attribute.
+			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().
-- 
1.7.9.5

[RFC BlueZ 6/7] attrib-api: Add RegisterWatcher/UnregisterWatcher methods

[Anderson Lizardo]

These methods are used to register or unregister watchers for
characteristics, so applications can be notified when the characteristic
value changes.

The Release() method is added to the Watcher interface to notify the
watcher object that it has been unregistered and is no longer valid.
---
 doc/attribute-api.txt |    7 +++++++
 doc/service-api.txt   |   21 +++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 4b392b9..0805756 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -120,3 +120,10 @@ Methods		void ValueChanged(object characteristic, dict value)
 
 			This method is only called when the "raw" setting is
 			enabled on Adapter.RegisterCharacteristicsWatcher().
+
+		void Release()
+
+			This method is called when the service daemon
+			unregisters the watcher, which can then perform cleanup
+			tasks. There is no need to unregister the watcher if
+			this method is called.
diff --git a/doc/service-api.txt b/doc/service-api.txt
index 5c8c7f3..0139f5f 100644
--- a/doc/service-api.txt
+++ b/doc/service-api.txt
@@ -43,6 +43,27 @@ Methods		uint32 AddRecord(string record)
 					 org.bluez.Error.DoesNotExist
 					 org.bluez.Error.Failed
 
+		void RegisterWatcher(object agent, dict settings,
+						array{object} characteristics)
+
+			Register a watcher to monitor characteristic changes.
+
+			A watcher will be registered for each specified
+			characteristic object. The settings dictionary has the
+			following format:
+
+			{
+				"raw": boolean (optional)
+			}
+
+			If the "raw" setting is enabled, the RawValueChanged()
+			watcher method is called when the characteristic value
+			changes, otherwise, ValueChanged() is called.
+
+		void UnregisterWatcher(object agent)
+
+			Unregister a characteristic watcher.
+
 		void RequestAuthorization(string address, uint32 handle)
 
 			Request an authorization for an incoming connection
-- 
1.7.9.5

[RFC BlueZ 7/7] doc: Add Register/Unregister GATT based services

[Anderson Lizardo]

From: Claudio Takahasi <claudio.takahasi@openbossa.org>

This patch extends the Service interface to allow applications to
register and unregister GATT based services.
---
 doc/service-api.txt |   33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/doc/service-api.txt b/doc/service-api.txt
index 0139f5f..1380932 100644
--- a/doc/service-api.txt
+++ b/doc/service-api.txt
@@ -43,6 +43,39 @@ Methods		uint32 AddRecord(string record)
 					 org.bluez.Error.DoesNotExist
 					 org.bluez.Error.Failed
 
+		void Register(string uuid, dict settings,
+					array{object} characteristics)
+
+			Add a GATT based service. The uuid represents the
+			primary/secondary service UUID. The settings
+			dictionary has the following format:
+			{
+				"id": string (optional)
+			}
+
+			settings field is being added to allow API
+			flexibility. The "id" field allows the core to
+			manage handle allocation and internal GATT storage.
+
+			GATT included services is supported by providing the
+			same characteristic object path (restricted to same
+			provider/owner).
+
+			The characteristic objects implemented by the
+			caller shall follow the interface defined in the
+			attribute API.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.AlreadyExists
+
+		void Unregister(string uuid)
+
+			Removes a given GATT based service previously
+			registered by the caller.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.NotAuthorized
+
 		void RegisterWatcher(object agent, dict settings,
 						array{object} characteristics)
 
-- 
1.7.9.5

Re: [RFC BlueZ 7/7] doc: Add Register/Unregister GATT based services

[Johan Hedberg]

Hi,

On Mon, Jul 23, 2012, Anderson Lizardo wrote:
> --- a/doc/service-api.txt
> +++ b/doc/service-api.txt
> @@ -43,6 +43,39 @@ Methods		uint32 AddRecord(string record)
>  					 org.bluez.Error.DoesNotExist
>  					 org.bluez.Error.Failed
>  
> +		void Register(string uuid, dict settings,
> +					array{object} characteristics)
> +
> +			Add a GATT based service. The uuid represents the
> +			primary/secondary service UUID. The settings
> +			dictionary has the following format:
> +			{
> +				"id": string (optional)
> +			}
> +
> +			settings field is being added to allow API
> +			flexibility. The "id" field allows the core to
> +			manage handle allocation and internal GATT storage.
> +
> +			GATT included services is supported by providing the
> +			same characteristic object path (restricted to same
> +			provider/owner).
> +
> +			The characteristic objects implemented by the
> +			caller shall follow the interface defined in the
> +			attribute API.
> +
> +			Possible errors: org.bluez.Error.InvalidArguments
> +					 org.bluez.Error.AlreadyExists
> +
> +		void Unregister(string uuid)
> +
> +			Removes a given GATT based service previously
> +			registered by the caller.
> +
> +			Possible errors: org.bluez.Error.InvalidArguments
> +					 org.bluez.Error.NotAuthorized

I don't think the Register/Unregister names are right since this is
purely LE/GATT specific. Or do you foresee this being used for
traditional (non-GATT) BR/EDR profiles? I'd either propose having a new
interface for these or then rename them (e.g. RegisterGATT?).

FWIW I'm also not sure that the interface name org.bluez.Service is
quite right. Interface names are supposed to describe something about
the object which implements them, but the object this interface is used
for (adapter) cannot be said to "be" a service. Instead, this interface
abstracts a local database of services. What would you think of calling
it ServiceManager or ServiceDatabase?

Johan

Re: [RFC BlueZ 0/7] Generic GATT API changes

[Johan Hedberg]

Hi,

On Mon, Jul 23, 2012, Anderson Lizardo wrote:
> This series contains the latest updates to the Generic GATT API planned for
> the next major BlueZ release. It was based on the discussions on the last BlueZ
> meeting, plus a few tweaks to the signature of some methods. For instance, the
> Register() method of the Service interface contains an optional "id" setting,
> which could allow to load the correct storage for registered GATT services when
> BlueZ daemon is restarted.
> 
> While reviewing these patches, please keep in mind that the plan is to allow to
> use the same API (or, more likely, a subset) when implementing external GATT
> services. This avoids creating another "asymmetric" API just for service
> registration. This approach has been already successfully adopted by other
> (audio related?) profiles in BlueZ.
> 
> Comments and suggestions are welcome.
> 
> Anderson Lizardo (6):
>   attrib-api: Remove local service hierarchy
>   attrib-api: Update introduction text
>   attrib-api: Remove GATT service hierarchy
>   attrib-api: Update Characteristic interface
>   attrib-api: Update Watcher interface methods
>   attrib-api: Add RegisterWatcher/UnregisterWatcher methods
> 
> Claudio Takahasi (1):
>   doc: Add Register/Unregister GATT based services

Patches 1-6 have been applied. The last two may need some more thinking
though.

Johan