[PATCH 1/4] Add the Attribute interface to the API

[PATCH 1/4] Add the Attribute interface to the API

[Claudio Takahasi]

From: Vinicius Costa Gomes <vinicius.gomes@openbossa.org>

For now the Attribute API will allow users to list all the GATT
services that a device has.
---
 doc/attribute-api.txt |   19 +++++++++++++++++++
 doc/device-api.txt    |    4 ----
 2 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 011691e..0989099 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -37,6 +37,25 @@ Methods
 Properties
 
 
+Attribute Protocol hierarchy
+============================
+
+Service		org.bluez
+Interface	org.bluez.Attribute
+Object path	[prefix]/{hci0}/{device0}
+
+
+Methods		dict GetProperties()
+
+			Returns all properties for the interface. See the
+			properties section for available properties.
+
+Properties	array{object} Services
+
+			List of all the Primary Services that this device
+			implements.
+
+
 Device Service hierarchy
 ========================
 
diff --git a/doc/device-api.txt b/doc/device-api.txt
index 95b5b22..b818299 100644
--- a/doc/device-api.txt
+++ b/doc/device-api.txt
@@ -139,10 +139,6 @@ Properties	string Address [readonly]
 			List of 128-bit UUIDs that represents the available
 			remote services.
 
-		array{object} Services [readonly]
-
-			List of characteristics based services.
-
 		boolean Paired [readonly]
 
 			Indicates if the remote device is paired.
-- 
1.7.3

[PATCH 2/4] Add GetProperties method in the Device service hierarchy

[Claudio Takahasi]

Changes the attribute API to become compliant with other BlueZ
APIs. Characteristics properties can be retrieved using GetProperties
method of the Device Characteristic hierarchy. This patch also removes
unneeded characteristic properties description which is already
explained in the next section.
---
 doc/attribute-api.txt |   28 +++-------------------------
 1 files changed, 3 insertions(+), 25 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index 0989099..a5e475b 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -64,15 +64,10 @@ Interface	org.bluez.Characteristic
 Object path	[prefix]/{hci0}/{device0}/{service0, service1, ...}
 		[prefix]/{hci0}/{device1}/{service0, service1, ...}
 
-Methods		array[(object, dict)] GetCharacteristics()
+Methods 	dict GetProperties()
 
-			Array of tuples with object path as identifier. An
-			alternative is doing dict of dict since the object
-			path is unique and the order of characteristics is
-			irrelevant. However it might be good to actually
-			present an order here.
-
-			See Characteristics properties for dictionary details.
+			Returns all properties for the interface. See the
+			Properties section for the available properties.
 
 		RegisterCharacteristicsWatcher(object path)
 
@@ -109,23 +104,6 @@ Properties	string Name (mandatory) [readonly]
 			includes. That way no complicated service includes array
 			is needed.
 
-			string UUID
-			string Name
-			string Description
-			struct Format (type, name, exponet etc.)
-
-			array{byte} Value
-			string Representation (of the binary Value)
-
-			object Service (the original service in case of includes)
-
-			At this point only GetProperties() method call should be
-			supported for simplicity. Changing characteristics is up
-			to future support.
-
-			The object path of the characteristics might be split
-			over multiple service objects, because of includes.
-
 
 Device Characteristic hierarchy
 ===============================
-- 
1.7.3

[PATCH 3/4] Add SetProperty in the Device characteristic hierarchy

[Claudio Takahasi]

Add SetProperty method to allow characteristic watchers or any other
D-Bus client application to change the value of a given characteristic.
Use cases: Changing sensors thresholds, client characteristic
configuration for notification/indication.
---
 doc/attribute-api.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index a5e475b..d0ce6f8 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -118,6 +118,13 @@ Methods		dict GetProperties()
 			Returns all properties for the characteristic. See the
 			properties section for available properties.
 
+		void SetProperty(string name, variant value)
+
+			Changes the value of the specified property. Only
+			read-write properties can be changed. On success
+			this will emit a PropertyChanged signal.
+
+			Possible Errors: org.bluez.Error.InvalidArguments
 
 Properties 	string UUID [readonly]
 
-- 
1.7.3

[PATCH 4/4] Fix object path in the register watcher method

[Claudio Takahasi]

The path argument in RegisterCharacteristicsWatcher method shall be
the agent's path. An agent will monitor changes in all characteristics.
---
 doc/attribute-api.txt |   11 ++++-------
 1 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index d0ce6f8..f66e9bc 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -69,18 +69,15 @@ Methods 	dict GetProperties()
 			Returns all properties for the interface. See the
 			Properties section for the available properties.
 
-		RegisterCharacteristicsWatcher(object path)
+		RegisterCharacteristicsWatcher(object agent)
 
-			Register a watcher for changes in specific characteristics
-			to monitor changes.
+			Register a watcher to monitor characteristic changes.
 
 			A watcher will be registered for this service and will
-			notifier about any changed characteristics in the service.
+			notify about any changed characteristics in the service.
 			This also notifies about any included characteristics.
 
-			Method for the watch objects still need to be defined.
-
-		UnregisterCharacteristicsWatcher(object path)
+		UnregisterCharacteristicsWatcher(object agent)
 
 			Unregister a watcher.
 
-- 
1.7.3

Re: [PATCH 1/4] Add the Attribute interface to the API

[Johan Hedberg]

Hi,

