6.7. 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.7.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
OK
6.7.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.7.3. TFTP file transfer¶
Only upload, aka “put”, in binary mode is supported.
6.7.4. Examples¶
Here are a few examples of how to upgrade the application using the different supported protocols.
6.7.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.7.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
OK
$ oam/upgrade/application/enter
Welcome to the test application!
6.7.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
OK
$ oam/upgrade/application/erase
OK
$ 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
OK
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)¶ Initialize the upgrade module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
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.