Skip to main content

imp.scanwifinetworks(callback)

Returns a list of WiFi networks detectable by the imp

Availability

Device (from impOS™ 27)

Parameters

Name Type Description
callback Function Optional single-parameter callback to be executed when the scan is complete (from impOS™ 36)

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.

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).

Module-specific Information

impC001

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

Release-specific Notes

impOS 36

From 36, 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).

impOS 34

From release 34, calling imp.scanwifinetworks() while on Ethernet (imp005) will cause the WiFi to be turned on for the duration of the scan. WiFi will automatically turned off when the scan is complete, unless other circumstances cause the it to stay on: for example, the Ethernet link is lost.

impOS 28

From release 28, if WiFi is turned off by Squirrel, for example by calling server.disconnect(), then imp.scanwifinetworks() causes WiFi to be briefly brought back up, the radio environment to be scanned and WiFi to be disabled once more. If there are any nearby networks, their details are returned.

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 (impOS 36 and up).