lriot 2.1.0.0
Macros | Functions
lr1110_wifi.h File Reference

Wi-Fi passive scan driver definition for LR1110. More...

#include "transceiver/lr1110_regmem.h"
#include "transceiver/lr1110_wifi_types.h"
#include "common/lr1110_types.h"
#include "common/lr1110_hal.h"

Go to the source code of this file.

Macros

#define LR1110_WIFI_N_RESULTS_MAX_PER_CHUNK   LR1110_WIFI_MAX_RESULTS
 The number of results max to fetch per SPI communication with the chip.
 

Functions

err_t lr1110_wifi_scan (lriot_t *ctx, lr1110_wifi_signal_type_scan_t signal_type, lr1110_wifi_channel_mask_t channels, lr1110_wifi_mode_t scan_mode, uint8_t max_results, uint8_t nb_scan_per_channel, uint16_t timeout_in_ms, bool abort_on_timeout)
 Start a Wi-Fi passive scan operation.
 
err_t lr1110_wifi_search_country_code (lriot_t *ctx, lr1110_wifi_channel_mask_t channels_mask, uint8_t nb_max_results, uint8_t nb_scan_per_channel, uint16_t timeout_in_ms, bool abort_on_timeout)
 Start a Wi-Fi passive scan for country codes extraction.
 
err_t lr1110_wifi_scan_time_limit (lriot_t *ctx, lr1110_wifi_signal_type_scan_t signal_type, lr1110_wifi_channel_mask_t channels, lr1110_wifi_mode_t scan_mode, uint8_t max_results, uint16_t timeout_per_channel_ms, uint16_t timeout_per_scan_ms)
 Start a Wi-Fi passive scan operation with duration stop conditions.
 
err_t lr1110_wifi_search_country_code_time_limit (lriot_t *ctx, lr1110_wifi_channel_mask_t channels_mask, uint8_t nb_max_results, uint16_t timeout_per_channel_ms, uint16_t timeout_per_scan_ms)
 Start a Wi-Fi passive scan for country codes extraction with duration stop conditions.
 
err_t lr1110_wifi_get_nb_results (lriot_t *ctx, uint8_t *nb_results)
 Returns the number of results currently available in LR1110.
 
err_t lr1110_wifi_read_basic_complete_results (lriot_t *ctx, uint8_t start_result_index, uint8_t nb_results, lr1110_wifi_basic_complete_result_t *results)
 Read basic complete results.
 
err_t lr1110_wifi_read_basic_mac_type_channel_results (lriot_t *ctx, uint8_t start_result_index, uint8_t nb_results, lr1110_wifi_basic_mac_type_channel_result_t *results)
 Read basic MAC, Wi-Fi type and channel results.
 
err_t lr1110_wifi_read_extended_full_results (lriot_t *ctx, uint8_t start_result_index, uint8_t nb_results, lr1110_wifi_extended_full_result_t *results)
 Read extended complete results.
 
err_t lr1110_wifi_reset_cumulative_timing (lriot_t *ctx)
 Reset the internal counters of cumulative timing.
 
err_t lr1110_wifi_read_cumulative_timing (lriot_t *ctx, lr1110_wifi_cumulative_timings_t *timing)
 Read the internal counters of cumulative timing.
 
err_t lr1110_wifi_get_nb_country_code_results (lriot_t *ctx, uint8_t *nb_country_code_results)
 Get size of country code search results.
 
err_t lr1110_wifi_read_country_code_results (lriot_t *ctx, uint8_t start_result_index, uint8_t nb_country_results, lr1110_wifi_country_code_t *country_code_results)
 Read country code results.
 
err_t lr1110_wifi_cfg_timestamp_ap_phone (lriot_t *ctx, uint32_t timestamp_in_s)
 Configure the timestamp used to discriminate mobile access points from gateways.
 
err_t lr1110_wifi_read_version (lriot_t *ctx, lr1110_wifi_version_t *wifi_version)
 Get the internal wifi firmware version.
 
void lr1110_wifi_parse_channel_info (lr1110_wifi_channel_info_byte_t channel_info, uint8_t *channel, bool *rssi_validity, uint8_t *mac_origin_estimation)
 Retreive channel information from channel info byte.
 
uint8_t lr1110_wifi_extract_channel_from_info_byte (lr1110_wifi_channel_info_byte_t channel_info)
 Helper method to retrieve channel from channel info byte.
 
