imp.net.open(nic, callback)

Description

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 required interface is indicated using a Network Interface Configuration (NIC), which is a table containing one or more of the following keys. The first key, interface, is mandatory; the others are optional:

Key	Data Type	Required?	Description
interface	String	Yes	An identifier for the interface through which to attempt the connection, eg. "wl0", "eth0", "cell0"
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 requested NIC, 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 the interface object that is returned by imp.net.open(). This object represents the opened interface and may be used to initiate a local connection. Currently, only UDP connections are 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 opened interface’s current state.

Network Configuration Persistence

If you provide extended configuration information in a call to imp.net.open(), ie. you include any of the ...config keys, impOS will not retain this information in persistent storage. If the connection attempt fails, or if the attempt to connect is successful but the connection is subsequently lost for any reason at all, including Squirrel virtual machine restarts, device power-cycles, and manually initiated or unexpected disconnections, then the supplied configuration will be discarded and will not be used by impOS in any further connection attempts. This is also the case if the interface object returned by imp.net.open() goes out of scope.

Additionally, any attempt to connect using server.connect() that is made while the imp is still processing the imp.net.open() call (which takes place asynchronously) will cause the extended NIC to be discarded and whichever configuration has been written to persistent storage, eg. by BlinkUp™ or calls to the imp API methods imp.setwificonfiguration(), imp.setstaticnetworkconfiguration() or imp.setproxy(), to be used in its place for both the connection to the server and to the local network.

If, however, you call imp.net.open() and simply name an interface in your NIC, eg. {"interface" : "wl0"}, then impOS will use that interface for all future connections, or until an alternative interface is specified. Interfaces that required extra information to connect — for example, WiFi connections may require an SSID and password to be supplied — will make use of persisted configuration data in this instance. If there is no relevant configuration data available, the connection attempt will fail immediately and report the imp.net.WIFI_STOPPED state.

You should also note that the interface represented by an interface object only stays open while the object exists. If an interface object goes out of scope, then the interface it represents will be closed and subsequent attempts to make use of it will fail. This is the case however you configure the interface’s NIC.

To close an interface at any time, you can therefore simply set the reference to null:

wifi <- imp.net.open({"interface": "wl0"}, function(state) {
    if (state == imp.net.CONNECTED) {
        // Network up -- broadcast info
        local udpsocket = wifi.openudp(null, 1234);
        udpsocket.send("255.255.255.255", 1234, "Broadcast Data");
        udpsocket.close();

        // Close the interface
        wifi = null;
    }
});

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" }};

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;
local wifi = imp.net.open(wifiSettingsMin, wifiCallback);