[PATCH] Health Device Profile API

[PATCH] Health Device Profile API

[Elvis Pfützenreuter]

From: Elvis Pfutzenreuter <epx@signove.com>

Initial Health API proposal. Includes Adapter, Device and HealthAgent API
description. Proposed API can address Health source and sink roles.

Adapter methods exported on Health interface allow HealthAgent
registration. Device methods exported on Health interface allow
applications to actively created MCAP data channels and get informations
of the services exported by the endpoints.

HealthAgent allows applications to receive multiple data streams encoded
on IEEE 11073-20601 Personal Health Data Exchange Protocol.

v2 changes: added HealthData connection object interface
	    assumes at most one HDP set of roles per application
---
 doc/health-api.txt |  187 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 187 insertions(+), 0 deletions(-)
 create mode 100644 doc/health-api.txt

diff --git a/doc/health-api.txt b/doc/health-api.txt
new file mode 100644
index 0000000..49c043d
--- /dev/null
+++ b/doc/health-api.txt
@@ -0,0 +1,187 @@
+BlueZ D-Bus Health API description
+*********************************
+
+Copyright (C) 2010 Elvis Pfutzenreuter <epx@signove.com>
+
+Health Adapter hierarchy
+========================
+
+Service		org.bluez
+Interface	org.bluez.Health
+Object path	[variable prefix]/{hci0,hci1,...}
+
+This object hierarchy intend to be used by applications which want to enable
+a Health source or sink end point. The most common usage scenario is the sink
+role. Multi-channel protocol internals are hidden from the application interface.
+
+Methods:
+	void RegisterRole(dict options, object path)
+
+		Register an HDP role to the adapter and assign the health agent
+		that shall be responsible by address data channel connections.
+
+		Records and channels are automatically closed when the agent
+		leaves the bus. Mandatory and optional options are described
+		below:
+			Optional parameters (dinamically assigned when not
+			informed):
+			uint16 CPSM: control channel PSM
+			uint16 DPSM: data channel PSM
+
+			Mandatory parameters:
+			array{dict EndPoint} EndPoints: Array of end points.
+				Possible EndPoint properties:
+				uint8 MDEPId: Mandatory MCAP Data End Point
+					Identification
+				uint16 DataType: Mandatory Endpoint data type
+				string Role: "source" or "sink"
+				string Description: Optional description
+
+	UnregisterRole()
+
+		Removes an HDP role and kills all connections related to it.
+
+
+Health Agent hierarchy
+======================
+
+Service		unique name
+Interface	org.bluez.HealthAgent
+Object path	freely definable
+
+Agent responsible by address data channels connections. Either active or
+passive connections are notified. FD passing mechanism is used to allows
+the HealthAgent to access directly the data encoded on IEEE 11073-20601
+Personal Health Data Exchange Protocol.
+
+Methods:
+	void NewDataConnection(dict properties)
+
+		This method gets called when a new data channel connection
+		is established. It addresses host and remote initiated
+		connections.
+
+		Properties:
+			string device_path: the Health Device object path
+			string connection_path: the HealthData object path
+			boolean Passive: Device initiated connection
+			boolean Reconnection: Previous established data
+				channel reestablished
+
+	void Release()
+
+		This method gets called whenever the service daemon unregisters
+		the agent or whenever the Adapter where the HealthAgent
+		registers itself is removed.
+
+
+Health Device hierarchy
+=======================
+
+Service		org.bluez
+Interface	org.bluez.Health
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+The methods described below can be used by applications that need
+to manage data channel connections or get properties of service
+exported by the remote device.
+
+Methods:
+
+	string Connect(dict parameters)
+
+		Method used by applications that need to actively create
+		a data channel connection. When the remote connects back
+		in the data channel PSM, the connection is reported to
+		the registered HealthAgent.
+
+		Returns an HDP Connection object path. The same path
+		will be received again via Agent, when connection is
+		established.
+
+		If the reconnection is not possible, a new connection
+		will be created (automatic fallback). The MDL ID may
+		change; the application needs to check HealthData object
+		MDLId property when connection is notified via Agent.
+
+		Mandatory parameters:
+			uint8 local_mdepid: local MDEP ID (*)
+			uint8 remote_mdepid: remote MDEP ID
+		Optional parameters:
+			uint16 mdlid: MDL ID, if trying reconnection
+
+		(*) Was defined by application when it called RegisterRole().
+
+	dict GetProperties()
+
+		Returns the device properties.
+
+Signals:
+
+	PropertiesChanged()
+
+Properties:
+		array{MDEPs}: array of remote data end points. Attributes of
+			a MDEP entry are:
+				uint8 MDEPId
+				uint16 DataType
+				string Role: "source" or "sink"
+				string Description: optional description
+
+		array{MDLs}: array of open data channels. Mandatory
+			MDLs attributes are:
+			uint16 MDLId: Data channel identification
+			string path: HealthData object path
+
+		boolean Connected: true when the MCAP control channel is
+					established
+
+
+Health Device Data Connection hierarchy
+=======================================
+
+Service		org.bluez
+Interface	org.bluez.HealthData
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/YYYYYYYYYYY
+
+A HealthData object can be created either by active connection of by
+receiving a connection via HealthAgent.
+
+FD passing concept is used to allow applications to handle data channels.
+
+A HealthData object exists only while the data connection is up. If the
+connection is broken, the object is removed. The application may
+(and should) handle this situation, by trying a reconnection.
+If the connection was not deleted, the MDL ID outlives the respective
+HealthData object. (Another sign of connection breakage is file
+descriptor closure.)
+
+The methods described below can be used by applications to manage
+a single data channel or get its properties.
+
+Methods:
+
+	filedescriptor GetFD()
+
+		Obtains the raw filedescriptor for this data channel
+		(most likely a L2CAP socket.)
+
+	void Disconnect()
+
+		Closes this data channel and destroys the object,
+		but keeps the MDL ID valid for future reconnections.
+
+	void DeleteConnection()
+
+		Closes this data channel, destroys the object
+		 and invalidates the MDL ID.
+
+	dict GetProperties()
+
+		Returns the device properties.
+
+Properties:
+		uint8 LocalMDEPId: Local data channel identification
+		uint8 RemoteMDEPId: Remote data channel identification
+		uint16 MDLId: data channel ID
+		uint16 MTU: L2CAP channel message MTU
-- 
1.7.0.4

