Skip to main content

imp.net.setwifihints(BSSID, channel)

Set the imp’s preferred wireless router or access point’s BSSID, and WiFi channel

Availability

Device (from impOS™ 38)

Parameters

Name Type Description
BSSID String A router or access point’s BSSID as 12 hexadecimal characters
channel Integer The router or access point’s WiFi channel number

Returns

Nothing

Description

This method can be used to set the wireless network router or access point BSSID and WiFi channel (‘hints’) that the imp maintains to accelerate future re-connections to wireless networks.

When an imp connects to a wireless router or access point for the first time, it records both the network station’s BSSID and the WiFi channel on which the network is operating (1-13 for 2.4GHz, 36-165 for 5GHz). This saves the imp from having to scan for this data at every subsequent re-connect. If the router later changes channel, or the stored BSSID is not available on the imp’s target network when the imp attempts to re-connect, the imp will re-scan, and record the new BSSID and channel for future use.

The hints stored by the imp can updated manually using imp.net.setwifihints(): pass in the BSSID and channel number you would like the imp to record, or pass null as the first argument (channel will be ignored) to clear the record. Hints can also be cleared by calling the following code (but note that this will also clear the imp’s stored WiFi credentials):

imp.clearconfiguration(CONFIG_WIFI);

Only one pair of hints is stored at any one time; setting a pair of hints will overwrite any already stored.

Please note that not all channels are available for use in a given region: for example, only 2.4GHz channels 1—11 are permitted in the US, but in other parts of the world channels 12 and 13 are also available. Adding a hint for a channel which a given imp will not connect to (see imp.setcountry()) will add connection initiation latency as the imp will be forced to scan across the available channels. Equally, setting an incorrect BSSID will cause the imp to re-scan.

The imp’s currently stored hints can be retrieved using imp.net.getwifihints().

Module-specific Information

impC001

The impC001 does not currently implement imp.net.setwifihints().

Example Code

The following example checks the host imp’s hints to test whether it previously connected to a network in the 5GHz band. For this application, the 2.4GHz band (with its greater range) is preferred, so we set this manually using imp.net.setwifihints() and re-connect. The connection callback function, reconnect(), checks for a successful connection and schedules a further re-connection attempt if the server could not be reached.

Note A fuller implementation might do more to check that the stored BSSID is valid for 2.4GHz operation, or use imp.setwificonfiguration() to specify a specific 2.4GHz network, if known.