[RFC v3] doc: Connection Parameters command and event

[RFC v3] doc: Connection Parameters command and event

[Andre Guedes]

---
 doc/mgmt-api.txt | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 80 insertions(+), 1 deletion(-)

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index cd5cd24..6a536d8 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -1006,7 +1006,8 @@ Unpair Device Command
 	Return Parameters:	Address (6 Octets)
 				Address_Type (1 Octet)
 
-	Removes all keys associated with the remote device.
+	Removes all keys and connection parameters associated with the remote
+	device.
 
 	Possible values for the Address_Type parameter:
 		0	BR/EDR
@@ -1679,6 +1680,52 @@ Load Identity Resolving Keys Command
 				Invalid Index
 
 
+Load Connection Parameters Command
+====================================
+
+	Command Code:		0x0031
+	Controller Index:	<controller id>
+	Command Parameters:	Params_Count (2 Octets)
+				Params1 {
+					Address (6 Octets)
+					Address_Type (1 Octet)
+					Min_Connection_Interval (2 Octets)
+					Max_Connection_Interval (2 Octes)
+					Connection_Latency (2 Octets)
+					Supervision_Timeout (2 Octets)
+				}
+				Params2 {  }
+				...
+	Return Parameters:
+
+	This command is used to load connection parameters from several LE
+	devices into kernel. It is only supported on controllers with LE
+	support.
+
+	The provided Address and Address_Type are the identity of a device. So
+	either its public address or static random address. Unresolvable random
+	addresses and resolvable random addresses are not valid and will be
+	rejected.
+
+	Possible values for the Address_Type parameter:
+		0	Reserved (not in use)
+		1	LE Public
+		2	LE Random
+
+	The Min_Connection_Interval, Max_Connection_Interval, Connection_Latency
+	and Supervision_Timeout parameters should be configured as described in
+	Core 4.1 spec, Vol 2, 7.8.12.
+
+	This command can be used when the controller is not powered.
+
+	This command generates a Command Complete event on success or
+	a Command Status event on failure.
+
+	Possible errors:	Invalid Parameters
+				Invalid Index
+				Not Supported
+
+
 Command Complete Event
 ======================
 
@@ -2268,3 +2315,35 @@ New Signature Resolving Key Event
 
 	The provided Address and Address_Type are the identity of
 	a device. So either its public address or static random address.
+
+
+New Connection Parameters Event
+===============================
+
+	Event Code:		0x001a
+	Controller Index:	<controller id>
+	Event Parameters:	Store_Hint (1 Octet)
+				Address (6 Octets)
+				Address_Type (1 Octet)
+				Min_Connection_Interval (2 Octets)
+				Max_Connection_Interval (2 Octes)
+				Connection_Latency (2 Octets)
+				Supervision_Timeout (2 Octets)
+
+	This event indicates the new LE connection parameters set by GAP
+	Connection Parameter Update Procedure.
+
+	The Store_Hint parameter indicates whether the host is expected
+	to store the connection parameters persistently or not.
+
+	This event is sent only if the new parameters are different from the
+	parameters the user has configured (See Load Connection Parameters
+	Command) or if there is no parameters configured for that device.
+
+	Possible values for the Address_Type parameter:
+		0	Reserved (not in use)
+		1	LE Public
+		2	LE Random
+
+	The Connection_Interval, Connection_Latency and Supervision_Timeout
+	parameters are encoded as described in Core 4.1	spec, Vol 2, 7.7.65.3.
-- 
1.9.1

Re: [RFC v3] doc: Connection Parameters command and event

[Marcel Holtmann]

Hi Andre,