Re: [PATCH] Health Device Profile API

[Santiago Carot-Nemesio]

Hello Elvis,

We think that we are doing the same work in HDP. We are working in the
API for that pugin since last months but we prefer finish MCAP
implementation before fixing HDP API.

We saw your latest patches and next there are our comments. It seems a
lot with our first prototype implementation.
There are some functionalities that we like but we miss other else. We
are going to send an e-mail with the API that we propose.
We expect that we can work together to get a HDP API early. Remember
that we can talk in #openhealth if you want, just tell us when you can
attend ;)

El lun, 03-05-2010 a las 20:22 -0300, Elvis Pfützenreuter escribió:
> From: Elvis Pfutzenreuter <epx@signove.com>
> 
> Initial Health API proposal. Includes Adapter, Device and HealthAgent API
> description. Proposed API can address Health source and sink roles.
> 
> Adapter methods exported on Health interface allow HealthAgent
> registration. Device methods exported on Health interface allow
> applications to actively created MCAP data channels and get informations
> of the services exported by the endpoints.
> 
> HealthAgent allows applications to receive multiple data streams encoded
> on IEEE 11073-20601 Personal Health Data Exchange Protocol.
> 
> v2 changes: added HealthData connection object interface
> 	    assumes at most one HDP set of roles per application
> ---
>  doc/health-api.txt |  187 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 187 insertions(+), 0 deletions(-)
>  create mode 100644 doc/health-api.txt
> 
> diff --git a/doc/health-api.txt b/doc/health-api.txt
> new file mode 100644
> index 0000000..49c043d
> --- /dev/null
> +++ b/doc/health-api.txt
> @@ -0,0 +1,187 @@
> +BlueZ D-Bus Health API description
> +*********************************
> +
> +Copyright (C) 2010 Elvis Pfutzenreuter <epx@signove.com>
> +
> +Health Adapter hierarchy
> +========================
> +
> +Service		org.bluez
> +Interface	org.bluez.Health
> +Object path	[variable prefix]/{hci0,hci1,...}
> +
> +This object hierarchy intend to be used by applications which want to enable
> +a Health source or sink end point. The most common usage scenario is the sink
> +role. Multi-channel protocol internals are hidden from the application interface.
> +
> +Methods:
> +	void RegisterRole(dict options, object path)
> +
> +		Register an HDP role to the adapter and assign the health agent
> +		that shall be responsible by address data channel connections.
> +
> +		Records and channels are automatically closed when the agent
> +		leaves the bus. Mandatory and optional options are described
> +		below:
> +			Optional parameters (dinamically assigned when not
> +			informed):
> +			uint16 CPSM: control channel PSM
> +			uint16 DPSM: data channel PSM
> +
> +			Mandatory parameters:
> +			array{dict EndPoint} EndPoints: Array of end points.
> +				Possible EndPoint properties:
> +				uint8 MDEPId: Mandatory MCAP Data End Point
> +					Identification
> +				uint16 DataType: Mandatory Endpoint data type
> +				string Role: "source" or "sink"
> +				string Description: Optional description
> +
> +	UnregisterRole()
> +
> +		Removes an HDP role and kills all connections related to it.
> +

