Skip to main content

How To Restart An imp And Its Application

Understanding The imp API’s Device Restart Options

The imp API provides a number of ways to cause an imp to restart through application code. This guide looks at each of these methods to help you decide which to use in a given case. Your code may include any or all of these methods as determined by the needs of the application and the imp on which the code is running.

Before looking at each of the available restart methods, let’s review what normally happens to an imp after it is physically power-cycled. This action has the effect of completely resetting the hardware and software, in particular:

  • The BlinkUp system is activated and the LED begins to signal status. BlinkUp will be available for 120 seconds unless Squirrel, once running, disables it. BlinkUp is always available for at least 60 seconds from start-up.
  • Devices which connect primarily by WiFi:
    • WiFi power-save mode is disabled, even if previously enabled.
    • WiFi is brought up and, if the imp has stored credentials, it connects to the local access point and then to the impCloud. This will be signalled on the BlinkUp Status LED.
  • Devices which connect primarily by Ethernet:
    • The imp checks for an Ethernet link signal
      • If this fails, the imp will attempt to connect by WiFi if it is able to do so — the product may be configured (via imp.setnvramimage()) only for wired usage, for example.
    • The imp attempts to access the DHCP server (unless it has been configured to use a static IP) via the wired connection. This will be signalled on the BlinkUp Status LED.
  • Squirrel code, if present, runs afresh in a new VM after ten seconds or upon connection, whichever occurs first.
    Note If the device has a configured rescue pin and this is not triggered at start-up, then Squirrel code, if present, will start immediately.

Connections to the impCloud require DHCP negotiation via the local router (unless the imp has been configured to use a static IP), and the exchange and verification of certificates between the imp and the impCloud. This adds a necessary latency to the start of application.

This is called a cold boot and its flow is indicated on the imp Network State Diagram via the Cold Start event. The flow outlined above assumes that the device has already been activated, ie. an end-user has provided the unit with network access credentials, if required, and enrolled the device into the impCloud. Devices without WiFi credentials, for example, will keep BlinkUp activated and signalled on the status LED. Devices which have no Squirrel (new Development Devices and Production Devices set to download their application code after activation) will not start the Squirrel VM at this point.

Restart Method 1: server.sleepfor()/imp.deepsleepfor()

The first software-controlled restart method is to call server.sleepfor() or imp.deepsleepfor(). These calls both put the imp into a deep sleep state with a timer set to wake them after a supplied duration, provided as the functions’ argument. While this sleep period is typically of significant duration, by passing in zero as their sole argument, these calls can be used to cause an immediate restart, ie:

server.sleepfor(0);

or

imp.deepsleepfor(O);

These calls differ in that the former includes an implicit call to server.flush() to ensure that any messages in the transmit queue are sent before the imp sleeps; if you call imp.deepsleepfor() without previously calling server.flush() messages in the transmit queue, if any, will be lost, but this means the imp enters deep sleep more quickly, which may be advantageous for some applications.

When the imp awakes, all pins except any that have been been previously configured as a Zombie PWM return to their default states (tristated, except for some imp005 pins whose default state is different, see its pin mux page). In addition:

  • If it connects primarily by WiFi:
    • WiFi power-save mode is disabled, even if previously enabled, but remains powered down (it was powered down when the imp entered deep sleep).
    • It does not connect to the impCloud.
  • If it connects primarily by Ethernet:
    • It does not connect to the impCloud.
  • The BlinkUp system is activated and the LED begins to signal status.
  • Squirrel code runs afresh.

In this regard, this restart closely resembles a cold boot — other than the fact that the imp does not connect to the impCloud immediately. On the Network State Diagram this is the Warm Start point.

The imp will connect to the server as soon as Squirrel attempts to contact the device’s agent (ie. by agent.send()) or makes some other server-oriented call, such as server.log() or server.connect(). The device will attempt to connect outside of Squirrel control if a runtime error occurs.

This method is the traditional method of triggering a restart, but is not available to applications running on the imp005, which does not support deep sleep, or on devices which lack deep sleep because their imp003 or imp004m module is not connected to a 32kHz crystal. For these devices, impOS 38 adds the following method.

Restart Method 2: imp.reset()