void lr1110_wifi_parse_frame_type_info (lr1110_wifi_frame_type_info_byte_t frame_type_info, uint8_t *frame_type, lr1110_wifi_frame_sub_type_t *frame_sub_type, bool *to_ds, bool *from_ds)
 Retrieve the Frame Type, Frame Subtype, To/From DS fields from a frame info byte.
 
void lr1110_wifi_parse_data_rate_info (lr1110_wifi_datarate_info_byte_t data_rate_info, uint8_t *wifi_signal_type, uint8_t *wifi_data_rate)
 Retrieve the data rate information from data rate info byte.
 
uint8_t lr1110_wifi_get_nb_results_max_per_chunk (void)
 Return the maximal number of results to read per SPI communication.
 
uint8_t lr1110_wifi_extract_signal_type_from_data_rate_info (lr1110_wifi_datarate_info_byte_t data_rate_info)
 Helper method to retrieve the signal type from data rate info byte.
 
bool lr1110_wifi_is_well_formed_utf8_byte_sequence (uint8_t *buffer, uint8_t length)
 Helper function to check if a buffer is a well-formed UTF-8 byte sequence.
 

Detailed Description

Wi-Fi passive scan driver definition for LR1110.

The Clear BSD License Copyright Semtech Corporation 2021. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted (subject to the limitations in the disclaimer below) provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of the Semtech corporation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SEMTECH CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Macro Definition Documentation

◆ LR1110_WIFI_N_RESULTS_MAX_PER_CHUNK

#define LR1110_WIFI_N_RESULTS_MAX_PER_CHUNK   LR1110_WIFI_MAX_RESULTS

The number of results max to fetch per SPI communication with the chip.

This macro is used by the internals of the driver to size the internal buffers of the driver used in the read results functions.

It can be defined externally at compile time, or just before including this file.

Its value can be programmatically obtained at runtime by calling lr1110_wifi_get_nb_results_max_per_chunk() function.

Its default value is set to the maximum number of results saved by LR1110 chip.

Warning
Its value must be in the range [1,32] (inclusive). Defining out of this range leads to undefined behavior.

Function Documentation

◆ lr1110_wifi_cfg_timestamp_ap_phone()

err_t lr1110_wifi_cfg_timestamp_ap_phone ( lriot_t * ctx,
uint32_t timestamp_in_s )

Configure the timestamp used to discriminate mobile access points from gateways.

This filtering is based on the hypothesis that mobile access points have timestamp shorter than gateways.

Parameters
[in]ctxChip implementation context
[in]timestamp_in_sTimestamp value in second
Returns
Operation status

◆ lr1110_wifi_extract_channel_from_info_byte()

uint8_t lr1110_wifi_extract_channel_from_info_byte ( lr1110_wifi_channel_info_byte_t channel_info)

Helper method to retrieve channel from channel info byte.

Parameters
[in]channel_infoThe chanel info byte from passive scan result
Returns
The channel of scanned MAC address
See also
lr1110_wifi_parse_channel_info

◆ lr1110_wifi_extract_signal_type_from_data_rate_info()

uint8_t lr1110_wifi_extract_signal_type_from_data_rate_info ( lr1110_wifi_datarate_info_byte_t data_rate_info)

Helper method to retrieve the signal type from data rate info byte.

Parameters
[in]data_rate_infoThe data rate info byte from a passive scan result
Returns
The Signal Type of the scanned frame

◆ lr1110_wifi_get_nb_country_code_results()

err_t lr1110_wifi_get_nb_country_code_results ( lriot_t * ctx,
uint8_t * nb_country_code_results )

Get size of country code search results.

Parameters
[in]ctxChip implementation context
[out]nb_country_code_resultsNumber of country results to read
Returns
Operation status

◆ lr1110_wifi_get_nb_results()

err_t lr1110_wifi_get_nb_results ( lriot_t * ctx,
uint8_t * nb_results )

Returns the number of results currently available in LR1110.

It can be called before lr1110_wifi_read_basic_complete_results or lr1110_wifi_read_basic_mac_type_channel_results to know the number of results.

Parameters
[in]ctxChip implementation context
[out]nb_resultsThe number of results available in the LR1110
Returns
Operation status
See also
lr1110_wifi_read_basic_complete_results, lr1110_wifi_read_basic_mac_type_channel_results

◆ lr1110_wifi_get_nb_results_max_per_chunk()

uint8_t lr1110_wifi_get_nb_results_max_per_chunk ( void )

