6.5. upgrade — Software upgrade

Upgrade/upload an application over the air (OTA) or using a cable. HTTP, TFTP, Kermit and UDS protocols are supported.

The flash memory is partitioned into two partitions; the bootloader partition and the application partition. The software in the bootloader partition can perform a software upgrade of the application partition by using the erase and write commands.

Warning

The WiFi connection is often lost during the erase operation on ESP32. Troubleshooting ongoing...

6.5.1. Debug file system commands

Five debug file system commands are available, all located in the directory oam/upgrade/.

Command Description
application/enter Enter the appliaction.
application/erase Erase the appliaction. May not be called from the
application about to be erased.
application/is_valid Check is there is a valid application in the memory.
kermit/upload Upload a upgrade binary file using the Kermit file
transfer protocol.
bootloader/enter Enter the bootloader.

Example output from the shell:

$ oam/upgrade/application/is_valid
yes

6.5.2. HTTP requests

Five HTTP requests are available. Form the URL by prefixing them with http://<hostname>/oam/upgrade/, ie. http://<hostname>/oam/upgrade/application/is_valid.

Request Type Description
application/enter GET Enter the appliaction.
application/erase GET Erase the appliaction. May not be called from the
application about to be erased.
application/is_valid GET Check is there is a valid application in the memory.
upload POST Upload a upgrade binary file using the Kermit file
transfer protocol.
bootloader/enter GET Enter the bootloader.

6.5.3. TFTP file transfer

Only upload, aka “put”, in binary mode is supported.

6.5.4. Examples

Here are a few examples of how to upgrade the application using the different supported protocols.

6.5.4.1. HTTP

Build and upload the bootloader to the board over the serial port.

> make -C bootloader -s BOARD=nano32 run

Build the test application and use curl to upload it to the Nano32 over HTTP.

> make -C application -s BOARD=nano32
> cd application/build/nano32
> curl http://192.168.0.7/oam/upgrade/application/is_valid
no
> curl --header "Content-Type: application/octet-stream" \
       --data-binary @application.ubin \
       http://192.168.0.7/oam/upgrade/upload
> curl http://192.168.0.7/oam/upgrade/application/is_valid
yes

Then start it using HTTP.

> curl http://192.168.0.7/oam/upgrade/application/enter
Welcome to the test application!

6.5.4.2. TFTP

Build and upload the bootloader to the board over the serial port.

> make -C bootloader -s BOARD=nano32 run

Build the test application and use tftp to upload it to the Nano32 over TFTP.

> make -C application -s BOARD=nano32
> cd application/build/nano32
> tftp 192.168.0.7
tftp> mode binary
tftp> put application.ubin
5460544 bytes
tftp> q

Then start it using the serial port.

> kermit
C-Kermit>connect
$ oam/upgrade/application/is_valid
yes
$ oam/upgrade/application/enter
Welcome to the test application!

6.5.4.3. Kermit

Build and upload the bootloader to the board over the serial port.

> make -s -C bootloader BOARD=arduino_due run

Build the test application and use Kermit to upload it to the Arduino Due over the serial port.

> make -s -C application BOARD=arduino_due
> cd application/build/arduino_due
> kermit
C-Kermit>connect
$ oam/upgrade/application/is_valid
no
$ oam/upgrade/application/erase
$ oam/upgrade/kermit/upload       # Type '\+c' to return to kermit.
C-Kermit> send application.ubin

Then start it using the serial port.

C-Kermit> connect
$ oam/upgrade/application/is_valid
yes
$ oam/upgrade/application/enter
Welcome to the test application!

Source code: src/oam/upgrade.h, src/oam/upgrade.c, src/oam/upgrade

Test code: tst/oam/upgrade/main.c, tst/oam/upgrade/kermit/main.c, tst/oam/upgrade/uds/main.c

Test coverage: src/oam/upgrade.c, src/oam/upgrade

Example code: examples/upgrade/bootloader/main.c, examples/upgrade/application/main.c


Functions

int upgrade_module_init(void)
int upgrade_bootloader_enter(void)

Enter the bootloader. This function does not return if all preconditions for entering the bootloader are met.

Return
zero(0) or negative error code.

int upgrade_bootloader_stay_set(void)

Stay in the bootloader after next system reboot.

Return
zero(0) or negative error code.

int upgrade_bootloader_stay_clear(void)

Do not stay in the bootloader after next system reboot.

Return
zero(0) or negative error code.

int upgrade_bootloader_stay_get(void)

Check if the bootlaoder is forced to enter its main loop instead of calling any valid application.

Return
true(1) if the bootloder shall not call the application, otherwise false(0).

int upgrade_application_enter(void)

Enter the application. This function does not return if all preconditions for entering the application are met.

Return
zero(0) or negative error code.

int upgrade_application_erase(void)

Erase the application area.

Return
zero(0) or negative error code.

int upgrade_application_is_valid(int quick)

Returns true(1) if there is a valid application in the application area.

Return
true(1) if a valid application exists in the memory region, otherwise false(0).
Parameters
  • quick: Perform a quick validation. The quick validation is port specific, while the non-quick validation always calculates a checksum of the application and compares it to the expected checksum.

int upgrade_binary_upload_begin(void)

Begin an upload transaction of a .ubin file.

Return
zero(0) or negative error code.

int upgrade_binary_upload(const void *buf_p, size_t size)

Add data to current upload transaction.

Return
zero(0) or negative error code.
Parameters
  • buf_p: Buffer to write.
  • size: Size of the buffer.

int upgrade_binary_upload_end(void)

End current upload transaction.

Return
zero(0) or negative error code.