imp.enablerescuepin(enable)

Description

This method changes the imp006’s cold-boot behavior and configures a ‘rescue pin’ which can be used to bypass this modified behavior in the event of a Squirrel error.

Calling imp.enablerescuepin(true) in your Device Under Test (DUT) factory firmware activates the imp006’s fast-boot mode: whenever the device is subsequently power-cycled, it boots straight to Squirrel without first attempting to connect to the impCloud™.

This is in contrast with impOS’ standard boot behavior in which application Squirrel is not started until either the host imp has connected to the impCloud and downloaded any available application update, or ten seconds have elapsed.

Fast-boot mode is intended solely for devices which are powered down by the end-user rather than put to sleep, such as connected lighting products. It would not be acceptable for an end-user to remain in the dark while a connected lamp first joins WiFi and then checks for updated Squirrel code, or the ten-second timeout is exceeded, before turning on the light.

To ensure that fast-boot devices are able to check for fresh Squirrel at start-up, imp.enablerescuepin() sets the imp006’s RESCUE pin high. If this pin is pulled low at power-on then fast-boot mode is disabled for the current start-up sequence. The pin should be connected to GND via a button.

This provides a means to rescue a device from a state where errors in code — for example, an infinite loop, or an immediate sleep — have been deployed by mistake. Customers can instruct end-users to press the rescue button and power up the device to allow updated application code to be downloaded.

An imp006 which has an active rescue pin will perform the following extra actions early on during a cold boot:

• Configure the rescue pin as digital input with a pull-up resistor.
• Wait for 10ms for any capacitance on the pin to discharge. This is on the basis of a maximum of 50pF on this line.
• Read the rescue pin:
  • If the pin is high, the imp will execute its Squirrel code immediately and no attempt is made to connect to the impCloud. The application itself must initiate the connection in due course.
  • If the pin is low, the imp erases the Squirrel code stored and proceeds with a standard cold boot: it connects to the impCloud and re-downloads the application.

Activation of the imp006’s rescue pin does not prevent devices from receiving future application updates. When application code connects to the impCloud by calling any server method or by sending a message to the agent, the imp will receive updated Squirrel if any is available, restart the Squirrel VM and warm boot.

You should call imp.enablerescuepin() only in your DUT factory firmware. It will throw an exception if called in application firmware. It will also throw an exception if you do not pass an argument, or call the code on any imp other than the imp006.

Note imp.enablerescuepin() is intended for use with the imp006 only. To activate fast-boot mode and configure a rescue pin for other imps, you must use imp.setrescuepin().