Return the maximal number of results to read per SPI communication.

This function DOES NOT communicates with the LR1110. It returns the driver maximal number of Wi-Fi results it can retrieve per SPI communication.

Remarks
It is a driver limitation, not a LR1110 limitation, that avoid allocating temporary buffers of size too big when reading Wi-Fi passive scan results.
See also
LR1110_WIFI_N_RESULTS_MAX_PER_CHUNK
Returns
The maximal number of results to fetch per SPI calls

◆ lr1110_wifi_is_well_formed_utf8_byte_sequence()

bool lr1110_wifi_is_well_formed_utf8_byte_sequence ( uint8_t * buffer,
uint8_t length )

Helper function to check if a buffer is a well-formed UTF-8 byte sequence.

Parameters
[in]bufferThe buffer holding the bytes to be analyzed
[in]lengthThe number of bytes in the buffer
Returns
The result of the check

◆ lr1110_wifi_parse_channel_info()

void lr1110_wifi_parse_channel_info ( lr1110_wifi_channel_info_byte_t channel_info,
uint8_t * channel,
bool * rssi_validity,
uint8_t * mac_origin_estimation )

Retreive channel information from channel info byte.

This method is to be called with on the WiFi channel info byte of a scan result.

As the WiFi passive scan allows to get Access Point MAC address from Packet WiFi frames, it is possible that the frame does not comes from the Access Point, but from a device. In that case, the RSSI reported by LR1110 is the one of the frame received from the device and not from the Access Point. The rssi_validity flag allows to detect that case.

It is possible for an Access Point to be a mobile AP, which is of low interest for location purpose. The LR1110 tries to detect mobile AP based on Access Point up time and set the flag mac_origin_estimation accordingly.

Parameters
[in]channel_infoThe channel info byte to retrieve channel information from. It is obtained from WiFi passive scan result
[out]channelThe channel of the scanned mac address
[out]rssi_validityThe validity of the scanned MAC address
[out]mac_origin_estimationIndicates the estimation of MAC address origin by LR1110
See also
lr1110_wifi_read_basic_complete_results, lr1110_wifi_read_basic_mac_type_channel_results, lr1110_wifi_cfg_timestamp_ap_phone

◆ lr1110_wifi_parse_data_rate_info()

void lr1110_wifi_parse_data_rate_info ( lr1110_wifi_datarate_info_byte_t data_rate_info,
uint8_t * wifi_signal_type,
uint8_t * wifi_data_rate )

Retrieve the data rate information from data rate info byte.

This method is intended to be called on a data rate info byte of a passive scan result structure.

Parameters
[in]data_rate_infoThe data rate info byte from a passive scan result
[out]wifi_signal_typeThe wifi signal type of the scanned frame
[out]wifi_data_rateThe data rate of the scanned frame

◆ lr1110_wifi_parse_frame_type_info()

void lr1110_wifi_parse_frame_type_info ( lr1110_wifi_frame_type_info_byte_t frame_type_info,
uint8_t * frame_type,
lr1110_wifi_frame_sub_type_t * frame_sub_type,
bool * to_ds,
bool * from_ds )

Retrieve the Frame Type, Frame Subtype, To/From DS fields from a frame info byte.

This method is intended to be called on the channel info byte of a passive scan result structure.

The from_ds/to_ds (Distribution Station) fields have the following meaning:

to_ds value from_ds value Meaning
False False Frame was between two Stations
True False Frame was from Station to Access Point
False True Frame was sent from Access Point or Distribution Stations
True True Mesh network only, frame was between Stations
Parameters
[in]frame_type_infoThe frame info byte from passive scan result
[out]frame_typeThe Frame Type of the received frame
[out]frame_sub_typeThe Frame SubType of the frame received
[out]to_dsto_ds field of the frame received
[out]from_dsfrom_ds field of the frame received

◆ lr1110_wifi_read_basic_complete_results()

err_t lr1110_wifi_read_basic_complete_results ( lriot_t * ctx,
uint8_t start_result_index,
uint8_t nb_results,
lr1110_wifi_basic_complete_result_t * results )

Read basic complete results.

This function can be used to fetch all results in a row, or one after the other.

An example of usage to fetch all results in a row is:

