Skip to main content

imp.setrescuepin(pin, polarity)

Configures a rescue pin

Availability

Device (from impOS™ 36)
Available for use in Factory Firmware only

Parameters

Name Type Description
pin An imp pin object The assigned rescue pin, or null to clear the setting
polarity Integer 1 for Logic High, 0 for Logic Low

Returns

Nothing

Description

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:

  • 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.
  • Unconfigure the pin to allow Squirrel code to subsequently make use of it.
  • If the pin was the same as the configured polarity — for example, if a reset 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.
  • If the pin shows a different polarity than the specified default — if the reset button is being pressed — then the imp clears any Squirrel code stored and proceeds with a standard cold boot as outlined above. Because squirrel is cleared at this point, the device requires a connection at this point to re-load Squirrel.

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 a runtime error if called in application firmware.

Example Code

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.