We believe that it is better that applications doesn't need to provide
parameters that can be managed internally by HDP plugin such as MDEPs.
Then applications could get an avaible MDEP provided by HDP instead of
provide it. This way HDP doesn't have to check that the mdep provided is
a valid mdep and that mdep is not registered two times with different
roles.
We have provided an abstraction based in HDP sessions becasue there may
exist different HDP sessions running in the same host. Your API doesn't
seem to take in count that possibility.

> +
> +Health Agent hierarchy
> +======================
> +
> +Service		unique name
> +Interface	org.bluez.HealthAgent
> +Object path	freely definable
> +
> +Agent responsible by address data channels connections. Either active or
> +passive connections are notified. FD passing mechanism is used to allows
> +the HealthAgent to access directly the data encoded on IEEE 11073-20601
> +Personal Health Data Exchange Protocol.
> +
> +Methods:
> +	void NewDataConnection(dict properties)
> +
> +		This method gets called when a new data channel connection
> +		is established. It addresses host and remote initiated
> +		connections.
> +
> +		Properties:
> +			string device_path: the Health Device object path
> +			string connection_path: the HealthData object path
> +			boolean Passive: Device initiated connection
> +			boolean Reconnection: Previous established data
> +				channel reestablished
> +
> +	void Release()
> +
> +		This method gets called whenever the service daemon unregisters
> +		the agent or whenever the Adapter where the HealthAgent
> +		registers itself is removed.
> +
> +

Above callbacks reflect same ideas that we have, but we propose a
session oriented agent (we call HdpAgent in the e-mail) that
applications should provide when they connect to a HdpSession. Once
applications are connected to a session, HDP will notify them using that
d-bus object.

> +Health Device hierarchy
> +=======================
> +
> +Service		org.bluez
> +Interface	org.bluez.Health
> +Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
> +
> +The methods described below can be used by applications that need
> +to manage data channel connections or get properties of service
> +exported by the remote device.
> +
You can't rely in remote HDP record for Source devices (it is not
mandatory for them to registry it).  we dont understand why you need to
provide a local mdep for the connection of the data channel, only the
remote mdep is required for do that.

> +Methods:
> +
> +	string Connect(dict parameters)
> +
> +		Method used by applications that need to actively create
> +		a data channel connection. When the remote connects back
> +		in the data channel PSM, the connection is reported to
> +		the registered HealthAgent.
> +
> +		Returns an HDP Connection object path. The same path
> +		will be received again via Agent, when connection is
> +		established.
> +
> +		If the reconnection is not possible, a new connection
> +		will be created (automatic fallback). The MDL ID may
> +		change; the application needs to check HealthData object
> +		MDLId property when connection is notified via Agent.
> +
> +		Mandatory parameters:
> +			uint8 local_mdepid: local MDEP ID (*)
> +			uint8 remote_mdepid: remote MDEP ID
> +		Optional parameters:
> +			uint16 mdlid: MDL ID, if trying reconnection

Reconnections may be transparent for applications, we believe that HDP
knows when a data channels is re-connected. (see our API for more
details)