uint8_t nb_results = 0;
lr1110_wifi_get_nb_results(&radio, &nb_results);
lr1110_wifi_basic_complete_result_t all_results[LR1110_WIFI_MAX_RESULTS] = {0};
lr1110_wifi_read_basic_complete_results(&radio, 0, nb_results, all_results);
lr1110_wifi_get_nb_results
err_t lr1110_wifi_get_nb_results(lriot_t *ctx, uint8_t *nb_results)
Returns the number of results currently available in LR1110.
lr1110_wifi_read_basic_complete_results
err_t lr1110_wifi_read_basic_complete_results(lriot_t *ctx, uint8_t start_result_index, uint8_t nb_results, lr1110_wifi_basic_complete_result_t *results)
Read basic complete results.
LR1110_WIFI_MAX_RESULTS
#define LR1110_WIFI_MAX_RESULTS
Definition lr1110_wifi_types.h:61
lr1110_wifi_basic_complete_result_s
Basic complete result structure.
Definition lr1110_wifi_types.h:305

On the other hand, fetching result one after the other:

uint8_t nb_results = 0;
lr1110_wifi_get_nb_results(&radio, &nb_results);
lr1110_wifi_basic_complete_result_t single_results = {0};
for(uint8_t index_result = 0; index_result < nb_results; index_result++){
lr1110_wifi_read_basic_complete_results(&radio, index_result, 1, &single_results);
// Do something with single_results
}
Remarks
: This result fetching function MUST be used only if the scan function call was made with Scan Mode set to LR1110_WIFI_SCAN_MODE_BEACON or LR1110_WIFI_SCAN_MODE_BEACON_AND_PKT.
Parameters
[in]radioRadio abstraction
[in]start_result_indexResult index from which starting to fetch the results
[in]nb_resultsNumber of results to fetch
[out]resultsPointer to an array of result structures to populate. It is up to the caller to ensure this array can hold at least nb_results elements.
Returns
Operation status

/see lr1110_wifi_read_basic_mac_type_channel_results, lr1110_wifi_read_extended_full_results

◆ lr1110_wifi_read_basic_mac_type_channel_results()

err_t lr1110_wifi_read_basic_mac_type_channel_results ( lriot_t * ctx,
uint8_t start_result_index,
uint8_t nb_results,
lr1110_wifi_basic_mac_type_channel_result_t * results )

Read basic MAC, Wi-Fi type and channel results.

This function can be used to fetch all results in a row, or one after the other.

An example of usage to fetch all results in a row is:

uint8_t nb_results = 0;
lr1110_wifi_get_nb_results(&radio, &nb_results);
lr1110_wifi_basic_mac_type_channel_result_t all_results[LR1110_WIFI_MAX_RESULTS] = {0};
lr1110_wifi_read_basic_mac_type_channel_results(&radio, 0, nb_results, all_results);
lr1110_wifi_read_basic_mac_type_channel_results
err_t lr1110_wifi_read_basic_mac_type_channel_results(lriot_t *ctx, uint8_t start_result_index, uint8_t nb_results, lr1110_wifi_basic_mac_type_channel_result_t *results)
Read basic MAC, Wi-Fi type and channel results.
lr1110_wifi_basic_mac_type_channel_result_s
Basic MAC, type, channel result structure.
Definition lr1110_wifi_types.h:321

On the other hand, fetching result one after the other:

uint8_t nb_results = 0;
lr1110_wifi_get_nb_results(&radio, &nb_results);
lr1110_wifi_basic_mac_type_channel_result_t single_results = {0};
for(uint8_t index_result = 0; index_result < nb_results; index_result++){
lr1110_wifi_read_basic_mac_type_channel_results(&radio, index_result, 1, &single_results);
// Do something with single_results
}
Remarks
: This result fetching function MUST be used only if the scan function call was made with Scan Mode set to LR1110_WIFI_SCAN_MODE_BEACON or LR1110_WIFI_SCAN_MODE_BEACON_AND_PKT.
Parameters
[in]radioRadio abstraction
[in]start_result_indexResult index from which starting to fetch the results
[in]nb_resultsNumber of results to fetch
[out]resultsPointer to an array of result structures to populate. It is up to the caller to ensure this array can hold at least nb_results elements.
Returns
Operation status

/see lr1110_wifi_read_basic_complete_results, lr1110_wifi_read_extended_full_results

◆ lr1110_wifi_read_country_code_results()

err_t lr1110_wifi_read_country_code_results ( lriot_t * ctx,
uint8_t start_result_index,
uint8_t nb_country_results,
lr1110_wifi_country_code_t * country_code_results )