> doc/mgmt-api.txt | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 80 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index cd5cd24..6a536d8 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -1006,7 +1006,8 @@ Unpair Device Command
> 	Return Parameters:	Address (6 Octets)
> 				Address_Type (1 Octet)
> 
> -	Removes all keys associated with the remote device.
> +	Removes all keys and connection parameters associated with the remote
> +	device.
> 
> 	Possible values for the Address_Type parameter:
> 		0	BR/EDR
> @@ -1679,6 +1680,52 @@ Load Identity Resolving Keys Command
> 				Invalid Index
> 
> 
> +Load Connection Parameters Command
> +====================================
> +
> +	Command Code:		0x0031
> +	Controller Index:	<controller id>
> +	Command Parameters:	Params_Count (2 Octets)

				Param_Count

> +				Params1 {

				Param1
> +					Address (6 Octets)
> +					Address_Type (1 Octet)
> +					Min_Connection_Interval (2 Octets)
> +					Max_Connection_Interval (2 Octes)
> +					Connection_Latency (2 Octets)
> +					Supervision_Timeout (2 Octets)
> +				}
> +				Params2 {  }

				Param2

It should be loading multiple sets of parameter. The specification also talks about Connection Parameter as in singular set.

> +				...
> +	Return Parameters:
> +
> +	This command is used to load connection parameters from several LE
> +	devices into kernel. It is only supported on controllers with LE
> +	support.
> +
> +	The provided Address and Address_Type are the identity of a device. So
> +	either its public address or static random address. Unresolvable random
> +	addresses and resolvable random addresses are not valid and will be
> +	rejected.
> +
> +	Possible values for the Address_Type parameter:
> +		0	Reserved (not in use)
> +		1	LE Public
> +		2	LE Random
> +
> +	The Min_Connection_Interval, Max_Connection_Interval, Connection_Latency
> +	and Supervision_Timeout parameters should be configured as described in
> +	Core 4.1 spec, Vol 2, 7.8.12.
> +
> +	This command can be used when the controller is not powered.
> +
> +	This command generates a Command Complete event on success or
> +	a Command Status event on failure.
> +
> +	Possible errors:	Invalid Parameters
> +				Invalid Index
> +				Not Supported
> +
> +
> Command Complete Event
> ======================
> 
> @@ -2268,3 +2315,35 @@ New Signature Resolving Key Event
> 
> 	The provided Address and Address_Type are the identity of
> 	a device. So either its public address or static random address.
> +
> +
> +New Connection Parameters Event

		Parameter

> +===============================
> +
> +	Event Code:		0x001a
> +	Controller Index:	<controller id>
> +	Event Parameters:	Store_Hint (1 Octet)

				Param {

> +				Address (6 Octets)
> +				Address_Type (1 Octet)
> +				Min_Connection_Interval (2 Octets)
> +				Max_Connection_Interval (2 Octes)
> +				Connection_Latency (2 Octets)
> +				Supervision_Timeout (2 Octets)

				}

To match this up on how we designed the other events.

> +
> +	This event indicates the new LE connection parameters set by GAP
> +	Connection Parameter Update Procedure.
> +
> +	The Store_Hint parameter indicates whether the host is expected
> +	to store the connection parameters persistently or not.
> +
> +	This event is sent only if the new parameters are different from the
> +	parameters the user has configured (See Load Connection Parameters
> +	Command) or if there is no parameters configured for that device.
> +
> +	Possible values for the Address_Type parameter:
> +		0	Reserved (not in use)
> +		1	LE Public
> +		2	LE Random
> +
> +	The Connection_Interval, Connection_Latency and Supervision_Timeout
> +	parameters are encoded as described in Core 4.1	spec, Vol 2, 7.7.65.3.
> — 

Besides these minor details, looks good to me.

The only question that I still have is if we need to take into account different parameters based on if we are slave or master. So similar to the long term keys, where we have two types of keys. One for each direction.

Since we are planning to support LE peripheral role more and more, I think this is important to consider before we make this API official. It should not stop you to get the initial patches written and submitted for review, but it is something I like to get figured out before we merge anything.

With Bluetooth 4.0 and the L2CAP based connection update procedure it was clear that it is always the slave that mandates the chosen values. However with link layer topology from Bluetooth 4.1 both sides can chose new parameters.

