ExecuteSoftReset

1. Synopsis

2. Parameter

3. Description

4. Return Value

5. Conforming To

6. Example

7. See Also

¶Synopsis

 unsigned int executeSoftReset(uint32_t options) 

¶Parameter

¶Description

NOTE: This functionality only works on chipKIT boards. Arduino boards do not support software reset in this manner. There are workarounds that are available for Arduino but at this writing there is no standardized support in the Arduino wiring libraries.

When the reset button is pressed on a chipKIT board the PIC32 chip is “reset” to its power on state and starts running the bootloader program. On chipKIT boards that have a program button input, the bootloader looks at the state of this input. If the input is asserted the bootloader enters a mode where it waits for a new program to be sent over the serial port to be programmed in to the memory of the chip. If the program input is not asserted, then the bootloader tries to run a previously loaded program.

The chipKIT-core library includes a function called executeSoftReset that allows us, in software, to reset the board. The function takes a single parameter and allows us to choose the functionality after reset. Either we can enter the bootloader to accept a new program or we can run a sketch that was previously programmed. The two ways to call the function are shown below:

// Run previously loaded sketch after executing the soft reset executeSoftReset(RUN_SKETCH_ON_BOOT);

// Enter the bootloader after executing the soft reset executeSoftReset(ENTER_BOOTLOADER_ON_BOOT);

Some chipKIT boards that have an external USB chip and typically will not support the ENTER_BOOTLOADER_ON_BOOT option. If this is the case the function will return a false value and your program will continue execution.

This function uses the LAT bit of the program button (if the board has one) as the 'virtual' program button. The bootloader will read this bit upon boot (only after a software reset) to see if it should go into bootload mode or just run the sketch. Availabel Options:

¶Return Value

False, if there is no virtual program button on the board or the bootloader is not supporting this. The True state is never reached as the board goes into bootloader mode before returning.

¶Conforming To

The Task Management Functions are specific to ChipKit and exceed the Arduino 1.6.x specification.

¶Example

This example causes a pulled up button on pin 0 to restart the sketch and a pulled up button on pin 1 to return to bootloader.

void setup() {
  // Setup IO
  pinMode(0, INPUT);
  pinMode(1, INPUT);
  pinMode(PIN_LED1, OUTPUT);

  // Blink the LED once slowly to visualize setup()
  digitalWrite(PIN_LED1, HIGH);
  delay(2000);
  digitalWrite(PIN_LED1, LOW);
  delay(2000);
}

void loop() {
  // Blink the LED fast to visualize loop()
  digitalWrite(PIN_LED1, HIGH);
  delay(300);
  digitalWrite(PIN_LED1, LOW);
  delay(50);

  // execute reset on button press
  if(digitalRead(0) == LOW) executeSoftReset(RUN_SKETCH_ON_BOOT);
  if(digitalRead(1) == LOW) executeSoftReset(ENTER_BOOTLOADER_ON_BOOT);
}

¶See Also

executeSoftReset(), getPeripheralClock(), lockPps(), mapPps(), unlockPps()