Read country code results.

The total number of country code results to read is obtained from a previous call to lr1110_wifi_get_nb_country_code_results

Parameters
[in]ctxChip implementation context
[in]start_result_indexThe result index to start reading results from
[in]nb_country_resultsNumber of country code results to read
[out]country_code_resultsAn array of lr1110_wifi_country_code_t to be filled. It is up to the application to ensure this array is big enough to hold nb_country_results elements
Returns
Operation status
See also
lr1110_wifi_get_nb_country_code_results, lr1110_wifi_search_country_code

◆ lr1110_wifi_read_cumulative_timing()

err_t lr1110_wifi_read_cumulative_timing ( lriot_t * ctx,
lr1110_wifi_cumulative_timings_t * timing )

Read the internal counters of cumulative timing.

Parameters
[in]ctxChip implementation context
[out]timingA pointer to the cumulative timing structure to populate
Returns
Operation status

◆ lr1110_wifi_read_extended_full_results()

err_t lr1110_wifi_read_extended_full_results ( lriot_t * ctx,
uint8_t start_result_index,
uint8_t nb_results,
lr1110_wifi_extended_full_result_t * results )

Read extended complete results.

This function can be used to fetch all results in a row, or one after the other.

An example of usage to fetch all results in a row is:

uint8_t nb_results = 0;
lr1110_wifi_get_nb_results(&radio, &nb_results);
lr1110_wifi_extended_full_result_t all_results[LR1110_WIFI_MAX_RESULTS] = {0};
lr1110_wifi_read_extended_full_results(&radio, 0, nb_results, all_results);
lr1110_wifi_read_extended_full_results
err_t lr1110_wifi_read_extended_full_results(lriot_t *ctx, uint8_t start_result_index, uint8_t nb_results, lr1110_wifi_extended_full_result_t *results)
Read extended complete results.
lr1110_wifi_extended_full_result_t
Extended full result structure.
Definition lr1110_wifi_types.h:340

On the other hand, fetching result one after the other:

uint8_t nb_results = 0;
lr1110_wifi_get_nb_results(&radio, &nb_results);
lr1110_wifi_extended_full_result_t single_results = {0};
for(uint8_t index_result = 0; index_result < nb_results; index_result++){
lr1110_wifi_read_extended_full_results(&radio, index_result, 1, &single_results);
// Do something with single_results
}
Remarks
: This result fetching function MUST be used only if the scan function call was made with Scan Mode set to LR1110_WIFI_SCAN_MODE_FULL_BEACON.
Parameters
[in]ctxRadio abstraction
[in]start_result_indexResult index from which starting to fetch the results
[in]nb_resultsNumber of results to fetch
[out]resultsPointer to an array of result structures to populate. It is up to the caller to ensure this array can hold at least nb_results elements.
Returns
Operation status

/see lr1110_wifi_read_basic_complete_results, lr1110_wifi_read_basic_mac_type_channel_results

◆ lr1110_wifi_read_version()

err_t lr1110_wifi_read_version ( lriot_t * ctx,
lr1110_wifi_version_t * wifi_version )

Get the internal wifi firmware version.

Parameters
[in]ctxChip implementation context
[out]wifi_versionThe wifi version structure populated with version numbers
Returns
Operation status

◆ lr1110_wifi_reset_cumulative_timing()

err_t lr1110_wifi_reset_cumulative_timing ( lriot_t * ctx)

Reset the internal counters of cumulative timing.

Parameters
[in]ctxChip implementation context
Returns
Operation status

◆ lr1110_wifi_scan()

err_t lr1110_wifi_scan ( lriot_t * ctx,
lr1110_wifi_signal_type_scan_t signal_type,
lr1110_wifi_channel_mask_t channels,
lr1110_wifi_mode_t scan_mode,
uint8_t max_results,
uint8_t nb_scan_per_channel,
uint16_t timeout_in_ms,
bool abort_on_timeout )

Start a Wi-Fi passive scan operation.

During the complete passive scan operation, the LR1110 remains busy and cannot receive any commands. Using this command DOES reset the results already obtained by previous passive scan operations.

The result can be read at the end of the passive scan issuing the command lr1110_wifi_get_nb_results (to get the number of results to read) and lr1110_wifi_read_basic_complete_results or lr1110_wifi_read_basic_mac_type_channel_results to actually get the result bytes.

