Proposal for GATT Client Dbus API.

* Proposal for GATT Client Dbus API.
@ 2011-10-04 13:59 ` Vijaykumar Dadmode
  2011-10-13 18:27   ` Claudio Takahasi
  2011-10-14 13:13   ` Anderson Lizardo
  0 siblings, 2 replies; 17+ messages in thread
From: Vijaykumar Dadmode @ 2011-10-04 13:59 UTC (permalink / raw)
  To: 'linux-bluetooth@vger.kernel.org'

[-- Attachment #1: Type: text/plain, Size: 3069 bytes --]

Hi,

This post contains a proposal for the DBUS GATT API(Gatt CLIENT) that enhances the existing GATT
functionality provided by DBUS APIs interface. Which include Methods,Signals and Properties. 
Could you please provide your comments and feedback for the same? Or we need more APIs to cover all GATT Client functionality?

. RegisterCharacteristicsWatcher can be used to monitor specific Characteristic change. 
. PropertyChanged Signal for the SetProperty().
. ServiceChanged and CharacteristicChanged Signal for Service or Characteristic changes on the server. 
. New Properties for Permissions and remaining Characteristic Descriptors. 

PFA the updated document "new-attribute-api.txt".

Proposed New API:

Device Characteristic hierarchy
===============================
Service                 org.bluez
Interface             org.bluez.Characteristic
Object path        [prefix]/{hci0}/{device0}/{service0}/{characteristic0,...}

Methods:
      			RegisterCharacteristicsWatcher(object agent)
                                    Register a watcher to monitor characteristic changes.
                                    A watcher will be registered for the specific characteristic and will
                                    notify about any changed characteristics.
Signals:
                        PropertyChanged(string name, variant value)
                                    This signal indicates a changed value of the given
                                    property.

                        ServiceChanged (dict values)
                                    This signal indicates service added on server.

                        CharacteristicChanged (dict values)
                                    This signal indicates characteristic added on server.

Properties:
                        uint8 Property [readonly]
                                    The characteristic property, format defined by GATT spec. 

                        uint16 Configuration [readonly]
                                    Optional field containing the configuration value on the server.

                        uint16 Extended [readonly]
                                    The characteristic descriptor describing
                                    the additional Characteristic Properties. 

                        uint16 Aggregate [readonly]
                                    Optional Characteristic descriptor which defines the 
					      format of an aggregated Characteristic Value.

                        uint16 Custom [readonly]
						Optional Characteristic descriptor which defines profile defined descriptor UUID's.

Thanks,
Vijay

Member of the CSR plc group of companies. CSR plc registered in England and Wales, registered number 4187346, registered office Churchill House, Cambridge Business Park, Cowley Road, Cambridge, CB4 0WZ, United Kingdom
More information can be found at www.csr.com. Follow CSR on Twitter at http://twitter.com/CSR_PLC and read our blog at www.csr.com/blog

[-- Attachment #2: new-attribute-api.txt --]
[-- Type: text/plain, Size: 6122 bytes --]

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

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.

Local Service hierarchy
=======================

Service		org.bluez
Interface	org.bluez.Service
		org.bluez.Characteristic
Object path	[prefix]/{hci0}/{service0, service1, ...}

Methods

Properties

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

Service		org.bluez
Interface	org.bluez.Characteristic
Object path	[prefix]/{hci0}/{device0}/{service0}/{characteristic0,...}
		[prefix]/{hci0}/{device0}/{service1}/{characteristic0,...}

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.

    RegisterCharacteristicsWatcher(object agent)

			Register a watcher to monitor characteristic changes.
			A watcher will be registered for the characteristic and will
			notify about any changed characteristics.

			Possible Errors: org.bluez.Error.InvalidArguments

Signals		PropertyChanged(string name, variant value)
			This signal indicates a changed value of the given
			property.

			ServiceChanged (dict values)
			This signal indicates service added on server.

  		CharacteristicChanged (dict values)
			This signal indicates characteristic added on server.

Properties 	string UUID [readonly]
			UUID128 of this characteristic.

		string Name [readonly]
			Optional field containing a friendly name for the
			Characteristic UUID.

		uint8 Property [readonly]
			The characteristic property, format defined by GATT spec. 

		uint16 Configuration [readonly]
			Optional field containing the configuration value on the server.

		uint16 Extended [readonly]
			The characteristic descriptor describing
			the additional Characteristic Properties. 

		uint16 Aggregate [readonly]
			Optional Characteristic descriptor which defines the 
      			format of an aggregated Characteristic Value.

    uint16 Custom [readonly]
			Optional Characteristic descriptor which defines profile defined descriptor UUID’s.

		string Description [readonly]
			Textual optional characteristic descriptor describing
			the Characteristic Value.

		struct Format [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.

			  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.

		array{byte} Value [readwrite]

			Raw value of the Characteristic Value attribute.

		string Representation (of the binary Value) [readonly]

			Friendly representation of the Characteristic Value
			based on the format attribute.

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

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

Methods		void ValueChanged(object characteristic, array{byte})

			New raw value of the Characteristic Value attribute.

^ permalink raw reply	[flat|nested] 17+ messages in thread