Imp Network State Diagram

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:

• To keep a sensor logging every minute even while WiFi goes down, reporting all the readings in one go when it comes back up again.
• On battery-powered devices, to keep the (relatively power-hungry) WiFi sub-system turned off when not needed.

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.

The impOS Network Flow

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.

SUSPEND_ON_ERROR

Click for a larger version

RETURN_ON_ERROR

Click for a larger version

• 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:

  • SUSPEND_ON_ERROR — Go to ACTIVE_CONNECTING and make a second attempt to connect.
  • RETURN_ON_ERROR — Go to ACTIVE OFFLINE and wait until Squirrel attempts to connect.
    Note the imp will remain in SUSPEND_ON_ERROR mode until your Squirrel code calls server.setsendtimeoutpolicy() to change this to RETURN_ON_ERROR. When it does, the imp will immediately move from ACTIVE_CONNECTING to ACTIVE OFFLINE. Until server.setsendtimeoutpolicy() is called, the ACTIVE_CONNECTING connection attempt could fail, sending the imp to SNOOZE.
     

• 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:

  • If it fails to read data from the server for any reason, it will enter ACTIVE CONNECTING and try to reconnect.
  • If it fails to send data to the server, the effect depends on the mode of operation:
    • SUSPEND_ON_ERROR — the imp enters the SUSPENDED CONNECTING state: it pauses Squirrel execution and tries to reconnect.
    • RETURN_ON_ERROR — the imp calls any unexpected-disconnect handler registered using server.onunexpecteddisconnect(), enters the ACTIVE OFFLINE state and remains disconnected until told otherwise by Squirrel.
  • If Squirrel calls server.disconnect() to explicitly disconnect from the server, the imp enters the ACTIVE OFFLINE state. Because this is an expected disconnection, impOS does not call the unexpected-disconnect handler.
  • As with any state where Squirrel is running, a Squirrel runtime error will send it to the GET SQUIRREL #2 state in order to see if there is updated code to download.
  • As with any state where Squirrel is running, a call to server.restart() will send it to the GET SQUIRREL #2 state in order to check if there is updated code to download.
  • As with any state where Squirrel is running, server.sleepfor() or server.sleepuntil() will send it to the ASLEEP state.
     

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

  • If the reconnection succeeds within one minute, the imp returns to ACTIVE ONLINE as if nothing had happened.
  • If the reconnection fails (a timeout), the effect depends on the mode of operation:
    • SUSPEND_ON_ERROR — the imp enters the SNOOZE state.
    • RETURN_ON_ERROR — the imp calls any unexpected-disconnect handler and enters ACTIVE OFFLINE.
  • As with any state where Squirrel is running, a Squirrel run-time error will send it to the GET SQUIRREL #2 state in order to see if there is updated code to download.
  • As with any state where Squirrel is running, a call to server.restart() will send it to the GET SQUIRREL #2 state in order to check if there is updated code to download.
  • As with any state where Squirrel is running, server.sleepfor() or server.sleepuntil() will send it to the ASLEEP state.
     

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

  • In RETURN_ON_ERROR mode, only an explicit call to server.connect() will send it to the ACTIVE CONNECTING state and thence to ACTIVE ONLINE; other attempted network activity will return errors without re-attempting connection.
  • In SUSPEND_ON_ERROR mode, any attempted network activity (such as a call to server.log() or agent.send()) will send it to the SUSPENDED CONNECTING state (during which Squirrel execution is paused) and hopefully thence to ACTIVE ONLINE.
  • As with any state where Squirrel is running, a Squirrel run-time error will send it to the GET SQUIRREL #2 state in order to see if there is updated code to download.
  • As with any state where Squirrel is running, a call to server.restart() will send it to the GET SQUIRREL #2 state in order to check if there is updated code to download.
  • As with any state where Squirrel is running, server.sleepfor() or server.sleepuntil() will send it to the ASLEEP state.
     

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

  • SUSPEND_ON_ERROR: impOS will try for one minute to reconnect to the server; if it manages to do so, it enters ACTIVE ONLINE again, otherwise it enters the SNOOZE state.
  • RETURN_ON_ERROR: imps in this mode never enter SUSPENDED CONNECTING.

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

  • Note The imp005 cannot currently enter this state as it does not support deep sleep.

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

Consequences of the Flow

• 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 performs 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 to 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.

BlinkUp LED Status Indication

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.

Up to impOS 41/42, 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().

From impOS 41/42, there is no longer a 60-second period for which BlinkUp will always remain active after a call to imp.enableblinkup() to disable BlinkUp. Customers should note that if the imp cold boots and fails to connect to the server within ten seconds, Squirrel will start and an early call to imp.enableblinkup() may come too quickly to allow end-users to re-configure activated devices.

If BlinkUp takes place while the imp is running, impOS is rebooted and the imp effectively goes straight to ACTIVE CONNECTING.

Polite Deployment

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.