Parameters
[in]ctxChip implementation context
[in]signal_typeThe type of Wi-Fi Signals to scan for. If LR1110_WIFI_TYPE_SCAN_B_G_N is selected, the LR1110 already starts by scanning all selected channels for Wi-Fi signals B. Then the LR1110 scans all selected channels for Wi-Fi signals G/N.
[in]channelsMask of the Wi-Fi channels to scan
[in]scan_modeScan mode to execute
[in]max_resultsThe maximal number of results to gather. When this limit is reached, the passive scan automatically stop. Range of allowed values is [1:32]. Note that value 0 is forbidden.
[in]nb_scan_per_channelThe number of internal scan sequences per channel scanned. Range of accepted values is [1:255]. Note that value 0 is forbidden.
[in]timeout_in_msThe maximal duration of a single preamble search. Expressed in ms. Range of allowed values is [1:65535]. Note that value 0 is forbidden.
[in]abort_on_timeoutIf true, the beacon search jumps to next configured Wi-Fi channel (or stop if there is no more channel to scan) as soon as a search timeout is encountered
Returns
Operation status
See also
lr1110_wifi_read_basic_complete_results, lr1110_wifi_read_basic_mac_type_channel_results

◆ lr1110_wifi_scan_time_limit()

err_t lr1110_wifi_scan_time_limit ( lriot_t * ctx,
lr1110_wifi_signal_type_scan_t signal_type,
lr1110_wifi_channel_mask_t channels,
lr1110_wifi_mode_t scan_mode,
uint8_t max_results,
uint16_t timeout_per_channel_ms,
uint16_t timeout_per_scan_ms )

Start a Wi-Fi passive scan operation with duration stop conditions.

This passive scan API does not require the number of scan per channel, so that it searches for Wi-Fi signals until it finds one, or until the exhaustion of timeout_per_scan_ms or timeout_per_channel_ms.

The maximal duration of a scan is determined by the number of channels to scan times the timeout_per_channel_ms configured. However, this duration may be exceeded depending on the crystal drift of the clock source and on the instant the last Wi-Fi signal is detected by the device. Therefore the maximal duration of a Wi-Fi scan with this API is provided by the following equations:

For signal type being LR1110_WIFI_TYPE_SCAN_B, LR1110_WIFI_TYPE_SCAN_G or LR1110_WIFI_TYPE_SCAN_N:

$ T_{max} = N_{channel} \times ((1 + Xtal_{precision})timeout\_per\_channel + T_{offset} ) $

$ Xtal_{precision} $ depends on the crystal used as clock source. If the clock source is configured with 32kHz internal RC, then $ Xtal_{precision} = 1/100 $

$ T_{offset} $ depends on the $ signal\_type $ and the $scan\_mode$ selected:

  • LR1110_WIFI_TYPE_SCAN_B:
    • if $scan\_mode != LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$: 2.31 ms
    • if $scan\_mode == LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$: 9.59 ms
  • LR1110_WIFI_TYPE_SCAN_G:
    • if $scan\_mode != LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$: 52.55 ms
    • if $scan\_mode == LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$: N/A

For signal type being LR1110_WIFI_TYPE_SCAN_B_G_N:

$ T_{max} = 2 \times N_{channel} \times (1 + Xtal_{precision})timeout\_per\_channel + T_{offset} $

$ T_{offset} $ depends on the $scan\_mode$ selected:

  • $scan\_mode != LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$: 54.86 ms
  • $scan\_mode == LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$: 9.59 ms.
Note
With $scan\_mode != LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$ the T_offset is actually the worst case of Wi-Fi type B and Wi-Fi type G/N. Moreover, the Wi-Fi types G and N are scanned within the same steps (it is not two different scans). So the T_offset is the addition of 2.31 + 52.55 = 54.86.
With $scan\_mode == LR1110\_WIFI\_SCAN\_MODE\_FULL\_BEACON$, only Wi-Fi types B can be scanned. So scans for Wi-Fi types G/N are silently discarded. Therefore the T_offset is the same as for scan with Wi-Fi type B.
Parameters
[in]ctxChip implementation context
[in]signal_typeThe type of Wi-Fi Signals to scan for. If LR1110_WIFI_TYPE_SCAN_B_G_N is selected, the LR1110 already starts by scanning all selected channels for Wi-Fi signals B. Then the LR1110 scans all selected channels for Wi-Fi signals G/N.
[in]channelsMask of the Wi-Fi channels to scan
[in]scan_modeScan mode to execute
[in]max_resultsThe maximal number of results to gather. When this limit is reached, the passive scan automatically stop. Maximal value is 32
[in]timeout_per_channel_msThe time to spend scanning one channel. Expressed in ms. Value 0 is forbidden and will result in the raise of WIFI_SCAN_DONE interrupt, with stat1.command_status being set to LR1110_SYSTEM_CMD_STATUS_PERR
[in]timeout_per_scan_msThe maximal time to spend in preamble detection for each single scan. The time spent on preamble search is reset at each new preamble search. If the time spent on preamble search reach this timeout, the scan on the current channel stops and start on next channel. If set to 0, the command will keep listening until exhaustion of timeout_per_channel_ms or until nb_max_results is reached. Expressed in ms. Range of allowed values is [0:65535].
Returns
Operation status
See also
lr1110_wifi_read_basic_results, lr1110_wifi_read_extended_results

