Skip to main content

imp.scanwifinetworks(callback)

Returns a list of WiFi networks detectable by the imp

Availability

Device

Parameters

Name Type Description
callback Function Optional single-parameter callback to be executed when the scan is complete

Returns

Array — a list of nearby WiFi networks, each detailed in a table

Description

This method causes the imp to determine all the WiFi networks that are nearby and return the results of the scan as an array of tables, one for each nearby network, with the following keys:

Key Type Description
ssid string SSID (network name)
bssid string BSSID (access point’s MAC address), in 0123456789ab format
channel integer Channel number: 1-13 (2.4GHz), 36-165 (5GHz)
rssi integer RSSI (signal strength), ranging from about -95 for a network on the limit, to -11 for a super-strong one
open bool Whether the network is open (password-free)

If no networks are available, an empty array is returned.

imp.scanwifinetworks() can operate asynchronously: pass a callback into the method and it will be executed when the scan is complete. The callback must have one parameter into which the array of network records is passed. If no networks have been detected, the array is an empty one.

If you initiate a second scan while the first is being run, Squirrel will issue the following error: "scan already running in imp.scanwifinetworks(callback)".

If WiFi is turned off mid-scan, then the scan is aborted and any networks that have been found thus are returned via the callback function or return value as appropriate.

If the imp is attempting to connect to a router using WPS when imp.scanwifinetworks() is called asynchronously, the callback will be executed immediately and be passed an empty array (ie. indicate there are no nearby WiFi networks).

Note If the imp is attempting to connect to a router using WPS when imp.scanwifinetworks() is called, this method will immediately return an empty array (ie. indicate there are no nearby WiFi networks).

Release-specific Information

impOS 42

If imp.net.open(), a method introduced in impOS 42, is called to command the imp to connect to a WiFi network while imp.scanwifinetworks() is already conducting an asynchronous scan (see above), the outcome will depend on whether or not the imp is currently connected to the server via WiFi.

If the imp is not connected to WiFi, the WiFi scan callback will be triggered immediately and any partial scan results will be passed into it. This is because the imp must attempt to join a network, and this implicitly terminates any in-progress scan.

However, if the imp is already connected to WiFi, then the WiFi scan is not interrupted — there is no join operation — and the scan callback will be triggered at the end of the full scan.

Module-specific Information

impC001

The impC001 does not currently implement imp.scanwifinetworks().

Example Code

This code uses imp.scanwifinetworks() synchronously to log details of all the wireless networks in the imp’s vicinity.

This code snippet shows imp.scanwifinetworks() used in asynchronous mode.