Configures a rescue pin
Device (from impOS™ 36)
Available for use in Factory Firmware only
|pin||An imp pin object||
The assigned rescue pin, or
1 for Logic High, 0 for Logic Low
This method alters the imp’s cold-boot behavior. It also configures a ‘rescue pin’ which can be used to bypass this modified behavior, for example to mitigate issues in the device’s Squirrel code. The new mode of operation is typically required by devices which are powered down by the end-user rather than put to sleep. An example is connected lighting. It would be not be acceptable for an end-user to remain in the dark while the light connects to WiFi and checks for updated Squirrel code at start-up, as is customarily the case during cold starts. In the event of a power outage and restoration, the end-user’s Internet connection may not come up for several minutes, so the imp will be unable to verify Squirrel within the ten-second timeout usually allowed for this.
Instead, imp.setrescuepin() allows the customer to set the imp-enabled light essentially to boot straight to Squirrel without connecting to the impCloud™ in place of the usual cold boot procedure.
If, however, the rescue pin is asserted at start-up, the device does perform the usual cold boot procedure. However, Squirrel is cleared so that when the device connects to the impCloud it always downloads new application code. Indeed, the device must now connect to the Internet to operate.
This provides a way to rescue a device from a state where errors in code — for example, an infinite loop, or an immediate sleep — has been deployed by mistake. Customers can instruct end-users to press the reset button and power up the device (and connect it to a network if it does not already have valid credentials). This ensures updated application code will be downloaded.
The method’s parameters are an imp pin object which will be connected to a switch. The polarity value indicates whether the pin should be configured to make use of an internal pull-up and will be triggered by externally being taken low (polarity set to 0), or a pull-down and triggered by externally being taken high (polarity set to 1). When called, the method writes these values to the imp’s configuration page.
The rescue pin configuration, if set, will not cleared by imp.clearconfiguration(), but the rescue pin configuration can be disabled by passing
null into setrescuepin()’s pin parameter.
An imp which has an active rescue pin configuration will perform the following extra actions early on during a cold boot:
This does not prevent devices from receiving future application updates. When application code connects to the impCloud by calling any server method or sending a message to the agent, the imp will receive updated code if any is available, restart the Squirrel VM and warm boot.
You should call imp.setrescuepin() only in your 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.