Merge pull request #17 from electricimp/develop

Develop

Author: Pavel Petroshenko

Diff for: ConnectionManager.lib.nut

@@ -1,15 +1,39 @@
-// Copyright (c) 2015-2017 Electric Imp
-// This file is licensed under the MIT License
-// http://opensource.org/licenses/MIT
+// MIT License
+
+// Copyright 2015-2017 Electric Imp
+
+// SPDX-License-Identifier: MIT
+
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+
+// The above copyright notice and this permission notice shall be
+// included in all copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+// EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+// OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+// OTHER DEALINGS IN THE SOFTWARE.
+
 
 class ConnectionManager {
-    static version = [1,1,0];
+    static VERSION = "2.0.0";
 
     static BLINK_ALWAYS = 0;
     static BLINK_NEVER = 1;
     static BLINK_ON_CONNECT = 2;
     static BLINK_ON_DISCONNECT = 3;
     static FLUSH_TIMEOUT = 30;
+    static START_NO_ACTION = 0;
+    static START_CONNECTED = 1;
+    static START_DISCONNECTED = 2;
 
     // Settings
     _connectTimeout = null;
@@ -38,8 +62,7 @@ class ConnectionManager {
         _stayConnected = ("stayConnected" in settings) ? settings.stayConnected : false;
         _blinkupBehavior = ("blinkupBehavior" in settings) ? settings.blinkupBehavior : BLINK_ON_DISCONNECT;
         _retryOnTimeout = ("retryOnTimeout" in settings) ? settings.retryOnTimeout : true;
-        local startDisconnected = ("startDisconnected" in settings) ? settings.startDisconnected : false;
-        local startConnected = ("startConnected" in settings) ? settings.startConnected : false;
+        local startBehavior = ("startBehavior" in settings) ? settings.startBehavior : START_NO_ACTION;
         local ackTimeout = ("ackTimeout" in settings) ? settings.ackTimeout : 1;
 
         // Initialize the onConnected task queue and logs
@@ -49,13 +72,18 @@ class ConnectionManager {
         // Set the timeout policy + disconnect if required
         server.setsendtimeoutpolicy(RETURN_ON_ERROR, WAIT_TIL_SENT, ackTimeout);
 
-        if (startDisconnected) {
-            // Disconnect if required
-            server.disconnect();
-            _connected = false;
-        } else if (startConnected) {
-            // Start connecting if they ask for it
-            imp.wakeup(0, connect.bindenv(this));
+        switch (startBehavior) {
+            case START_NO_ACTION:
+                // Do nothing
+                break;
+            case START_CONNECTED:
+                // Start connecting if they ask for it
+                imp.wakeup(0, connect.bindenv(this));
+                break;
+            case START_DISCONNECTED:
+                // Disconnect if required
+                imp.wakeup(0, disconnect.bindenv(this));
+                break;
         }
 
         // Get the initial state and set BlinkUp accordingly
@@ -159,7 +187,7 @@ class ConnectionManager {
         // If we're connecting / disconnecting, try again in 0.5 seconds
         if (_connecting) { return false; }
 
-        // if we're already disconnected: invoke the onDisconnectedFlow and return
+        // If we're already disconnected: invoke the onDisconnectedFlow and return
         if (!_connected) {
             _onDisconnectedFlow(true);
             return true;

Diff for: LICENSE

@@ -1,6 +1,8 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2015-2017 Electric Imp
+Copyright 2015-2017 Electric Imp
+
+SPDX-License-Identifier: MIT
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +11,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

Diff for: README.md

@@ -1,10 +1,10 @@
-# ConnectionManager 1.1.0
+# ConnectionManager 2.0.0
 
 The ConnectionManager class is an Electric Imp device-side library aimed at simplifying connect and disconnect flows.
 
 **Note** If you are using the ConnectionManager class in your model, you should ensure that you *never* call  [**server.connect()**](https://electricimp.com/docs/api/server/connect/) or [**server.disconnect()**](https://electricimp.com/docs/api/server/disconnect/) in your application code. Instead you should use the ConnectionManager’s *connect()* and *disconnect()* methods.
 
-**To add this library to your project, add** `#require "ConnectionManager.lib.nut:1.1.0"` **to the top of your device code.**
+**To add this library to your project, add** `#require "ConnectionManager.lib.nut:2.0.0"` **to the top of your device code.**
 
 ## Class Usage
 
@@ -14,8 +14,7 @@ The ConnectionManager class can be instantiated with an optional table of settin
 
 | key               | default             | notes |
 | ----------------- | ------------------- | ----- |
-| *startConnected*    | `false`             | When set to `true` the device immediately connects |
-| *startDisconnected* | `false`             | When set to `true` the device immediately disconnects |
+| *startupBehavior*    | START_NO_ACTION  | See below |
 | *stayConnected*     | `false`             | When set to `true` the device will aggressively attempt to reconnect when disconnected |
 | *retryOnTimeout*    | `true`              | When set to `true` the device will attempt to connect again if it times out. |
 | *blinkupBehavior*   | BLINK_ON_DISCONNECT | See below |
@@ -24,7 +23,7 @@ The ConnectionManager class can be instantiated with an optional table of settin
 | *ackTimeout*        | 1                   | Float. Maximum time (in seconds) allowed for the server to acknowledge receipt of data. |
 
 ```squirrel
-#require "ConnectionManager.lib.nut:1.1.0"
+#require "ConnectionManager.lib.nut:2.0.0"
 
 // Instantiate ConnectionManager so BlinkUp is always enabled,
 // and we automatically agressively try to reconnect on disconnect
@@ -38,10 +37,11 @@ imp.setsendbuffersize(8096);
 ```
 
 **Note** We’ve found setting the buffer size to 8096 to be very helpful in many applications using the ConnectionManager class, though your application may require a different buffer size.
-
-#### ackTimeout
-
-This value is passed into the imp API method [**server.setsendtimeoutpolicy()**](https://electricimp.com/docs/api/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()**](https://electricimp.com/docs/api/server/setsendtimeoutpolicy/) in your application code.
+#### startupBehavior
+The startupBehavior flag modifies what action the ConnectionManager takes when initialized.
+- *ConnectionManager.START_DO_NOTHING* will take no action after being initialized. This is the default value.
+- *ConnectionManager.START_CONNECTED* will try to connect after being initialized.
+- *ConnectionManager.START_DISCONNECTED* will disconnect after being initialized.
 
 #### blinkupBehavior
 
@@ -54,6 +54,11 @@ The blinkupBehavior flag modifies when the ConnectionManager enables the BlinkUp
 
 **Note** impOS™ *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.
 
+#### ackTimeout
+
+This value is passed into the imp API method [**server.setsendtimeoutpolicy()**](https://electricimp.com/docs/api/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()**](https://electricimp.com/docs/api/server/setsendtimeoutpolicy/) in your application code.
+
+
 ## Class Methods
 
 ### setBlinkUpBehavior(*blinkupBehaviorFlag*)
@@ -65,7 +70,7 @@ The *setBlinkUpBehavior()* method changes the class’ BlinkUp behavior (see [bl
 cm.setBlinkUpBehavior(ConnectionManager.BLINK_ON_CONNECT);
 ```
 
-## isConnected()
+### isConnected()
 
 The *isConnected()* method returns the value of ConnectionManager’s internal connected state flag (whether or not we are connected). This flag is updated every five seconds, or as set by the *checkTimeout* setting in the constructor.
 
@@ -79,7 +84,7 @@ if (!cm.isConnected()) {
 }
 ```
 
-## onDisconnect(*callback*)
+### onDisconnect(*callback*)
 
 The *onDisconnect()* 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 the ConnectionManager’s *disconnect()* method is called (even if the device is already disconnected).
 
@@ -97,7 +102,7 @@ cm.onDisconnect(function(expected) {
 });
 ```
 
-## onConnect(*callback*)
+### onConnect(*callback*)
 
 The *onConnect()* method assigns a callback method to the onConnect event. The onConnect event will fire every time the connection state changes from offline to online, or when the ConnectionManager’s *connect()* method is called (even if the device is already connected).
 
@@ -110,7 +115,7 @@ cm.onConnect(function() {
 });
 ```
 
-## onTimeout(callback)
+### onTimeout(callback)
 
 The *onTimeout* method assigns a callback method to the onTimeout event. The onTimeout event will fire every time the device attempts to connect but does not succeed.
 
@@ -123,7 +128,7 @@ cm.onTimeout(function() {
 });
 ```
 
-## onNextConnect(*callback*)
+### onNextConnect(*callback*)
 
 The *onNextConnect()* method queues a task (the callback) to run the next time the device connects. If the imp is already connected, the callback will be invoked immediately.
 
@@ -150,7 +155,7 @@ function poll() {
 
 **Note** If the imp enters a deep sleep or performs a cold boot, the task queue will be cleared.
 
-## connectFor(*callback*)
+### connectFor(*callback*)
 
 The *connectFor()* method tells the imp to connect, run the callback method, then disconnect when complete. If the imp is already connected, the callback will be invoked immediately, and the imp will disconnect upon completion.
 

Diff for: example/ConnectionManager.example.nut

@@ -1,9 +1,34 @@
-#require "ConnectionManager.lib.nut:1.1.0"
+// MIT License
+
+// Copyright 2015-2017 Electric Imp
+
+// SPDX-License-Identifier: MIT
+
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+
+// The above copyright notice and this permission notice shall be
+// included in all copies or substantial portions of the Software.
+
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+// EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+// OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+// OTHER DEALINGS IN THE SOFTWARE.
+
+ 
+#require "ConnectionManager.lib.nut:2.0.0"
 
 // Instantiate ConnectionManager so BlinkUp is always enabled,
 // and starts connected.
 cm <- ConnectionManager({
-    "startConnected": true,
+    "startupBehavior": START_CONNECTED,
     "connectTimeout": 90,
     "blinkupBehavior": ConnectionManager.BLINK_ALWAYS
 });