What Happens When An imp’s Network Connection Changes, It Sleeps, Or Is Power-cycled
For most applications, the imp takes care of controlling its embedded WiFi chip and of re-contacting the servers if the connection drops for any reason. However, for specialist applications, a Squirrel program can turn WiFi on and off directly, and be notified of any connection loss. This is useful in various situations:
API documentation and examples can be found under server.disconnect(), server.expectonlinein()/server.expectonlineat(), and the pages linked from them, but it’s helpful to have an overall picture of the flow.
The imp005 module supports Ethernet in addition to WiFi. The network flow doesn’t distinguish between these two networking types, only whether the device is connected or not. For example, if an imp005 is connected to an Ethernet network, it will go through the same stages on the chart as if it expects to connect by WiFi.
impOS has two different modes of operation: SUSPEND_ON_ERROR and RETURN_ON_ERROR. The former may be thought of as ‘automatic reconnect’, or ‘simple mode’, while the second is more like ‘manual reconnect’, or ‘expert mode’. The mode of operation is set by passing either of these two constants into the method server.setsendtimeoutpolicy().
The following diagrams show the flows for each of these two modes. An explanation of the various states is included below the diagrams.
COLD START All imps start here when power is first applied. It is also the state to which the imp moves if imp.reset() is called from running Squirrel (impOS 38 and up), and the state to which the imp moves after an impOS update is installed (or if the installation failed).
RESCUE PIN If a rescue pin has been set via factory firmware, it is checked now. If the pin is not asserted — ie. a reset button connected to it has not been pressed — the imp goes direct to the ACTIVE OFFLINE state and waits until Squirrel attempts to connect. See the imp.setrescuepin() documentation for more information.
GET SQUIRREL #1 impOS attempts to connect to the server, powering up the WiFi chip, Ethernet PHY or cellular modem as required. If it connects to the impCloud within ten seconds, it goes to ACTIVE ONLINE. If it fails to connect in this time, the imp will either:
RUNNING SQUIRREL Any path into this area implicitly see impOS instantiate a Squirrel Virtual Machine. Paths moving out of this area will result in the VM being suspended (paused) or torn down, to be re-instantiated later, as required.
ACTIVE ONLINE The imp is connected to the server, and Squirrel code is running. The imp will remain in this state until something happens to force it out:
ACTIVE CONNECTING The imp is not connected to the server (though WiFi may be powered up, if that is the connection mode) and Squirrel execution continues. impOS attempts reconnection, without telling Squirrel it’s doing so. This is done to avoid over-reacting to brief outages.
ACTIVE OFFLINE If the imp is using WiFi, this is turned off, providing substantial power savings compared to the other active modes. Squirrel execution continues.
GET SQUIRREL #2 The imp has no Squirrel code, its running Squirrel code has generated a runtime error, or impOS has received a ‘reload’ message from the server. In these cases, impOS attempts to connect (if it isn’t connected already) and download a fresh Squirrel program. If it does so within one minute, it proceeds to SNOOZE.
SUSPENDED CONNECTING The imp is not connected to the server (though WiFi may be powered up, if that is the connection mode) and Squirrel execution is suspended.
SNOOZE The CPU is in deep sleep (~6μA power consumption) and, if WiFi is the connection mode, WiFi is off. Nine minutes later, the imp will wake and enter the ACTIVE CONNECTING state.
ASLEEP The CPU is in deep sleep (~6μA power consumption) and, if WiFi is the connection mode, WiFi is off. When the sleep timer fires, the imp wakes up again. If it also configured to do so, it will wake up earlier if it sees a logic-high level on the imp’s wakeup pin (see the imp pin mux for your module’s specific wakeup pin). When woken, it begins the WARM START procedure.
WARM START The imp proceeds to ACTIVE OFFLINE. Squirrel is started afresh; only data preserved in the nv table is retained from the previous run (note that the imp004m has no nv table). If the imp doesn’t have the right Squirrel program yet, it proceeds to GET SQUIRREL #2 to try and download some.
An imp can wake from sleep, talk to hardware, perhaps store some data in the deep-sleep storage table (not supported by the imp004m), and go back to sleep again without the WiFi ever being powered on — provided it does no send/connect operations or, if it uses the RETURN_ON_ERROR policy, makes no server.connect() calls. In either case, it will be necessary for the imp will connect and transfer the data at some future time, or if some threshold is exceeded.
An imp set to RETURN_ON_ERROR should almost always also have a call to server.connect() somewhere within its application program, whether in an unexpected-disconnect handler or when it knows it has some data to send. Otherwise it may never reconnect to the server.
While an imp’s status LED is illuminated, it will indicate the state of the network connection. If the imp cannot connect when it needs to do so because it lacks WiFi credentials, a plan ID for enrollment or an active Ethernet link, it will flash amber. When it has successfully connected, it flashes green. These status patterns and those of intermediate connection states are listed here.
Note imps with external SPI flash (imp003, imp004m and imp005) also use the LED to signal SPI flash errors. Please see the appropriate ‘Design with imp’ guide for further details.
The LED will always be illuminated for at least one minute after Cold Start; beyond this, it may be controlled by Squirrel, either to disable it immediately or to keep it active continuously. The LED is controlled this way using imp.enableblinkup().
If BlinkUp takes place while the imp is running, impOS is rebooted and the imp effectively goes straight to ACTIVE CONNECTING.
Polite deployment is a device-side Squirrel-based mechanism that allows application code to defer impOS and application code updates if they would interrupt a critical task. When the device is ready to update, its code should call server.restart() to cause the device to shut down Squirrel and either jump to Cold Start to download and install the impOS update or, if there is just new application code, enter the GET SQUIRREL #2 state.
For impOS upgrades, with a polite deployment handler in place there is no state change until server.restart() is called, at which point the imp will attempt to obtain and install the update. With no polite deployment handler in place, this happens immediately. Whether the update succeeds or fails, the imp then moves to the COLD START state.