Regards

Marcel

Re: [RFC v3] doc: Connection Parameters command and event

[Andre Guedes]

Hi Marcel,

On 04/07/2014 06:49 PM, Marcel Holtmann wrote:
> Hi Andre,
>
>> doc/mgmt-api.txt | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>> 1 file changed, 80 insertions(+), 1 deletion(-)
>>
>> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
>> index cd5cd24..6a536d8 100644
>> --- a/doc/mgmt-api.txt
>> +++ b/doc/mgmt-api.txt
>> @@ -1006,7 +1006,8 @@ Unpair Device Command
>> 	Return Parameters:	Address (6 Octets)
>> 				Address_Type (1 Octet)
>>
>> -	Removes all keys associated with the remote device.
>> +	Removes all keys and connection parameters associated with the remote
>> +	device.
>>
>> 	Possible values for the Address_Type parameter:
>> 		0	BR/EDR
>> @@ -1679,6 +1680,52 @@ Load Identity Resolving Keys Command
>> 				Invalid Index
>>
>>
>> +Load Connection Parameters Command
>> +====================================
>> +
>> +	Command Code:		0x0031
>> +	Controller Index:	<controller id>
>> +	Command Parameters:	Params_Count (2 Octets)
>
> 				Param_Count
>
>> +				Params1 {
>
> 				Param1
>> +					Address (6 Octets)
>> +					Address_Type (1 Octet)
>> +					Min_Connection_Interval (2 Octets)
>> +					Max_Connection_Interval (2 Octes)
>> +					Connection_Latency (2 Octets)
>> +					Supervision_Timeout (2 Octets)
>> +				}
>> +				Params2 {  }
>
> 				Param2
>
> It should be loading multiple sets of parameter. The specification also talks about Connection Parameter as in singular set.
>
>> +				...
>> +	Return Parameters:
>> +
>> +	This command is used to load connection parameters from several LE
>> +	devices into kernel. It is only supported on controllers with LE
>> +	support.
>> +
>> +	The provided Address and Address_Type are the identity of a device. So
>> +	either its public address or static random address. Unresolvable random
>> +	addresses and resolvable random addresses are not valid and will be
>> +	rejected.
>> +
>> +	Possible values for the Address_Type parameter:
>> +		0	Reserved (not in use)
>> +		1	LE Public
>> +		2	LE Random
>> +
>> +	The Min_Connection_Interval, Max_Connection_Interval, Connection_Latency
>> +	and Supervision_Timeout parameters should be configured as described in
>> +	Core 4.1 spec, Vol 2, 7.8.12.
>> +
>> +	This command can be used when the controller is not powered.
>> +
>> +	This command generates a Command Complete event on success or
>> +	a Command Status event on failure.
>> +
>> +	Possible errors:	Invalid Parameters
>> +				Invalid Index
>> +				Not Supported
>> +
>> +
>> Command Complete Event
>> ======================
>>
>> @@ -2268,3 +2315,35 @@ New Signature Resolving Key Event
>>
>> 	The provided Address and Address_Type are the identity of
>> 	a device. So either its public address or static random address.
>> +
>> +
>> +New Connection Parameters Event
>
> 		Parameter
>
>> +===============================
>> +
>> +	Event Code:		0x001a
>> +	Controller Index:	<controller id>
>> +	Event Parameters:	Store_Hint (1 Octet)
>
> 				Param {
>
>> +				Address (6 Octets)
>> +				Address_Type (1 Octet)
>> +				Min_Connection_Interval (2 Octets)
>> +				Max_Connection_Interval (2 Octes)
>> +				Connection_Latency (2 Octets)
>> +				Supervision_Timeout (2 Octets)
>
> 				}
>
> To match this up on how we designed the other events.
>
>> +
>> +	This event indicates the new LE connection parameters set by GAP
>> +	Connection Parameter Update Procedure.
>> +
>> +	The Store_Hint parameter indicates whether the host is expected
>> +	to store the connection parameters persistently or not.
>> +
>> +	This event is sent only if the new parameters are different from the
>> +	parameters the user has configured (See Load Connection Parameters
>> +	Command) or if there is no parameters configured for that device.
>> +
>> +	Possible values for the Address_Type parameter:
>> +		0	Reserved (not in use)
>> +		1	LE Public
>> +		2	LE Random
>> +
>> +	The Connection_Interval, Connection_Latency and Supervision_Timeout
>> +	parameters are encoded as described in Core 4.1	spec, Vol 2, 7.7.65.3.
>> —
>
> Besides these minor details, looks good to me.

