imp.setrescuepin(pin, polarity)

Description

This method changes the imp’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. It applies to all imps other than the imp006, which offers its own method for this task: imp.enablerescuepin().

Calling imp.setrescuepin() in your Device Under Test (DUT) factory firmware activates the imp’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.setrescuepin() sets the specified imp pin object (typically connected to a button) as a digital input with an internal pull-up (polarity passed 1) or pull-down (polarity passed 0) resistor. The method writes these values to the imp’s configuration page. If the registered pin’s state doesn’t match the recorded polarity at start-up then fast-boot mode is disabled for the current start-up sequence.

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 imp 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 the required pull-up or pull-down 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 has the configured polarity — for example, a button connected to the rescue pin has not been pressed — then 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 shows a different polarity than the configured value — the button is being pressed — then the imp clears the stored Squirrel code and proceeds with a standard cold boot as outlined above. Because squirrel is cleared, the device requires a connection at this point to re-load Squirrel.
• Unconfigure the pin to allow Squirrel code to subsequently make use of it.

Activation of the imp’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.

The rescue pin configuration, if set, will not cleared by imp.clearconfiguration(), but the rescue pin configuration can be disabled by passing null into imp.setrescuepin()’s pin parameter. The polarity argument is still required, even though it has no meaning in this case:

imp.setrescuepin(null, 1);

You should call imp.setrescuepin() only in your DUT factory firmware. It will throw an exception if called in application firmware.