◆ lr1110_wifi_search_country_code()

err_t lr1110_wifi_search_country_code ( lriot_t * ctx,
lr1110_wifi_channel_mask_t channels_mask,
uint8_t nb_max_results,
uint8_t nb_scan_per_channel,
uint16_t timeout_in_ms,
bool abort_on_timeout )

Start a Wi-Fi passive scan for country codes extraction.

This command starts a Wi-Fi passive scan operation for Beacons and Probe Responses on Wi-Fi type B only. It is to be used to extract the Country Code fields.

During the passive scan, the results are filtered to keep only single MAC addresses.

Parameters
[in]ctxChip implementation context
[in]channels_maskMask of the Wi-Fi channels to scan
[in]nb_max_resultsThe maximum number of country code to gather. When this limit is reached, the passive scan automatically stops. Maximal value is 32
[in]nb_scan_per_channelMaximal number of scan attempts per channel. Maximal value is 255
[in]timeout_in_msThe maximal duration of a single beacon search. Expressed in ms. Maximal value is 65535 ms
[in]abort_on_timeoutIf true, the beacon search jumps to next configured Wi-Fi channel (or stop if there is no more channel to scan) as soon as a search timeout is encountered
Returns
Operation status

◆ lr1110_wifi_search_country_code_time_limit()

err_t lr1110_wifi_search_country_code_time_limit ( lriot_t * ctx,
lr1110_wifi_channel_mask_t channels_mask,
uint8_t nb_max_results,
uint16_t timeout_per_channel_ms,
uint16_t timeout_per_scan_ms )

Start a Wi-Fi passive scan for country codes extraction with duration stop conditions.

This command starts a Wi-Fi passive scan operation for Beacons and Probe Responses on Wi-Fi type B only. It is to be used to extract the Country Code fields. This passive scan API does not require the number of scan per channel, so that it searches for Wi-Fi signals until it finds one, or until the exhaustion of timeout_per_scan_ms or timeout_per_channel_ms.

The maximal duration of a scan is determined by the number of channels to scan times the timeout_per_channel_ms configured. However, this duration may be exceeded depending on the crystal drift of the clock source and on the instant the last Wi-Fi signal is detected by the device. Therefore the maximal duration of a Wi-Fi scan with this API is provided by the following equation:

$ T_{max} = N_{channel} \times ((1 + Xtal_{precision})timeout\_per\_channel + T_{offset} ) $

$ Xtal_{precision} $ depends on the crystal used as clock source. If the clock source is configured with 32kHz internal RC, then $ Xtal_{precision} = 1/100 $

$ T_{offset} $ is always the same: 9.59 ms.

Parameters
[in]ctxChip implementation context
[in]channels_maskMask of the Wi-Fi channels to scan
[in]nb_max_resultsThe maximum number of country code to gather. When this limit is reached, the passive scan automatically stops. Maximal value is 32
[in]timeout_per_channel_msThe time to spend scanning one channel. Expressed in ms. Value 0 is forbidden and will result in the raise of WIFI_SCAN_DONE interrupt, with stat1.command_status being set to LR1110_SYSTEM_CMD_STATUS_PERR
[in]timeout_per_scan_msThe maximal time to spend in preamble detection for each single scan. The time spent on preamble search is reset at each new preamble search. If the time spent on preamble search reach this timeout, the scan on the current channel stops and start on next channel. If set to 0, the command will keep listening until exhaustion of timeout_per_channel_ms or until nb_max_results is reached. Expressed in ms. Range of allowed values is [0:65535].
Returns
Operation status