Enable ReportDelay/NumberOfMatches/MatchMode settings in ScanSettings.Builder

[fonix232]

Summary

Currently, ScanSettings's matchMode, reportDelayinMillis and mNumOfMatchesPerFilter are all commented out (see here). This is a quite annoying oversight that has not been fixed for the past two years, and doesn't even require that much of a change.

However the hindered functionality is quite high priority in quite a few cases, and makes timed updates impossible to create (e.g. if one wants low latency scan results, but batched so every update is delivered at a 2 second interval).

Library version

1.10.1

Preconditions

None, the code bits are intentionally commented out

Steps to reproduce actual result

1. Add RxAndroidBle to project
2. Try to create a ScanSettings instance with report delay
3. The call is not present on ScanSettings.Builder

Actual result

The calls are not present on ScanSettings.Builder

Expected result

The calls should be available

Solution

Uncomment the three mentioned ScanSettings.Builder methods

[dariuszseweryn]

Hello @fonix232

Thank you for using the library.

This is a quite annoying oversight that has not been fixed for the past two years, and doesn't even require that much of a change.

A bit of background — this was not an oversight. The library aims for a consistent behaviour across OS API levels. This behaviour is not available on API <21 at all. Even some devices with API >21 may not support all options correctly (I have started work on a fallback mechanism for handling such cases — see branch scan_fallback_and_better_control, related issue #561).

There is a need to create (and test!) emulated versions of those commented out functionalities. There are some potential edge cases where different settings could interfere with each other. This may not be trivial.

I also do lack knowledge about what is the exact logic behind NUM_OF_MATCHES and MATCH_MODE. Any pointers to it would be valuable.

I may include this background as a comment in the code so next people will not be surprised as you.

As till now I have not seen any requests for this functionality — you are the first. I do not have enough time to do it all properly but I will happily help if someone would like to contribute.

P.S. Batching updates is quite easy to do depending on your exact use-case using only RxJava. E.g. see window, flatMap and toList operators

[fonix232]

Hi @dariuszseweryn

Sorry for the late reply.

I agree that on lower level APIs, the emulation of these properties (via manual filtering after the system returns the results?) would be the way to go - although I'm not sure how long you'd like to keep supporting low level APIs (specifically, <21), since the number of devices running such a low OS version is quite rare now, luckily.

I can't say much about NUM_OF_MATCHES and MATCH_MODE sadly. I don't really have a scenario where I need to use them. My limited understanding of MATCH_MODE is that this property raises/lowers the "sensitivity" required by the PHY/HW layer for a scan record to be created (i.e. it determines if the signal is strong enough. NUM_OF_MATCHES seems to direct the hardware to "stop" filtering out a scan batch after a number of hits (e.g. with the option of MATCH_NUM_ONE_ADVERTISEMENT you'd only get the first result with advertisement matching your requirements, FEW_ADVERTISEMENT would be a few that does not overload the hardware, and MAX_ADVERTISEMENT would be matching as many as physically possible by the underlying hardware).

For me the most important of these three would be the report delay, as that would allow me to batch scan results - which is quite useful for purposes of displaying a list of results, without the list jumping around - by using the BT/BLE hardware instead of the CPU for this. I know it sounds like a stupid little optimisation, but one would do anything to ensure fluid UI :)

Using RxJava is an option, yes, but then instead of window I'd rather use buffer with a time constraint on it.

[dariuszseweryn]

I agree that on lower level APIs, the emulation of these properties (via manual filtering after the system returns the results?) would be the way to go - although I'm not sure how long you'd like to keep supporting low level APIs (specifically, <21), since the number of devices running such a low OS version is quite rare now, luckily.

Potentially there are also phones with API >=21 that do not support certain ScanOption settings. See #561

I can't say much about NUM_OF_MATCHES and MATCH_MODE sadly. I don't really have a scenario where I need to use them. My limited understanding of MATCH_MODE is that this property raises/lowers the "sensitivity" required by the PHY/HW layer for a scan record to be created (i.e. it determines if the signal is strong enough. NUM_OF_MATCHES seems to direct the hardware to "stop" filtering out a scan batch after a number of hits (e.g. with the option of MATCH_NUM_ONE_ADVERTISEMENT you'd only get the first result with advertisement matching your requirements, FEW_ADVERTISEMENT would be a few that does not overload the hardware, and MAX_ADVERTISEMENT would be matching as many as physically possible by the underlying hardware).

I would need to have exact data/specification to be able to make an emulation equivalent

Using RxJava is an option, yes, but then instead of window I'd rather use buffer with a time constraint on it.

This may be a viable option. I do not remember all operators unfortunately.