Skip to main content

imp.setwificonfiguration(ssid, key)

Sets an imp’s saved WiFi network access data

Availability

Device

Parameters

Name Type Description
ssid String The name of the network you want the imp to connect to
key String The network pre-shared key in plain text or an empty string ("") if there is no encryption

Returns

Nothing

Description

This method updates the WiFi network settings information stored in an imp’s non-volatile memory. The new settings will be used for all subsequent connections attempted by the device, including those taking place after a cold boot. You only need to supply the network’s password; the encryption type (WEP, WPA2, etc.) is determined automatically upon connection and is cached to make future connection attempts faster. For an open network (ie. one with no encryption), pass an empty string ("") for the password.

Settings applied using imp.setwificonfiguration() can be overwritten by a later BlinkUp™, and care should be taken reconfiguring devices in the field because there is no way to remotely recover a device with bad WiFi settings.

The currently-configured SSID can be read using imp.net.info(). For security reasons, the currently-configured password cannot be read.

Release Specific Notes

impOS 42

Connecting to a new WiFi network by calling server.connectwith() (introduced in impOS™ 42) and passing in a suitably configured WiFi Network Interface Configuration (NIC) will not cause the NIC’s SSID and password settings to be persisted. The only way to do so is to call imp.setwificonfiguration() separately:

local nic = { "interface"  : "wl0",
              "wificonfig" : { "ssid" : "fintlewoodlewix",
                             "key"  : "verybadpassw0rd!" }};
server.connectwith(nic, function(result, interfaceName) {
    if (result == SERVER_CONNECTED) {
        // Persist the WiFi config across future reboots
        imp.setwificonfiguration(nic.wificonfig.ssid, nic.wificonfig.key);
    }
});

Calling imp.setwificonfiguration() with different settings to those included in the current NIC will have no effect on the current connection or the NIC itself.

The currently-configured SSID can be read using either of the imp API methods imp.net.info() and imp.net.getcurrentconfig(). The currently-configured password is not available via imp.net.info(), but it can be read, in an encrypted form, using imp.net.getcurrentconfig(). This is to facilitate the storage and re-use of WiFi NICs via server.connectwith(). WiFi passwords are not available in plaintext.

Note An encrypted WiFi password retrieved using imp.net.getcurrentconfig() cannot be passed into imp.setwificonfiguration(), which takes a value in plain text.

Example Code

This example shows one way to disconnect from the current network (set via BlinkUp), change an imp’s WiFi credentials and reconnect to the new, hard-coded network.