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
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
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
SIM_ERROR 9 The imp cannot communicate with the modem’s SIM card. Cellular specific
NO_REGISTRATION 10 The imp could not detect a cellular network. Cellular specific
REGISTRATION_DENIED 11 The imp was not allowed to access the cellular network. Cellular specific
NO_PPP_CONNECTION 12 The imp could not establish a PPP connection. Cellular specific
PPP_NO_CONNECTIVITY 13 The imp could not establish an Internet connection. Cellular specific

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 41.16

On cellular imps, server.connect timeouts shorter than 120 seconds are silently rounded up to 120 seconds.

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.