Skip to main content

server.onunexpecteddisconnect(callback)

Registers a function to be called if the imp unexpectedly disconnects from the server

Availability

Device

Parameters

Name Type Description
callback Function A function to be called whenever the imp unexpectedly disconnects from the server

Returns

Nothing

Description

This method nominates a function to be called if the device is unexpectedly disconnected from the server, but only if the imp has been set to a timeout policy of RETURN_ON_ERROR. If the SUSPEND_ON_ERROR timeout policy is in force, the callback will not be executed when the imp unexpectedly disconnects from the server.

Upon a loss of connectivity, impOS™ immediately attempts to reconnect. Only if the connection is not restored within 60 seconds, is the callback function registered using server.onunexpecteddisconnect() triggered. If the connection is restored within this timeout period, the callback function is not executed. This procedure is followed to ensure that only true outages, not, for example, momentary dips in WiFi signal, trigger the callback.

The function passed into the callback parameter should include a single parameter of its own: reason. This will be passed an integer specifying the reason for the disconnection, whether known or not. The value will be one of the following constants:

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
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.

The callback can be used to perform state-related operations, such as lighting an LED to warn the end-user that the device is not connected. Under the RETURN_ON_ERROR policy, it is up to your application to re-establish a connection to the server. This is typically performed within the callback and actioned by calling server.connect() either immediately or after a short interval appropriate to the application.

Because the callbacks registered with server.connect() and server.onunexpecteddisconnect() take a single integer reason as a parameter, it is commonplace (but not mandatory) to use these methods to register the same callback function, as the example below shows.

Known Issue

In certain rare circumstances, the function registered with server.onunexpecteddisconnect() may be called twice. For example, if the imp is connected to a WiFi access point that communicates with a router via Ethernet, and the connection between the access point and router is lost, the loss of Internet access will trigger the server.onunexpecteddisconnect()-registered function as described above. However, because is still connected by WiFi, it will attempt to reconnect and when this fails, the server.onunexpecteddisconnect()-registered function will be called again.

One workaround is to set a flag on the first pass through the disconnection handler according to the reason supplied. If the handler is shortly called again with with the same reason and the flag is set, the handler can simply return. Using the example above, we might use:

function disconnectionHandler(reason) {
    // Called if the server connection is broken or re-established, initially by impOS' unexpected disconnect
    // code and then repeatedly by server.connect(), below, as it periodically attempts to reconnect
    if (reason == NO_IP_ADDRESS) {
        if (noIPAddressFlag) return;
        noIPAddressFlag = true;
    }

    if (reason != SERVER_CONNECTED) {
        isConnected = false;

        // Schedule an attempt to re-connect in 'reconnectDelay' seconds
        imp.wakeup(60, function() {
            server.connect(disconnectionHandler, 30);
        });
    } else {
        // The imp is back online - reset state data
        isConnected = true;
        noIPAddressFlag = false;
    }
}

Example Code

This example will turn on an LED when your device disconnects from the server. When the connection loss is detected, the LED comes on.

This example demonstrates how you can use RETURN_ON_ERROR with a server.onexpecteddisconnect() callback to cycle through a list of known connections and attempt to connect to each one of them until you find one that works.