> +
> +		(*) Was defined by application when it called RegisterRole().
> +
> +	dict GetProperties()
> +
> +		Returns the device properties.
> +
> +Signals:
> +
> +	PropertiesChanged()

We think that it is unnecessary because properties should not change
when a HDP session is running.

> +
> +Properties:
> +		array{MDEPs}: array of remote data end points. Attributes of
> +			a MDEP entry are:
> +				uint8 MDEPId
> +				uint16 DataType
> +				string Role: "source" or "sink"
> +				string Description: optional description

We like this. we think that it is helpful for to get remote information
from a remote device.

> +
> +		array{MDLs}: array of open data channels. Mandatory
> +			MDLs attributes are:
> +			uint16 MDLId: Data channel identification
> +			string path: HealthData object path

I think that above method is not necessary because an HdpAgent always is
notified when a new data channel is created or destroyed, but we are
open to discuss.

> +
> +		boolean Connected: true when the MCAP control channel is
> +					established
> +
> +
> +Health Device Data Connection hierarchy
> +=======================================
> +
> +Service		org.bluez
> +Interface	org.bluez.HealthData
> +Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/YYYYYYYYYYY
> +
> +A HealthData object can be created either by active connection of by
> +receiving a connection via HealthAgent.
> +
> +FD passing concept is used to allow applications to handle data channels.
> +
> +A HealthData object exists only while the data connection is up. If the
> +connection is broken, the object is removed. The application may
> +(and should) handle this situation, by trying a reconnection.
> +If the connection was not deleted, the MDL ID outlives the respective
> +HealthData object. (Another sign of connection breakage is file
> +descriptor closure.)
> +
We believe that connections and reconnections should be transparents to
application, for example, if data channel is closed, next time that an
application want to get the data channel fd to send data, HDP could
re-connected the previously closed data channel.
We have done that because under some conditions, devices can close an
MCL for power saving and upper application shouldn't be affected (you
can see 11073-20601 state machine for more details or HDP white paper)

> +The methods described below can be used by applications to manage
> +a single data channel or get its properties.
> +
> +Methods:
> +
> +	filedescriptor GetFD()
> +
> +		Obtains the raw filedescriptor for this data channel
> +		(most likely a L2CAP socket.)
> +
> +	void Disconnect()
> +
> +		Closes this data channel and destroys the object,
> +		but keeps the MDL ID valid for future reconnections.
> +
> +	void DeleteConnection()
> +
> +		Closes this data channel, destroys the object
> +		 and invalidates the MDL ID.

This is more or less that we have thought, but taking in count that
there may exist more Hdp session running on the same host.
> +
> +	dict GetProperties()
> +
> +		Returns the device properties.
> +
> +Properties:
> +		uint8 LocalMDEPId: Local data channel identification
> +		uint8 RemoteMDEPId: Remote data channel identification
> +		uint16 MDLId: data channel ID
> +		uint16 MTU: L2CAP channel message MTU

Regards.
Jose and Santiago

Re: [PATCH] Health Device Profile API

[Elvis Pfützenreuter]

> 
> We have provided an abstraction based in HDP sessions becasue there may
> exist different HDP sessions running in the same host. Your API doesn't
> seem to take in count that possibility.

Note that our adapter.RegisterRole() is bound to a client process. You can have any number of processes, each one calling adapter.RegisterRole() and publishing its own HDP profile. When a process exits, the respective profile is killed.

Our adapter.RegisterRole() has two limitations that you noted.

First: only one HDP profile per client application. We feel that this is not bad.

Second: we don't provide an option NOT to publish an HDP profile. This may be a bug indeed (sinks are not required to publish HDP records, as you kindly noted yesterday via IRC;i in our API we intended to force every every HDP service provider to publish a SDP record.

> Above callbacks reflect same ideas that we have, but we propose a
> session oriented agent (we call HdpAgent in the e-mail) that
> applications should provide when they connect to a HdpSession. Once
> applications are connected to a session, HDP will notify them using that
> d-bus object.

As said above, there is an (implicit) session per client.

> You can't rely in remote HDP record for Source devices (it is not
> mandatory for them to registry it).  we dont understand why you need to
> provide a local mdep for the connection of the data channel, only the
> remote mdep is required for do that.

Point.

