Latest Version: 3.1.1
The ConnectionManager class is an Electric Imp device-side library created to simplify connect and disconnect flows.
Note If you are using ConnectionManager in your code, you should ensure that you never call server.connect() or server.disconnect(). Instead you should only use ConnectionManager’s connect() and disconnect() methods.
You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.
To include this library in your project, add
#require "ConnectionManager.lib.nut:3.1.1"
at the top of your device code.
ConnectionManager can be instantiated with an optional table of settings that modify its behavior. The following settings are available:
| Key | Required? | Description |
|---|---|---|
| startBehavior | No | See below. Default: CM_START_NO_ACTION |
| stayConnected | No | When set to true, the device will aggressively attempt to reconnect when disconnected. Default: false |
| retryOnTimeout | No | When set to true, the device will attempt to connect again if it times out. Default: true |
| blinkupBehavior | No | See below. Default: CM_BLINK_ON_DISCONNECT |
| checkTimeout | No | Changes how often the ConnectionManager checks the connection state (online/offline. Default: 5 |
| connectTimeout | No | Maximum time (in seconds) allowed for the imp to connect to the server before timing out. Default: 60.0 |
| errorPolicy | No | The disconnection handling policy: SUSPEND_ON_ERROR, RETURN_ON_ERROR or RETURN_ON_ERROR_NO_DISCONNECT. Default: RETURN_ON_ERROR |
| waitPolicy | No | The successful transmission criterion: either WAIT_TIL_SENT or WAIT_FOR_ACK. Default: WAIT_TIL_SENT |
| ackTimeout | No | The maximum time (in seconds) allowed for the server to acknowledge receipt of data. Default: 1.0 |
#require "ConnectionManager.lib.nut:3.1.1"
// Instantiate ConnectionManager so BlinkUp is always enabled,
// and we automatically aggressively try to reconnect on disconnect
cm <- ConnectionManager({ "blinkupBehavior": CM_BLINK_ALWAYS,
"stayConnected" : true });
// Set the recommended buffer size (see note below)
imp.setsendbuffersize(8096);
Note We’ve found setting the buffer size to 8096 to be very helpful in many applications using ConnectionManager, though your application may require a different buffer size.
The startBehavior flag modifies what action ConnectionManager takes when initialized:
The blinkupBehavior flag modifies when ConnectionManager enables the BlinkUp™ circuit (using imp.enableblinkup():
Note impOS™ 40 and under always enables the BlinkUp circuit for the first 60 seconds after a cold boot to ensure the imp never enters an unrecoverable state. As a result, regardless of what blinkupBehavior flag is set, the imp will enable the BlinkUp circuit for 60 seconds after a cold boot.
Important impOS 42 changes this behavior: BlinkUp is disabled as soon as impOS is asked to do so, even within the initial 60-second period. If your code disables BlinkUp early, end-users may have as little as ten seconds to perform BlinkUp. Please see the imp.enableblinkup() documentation for more guidance.
This value is passed into the imp API method server.setsendtimeoutpolicy(), overriding any value your code may have already set in a separate call to that method (or overridden by a subsequent call your code makes). We recommend that if you make use of ConnectionManager, you ensure that you never call server.setsendtimeoutpolicy() in your application code.
This method can be used to change the class’ BlinkUp behavior.
Nothing.
// Set ConnectionManager to enable BlinkUp only while it's connected
cm.setBlinkUpBehavior(CM_BLINK_ON_CONNECT);
This method can be used to determine the value of ConnectionManager’s internal connection state flag (ie. whether or not the imp is connected). This flag is updated every five seconds, or as set by the checkTimeout setting in the constructor.
Boolean — true if the device is connected, otherwise false.
if (!cm.isConnected()) {
// If we're not connected, gather some data, then connect
cm.onNextConnect(function() {
local data = sensor.read();
agent.send("data", data);
}).connect();
}
This method assigns a callback function to the onDisconnect event. The onDisconnect event will fire every time the connection state changes from online to offline, or when ConnectionManager’s disconnect() method is called (even if the device is already disconnected).
ConnectionManager allows multiple onDisconnect callbacks to be registered. Each of the callbacks should have a unique string identifier passed into the second parameter, callbackID. If the callbackID parameter’s argument is not specified, a default value is used ("DEFAULT_CB_ID"). Calling onDisconnect() multiple times with the same or no callbackID overwrites the previously set callback.
Pass null into callback to clear the onDisconnect callback for the specified (or the default) callback ID.
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| callback | Function | Yes | Called when ConnectionManager’s connection state changes from online to offline. See below for details |
| callbackID | String | No | Optional identifier |
The callback function has a single parameter, expected, which is true when the onDisconnect event fired due to disconnect() being called, and false otherwise (an unexpected state change from connected to disconnected).
Nothing.
cm.onDisconnect(function(expected) {
if (expected) {
// Log a regular message that we disconnected as expected
cm.log("Expected Disconnect");
} else {
// Log an error message that we unexpectedly disconnected
cm.error("Unexpected Disconnect");
}
});
This method assigns a callback function to the onConnect event. The onConnect event will fire every time the connection state changes from offline to online, or when ConnectionManager’s connect() method is called (even if the device is already connected).
ConnectionManager allows multiple onConnect callbacks to be registered. Each of the callbacks should have a unique string identifier passed into the second parameter, callbackID. If the callbackID parameter’s argument is not specified, a default value is used ("DEFAULT_CB_ID"). Calling onConnect() multiple times with the same or no callbackId overwrites the previously set callback.
Pass null into callback to clear the onConnect callback for the specified (or the default) callback ID.
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| callback | Function | Yes | Called when ConnectionManager’s connection state changes from offline to online. The callback function has no parameters |
| callbackID | String | No | Optional identifier |
Nothing.
cm.onConnect(function() {
// Send a message to the agent indicating that we're online
agent.send("online", true);
});
This method assigns a callback function to the onTimeout event. The onTimeout event will fire every time the device attempts to connect but does not succeed.
ConnectionManager allows multiple onTimeout callbacks to be registered. Each of the callbacks should have a unique string identifier passed into the second parameter, callbackID. If the callbackID parameter’s argument is not specified, a default value is used ("DEFAULT_CB_ID"). Calling onTimeout() multiple times with the same or no callbackID overwrites the previously set callback.
Pass null into callback to clear the onTimeout callback for the specified (or the default) callback ID.
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| callback | Function | Yes | Called when the device attempts to connect but fails to do so. The callback function has no parameters |
| callbackID | String | No | Optional identifier |
Nothing.
cm.onTimeout(function() {
// Go to sleep for 10 minutes if the device fails to connect
server.sleepfor(600);
});
This method queues a function to run the next time the device connects for whatever reason. If the device is already connected, the callback will be invoked immediately. There is no limit on the number of tasks that can be queued (excluding any memory or time restraints your application may have).
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| callback | Function | Yes | Called when the device next connects, or is connected already. The callback function has no parameters |
Nothing.
function poll() {
// Wake up every 60 seconds and gather data
imp.wakeup(60, poll);
// Read the data, and insert the timestamp into the data table
// (in this example, we assume sensor.read() returns a table)
local data = sensor.read();
data.ts <- time();
// Send the data the next time we connect
cm.onNextConnect(function() {
agent.send("data", data);
});
}
Note If the imp enters a deep sleep or performs a cold boot, the task queue will be cleared.
This method tells the device to connect, run the supplied callback function, and then disconnect when complete. If the device is already connected, the callback will be invoked immediately, and the device will disconnect upon completion.
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| callback | Function | Yes | Called when the device has connected, or is connected already. The callback function has no parameters |
Nothing.
function poll() {
// Wake up every 60 seconds, connect, send data and disconnect
imp.wakeup(60, poll);
cm.connectFor(function() {
// Read and send the data
local data = sensor.read();
data.ts <- time();
agent.send("data", data);
});
}
Note The connectFor() method is equivalent to:
cm.onNextConnect(function() {
// Do something
...
cm.disconnect();
}).connect();
This method tells ConnectionManager to attempt to connect to the server. If it successfully connects (or is already connected), ConnectionManager will execute any registered onConnect callback, perform any tasks queued from onNextConnect, and log all offline log messages (from log() and error()).
If a connection attempt is already in process, connect() will not attempt to connect or invoke any callbacks.
Boolean — true if ConnectionManager is now attempting to connect, or false if a connection attempt is already in process.
cm.connect();
This method tells ConnectionManager to attempt to disconnect from the server. If it successfully disconnects (or is already disconnected), the ConnectionManager will execute the registered onDisconnect callback, if there is one.
If a connection attempt is in process, disconnect() will not attempt to disconnect or invoke any callbacks.
| Parameter | Data Type | Required | Description |
|---|---|---|---|
| force | Boolean | No | Force ConnectionManager to disconnect regardless of the connection status (ie. whether it’s in progress or not). Default: false |
| flushTimeout | Integer or float | No | The timeout value used for server.flush() calls. If set to -1, no flush is performed. Default: CM_FLUSH_TIMEOUT (30 seconds) |
Boolean — true if ConnectionManager is now attempting to disconnect, otherwise false.
cm.disconnect();
This method will execute a server.log() command (if connected), or queue the value of message to be logged on the next connect. Any object that can be passed to server.log() can be passed to log().
Note ConnectionManager stores log messages in memory but doesn’t persist them across deep sleeps and cold boots.
Nothing.
cm.onDisconnect(function(expected) {
if (expected) {
// Log a regular message that we disconnected as expected
cm.log("Expected Disconnect");
} else {
// Log an error message that we unexpectedly disconnected
cm.error("Unexpected Disconnect");
}
});
The error() method will execute a server.error() command (if connected), or queue the value of errorMessage to be logged on the next connect. Any object that can be passed to server.error() can be passed to error().
Note ConnectionManager stores error messages in memory but doesn’t persist them across deep sleeps and cold boots.
Nothing.
See log(), above, for example code.
The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.
| Version | Source Code | Notes |
|---|---|---|
| 1.0.0 | GitHub | Initial release |
| 1.0.1 | GitHub | Updated code; consistent spelling of ‘behavior’; no API changes |
| 1.0.2 | GitHub | Added timeout acknowledgement; corrected logging |
| 2.0.0 | GitHub | Updated library name to meet new naming scheme; add onTimeout() method; extend initialization options |
| 2.1.0 | GitHub | Updated to support changes to server.setsendtimeoutpolicy() |
| 3.0.0 | GitHub | Add optional force and flushTimeout parameters to disconnect() method; renamed all constants: eg. ConnectionManager.BLINK_ALWAYS becomes CM_BLINK_ALWAYS — this is a breaking change |
| 3.1.0 | GitHub | Add support for multiple onDisconnect, onConnect and onTimeout callbacks |
| 3.1.1 | GitHub | Correct handling of the named callbacks |
This library is licensed under the MIT License.