I'm fixing these minor details and re-sending this RFC.

> The only question that I still have is if we need to take into account different parameters based on if we are slave or master. So similar to the long term keys, where we have two types of keys. One for each direction.
>
> Since we are planning to support LE peripheral role more and more, I think this is important to consider before we make this API official. It should not stop you to get the initial patches written and submitted for review, but it is something I like to get figured out before we merge anything.

Sure, I'll also think about how to support peripheral role in this API.

Additionally, I'll start writing patches to implement this API.

Best regards,

Andre

Re: [RFC v3] doc: Connection Parameters command and event

[Johan Hedberg]

Hi Marcel,

On Mon, Apr 07, 2014, Marcel Holtmann wrote:
> > +Load Connection Parameters Command
> > +====================================
> > +
> > +	Command Code:		0x0031
> > +	Controller Index:	<controller id>
> > +	Command Parameters:	Params_Count (2 Octets)
> 
> 				Param_Count
> 
> > +				Params1 {
> 
> 				Param1
> > +					Address (6 Octets)
> > +					Address_Type (1 Octet)
> > +					Min_Connection_Interval (2 Octets)
> > +					Max_Connection_Interval (2 Octes)
> > +					Connection_Latency (2 Octets)
> > +					Supervision_Timeout (2 Octets)
> > +				}
> > +				Params2 {  }
> 
> 				Param2
> 
> It should be loading multiple sets of parameter. The specification
> also talks about Connection Parameter as in singular set.

This would be very funny sounding English imo. The specification only
uses singular for the HCI Commands and Event (where "Connection
Parameter Request" does sound ok and doesn't mean that we're dealing
with a single parameter). In the command and event descriptions the spec
is pretty clear that we're dealing with multiple parameters, e.g.:

(from 7.8.31):
	"This indicates that the Host has accepted the remote device’s
	request to change connection parameters."

	"The Interval_Min parameter shall not be greater than the
	Interval_Max parameter"

	"The Timeout parameter shall..."o

(from 7.8.32):
	"This indicates that the Host has rejected the remote device’s
	request to change connection parameters."

(from 7.7.65.6):
	"This event indicates to the master’s Host or the slave’s Host
	that the remote device is requesting a change in the connection
	parameters."

So imo the spec is pretty clear that we're dealing with multiple
parameters per device.


> > +New Connection Parameters Event
> 
> 		Parameter

Nope. We're notifying user space of a new set of multiple parameters.
Using the singular form here makes this sound quite funny. If you had
just one parameter then we wouldn't even name the event like this but
directly spell out which parameter is in question (e.g. "New Connection
Latency Event").

If you don't believe me feel free to get another opinion from a native
English speaker ;)

Johan

Re: [RFC v3] doc: Connection Parameters command and event

[Marcel Holtmann]

Hi Johan,

