Skip to main content

server.connect(callback, timeout)

Attempts to establish a connection between the imp and the server

Availability

Device

Parameters

Name Type Description
callback Function Function to be called when a connection has been made or failed. Ignored when SUSPEND_ON_ERROR is in effect
timeout Integer Optional time in seconds to wait for a connection to be made (default = 60). Ignored when SUSPEND_ON_ERROR is in effect

Returns

Nothing

Description

This method attempts to initiate a connection to the server. Depending on the current timeout policy, it will behave in one of two ways:

If the SUSPEND_ON_ERROR policy is in effect, the connection proceeds synchronously. You should not supply a callback function or a timeout value. This is the default setting.

If the RETURN_ON_ERROR policy is in effect, the connection proceeds asynchronously. The function passed into the callback parameter will be executed when a connection is completed or if an error occurs. Whatever the outcome, one of the following constants will be passed to the callback’s single parameter, reason:

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.

Only one callback can be registered at any one time. If server.connect() is called a second time, before the first callback to be registered has been executed, then the function nominated in the second call will be executed when the server responds, not the first. Whichever attempt to connect succeeds or times out first, it will be the second callback that is triggered.

If the device is already connected when server.connect() is called, the callback will not be executed.

Release-specific Notes

impOS 42

Under impOS 42 and up, server.connect() will connect using the current interface. The current interface is selected according to which network management mode the imp is operating under. In legacy mode, the current interface is chosen by impOS according to a default list of interfaces; in automatic mode, the default list of interfaces has been superseded by one set by the application. In manual mode, the current interface is set by calling server.connectwith().

impOS 40

Callback connection state codes now include cellular-specific events.

impOS 36

impOS 36 adds the method imp.net.configurewps(), which instructs the imp to make its next connection attempt begin with a WiFi Protected Setup (WPS) request to a nearby router for its network access credentials. In such circumstances, when server.connect() is called, the timeout applied (either as a method parameter or the default value) will be ignored, and the connection may take up to two minutes to complete (or fail).

impOS 34

From impOS 34 and up, imps may be set to connect through a proxy server, specified using imp.setproxy(). Proxy connections may result in two new reason codes: NO_PROXY and NOT_AUTHORISED. The former is returned when the saved proxy address and/or port are incorrect, the latter when the access credentials the device submits are rejected — the proxy returns a 4xx status code.

impOS 30

From impOS 30 and up, the timeout parameter is optional, defaulting to a period of 60 seconds if no value is specified. Code running on impOS releases before 30 must include a timeout value.

The constant NOT_CONNECTED is provided from impOS release 30 onward; in previous releases, such an error would simply be returned as zero.

Known Issues

If server.connect() returns NO_SERVER to indicate an error, this same code may be repeated if subsequent connection attempts fail, even if they fail for a different reason. This issue is scheduled to be addressed in a future impOS release.

Example Code

The following two example shows you how to change an imp001’s WiFi credentials and then immediately disconnect from the current network and reconnect to a new network. In the first block, we do not change the timeout policy so server.connect() is synchronous and should not be called with a callback and timeout. However, if RETURN_ON_ERROR is in effect, and a device is already connected to the server when the server.connect() call is made, the callback will not be executed. The connect() function in this second block will always execute the callback. If the device is already connected, it will be treated as though it just connected.

The following snippet provides a way to deal with multiple proximate calls to server.connect(). Only one callback is registered; if two calls to server.connect() are made that register different callbacks, the second registration will replace the first, which will never be called. The code provides a mechanism to ensure that the operations embedded in each callback function are still performed. The scenario is that two sensor readings may exceed threshold values that warrant a connection to the server to, say, log the fact. If the triggers occur close together, the second may overwrite the server.connect() of the first. However, the outcome of the first attempt to connect still needs to be managed.