Introduction¶

This wiki page will provide instructions for updating firmware on the mDot and Dragonfly using the MTS bootloader. The MTS bootloader is able to receive new firmware over the debug serial port using the YMODEM protocol, validate the integrity of the new firmware, and program the new firmware into the processor flash.

Bootloader Flow Diagram¶

The following high level flow diagram illustrates how the MTS bootloader works.

Updating Firmware Using the MTS Bootloader CLI¶

To enter CLI mode, connect a terminal emulator to the USB debug port at 115200 8N1 with flow control disabled. Hold down any key on your keyboard and reset the mDot or Dragonfly. You should see the following prompt appear:

bootloader :> 

The bootloader CLI supports a number of commands. Typing "help" on the command line will result in a list of available commands and descriptions being printed.

Follow the following steps to upgrade the firmware on a mDot or Dragonfly using the MTS bootloader CLI and YMODEM.

• Enter bootloader CLI mode as described above
• Type "upgrade ymodem" and press the enter key
• Begin the YMODEM transfer of the new firmware on the debug port
  • For minicom:
    1. Type <CTRL> A then <SHIFT> S to enter the "Upload" menu
    2. Select "ymodem" by using the Up/Down arrows or J/K keys and press <Enter>
    3. Select the new firmware by using the Up/Down arrows or J/K keys to navigate, double tapping the spacebar to enter a directory, single tapping the spacebar to highlight a file, and press <Enter>
    4. A box should pop up displaying the status of the transfer
    5. When the transfer is complete, press <Enter>
  • For Tera Term:
    1. Select File->Transfer->YMODEM->Send
    2. Select the new firmware using the file browser that pops up
    3. A box should pop up displaying the status of the transfer
    4. When the transfer is complete, the status box should disappear
• The new firmware is now stored in the filesystem on the external SPI flash with the name "fw_upgrade.bin"
• The bootloader will verify the new firmware by running a checksum and comparing it to a checksum embedded in the firmware
• After the verification succeeds, the bootloader will erase the application region of flash, which erases the old application
• The bootloader will then write the new application to the application region of flash
• After the new application is written to the processor's flash, it is deleted from the filesystem

The bootloader logs out the debug port while it is upgrading the application.

After the upgrade process is complete, the bootloader will automatically reset the system which will start executing the new application.

Updating Firmware from User Applications¶

Updating firmware on a mDot or Dragonfly from the application involves 3 major steps:

1. Get the new firmware into the filesystem on the external SPI flash and name the file properly
2. Soft reset the system
3. The bootloader sees the new firmware and upgrades the user application

Move New Firmware Into the Filesystem

It is the responsibility of the application to get the new firmware into the filesystem. This can be done using the SPI flash driver and the spiffs filesystem driver on the Dragonfly. An example program demonstrating how to use the filesystem can be found here. The new firmware must be saved with the name "fw_upgrade.bin" in order for the bootloader to detect it.

On the mDot, the filesystem API in libmDot should be used. The function moveUserFileToFirmwareUpgrade() should be used to properly rename the file so it will be detected by the bootloader.

Soft Reset the System

After the new firmware is in place in the filesystem and correctly named, invoke a soft reset so the bootloader executes and finds the new firmware. On mDot devices, the resetCpu() function should be used. On Dragonfly devices, the HAL_NVIC_SystemReset() function should be used.

Bootloader Sees New Firmware and Upgrades

After reset, the bootloader will execute and detect the new firmware. It goes through the following steps in the upgrade process:

• The bootloader will verify the new firmware by running a checksum and comparing it to a checksum embedded in the firmware
• The bootloader will back up the current application into the filesystem on the external SPI flash
• After the current firmware is backed up, the bootloader will erase the application region of flash, which erases the old application
• Then the bootloader will then write the new application to the application region of flash
• After the new application has been successfully written to the application region of flash, the bootloader will clean up by deleting the new firmware and the backup of the old firmware from the filesystem on the external SPI flash
• The bootloader will initiate a soft reset, which will begin execution of the new application

The bootloader logs out the debug port while it is upgrading the application.

If programming the new firmware fails, the bootloader will attempt to restore the old firmware to prevent bricking the device.