Configures a rescue pin
Available for use in Device-Under-Test Factory Firmware only. The DUT must not be an imp006
|pin||An imp pin object||
The assigned rescue pin, or
1 for Logic High (pull up on pin), 0 for Logic Low (pull down on pin)
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:
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:
You should call imp.setrescuepin() only in your DUT factory firmware. It will throw an exception if called in application firmware.
The following functions will not operate in their own right, but are intended to by used in conjunction with our standard factory firmware. Add the first function to that code, and replace the existing blessDeviceUnderTest() function with the one included below.