Yogesh k

Important changes to forums and questions

All forums and questions are now archived. To start a new conversation or read the latest updates go to forums.mbed.com.

5 years, 9 months ago.

Cordio BLE API: Clarifications regarding using Scan Parameters & startScan API?

In the new Cordio BLE API, it seems like the Scan Parameters is used to set the Scan Interval and Scan Window. However the Cordio BLE startScan API accepts the following parameters:

startScan method

/** Start scanning.
     *
     * @param duration How long to scan for. Special value 0 means scan forever.
     * @param filtering Filtering policy.
     * @param period How long to scan for in single period. If the period is 0 and duration
     *               is nonzero the scan will last for single duration.
     *
     * @note When the duration and period parameters are non-zero scanning will last for
     * the duration within the period. After the scan period has expired a new scan period
     * will begin and scanning. This will repeat until stopScan() is called.
     *
     * @return BLE_ERROR_NONE on success.
     *
     * @see EventHandler::onAdvertisingReport to collect advertising reports.
     * @see EventHandler::onScanTimeout when scanning timeout.
     */
    virtual ble_error_t startScan(
        scan_duration_t duration = scan_duration_t::forever(),
        duplicates_filter_t filtering = duplicates_filter_t::DISABLE,
        scan_period_t period = scan_period_t(0)
    );

So the questions I have are the following.

1) When the ScanParameters are set via the setScanParameters method and in the startScan method mentioned above, are the default parameters ignored and the ScanParameters set previously used? I am assuming duration parameter in startScan method is the same as ScanWindow and the period parameter is the same as the ScanInterval?

2) In the previous versions of mbed-os prior to Cordio BLE API the startScan method accepted a ScanTimout interval and the ScanTimeout event was called once the ScanTimeout interval elapsed. However when is the ScanTimout handler called in the Cordio BLE API. Also is there a way to set a ScanTimeout interval in Cordio BLE API?

Thanks, Yogesh

1 Answer

Desmond Chen
5 years, 9 months ago.

Hi Yogesh,

Those parameters in those two APIs are all having different meanings.

Of setScanParamters(), we have the two parameters,

scan_window_t scan_interval: This is LE_Scan_Window of HCI LE Set Scan Parameters Command.

scan_interval_t scan_window: This is LE_Scan_Interval of HCI LE Set Scan Parameters Command.

Of startScan(), we have the two parameters,

scan_duration_t duration: This is the duration of the scan process, 0 means scan process never ends.

scan_period_t period: This is Period of HCI LE Set Extended Scan, if you are doing legacy scan, this should be set as 0.

The detail is described in Mbed OS documentation.[https://os.mbed.com/docs/mbed-os/v5.11/mbed-os-api-doxy/group__gap.html#gac0cd8ca22a69897824561dce98703757]

So for the ScanTimeout configuration, now you should configure scan_duration_t duration of startScan() to decide how long the scan process goes.

Hope this answer helps you well.

Thanks,

- Desmond, team Mbed

Hi Desmond,

Thanks so much for clarifying the purpose of the different parameters in the API. However i have a follow up question regarding the link describing the various valid values/range for these various parameters. For ex:

typedef Duration<uint16_t, 625, Range<0x04, 0xFFFF> > scan_interval_t The duration is in unit of 625µs and ranges from 0x04 to 0xFFFF.

so based on the definition above I can set the scan_interval_t any value between 4 to 65535 correct? The BLE API internally will translate it in terms of 625µs units or is it the other way around?

Thanks, Yogesh

posted by Yogesh k 06 Mar 2019

Hi Yogesh,

For legacy scanning, you can set the range from 0x04 to 0x4000.

For extended scanning, you can set the range from 0x04 to 0xFFFF.

Actually the BLE object doesn't translate the value by the units, it will pass the value to controller(link layer) via HCI command, controller do the translation.

Desmond

posted by Desmond Chen 07 Mar 2019

Hi Desmond,

I have been trying to figure out what translation means. Lets say I want to set a scan duration of 5 minutes, so that the scanning times out in 5 minutes. So since scan_duration_t is in units of 10ms, does that mean the value I would set for 5 minutes duration would be 300000 ms /10 ms = 30000. Is this correct or should I be calculating differently?

Thanks, Yogesh

posted by Yogesh k 11 Apr 2019

Hi Yogesh,

Your understanding of calculation is correct, however, the upper bound for scan duration is 655.35s, to be more clear, the time range is 10ms to 655.35s.

Please be aware of the type of duration is uint16_t which means the max value is 0xFFFF.

Desmond

posted by Desmond Chen 11 Apr 2019