>>> +Load Connection Parameters Command
>>> +====================================
>>> +
>>> +	Command Code:		0x0031
>>> +	Controller Index:	<controller id>
>>> +	Command Parameters:	Params_Count (2 Octets)
>> 
>> 				Param_Count
>> 
>>> +				Params1 {
>> 
>> 				Param1
>>> +					Address (6 Octets)
>>> +					Address_Type (1 Octet)
>>> +					Min_Connection_Interval (2 Octets)
>>> +					Max_Connection_Interval (2 Octes)
>>> +					Connection_Latency (2 Octets)
>>> +					Supervision_Timeout (2 Octets)
>>> +				}
>>> +				Params2 {  }
>> 
>> 				Param2
>> 
>> It should be loading multiple sets of parameter. The specification
>> also talks about Connection Parameter as in singular set.
> 
> This would be very funny sounding English imo. The specification only
> uses singular for the HCI Commands and Event (where "Connection
> Parameter Request" does sound ok and doesn't mean that we're dealing
> with a single parameter). In the command and event descriptions the spec
> is pretty clear that we're dealing with multiple parameters, e.g.:
> 
> (from 7.8.31):
> 	"This indicates that the Host has accepted the remote device’s
> 	request to change connection parameters."
> 
> 	"The Interval_Min parameter shall not be greater than the
> 	Interval_Max parameter"
> 
> 	"The Timeout parameter shall..."o
> 
> (from 7.8.32):
> 	"This indicates that the Host has rejected the remote device’s
> 	request to change connection parameters."
> 
> (from 7.7.65.6):
> 	"This event indicates to the master’s Host or the slave’s Host
> 	that the remote device is requesting a change in the connection
> 	parameters."
> 
> So imo the spec is pretty clear that we're dealing with multiple
> parameters per device.
> 
> 
>>> +New Connection Parameters Event
>> 
>> 		Parameter
> 
> Nope. We're notifying user space of a new set of multiple parameters.
> Using the singular form here makes this sound quite funny. If you had
> just one parameter then we wouldn't even name the event like this but
> directly spell out which parameter is in question (e.g. "New Connection
> Latency Event").
> 
> If you don't believe me feel free to get another opinion from a native
> English speaker ;)

all of our commands are containing multiple parameters, but I do not like the wording of making it all plural. The notification event should be singular and the loading command should be plural. For me it is always a set of multiple individual parameters that make up the command and event.

Regards

Marcel

Re: [RFC v3] doc: Connection Parameters command and event

[Luiz Augusto von Dentz]

Hi Marcel, Johan, Andre,

On Tue, Apr 8, 2014 at 5:35 PM, Marcel Holtmann <marcel@holtmann.org> wrote=
:
> Hi Johan,
>
>>>> +Load Connection Parameters Command
>>>> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>>>> +
>>>> +   Command Code:           0x0031
>>>> +   Controller Index:       <controller id>
>>>> +   Command Parameters:     Params_Count (2 Octets)
>>>
>>>                              Param_Count
>>>
>>>> +                           Params1 {
>>>
>>>                              Param1
>>>> +                                   Address (6 Octets)
>>>> +                                   Address_Type (1 Octet)
>>>> +                                   Min_Connection_Interval (2 Octets)
>>>> +                                   Max_Connection_Interval (2 Octes)
>>>> +                                   Connection_Latency (2 Octets)
>>>> +                                   Supervision_Timeout (2 Octets)
>>>> +                           }
>>>> +                           Params2 {  }

Regarding the parameters it seems we should include the scan interval
and window as well otherwise the logic will not be completely in the
kernel and the userspace will still have to keep a list of devices and
set the scan parameters by itself. IMO it would be better the leave
the kernel to control everything, anyway it will have to deal with
scanning logic based on connection list, so it will be able to detect
if a certain connection requires a more aggressive scanning and also
relax the scanning once connected.