This call closely resembles the use of server.sleepfor(0) and imp.deepsleepfor(0) to invoke an immediate restart, with one crucial difference: it causes the imp to follow the Cold Start path in the Network State Diagram. All pins except any that have been been previously configured as a Zombie PWM return to their default states (tristated, except for some imp005 pins whose default state is different, see its pin mux page). In addition:

  • If the imp connects primarily by WiFi:
    • WiFi power-save mode is disabled, even if previously enabled.
    • WiFi is brought up and, if the imp has stored credentials, it connects to the impCloud.
  • If the imp connects primarily by Ethernet:
    • The imp connects to the impCloud via the wired connection.
    • If this fails, the imp will attempt to connect by WiFi if it is able to do so.
  • The BlinkUp system is activated and the LED begins to signal status.
  • Squirrel code runs afresh.

This approach has the additional impact that the imp performs checks for new Squirrel code and impOS updates, which the Warm Start path does not include (unless a Squirrel error subsequently triggers one).

In addition, imp.reset() is available to imps which are not connected to a 32kHz crystal, ie. those which cannot deep sleep. This includes the imp005, for which server.sleepfor() and imp.deepsleepfor() have been disabled and therefore cannot be called.

Restart Method 3: server.restart()

This call causes the imp’s current Squirrel Virtual Machine to be taken down and re-instantiated. This action has the effect of completely resetting the application software — your Squirrel code runs afresh — and all pins except any that have been configured as a Zombie PWM return to their default states (tristated, except for some imp005 pins whose default state is different, see its pin mux page). However:

  • WiFi or Ethernet remain connected.
  • WiFi power-save mode remains unchanged.
  • The BlinkUp system state remains unchanged.

As such server.restart() is intended solely to be used to restart Squirrel, primarily in response to a message from the impCloud that fresh Squirrel and/or an impOS update is available; restarting Squirrel immediately causes such updates to be retrieved and installed — without the need to first boot the hardware and re-establish the network connection. This is part of impOS’ polite deployment mechanism.

You should know, however, that an impOS upgrade will trigger a warm boot after the update has been installed. Updating Squirrel simply restarts the VM.

This is the fastest means to restart an application as it does not cause the imp’s connection to be broken then re-established (unless it actions an impOS update) but it does not reset hardware.

Restart Method 4: impCentral

This is a special case since it is not under the control of the Squirrel application code, but is included here for completeness. In this case, an operator uses the impCentral™ web app (or another impCentral API-based tool) to cause devices to restart. Such a command can also reach multiple devices if it is made to a Device Group rather than to a specific device. Restarts may be forced (the device(s) must restart) or conditional (device(s) restart only if are running application code that is older than the current minimum supported deployment).

The restart is essentially an externally triggered call to server.restart() and has the effect of completely resetting the software — your Squirrel code runs afresh — but has no impact on the hardware.

Which Restart Method To Use In Your Code

Which of the above methods you apply should be determined by why you need the device to restart. You may of course use multiple calls, depending on circumstance, eg. server.restart() in your polite deployment handler and imp.reset() in the code you have written to process a reset command issued by the end-user.

  • To trigger an immediate full device reboot, including a network re-connection, call imp.reset()
    This is typically performed in response to the triggering of a reset button connected to GPIO, or a reset trigger sent from a control app via the device’s agent.
  • To trigger an immediate full device reboot on an imp that cannot deep sleep, call imp.reset()
    Note that if the imp is not running impOS 38, this will not be possible and you cannot trigger a full device reboot on such a device.
  • To trigger an immediate full device reboot, but with no re-connection, call imp.deepsleepfor() or server.sleepfor() with a zero sleep time
    This is only recommended as a restart mechanism if you specifically need the imp to remain disconnected after it wakes — perhaps on a battery powered device — or if the imp is not yet running impOS 38.
  • To respond to a notification that there is an impOS or Squirrel update available, call server.restart()
    This is the method to call if your application is asked to restart because new Squirrel code is ready to be installed. It is not necessary to do a full device reset in this instance.
  • To restart your application as quickly as possible, call server.restart()
    This is the quickest method because the device does not disconnect then reconnect to the network and the impCloud, which is the case with imp.reset().
  • To restart an agent, call server.restart() on the agent.
    This is the only method to force an agent to restart.

Summary

imp API Method Resets Connection Requires Manual Reconnection Resets Application Resets GPIO
imp.reset()
server.restart()
server.sleepfor(0)