> Reconnections may be transparent for applications, we believe that HDP
> knows when a data channels is re-connected. (see our API for more
> details)

See other email about FD, reconnection semantics. I feel we must either expose both reconnections and FDs for the application, or neither one.

>> +		array{MDLs}: array of open data channels. Mandatory
>> +			MDLs attributes are:
>> +			uint16 MDLId: Data channel identification
>> +			string path: HealthData object path
> 
> I think that above method is not necessary because an HdpAgent always is
> notified when a new data channel is created or destroyed, but we are
> open to discuss.

As an occasional application writer, I'd like to have this list at hand :) Indeed the application can integrate every connection/disconnection and know the current state, but...

Re: [PATCH] Health Device Profile API

[José Antonio Santos Cadenas]

Hello,

El Wednesday 05 May 2010 02:19:37 Elvis Pfützenreuter escribió:
> > 
> > We have provided an abstraction based in HDP sessions becasue there may
> > exist different HDP sessions running in the same host. Your API doesn't
> > seem to take in count that possibility.
> 
> Note that our adapter.RegisterRole() is bound to a client process. You can have any number of processes, each one calling adapter.RegisterRole() and publishing its own HDP profile. When a process exits, the respective profile is killed.

This is a good idea.  Sessions live while the process that creates them 
is conencted to the bus. We have included in the 0.2 version of the api
that we just sent. Please, feel free to comment.

> 
> Our adapter.RegisterRole() has two limitations that you noted.
> 
> First: only one HDP profile per client application. We feel that this is not bad.
> 
> Second: we don't provide an option NOT to publish an HDP profile. This may be a bug indeed (sinks are not required to publish HDP records, as you kindly noted yesterday via IRC;i in our API we intended to force every every HDP service provider to publish a SDP record.

We proposed a mixed API with dictionaries that in just one petition is completly configured
(you were rigth, our API could be a little bit complicated in this aspect) but that allows 
sessions without a SDP register.

> 
> > Above callbacks reflect same ideas that we have, but we propose a
> > session oriented agent (we call HdpAgent in the e-mail) that
> > applications should provide when they connect to a HdpSession. Once
> > applications are connected to a session, HDP will notify them using that
> > d-bus object.
> 
> As said above, there is an (implicit) session per client.

We are not sure if this could be a limitation in the future, may be
good to talk about this before fixing an API. There could be process thad 
needs more than one session. (i.e., a manager than wants to be perceived
by the agents as different sessions). Please, note that HDP specification
does not limit the number of session per peer nor process, so we shouldn't
close the API to this possibility so can limit the application's functionality
using HDP in Linux.

> 
> > You can't rely in remote HDP record for Source devices (it is not
> > mandatory for them to registry it).  we dont understand why you need to
> > provide a local mdep for the connection of the data channel, only the
> > remote mdep is required for do that.
> 
> Point.
> 
> > Reconnections may be transparent for applications, we believe that HDP
> > knows when a data channels is re-connected. (see our API for more
> > details)
> 
> See other email about FD, reconnection semantics. I feel we must either expose both reconnections and FDs for the application, or neither one.
> 
> >> +		array{MDLs}: array of open data channels. Mandatory
> >> +			MDLs attributes are:
> >> +			uint16 MDLId: Data channel identification
> >> +			string path: HealthData object path
> > 
> > I think that above method is not necessary because an HdpAgent always is
> > notified when a new data channel is created or destroyed, but we are
> > open to discuss.
> 
> As an occasional application writer, I'd like to have this list at hand :) Indeed the application can integrate every connection/disconnection and know the current state, but...

Sounds good to be in the API. We added it in the proposal.

Regards.

[PATCH] Health Device Profile API

[Elvis Pfutzenreuter]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 5232 bytes --]

Initial Health API proposal. Includes Adapter, Device and HealthAgent API
description. Proposed API can address Health source and sink roles.

Adapter methods exported on Health interface allow HealthAgent
registration. Device methods exported on Health interface allow
applications to actively created MCAP data channels and get informations
of the services exported by the endpoints.

HealthAgent allows applications to receive multiple data streams encoded
on IEEE 11073-20601 Personal Health Data Exchange Protocol.
---
 doc/health-api.txt |  141 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 141 insertions(+), 0 deletions(-)
 create mode 100644 doc/health-api.txt

