Skip to main content

imp.net.open(nic, callback)

Attempt to bring up a generic local network connection

Availability

Device (from impOS™ 42)

Parameters

Name Type Description
nic String A standard Network Interface Configuration table
callback Function An optional function to receive connection-state change notifications

Returns

An interface object

Description

This is draft documentation which covers impOS™ functionality that, though currently in internal development, has been made available to a number of customers for testing purposes only. Both the functionality described here and the documentation itself are subject to change, including breaking changes, and may differ significantly from their final release versions.


This method attempts to open a connection through the specified network interface. This is not a connection to the Electric Imp impCloud™ (ie. the agent server), but out to the local network: for example, using UDP.

The interface is indicated using a Network Interface Configuration (NIC), which is a table containing one or more of the following keys, the first of which is mandatory:

Key Data Type Required? Description
interface String Yes An identifier for the interface through which to attempt the connection, eg. "wl0", "eth0"
proxyconfig Table No Optional proxy server configuration. Not applicable to cellular connections, only Ethernet and WiFi. For a list of accepted keys, please see imp.setproxy()
staticconfig Table No Optional static network configuration. Not applicable to cellular connections, only Ethernet and WiFi. For a list of accepted keys, please see imp.setstaticnetworkconfiguration()
wificonfig Table No Optional WiFi configuration. Not applicable to ethernet or cellular connections, only WiFi. The keys are listed below

The keys used in the wificonfig table are:

Key Data Type Required? Description
ssid String Yes The name of the wireless network
key String or blob Yes The key for the wireless network (if any). Plain text keys are passed as strings; encrypted keys are blobs. In the case of an open network, pass in null or an empty string ("")

In addition to the chosen interface, you may provide imp.net.open() with a callback function which will be executed whenever there is a change in the state of the connection. This function has one parameter of its own: state, which receives an integer code indicating the current state of the connection. The value passed into state may be one of the following:

impOS Constant Value Network Interface State
imp.net.UNKNOWN -1 Idle/unknown
imp.net.STARTING 0 Starting
imp.net.CONNECTED 1 Connected
imp.net.WIFI_SCANNING 100 WiFi scanning
imp.net.WIFI_JOINING 101 WiFi joining
imp.net.WIFI_WPSING 102 WiFi WPS in progress
imp.net.WIFI_LINK_UP 103 WiFi link up
imp.net.WIFI_DHCPING 104 WiFi getting IP address via DHCP
imp.net.WIFI_STOPPED 105 WiFi stopped
imp.net.WIFI_STOPPED_UNHAPPY 106 WiFi sub-system unhappy
imp.net.ETHERNET_LINK_UP 200 Ethernet link up
imp.net.ETHERNET_DHCPING 201 Ethernet getting IP address via DHCP
imp.net.ETHERNET_STOPPED 202 Ethernet stopped
imp.net.ETHERNET_STOPPED_UNHAPPY 203 Ethernet sub-system unhappy
imp.net.ETHERNET_STOPPED_NO_LINK 204 Ethernet stopped: No link
imp.net.CELLULAR_PINGING 300 Cellular contacting modem
imp.net.CELLULAR_WAITING_FOR_SIM 301 Cellular waiting for SIM
imp.net.CELLULAR_PPP_CONNECTING 302 Cellular connecting via PPP
imp.net.CELLULAR_REGISTERING 303 Cellular registering with network
imp.net.CELLULAR_REGISTRATION_DENIED 304 Cellular network registration request denied
imp.net.CELLULAR_STOPPED 305 Cellular stopped
imp.net.CELLULAR_STOPPED_UNHAPPY 306 Cellular modem unhappy

Electric Imp reserves the right to alter the value of these constants in future impOS releases.

The value passed into state can also be retrieved by calling getstate() on an interface object returned by imp.net.open(). This object represents the open interface and can be used to initiate a local connection. Currently, only UDP is supported: call the interface object’s openudp() method.

Note If you do not include a callback in the imp.net.open() call, then interface.getstate() is the only way to determine the interface’s current state.

Known Issue

Currently, imp.net.open() will reject any NIC containing proxyconfig, staticconfig and/or wificonfig keys when it addresses an interface which is already in use — even if it exactly matches the NIC that is in use. Until this issue is addressed, please include NICs with only an interface key when re-calling imp.net.open().

For example, the following code will currently fail with ERROR: cannot reconfigure interface when active in net.open(interface[, callback]):

local wifiSettings = { "interface"  : "wl0",
                       "wificonfig" : { "ssid" : "Network",
                                        "key" : "Password" }};

server.setsendtimeoutpolicy(RETURN_ON_ERROR, WAIT_FOR_ACK);
server.connectwith(wifiSettings);
local wifi = imp.net.open(wifiSettings, wifiCallback);

To remedy this, apply the NICs as follows:

local wifiSettingsMain = { "interface"  : "wl0",
                           "wificonfig" : { "ssid" : "Network",
                                            "key" : "Password" }};
local wifiSettingsMin = clone wifiSettingsMain;
delete wifiSettingsMin.wificonfig;

server.setsendtimeoutpolicy(RETURN_ON_ERROR, WAIT_FOR_ACK);
server.connectwith(wifiSettingsMain);
local wifi = imp.net.open(wifiSettingsMin, wifiCallback);