Attempts to establish a connection between the imp and the server
Device
| 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
|
Nothing
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.
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().
On cellular imps, server.connect timeouts shorter than 120 seconds are silently rounded up to 120 seconds.
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.
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.