Skip to main content

server.connectwith(nic, callback, timeout)

Attempt to connect to the impCloud using a specified network interface

Availability

Device (from impOS™ 42)

Parameters

Name Type Description
nic Table Settings for the network interface to be used to connect
callback Function A function to be called when the connection attempt succeeds or fails
timeout Integer An optional timeout in seconds for the connection attempt. Default: 60s

Returns

Nothing

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 connect the imp to the Electric Imp impCloud™ using a specific imp Network Interface Configuration (NIC) which is passed into the method’s first parameter. A NIC 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. "wifi", "wl0", "ethernet", "eth0", "cell1"
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
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 ("")
ssid String Yes The name of the wireless network

server.connectwith() is only available if you have selected the RETURN_ON_ERROR or RETURN_ON_ERROR_NO_DISCONNECT reconnection policies, as applied using server.setsendtimeoutpolicy(). Calling server.connectwith() while the SUSPEND_ON_ERROR policy is in force — the default policy at start-up — will cause an exception to be thrown.

For example:

local nic = { "interface"  : "wl0",
              "wificonfig" : { "ssid" : "fintlewoodlewix",
                               "key"  : "verybadpassw0rd!" }
};

server.connectwith(nic, function(result, interfaceName) {
    if (result == SERVER_CONNECTED) {
        server.log("Connected to impCloud via interface " + interfaceName);
    } else {
        server.error("Could not connect to impCloud via interface " + interfaceName);
    }
});

If you call server.connectwith() on interface B, while there is an existing impCloud server connection on interface A, the imp will immediately disconnect from interface and power it down. It will then attempt to connect with interface B. Interface A will have to be opened again if it is to be re-used, eg. for local networking.

Calling server.connectwith() and providing a NIC that defines a WiFi network will not cause that network’s SSID and password to be recorded in the imp’s persistent storage. If the imp subsequently reboots (eg. after deep sleep or a power-cycle), the current WiFi network will be set to whichever network is recorded in persistent storage and will be used in any attempt to connect automatically, eg. by calling agent.send(), server.connect() or server.log(). To ensure the network activated via server.connectwith() is used in these circumstances, call imp.setwificonfiguration() to store its SSID and password in persistent storage.

The Callback

Once called, server.connectwith() will attempt to connect to the server using the supplied settings. It does not block. Whether it succeeds, fails or the timeout period is exceeded, the function passed into the method’s callback parameter will be executed. This function should have two parameters of its own: result and interfaceIdentifier. The latter is the interface’s identifier string (set in the NIC, above). The result parameter receives an integer status code. It can take any of the following standard (as per server.connect()) outcome values:

Constant Value Description
SERVER_CONNECTED 5 The server is connected
NOT_CONNECTED 0 The imp is not able to connect for a reason other than those listed below
NO_WIFI 1 Failed to join WiFi
NO_LINK 1 Failed to connect via Ethernet. imp005 only. From impOS™ 34
NO_IP_ADDRESS 2 Failed to get an IP address
NOT_RESOLVED 3 The IP address of an Electric Imp server or proxy could not be resolved
NO_SERVER 4 Failed to connect to the Electric Imp server
NO_PROXY 6 The imp cannot connect via saved proxy address and port. From impOS 34
NOT_AUTHORISED 7 The imp cannot connect because its proxy access credentials have been rejected. From impOS 34
NO_MODEM 8 The imp cannot detect a modem. Cellular specific. From impOS 40
SIM_ERROR 9 The imp cannot communicate with the modem’s SIM card. Cellular specific. From impOS 40
NO_REGISTRATION 10 The imp could not detect a cellular network. Cellular specific. From impOS 40
REGISTRATION_DENIED 11 The imp was not allowed to access the cellular network. Cellular specific. From impOS 40
NO_PPP_CONNECTION 12 The imp could not establish a PPP connection. Cellular specific. From impOS 40
PPP_NO_CONNECTIVITY 13 The imp could not establish an Internet connection. Cellular specific. From impOS 40

The values assigned to the constants may change in a future impOS release.

Your code should always check the value of result before proceeding.

Re-using Interface Tables

If the connection made with server.connectwith() was successful, the NIC can be retrieved using imp.net.getcurrentconfig(). The NIC can then be saved to persistent storage for future server connection attempts using server.connectwith(). You should use the NIC returned by imp.net.getcurrentconfig() in preference to the NIC used to initiate the connection (as in the example, above) because impOS encrypts sensitive data, such as a supplied WiFi password or proxy password. The NIC returned by imp.net.getcurrentconfig() includes the encrypted forms of these values, if present.