diff --git a/doc/health-api.txt b/doc/health-api.txt
new file mode 100644
index 0000000..9be3d6c
--- /dev/null
+++ b/doc/health-api.txt
@@ -0,0 +1,141 @@
+BlueZ D-Bus Health API description
+*********************************
+
+Copyright (C) 2010 Elvis Pfützenreuter <epx@signove.com>
+
+Health Adapter hierarchy
+===============
+
+Service		org.bluez
+Interface	org.bluez.Health
+Object path	[variable prefix]/{hci0,hci1,...}
+
+This object hierarchy intend to be used by applications which want to enable
+a Health source or sink end point. The most common usage scenario is the sink
+role. Multi-channel protocol internals are hidden from the application interface.
+
+FD passing concept is used to allow applications to handle data channels.
+
+Methods:
+	uint32 RegisterRole(dict options, object path)
+
+		Register an HDP role to the adapter and assign the health agent
+		that shall be responsible by address data channel connections.
+		Returns an identification for the HDP context.
+
+		Records and channels are automatically closed when the agent
+		leaves the bus. Mandatory and optional options are described
+		below:
+			Optional parameters(dinamically assigned when not
+			informed):
+			uint16 CPSM: control channel
+			uint16 DPSM: data channel
+
+			Mandatory parameters:
+			array{dict EndPoint} EndPoints: Array of end points.
+				Possible EndPoint properties:
+				uint8 MDEPId: Mandatory MCAP Data End Point
+					Identification
+				uint16 DataType: Mandatory Endpoint data type
+				string Role: "source" or "sink"
+				string Description: Optional description
+
+	UnregisterRole(uint32 id)
+
+		Removes an HDP role and kills all connections related to it.
+
+Health Agent hierarchy
+===============
+
+Service		unique name
+Interface	org.bluez.HealthAgent
+Object path	freely definable
+
+Agent responsible by address data channels connections. Either active or
+passive connections are notified. FD passing mechanism is used to allows
+the HealthAgent to access directly the data encoded on IEEE 11073-20601
+Personal Health Data Exchange Protocol.
+
+Methods:
+	void NewMDLConnection(filedescriptor fd, dict properties)
+
+		This method gets called when a new data channel connection
+		is established. It addresses host and remote initiated
+		connections.
+
+		Properties:
+			uint8 LocalMDEPId:
+			uint8 RemoteMDEPId:
+			uint16 MDLId:
+			boolean Passive: Device initiated connection
+			boolean Reconnection: Previous established data
+				channel reestablished
+
+	void Release()
+
+		This method gets called whenever the service daemon unregisters
+		the agent or whenever the Adapter where the HealthAgent
+		registers itself is removed.
+
+Health Device hierarchy
+===============
+
+Service		org.bluez
+Interface	org.bluez.Health
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+The methods described below can be used by applications that need
+to manage data channel connections or get properties of service
+exported by the remote device.
+
+Methods:
+
+	void Connect(uint8 local_mdepid, uint8 remote_mdepid, uint16 mdlid)
+
+		Method used by applications that need to actively create
+		a data channel connection. When the remote connects back
+		in the data channel PSM, the connection is reported to
+		the registered HealthAgent.
+
+		mdlid greater than zero, means that the host is attempt
+		to reestablish a previous session. Zero means that new
+		session shall be established.
+
+		If the reconnection is not possible, a new connection
+		will be created (automatic fallback). The MDL ID may
+		change; the application needs to check it when receiving
+		Agent connection data.
+
+	void Disconnect(uint16  mdlid)
+
+		Closes the give data channel but keeps the MDL ID valid for
+		future reconnections.
+
+	void DeleteConnection(uint16 mdlid)
+
+		Closes the MDL connection and invalidates the MDL ID
+
+	dict GetProperties()
+
+		Returns the device properties.
+
+Signals:
+
+	PropertiesChanged()
+
+Properties:
+		array{MDEPs}: array of remote data end points. Attributes of
+			a MDEP entry are:
+				uint8 MDEPId
+				uint16 DataType
+				string Role: "source" or "sink"
+				string Description: optional  description
+
+		array{MDLs}: array of valid data channels. Mandatory
+			MDLs attributes are:
+			uint16 MDLId: Data channel identification
+			uint8 LocalMDEPId: Local data channel identification
+			uint8 RemoteMDEPId: Remote data channel identification
+
+		boolean Connected: true when the MCAP control channel is
+					established
-- 
1.7.0.4