>>>                              Param2
>>>
>>> It should be loading multiple sets of parameter. The specification
>>> also talks about Connection Parameter as in singular set.
>>
>> This would be very funny sounding English imo. The specification only
>> uses singular for the HCI Commands and Event (where "Connection
>> Parameter Request" does sound ok and doesn't mean that we're dealing
>> with a single parameter). In the command and event descriptions the spec
>> is pretty clear that we're dealing with multiple parameters, e.g.:
>>
>> (from 7.8.31):
>>       "This indicates that the Host has accepted the remote device=E2=80=
=99s
>>       request to change connection parameters."
>>
>>       "The Interval_Min parameter shall not be greater than the
>>       Interval_Max parameter"
>>
>>       "The Timeout parameter shall..."o
>>
>> (from 7.8.32):
>>       "This indicates that the Host has rejected the remote device=E2=80=
=99s
>>       request to change connection parameters."
>>
>> (from 7.7.65.6):
>>       "This event indicates to the master=E2=80=99s Host or the slave=E2=
=80=99s Host
>>       that the remote device is requesting a change in the connection
>>       parameters."
>>
>> So imo the spec is pretty clear that we're dealing with multiple
>> parameters per device.
>>
>>
>>>> +New Connection Parameters Event
>>>
>>>              Parameter
>>
>> Nope. We're notifying user space of a new set of multiple parameters.
>> Using the singular form here makes this sound quite funny. If you had
>> just one parameter then we wouldn't even name the event like this but
>> directly spell out which parameter is in question (e.g. "New Connection
>> Latency Event").
>>
>> If you don't believe me feel free to get another opinion from a native
>> English speaker ;)
>
> all of our commands are containing multiple parameters, but I do not like=
 the wording of making it all plural. The notification event should be sing=
ular and the loading command should be plural. For me it is always a set of=
 multiple individual parameters that make up the command and event.

I would suggest to name it Load Connections Command and rename
Params_Count to Connection_Count, Param1 to Connection1, etc,
basically drop the term parameter and use connection as a set of
parameters.

--=20
Luiz Augusto von Dentz

Re: [RFC v3] doc: Connection Parameters command and event

[Marcel Holtmann]

Hi Luiz,

>>>>> +Load Connection Parameters Command
>>>>> +====================================
>>>>> +
>>>>> +   Command Code:           0x0031
>>>>> +   Controller Index:       <controller id>
>>>>> +   Command Parameters:     Params_Count (2 Octets)
>>>> 
>>>>                             Param_Count
>>>> 
>>>>> +                           Params1 {
>>>> 
>>>>                             Param1
>>>>> +                                   Address (6 Octets)
>>>>> +                                   Address_Type (1 Octet)
>>>>> +                                   Min_Connection_Interval (2 Octets)
>>>>> +                                   Max_Connection_Interval (2 Octes)
>>>>> +                                   Connection_Latency (2 Octets)
>>>>> +                                   Supervision_Timeout (2 Octets)
>>>>> +                           }
>>>>> +                           Params2 {  }
> 
> Regarding the parameters it seems we should include the scan interval
> and window as well otherwise the logic will not be completely in the
> kernel and the userspace will still have to keep a list of devices and
> set the scan parameters by itself. IMO it would be better the leave
> the kernel to control everything, anyway it will have to deal with
> scanning logic based on connection list, so it will be able to detect
> if a certain connection requires a more aggressive scanning and also
> relax the scanning once connected.

the reason why did it this way is, because these are the exact parameters used by the Connection Update Procedure. The scan parameters are actually not really of a concern.

Also keep in mind that these parameters are triggered mainly by the slave to update the parameters of the connection. And picking the right ones from the start increases the connection establishment time and the overall latency.

I left the scan parameters out on purpose since I do not want to have two policy engines fighting over who decides which scan parameters to use. My expectation is that the scan parameters will be mainly driven by the daemon that decides on how to use them. Today, we have already this. Userspace configured them and it is up to the kernel to just enforce it.

For connection establishment without a whitelist, you pick parameters with scan window and scan interval as the same value. Which essentially means a continues scan until the device has been found. So having extra scan parameters will not help you there. For the passive background scanning, userspace can happily tell the kernel and then the kernel can just adjust the scanning.

Regards

Marcel