---
doc/mgmt-api.txt | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 87 insertions(+), 1 deletion(-)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index daf036b4c1ec..2038f883cc95 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -2135,6 +2135,89 @@ Set Public Address Command
Invalid Index
+Start Service Discovery Command
+===============================
+
+ Command Code: 0x003a
+ Controller Index: <controller id>
+ Command Parameters: Address_Type (1 Octet)
+ RSSI_Threshold (1 Octet)
+ Num_UUID (1 Octet)
+ UUID[i] (16 Octets)
+ Return Parameters: Address_Type (1 Octet)
+
+ This command is used to start the process of discovering remote
+ devices with a specific UUID. A Device Found event will be sent
+ for each discovered device.
+
+ Possible values for the Address_Type parameter are a bit-wise or
+ of the following bits:
+
+ 0 BR/EDR
+ 1 LE Public
+ 2 LE Random
+
+ By combining these e.g. the following values are possible:
+
+ 1 BR/EDR
+ 6 LE (public & random)
+ 7 BR/EDR/LE (interleaved discovery)
+
+ The service discovery uses active scanning for Low Energy scanning
+ and will search for UUID in both advertising data and scan response
+ data.
+
+ Found devices that have a RSSI value smaller than RSSI_Threshold
+ are not reported via DeviceFound event. Setting a value of 127
+ will cause all devices to be reported.
+
+ The list of UUIDs identifies a logical OR. Only one of the UUIDs
+ have to match to cause a DeviceFound event. Providing an empty
+ list of UUIDs with Num_UUID set to 0 which means that DeviceFound
+ events are send out for all devices above the RSSI_Threshold.
+
+ In case the RSSI_Threshold is set to 127 and the Num_UUID is 0,
+ then this command behaves exactly the same as Start Discovery.
+
+ When the discovery procedure starts the Discovery event will
+ notify this similar to Start Discovery.
+
+ This command can only be used when the controller is powered.
+
+ This command generates a Command Complete event on success
+ or failure.
+
+ Possible errors: Busy
+ Not Supported
+ Invalid Parameters
+ Not Powered
+ Invalid Index
+
+
+Stop Service Discovery Command
+==============================
+
+ Command Code: 0x003b
+ Controller Index: <controller id>
+ Command Parameters: Address_Type (1 Octet)
+ Return Parameters: Address_Type (1 Octet)
+
+ This command is used to stop the service discovery process started
+ using the Start Service Discovery command.
+
+ When the discovery procedure stops the Discovery event will
+ notify this similar to Stop Discovery.
+
+ This command can only be used when the controller is powered.
+
+ This command generates a Command Complete event on success
+ or failure.
+
+ Possible errors: Rejected
+ Invalid Parameters
+ Invalid Index
+
+
Command Complete Event
======================
@@ -2555,7 +2638,10 @@ Discovering Event
This event indicates that the controller has started discovering
devices. This discovering state can come and go multiple times
- between a StartDiscover and a StopDiscovery command.
+ between a Start Discover and a Stop Discovery commands.
+
+ The Start Service Discovery and Stop Service Discovery commands
+ will also trigger this event.
The valid values for the Discovering parameter are 0x01
(enabled) and 0x00 (disabled).
--
1.9.3
Hi Jakub,
> I think that RSSI_Threshold should be per UUID:
>
> + Command Parameters: Address_Type (1 Octet)
> + Num_Filters (1 Octet)
> + Filter1 {
> + RSSI_Threshold (1 Octet)
> + UUID[i] (16 Octets)
> + }
> + Filter2 {}
> + ...
I need a bit more reason for this. Stating it does not convince me ;)
My take is that it is not needed for this one-shot discovering. Just select some good enough RSSI threshold and filter the rest later when you get TX power information. Like with Start Discovery it will stop once it is done with the search. So next time around you can select a different RSSI threshold.
Regards
Marcel
I think that RSSI_Threshold should be per UUID:
+ Command Parameters: Address_Type (1 Octet)
+ Num_Filters (1 Octet)
+ Filter1 {
+ RSSI_Threshold (1 Octet)
+ UUID[i] (16 Octets)
+ }
+ Filter2 {}
+ ...
On Fri, Oct 10, 2014 at 3:49 AM, Marcel Holtmann <[email protected]> wrote:
> ---
> doc/mgmt-api.txt | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 87 insertions(+), 1 deletion(-)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index daf036b4c1ec..2038f883cc95 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -2135,6 +2135,89 @@ Set Public Address Command
> Invalid Index
>
>
> +Start Service Discovery Command
> +===============================
> +
> + Command Code: 0x003a
> + Controller Index: <controller id>
> + Command Parameters: Address_Type (1 Octet)
> + RSSI_Threshold (1 Octet)
> + Num_UUID (1 Octet)
> + UUID[i] (16 Octets)
> + Return Parameters: Address_Type (1 Octet)
> +
> + This command is used to start the process of discovering remote
> + devices with a specific UUID. A Device Found event will be sent
> + for each discovered device.
> +
> + Possible values for the Address_Type parameter are a bit-wise or
> + of the following bits:
> +
> + 0 BR/EDR
> + 1 LE Public
> + 2 LE Random
> +
> + By combining these e.g. the following values are possible:
> +
> + 1 BR/EDR
> + 6 LE (public & random)
> + 7 BR/EDR/LE (interleaved discovery)
> +
> + The service discovery uses active scanning for Low Energy scanning
> + and will search for UUID in both advertising data and scan response
> + data.
> +
> + Found devices that have a RSSI value smaller than RSSI_Threshold
> + are not reported via DeviceFound event. Setting a value of 127
> + will cause all devices to be reported.
> +
> + The list of UUIDs identifies a logical OR. Only one of the UUIDs
> + have to match to cause a DeviceFound event. Providing an empty
> + list of UUIDs with Num_UUID set to 0 which means that DeviceFound
> + events are send out for all devices above the RSSI_Threshold.
> +
> + In case the RSSI_Threshold is set to 127 and the Num_UUID is 0,
> + then this command behaves exactly the same as Start Discovery.
> +
> + When the discovery procedure starts the Discovery event will
> + notify this similar to Start Discovery.
> +
> + This command can only be used when the controller is powered.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Busy
> + Not Supported
> + Invalid Parameters
> + Not Powered
> + Invalid Index
> +
> +
> +Stop Service Discovery Command
> +==============================
> +
> + Command Code: 0x003b
> + Controller Index: <controller id>
> + Command Parameters: Address_Type (1 Octet)
> + Return Parameters: Address_Type (1 Octet)
> +
> + This command is used to stop the service discovery process started
> + using the Start Service Discovery command.
> +
> + When the discovery procedure stops the Discovery event will
> + notify this similar to Stop Discovery.
> +
> + This command can only be used when the controller is powered.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Rejected
> + Invalid Parameters
> + Invalid Index
> +
> +
> Command Complete Event
> ======================
>
> @@ -2555,7 +2638,10 @@ Discovering Event
>
> This event indicates that the controller has started discovering
> devices. This discovering state can come and go multiple times
> - between a StartDiscover and a StopDiscovery command.
> + between a Start Discover and a Stop Discovery commands.
> +
> + The Start Service Discovery and Stop Service Discovery commands
> + will also trigger this event.
>
> The valid values for the Discovering parameter are 0x01
> (enabled) and 0x00 (disabled).
> --
> 1.9.3
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
> the body of a message to [email protected]
> More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Jakub,
>>>>>> I think that RSSI_Threshold should be per UUID:
>>>>>>
>>>>>> + Command Parameters: Address_Type (1 Octet)
>>>>>> + Num_Filters (1 Octet)
>>>>>> + Filter1 {
>>>>>> + RSSI_Threshold (1 Octet)
>>>>>> + UUID[i] (16 Octets)
>>>>>> + }
>>>>>> + Filter2 {}
>>>>>> + ...
>>>>>
>>>>> I need a bit more reason for this. Stating it does not convince me ;)
>>>>>
>>>>> My take is that it is not needed for this one-shot discovering. Just select some good enough RSSI threshold and filter the rest later when you get TX power information. Like with Start Discovery it will stop once it is done with the search. So next time around you can select a different RSSI threshold.
>>>>
>>>> Let's say I'm scanning for two kinds services:
>>>> - some security token, that needs to be very close to my machine
>>>> - temperature sensor, with no particular interest in range
>>>> - controller receives one packet from security token that advertise at
>>>> very high TX power and is very close, so I specify very high rssi
>>>> threshold
>>>> - then the temperature sensor, that advertises on low power will not be reported
>>>>
>>>> If I had rssi specified per UUID that won't be the case.
>>>
>>> I think having that is a good idea in general. Just not in the case of a one-shot discovery trigger. We should do that for adding these UUID filters to the background scanning.
>>>
>>> The difference between discovery and background scanning is that during discovery we are using active scanning (meaning scan responses will be requested) and during background scanning we are using passive scanning.
>>>
>>> So my thinking is that you use the service discovery to find your device/service now. You are actively looking for it at that point in time. In that case it really does not matter that you get a few false positives. You are actively using your radio to send scan requests anyway.
>>
>> Ok, I'll modify my patches so that start service discovery would get
>> only one rssi value for all services.
>>
>
> I just fixed my patches work as you described in doc/mgmt-api.txt
> Writing it as you proposed made the code much simpler and cleaner. Thanks!
> Can you please 'git am' this doc/mgmt.txt patch, or is there something
> more to do ?
I pushed the doc/mgmt-api.txt updates now.
Regards
Marcel
On Fri, Nov 21, 2014 at 7:19 PM, Jakub Pawlowski <[email protected]> wr=
ote:
> On Fri, Nov 21, 2014 at 6:16 PM, Marcel Holtmann <[email protected]> wr=
ote:
>> Hi Jakub,
>>
>>>>> I think that RSSI_Threshold should be per UUID:
>>>>>
>>>>> + Command Parameters: Address_Type (1 Octet)
>>>>> + Num_Filters (1 Octet)
>>>>> + Filter1 {
>>>>> + RSSI_Threshold (1 Octet)
>>>>> + UUID[i] (16 Octets)
>>>>> + }
>>>>> + Filter2 {}
>>>>> + ...
>>>>
>>>> I need a bit more reason for this. Stating it does not convince me ;)
>>>>
>>>> My take is that it is not needed for this one-shot discovering. Just s=
elect some good enough RSSI threshold and filter the rest later when you ge=
t TX power information. Like with Start Discovery it will stop once it is d=
one with the search. So next time around you can select a different RSSI th=
reshold.
>>>
>>> Let's say I'm scanning for two kinds services:
>>> - some security token, that needs to be very close to my machine
>>> - temperature sensor, with no particular interest in range
>>> - controller receives one packet from security token that advertise at
>>> very high TX power and is very close, so I specify very high rssi
>>> threshold
>>> - then the temperature sensor, that advertises on low power will not be=
reported
>>>
>>> If I had rssi specified per UUID that won't be the case.
>>
>> I think having that is a good idea in general. Just not in the case of a=
one-shot discovery trigger. We should do that for adding these UUID filter=
s to the background scanning.
>>
>> The difference between discovery and background scanning is that during =
discovery we are using active scanning (meaning scan responses will be requ=
ested) and during background scanning we are using passive scanning.
>>
>> So my thinking is that you use the service discovery to find your device=
/service now. You are actively looking for it at that point in time. In tha=
t case it really does not matter that you get a few false positives. You ar=
e actively using your radio to send scan requests anyway.
>
> Ok, I'll modify my patches so that start service discovery would get
> only one rssi value for all services.
>
I just fixed my patches work as you described in doc/mgmt-api.txt
Writing it as you proposed made the code much simpler and cleaner. Thanks!
Can you please 'git am' this doc/mgmt.txt patch, or is there something
more to do ?
I recently asked Johan and he said that it must happen before we can
apply my patches (after my patches are ok, of course).
>>
>>>
>>> I can also set the RSSI threshold at very low value to get notified
>>> about temperature sensor, but the I'll get a lot of device found
>>> events about security token that will wake my application unnecessary.
>>> We want to avoid that, and that's why we're doing scan in kernel, and
>>> plan to move it to controller.
>>>
>>> So my patches right now define rssi threshold per UUID this like that:
>>>
>>> struct mgmt_uuid_filter {
>>> __s8 rssi;
>>> __u8 uuid[16];
>>> } __packed;
>>>
>>> struct mgmt_cp_start_service_discovery {
>>> __u8 type;
>>> __le16 filter_count;
>>> struct mgmt_uuid_filter filter[0];
>>> } __packed;
>>
>> Add Start Service Discovery and Stop Service Discover is just the first =
step to support your needs. That is for actively finding devices at a speci=
fic point in time. For long time running background scanning we need to add=
these UUID to the background scanning list. And there we add/remove them o=
ne by one and with that can make it depending on the RSSI.
>
> Ok, but let's first get this short term scan in.
>>
>> Regards
>>
>> Marcel
>>
On Fri, Nov 21, 2014 at 6:16 PM, Marcel Holtmann <[email protected]> wrot=
e:
> Hi Jakub,
>
>>>> I think that RSSI_Threshold should be per UUID:
>>>>
>>>> + Command Parameters: Address_Type (1 Octet)
>>>> + Num_Filters (1 Octet)
>>>> + Filter1 {
>>>> + RSSI_Threshold (1 Octet)
>>>> + UUID[i] (16 Octets)
>>>> + }
>>>> + Filter2 {}
>>>> + ...
>>>
>>> I need a bit more reason for this. Stating it does not convince me ;)
>>>
>>> My take is that it is not needed for this one-shot discovering. Just se=
lect some good enough RSSI threshold and filter the rest later when you get=
TX power information. Like with Start Discovery it will stop once it is do=
ne with the search. So next time around you can select a different RSSI thr=
eshold.
>>
>> Let's say I'm scanning for two kinds services:
>> - some security token, that needs to be very close to my machine
>> - temperature sensor, with no particular interest in range
>> - controller receives one packet from security token that advertise at
>> very high TX power and is very close, so I specify very high rssi
>> threshold
>> - then the temperature sensor, that advertises on low power will not be =
reported
>>
>> If I had rssi specified per UUID that won't be the case.
>
> I think having that is a good idea in general. Just not in the case of a =
one-shot discovery trigger. We should do that for adding these UUID filters=
to the background scanning.
>
> The difference between discovery and background scanning is that during d=
iscovery we are using active scanning (meaning scan responses will be reque=
sted) and during background scanning we are using passive scanning.
>
> So my thinking is that you use the service discovery to find your device/=
service now. You are actively looking for it at that point in time. In that=
case it really does not matter that you get a few false positives. You are=
actively using your radio to send scan requests anyway.
Ok, I'll modify my patches so that start service discovery would get
only one rssi value for all services.
>
>>
>> I can also set the RSSI threshold at very low value to get notified
>> about temperature sensor, but the I'll get a lot of device found
>> events about security token that will wake my application unnecessary.
>> We want to avoid that, and that's why we're doing scan in kernel, and
>> plan to move it to controller.
>>
>> So my patches right now define rssi threshold per UUID this like that:
>>
>> struct mgmt_uuid_filter {
>> __s8 rssi;
>> __u8 uuid[16];
>> } __packed;
>>
>> struct mgmt_cp_start_service_discovery {
>> __u8 type;
>> __le16 filter_count;
>> struct mgmt_uuid_filter filter[0];
>> } __packed;
>
> Add Start Service Discovery and Stop Service Discover is just the first s=
tep to support your needs. That is for actively finding devices at a specif=
ic point in time. For long time running background scanning we need to add =
these UUID to the background scanning list. And there we add/remove them on=
e by one and with that can make it depending on the RSSI.
Ok, but let's first get this short term scan in.
>
> Regards
>
> Marcel
>
Hi Jakub,
>>> I think that RSSI_Threshold should be per UUID:
>>>
>>> + Command Parameters: Address_Type (1 Octet)
>>> + Num_Filters (1 Octet)
>>> + Filter1 {
>>> + RSSI_Threshold (1 Octet)
>>> + UUID[i] (16 Octets)
>>> + }
>>> + Filter2 {}
>>> + ...
>>
>> I need a bit more reason for this. Stating it does not convince me ;)
>>
>> My take is that it is not needed for this one-shot discovering. Just select some good enough RSSI threshold and filter the rest later when you get TX power information. Like with Start Discovery it will stop once it is done with the search. So next time around you can select a different RSSI threshold.
>
> Let's say I'm scanning for two kinds services:
> - some security token, that needs to be very close to my machine
> - temperature sensor, with no particular interest in range
> - controller receives one packet from security token that advertise at
> very high TX power and is very close, so I specify very high rssi
> threshold
> - then the temperature sensor, that advertises on low power will not be reported
>
> If I had rssi specified per UUID that won't be the case.
I think having that is a good idea in general. Just not in the case of a one-shot discovery trigger. We should do that for adding these UUID filters to the background scanning.
The difference between discovery and background scanning is that during discovery we are using active scanning (meaning scan responses will be requested) and during background scanning we are using passive scanning.
So my thinking is that you use the service discovery to find your device/service now. You are actively looking for it at that point in time. In that case it really does not matter that you get a few false positives. You are actively using your radio to send scan requests anyway.
>
> I can also set the RSSI threshold at very low value to get notified
> about temperature sensor, but the I'll get a lot of device found
> events about security token that will wake my application unnecessary.
> We want to avoid that, and that's why we're doing scan in kernel, and
> plan to move it to controller.
>
> So my patches right now define rssi threshold per UUID this like that:
>
> struct mgmt_uuid_filter {
> __s8 rssi;
> __u8 uuid[16];
> } __packed;
>
> struct mgmt_cp_start_service_discovery {
> __u8 type;
> __le16 filter_count;
> struct mgmt_uuid_filter filter[0];
> } __packed;
Add Start Service Discovery and Stop Service Discover is just the first step to support your needs. That is for actively finding devices at a specific point in time. For long time running background scanning we need to add these UUID to the background scanning list. And there we add/remove them one by one and with that can make it depending on the RSSI.
Regards
Marcel
On Mon, Oct 20, 2014 at 11:06 AM, Marcel Holtmann <[email protected]> wro=
te:
> Hi Jakub,
>
>> I think that RSSI_Threshold should be per UUID:
>>
>> + Command Parameters: Address_Type (1 Octet)
>> + Num_Filters (1 Octet)
>> + Filter1 {
>> + RSSI_Threshold (1 Octet)
>> + UUID[i] (16 Octets)
>> + }
>> + Filter2 {}
>> + ...
>
> I need a bit more reason for this. Stating it does not convince me ;)
>
> My take is that it is not needed for this one-shot discovering. Just sele=
ct some good enough RSSI threshold and filter the rest later when you get T=
X power information. Like with Start Discovery it will stop once it is done=
with the search. So next time around you can select a different RSSI thres=
hold.
>
> Regards
>
> Marcel
>
Let's say I'm scanning for two kinds services:
- some security token, that needs to be very close to my machine
- temperature sensor, with no particular interest in range
- controller receives one packet from security token that advertise at
very high TX power and is very close, so I specify very high rssi
threshold
- then the temperature sensor, that advertises on low power will not be rep=
orted
If I had rssi specified per UUID that won't be the case.
I can also set the RSSI threshold at very low value to get notified
about temperature sensor, but the I'll get a lot of device found
events about security token that will wake my application unnecessary.
We want to avoid that, and that's why we're doing scan in kernel, and
plan to move it to controller.
So my patches right now define rssi threshold per UUID this like that:
struct mgmt_uuid_filter {
__s8 rssi;
__u8 uuid[16];
} __packed;
struct mgmt_cp_start_service_discovery {
__u8 type;
__le16 filter_count;
struct mgmt_uuid_filter filter[0];
} __packed;