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
NO_WIFI 1 Failed to join WiFi
NO_LINK 1 Failed to join Ethernet. From impOS™ 34. 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
SERVER_CONNECTED 5 The server is connected
NO_PROXY 6 The imp cannot connect via saved proxy address and port. From impOS 33
NOT_AUTHORISED 7 The imp cannot connect because its proxy access credentials have been rejected. From impOS 33
NOT_CONNECTED 0 The imp is not able to connect for some other reason

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

Only one callback can be ‘active’ 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.

For more information on when imps connect and when to make use of server.connect(), consult the imp WiFi state diagram and the Developer Guide ‘How to Run an Imp-enabled Device Offline’.

Release-specific Notes

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 33

From impOS release 33 onward, 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 release 30 onwards, 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 a code 4 (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 your 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.