Re: [PATCH] Health Device Profile API

[Luiz Augusto von Dentz]

Hi Elvis,

On Fri, Apr 30, 2010 at 4:44 AM, Elvis Pfutzenreuter <epx@signove.com> wrote:
> Initial Health API proposal. Includes Adapter, Device and HealthAgent API
> description. Proposed API can address Health source and sink roles.
>
> Adapter methods exported on Health interface allow HealthAgent
> registration. Device methods exported on Health interface allow
> applications to actively created MCAP data channels and get informations
> of the services exported by the endpoints.
>
> HealthAgent allows applications to receive multiple data streams encoded
> on IEEE 11073-20601 Personal Health Data Exchange Protocol.
> ---
>  doc/health-api.txt |  141 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 141 insertions(+), 0 deletions(-)
>  create mode 100644 doc/health-api.txt
>
> diff --git a/doc/health-api.txt b/doc/health-api.txt
> new file mode 100644
> index 0000000..9be3d6c
> --- /dev/null
> +++ b/doc/health-api.txt
> @@ -0,0 +1,141 @@
> +BlueZ D-Bus Health API description
> +*********************************
> +
> +Copyright (C) 2010 Elvis Pfützenreuter <epx@signove.com>
> +
> +Health Adapter hierarchy
> +===============
> +
> +Service                org.bluez
> +Interface      org.bluez.Health
> +Object path    [variable prefix]/{hci0,hci1,...}
> +
> +This object hierarchy intend to be used by applications which want to enable
> +a Health source or sink end point. The most common usage scenario is the sink
> +role. Multi-channel protocol internals are hidden from the application interface.
> +
> +FD passing concept is used to allow applications to handle data channels.
> +
> +Methods:
> +       uint32 RegisterRole(dict options, object path)
> +
> +               Register an HDP role to the adapter and assign the health agent
> +               that shall be responsible by address data channel connections.
> +               Returns an identification for the HDP context.
> +
> +               Records and channels are automatically closed when the agent
> +               leaves the bus. Mandatory and optional options are described
> +               below:
> +                       Optional parameters(dinamically assigned when not
> +                       informed):
> +                       uint16 CPSM: control channel
> +                       uint16 DPSM: data channel
> +
> +                       Mandatory parameters:
> +                       array{dict EndPoint} EndPoints: Array of end points.
> +                               Possible EndPoint properties:
> +                               uint8 MDEPId: Mandatory MCAP Data End Point
> +                                       Identification
> +                               uint16 DataType: Mandatory Endpoint data type
> +                               string Role: "source" or "sink"
> +                               string Description: Optional description
> +
> +       UnregisterRole(uint32 id)
> +
> +               Removes an HDP role and kills all connections related to it.

I guess you wont be reusing the path for multiple roles, so I guess
you can unregister by path which IMHO are a better identifier in case
of D-Bus.

> +Health Agent hierarchy
> +===============
> +
> +Service                unique name
> +Interface      org.bluez.HealthAgent
> +Object path    freely definable
> +
> +Agent responsible by address data channels connections. Either active or
> +passive connections are notified. FD passing mechanism is used to allows
> +the HealthAgent to access directly the data encoded on IEEE 11073-20601
> +Personal Health Data Exchange Protocol.
> +
> +Methods:
> +       void NewMDLConnection(filedescriptor fd, dict properties)
> +
> +               This method gets called when a new data channel connection
> +               is established. It addresses host and remote initiated
> +               connections.
> +
> +               Properties:
> +                       uint8 LocalMDEPId:
> +                       uint8 RemoteMDEPId:
> +                       uint16 MDLId:
> +                       boolean Passive: Device initiated connection
> +                       boolean Reconnection: Previous established data
> +                               channel reestablished
> +
> +       void Release()
> +
> +               This method gets called whenever the service daemon unregisters
> +               the agent or whenever the Adapter where the HealthAgent
> +               registers itself is removed.

You might want to pass the MTU of the connection if the fd represent a
l2cap socket and probably inform the device path so the agent know who
is connecting, or even better if you have path to represent the
connection see the next connect for more details.

