Skip to main content

Imp Network State Diagram

What Happens When An imp’s Network ConnectionChanges, 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:

  • 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 update's installation fails).

  • 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 if necessary. If it connects within ten seconds, it goes to ACTIVE ONLINE. If it fails to connect in this time, the imp will either:

    • RETURN_ON_ERROR — Go to ACTIVE OFFLINE and wait until Squirrel attempts to connect.
    • SUSPEND_ON_ERROR — Go to ACTIVE_CONNECTING and make a second attempt to connect.
       
  • 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:
      • 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.
      • SUSPEND_ON_ERROR — the imp enters the SUSPENDED CONNECTING state: it pauses Squirrel execution and tries to reconnect.
    • 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:
      • RETURN_ON_ERROR — the imp calls anu unexpected-disconnect handler and enters ACTIVE OFFLINE.
      • SUSPEND_ON_ERROR — the imp enters the SNOOZE state.
    • 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 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.

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.

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

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.