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. If the connection is not restored within 60 seconds, the callback function registered using server.onunexpecteddisconnect() is 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 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
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.

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