> +Health Device hierarchy
> +===============
> +
> +Service                org.bluez
> +Interface      org.bluez.Health
> +Object path    [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
> +
> +The methods described below can be used by applications that need
> +to manage data channel connections or get properties of service
> +exported by the remote device.
> +
> +Methods:
> +
> +       void Connect(uint8 local_mdepid, uint8 remote_mdepid, uint16 mdlid)
> +
> +               Method used by applications that need to actively create
> +               a data channel connection. When the remote connects back
> +               in the data channel PSM, the connection is reported to
> +               the registered HealthAgent.
> +
> +               mdlid greater than zero, means that the host is attempt
> +               to reestablish a previous session. Zero means that new
> +               session shall be established.
> +
> +               If the reconnection is not possible, a new connection
> +               will be created (automatic fallback). The MDL ID may
> +               change; the application needs to check it when receiving
> +               Agent connection data.
> +
> +       void Disconnect(uint16  mdlid)
> +
> +               Closes the give data channel but keeps the MDL ID valid for
> +               future reconnections.
> +
> +       void DeleteConnection(uint16 mdlid)
> +
> +               Closes the MDL connection and invalidates the MDL ID
> +
> +       dict GetProperties()
> +
> +               Returns the device properties.
> +
> +Signals:
> +
> +       PropertiesChanged()
> +
> +Properties:
> +               array{MDEPs}: array of remote data end points. Attributes of
> +                       a MDEP entry are:
> +                               uint8 MDEPId
> +                               uint16 DataType
> +                               string Role: "source" or "sink"
> +                               string Description: optional  description
> +
> +               array{MDLs}: array of valid data channels. Mandatory
> +                       MDLs attributes are:
> +                       uint16 MDLId: Data channel identification
> +                       uint8 LocalMDEPId: Local data channel identification
> +                       uint8 RemoteMDEPId: Remote data channel identification
> +
> +               boolean Connected: true when the MCAP control channel is
> +                                       established

I guess it would be better if Connect takes a dict in this case, so we
can easily omit options if necessary, also I would suggest to return a
new path representing the connection, which can be reused, that one
has Connect/Disconnect and mdl properties, the reason for that is to
avoid array of structs which are not very nice to parse and confusing
to debug.

In case of MDEP we might want to have two interfaces
org.bluez.HealthSink and org.bluez.HealthSource, this should fix the
reusing the interface name with different methods in adapter path and
device path, internally the code can take care of matching local ones
with remotes ones, well at least we did that for a2dp sink/source
although it is a completely different profile I think it might be
useful to have a similar logic in this case otherwise the ui (if there
is any in this case) has to figure out a lot of details to connect,
again in a2dp there is also sink/source concept and support for
multiples remote/local seps but we try to hide as much as possible in
the API.

-- 
Luiz Augusto von Dentz
Computer Engineer

Re: [PATCH] Health Device Profile API

[Elvis Pfützenreuter]

Thanks for the feedback! I will work on this and submit a new proposal tomorrow.

Re: [PATCH] Health Device Profile API

[Elvis Pfützenreuter]

In the case of HDP, the same device may support two different roles (source and sink) on a single SDP record. For example, a data concentrator that collects data from sensors and forwards to a PC will have a number of source and sink MDEPs, all of them under a single SDP record and a single "listening" L2CAP socket for MCAP control channel. When a remoty party connects, only the data channels that match are connected (both of same data type, one side source, other side sink).

That's why we chose a single interface, a generic RegisterRole(), and role appears again in EndPoint dict.

> In case of MDEP we might want to have two interfaces
> org.bluez.HealthSink and org.bluez.HealthSource, this should fix the
> reusing the interface name with different methods in adapter path and
> device path, internally the code can take care of matching local ones
> with remotes ones, well at least we did that for a2dp sink/source
> although it is a completely different profile I think it might be
> useful to have a similar logic in this case otherwise the ui (if there
> is any in this case) has to figure out a lot of details to connect,
> again in a2dp there is also sink/source concept and support for
> multiples remote/local seps but we try to hide as much as possible in
> the API.
> 
> -- 
> Luiz Augusto von Dentz
> Computer Engineer