On Tue, Sep 28, 2010, Claudio Takahasi wrote:
> +Attribute Protocol hierarchy
> +============================
> +
> +Service		org.bluez
> +Interface	org.bluez.Attribute
> +Object path	[prefix]/{hci0}/{device0}
> +
> +
> +Methods		dict GetProperties()
> +
> +			Returns all properties for the interface. See the
> +			properties section for available properties.
> +
> +Properties	array{object} Services
> +
> +			List of all the Primary Services that this device
> +			implements.
> +
> +
>  Device Service hierarchy
>  ========================
>  
> diff --git a/doc/device-api.txt b/doc/device-api.txt
> index 95b5b22..b818299 100644
> --- a/doc/device-api.txt
> +++ b/doc/device-api.txt
> @@ -139,10 +139,6 @@ Properties	string Address [readonly]
>  			List of 128-bit UUIDs that represents the available
>  			remote services.
>  
> -		array{object} Services [readonly]
> -
> -			List of characteristics based services.
> -
>  		boolean Paired [readonly]
>  
>  			Indicates if the remote device is paired.

What's the motivation of moving this into its own D-Bus interface? I
thought the plan was to abstract both traditional SDP and ATT behind the
same API in which case having this in the Device interface makes more
sense imho.

Johan

Re: [PATCH 1/4] Add the Attribute interface to the API

[Claudio Takahasi]

On Wed, Sep 29, 2010 at 10:49 AM, Johan Hedberg <johan.hedberg@gmail.com> wrote:
> Hi,
>
> On Tue, Sep 28, 2010, Claudio Takahasi wrote:
>> +Attribute Protocol hierarchy
>> +============================
>> +
>> +Service              org.bluez
>> +Interface    org.bluez.Attribute
>> +Object path  [prefix]/{hci0}/{device0}
>> +
>> +
>> +Methods              dict GetProperties()
>> +
>> +                     Returns all properties for the interface. See the
>> +                     properties section for available properties.
>> +
>> +Properties   array{object} Services
>> +
>> +                     List of all the Primary Services that this device
>> +                     implements.
>> +
>> +
>>  Device Service hierarchy
>>  ========================
>>
>> diff --git a/doc/device-api.txt b/doc/device-api.txt
>> index 95b5b22..b818299 100644
>> --- a/doc/device-api.txt
>> +++ b/doc/device-api.txt
>> @@ -139,10 +139,6 @@ Properties       string Address [readonly]
>>                       List of 128-bit UUIDs that represents the available
>>                       remote services.
>>
>> -             array{object} Services [readonly]
>> -
>> -                     List of characteristics based services.
>> -
>>               boolean Paired [readonly]
>>
>>                       Indicates if the remote device is paired.
>
> What's the motivation of moving this into its own D-Bus interface? I
> thought the plan was to abstract both traditional SDP and ATT behind the
> same API in which case having this in the Device interface makes more
> sense imho.
>
> Johan
>

Hi Johan,

we forgot the SDP integration plan. Forget this patch.

>From the implementation point of view, implement inside the attrib
client plugin was the easiest way, if we keep this property inside the
Device interface a new function needs to be created in device.h to
register the available primary services object paths.

Claudio.

Re: [PATCH 1/4] Add the Attribute interface to the API

[Luiz Augusto von Dentz]

Hi,

On Wed, Sep 29, 2010 at 5:52 PM, Claudio Takahasi
<claudio.takahasi@openbossa.org> wrote:
>>
>> What's the motivation of moving this into its own D-Bus interface? I
>> thought the plan was to abstract both traditional SDP and ATT behind the
>> same API in which case having this in the Device interface makes more
>> sense imho.
>>
>> Johan
>>
>
> Hi Johan,
>
> we forgot the SDP integration plan. Forget this patch.
>
> From the implementation point of view, implement inside the attrib
> client plugin was the easiest way, if we keep this property inside the
> Device interface a new function needs to be created in device.h to
> register the available primary services object paths.

Well there is a more complicated way, which is to add support for
user_data per method/property, so a plugin could directly register
their methods and properties in e.g. Adapter and Device interfaces. Of
course this has drawbacks since the API could really became a mess
with plugins doing there thing carelessly, but in the other hand it
can greatly simplify the interfaces like Device.Disconnect()
propagation.

Just a crazy idea I had late in the night :D

-- 
Luiz Augusto von Dentz
Computer Engineer

Re: [PATCH 1/4] Add the Attribute interface to the API

[Claudio Takahasi]

On Wed, Sep 29, 2010 at 5:00 PM, Luiz Augusto von Dentz
<luiz.dentz@gmail.com> wrote:
> Hi,
>
> On Wed, Sep 29, 2010 at 5:52 PM, Claudio Takahasi
> <claudio.takahasi@openbossa.org> wrote:
>>>
>>> What's the motivation of moving this into its own D-Bus interface? I
>>> thought the plan was to abstract both traditional SDP and ATT behind the
>>> same API in which case having this in the Device interface makes more
>>> sense imho.
>>>
>>> Johan
>>>
>>
>> Hi Johan,
>>
>> we forgot the SDP integration plan. Forget this patch.
>>
>> From the implementation point of view, implement inside the attrib
>> client plugin was the easiest way, if we keep this property inside the
>> Device interface a new function needs to be created in device.h to
>> register the available primary services object paths.
>
> Well there is a more complicated way, which is to add support for
> user_data per method/property, so a plugin could directly register
> their methods and properties in e.g. Adapter and Device interfaces. Of
> course this has drawbacks since the API could really became a mess
> with plugins doing there thing carelessly, but in the other hand it
> can greatly simplify the interfaces like Device.Disconnect()
> propagation.
>
> Just a crazy idea I had late in the night :D
>
> --
> Luiz Augusto von Dentz
> Computer Engineer
>

Please ignore this patch sequence. A proper pull request will be sent
to the ML containing the last 3 patches only.
This patch [PATCH 1/4] will be removed.


Claudio