Jump to main content

# 1.1.6 UART Bootloader Host Script Help

Downloading the host script

To clone or download these host tools from Github, go to the main page of this repository and then click Clone button to clone this repo or download as zip file. This content can also be download using MCC content manager.

Path of the tool within the repository is tools/btl_host.py.

Setting up the Host PC

- The script is compatible with Python 3.x and higher

- It requires pyserial package to communicate with device over UART. Use below command to install the pyserial package.

      pip3 install pyserial

Description

- This host script should be used to communicate with the Bootloader running on the device via UART interface

- It is a command line interface and implements the bootloader protocol required to communicate from host PC

- If size of the input binary file is not aligned to device erase boundary it appends 0xFF to the binary to make it aligned and then sends the binary to the device

- It should be used with -s (--swap) option when using bootloader in Fail Safe Update mode to trigger a swap bank and reset

- It should be used with -b (--boot) option with address as 0x0 when updating the bootloader itself on Cortex-M based MCUs

Usage Examples

Below is the syntax to show help menu for the script:

    python <harmony3_path>/bootloader/tools/btl_host.py --help

Bootloader Basic mode syntax and example.

Below syntax and example can be used to program a binary and send a Reset command:

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM PORT> -d <Device Name> -a <address> -f <Application_binary_path>

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i COM18 -d same5x -a 0x2000 -f <harmony3_path>/bootloader_apps_uart/apps/uart_bootloader/test_app/firmware/sam_e54_xpro.X/dist/sam_e54_xpro/production/sam_e54_xpro.X.production.bin

Bootloader Fail Safe Update mode syntax and example.

Below syntax and example can be used to program a binary in Inactive Bank and send a Swap Bank and Reset command:

    python <harmony3_path>/bootloader/tools/btl_host.py -v -s -i <COM PORT> -d <Device Name> -a <Inactive Bank address> -f <Path to application binary>

Example to send Bootloader binary in inactive bank

    python <harmony3_path>/bootloader/tools/btl_host.py -v -s -i COM18 -d same5x -a 0x80000 -f <harmony3_path>/bootloader_apps_uart/apps/uart_fail_safe_bootloader/bootloader/firmware/sam_e54_xpro.X/dist/sam_e54_xpro/production/sam_e54_xpro.X.production.bin

Example to send Application binary in inactive bank

    python <harmony3_path>/bootloader/tools/btl_host.py -v -s -i COM18 -d same5x -a 0x82000 -f <harmony3_path>/bootloader_apps_uart/apps/uart_fail_safe_bootloader/test_app/firmware/sam_e54_xpro.X/dist/sam_e54_xpro/production/sam_e54_xpro.X.production.bin

Example to send the merged binary in inactive bank using btl_host.py

    python <harmony3_path>/bootloader/tools/btl_host.py -v -s -i COM18 -d same5x -a 0x80000 -f <Path_to_merged_binary>/btl_app_merged.bin

Example to send Device Configurations

- Refer to the Bootloader Device Configuration Input section for details on creating the Device Configuration text file

      python <harmony3_path>/bootloader/tools/btl_host.py -v -s -i COM18 -d pic32cm -a 0x800 -f <harmony3_path>/bootloader_apps_uart/apps/trustZone/bootloader/Secure/firmware/pic32cm_ls60_cpro_Secure.X/dist/pic32cm_ls60_cpro/production/pic32cm_ls60_cpro_Secure.X.production.bin -c <path_to_dev_cfg_txt>/devcfg.txt

MPU UART Bootloader syntax and example

Below syntax and example can be used to program a binary and send a Reset command:

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM PORT> -d <Device Name> -f <Application_binary_path>

Example to send Application binary for SD/eMMC media

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM PORT> -d sama5 -f <harmony3_path>/bootloader_apps_uart/apps/mpu_uart_bootloader/test_app/firmware/sam_a5d29_curiosity.X/dist/sam_a5d29_curiosity/production/harmony.bin

Example to send Application binary for Serial Flash media

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM PORT> -d sama5 -p 256 -f <harmony3_path>/bootloader_apps_uart/apps/mpu_uart_bootloader/test_app/firmware/sam_a5d29_curiosity.X/dist/sam_a5d29_curiosity/production/harmony.bin

Example to send Application binary for NAND Flash media

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM PORT> -d sam9x6 -p 4096 -f <harmony3_path>/bootloader_apps_uart/apps/mpu_uart_bootloader/test_app/firmware/sam_9x60_curiosity.X/dist/sam_9x60_curiosity/production/harmony.bin

Factory-Programmed UART Bootloader syntax and example

Below syntax and example can be used to program Application binary and Fuse config binary:

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM PORT> -d <Device Name> -a <address> -u even -f <Application_binary_path> -e <devCfgAddress> -g <Application_fuse_bits_path>

Example to send Application binary and Fuse bits for PIC32CM_SG00

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM_PORT> -d PIC32CM_GC00_SG00 -a 0xc000000 -u even -f <Application_ns_binary_path>/pic32cm_sg00.X.production.unified.bin -e 0xa000000 -g <Application_fuse_bits_path>\devcfg.bin

Example to send Application binary and Fuse bits for PIC32CK_SG01

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM_PORT> -d PIC32CK_GC01_SG01  -a 0xc000000 -u even -f <Application_ns_binary_path>/pic32ck_sg01_cult.X.production.unified.bin -e 0xa000000 -g <Application_fuse_bits_path>\devcfg.bin

Example of factory-programmed bootloader for PIC32CM-LE00

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM_PORT> -d pic32cm -a 0x1000 -u even -f <harmony3_path>\bootloader_apps_pic32cm_le_ls\apps\uart_i2c_bootloader\test_app\firmware\pic32cm_le00.X\dist\pic32cm_le00\production\pic32cm_le00.X.production.bin

Example of factory-programmed bootloader for PIC32CM-LS00

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM_PORT> -d pic32cm -a 0x1400 -u even -f <harmony3_path>\bootloader_apps_pic32cm_le_ls\apps\trustZone\test_app\NonSecure\firmware\pic32cm_ls00_NonSecure.X\dist\pic32cm_ls00\production\pic32cm_ls00_NonSecure.X.production.unified.bin -c <harmony3_path>\bootloader_apps_pic32cm_le_ls\apps\trustZone\images\ls_test_app_bootopt_0_devcfg_out.txt

Example of factory-programmed bootloader for PIC32CZ-CA70

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM_PORT> -d pic32cz -a 0x402000 -u even -f <harmony3_path>bootloader_apps_pic32cz_ca70\apps\uart_i2c_bootloader\test_app\pic32cz_ca70.X\dist\default\production\pic32cz_ca70.X.production.bin

Example of factory-programmed bootloader for PIC32CM JH01 CURIOSITY PRO

    python <harmony3_path>/bootloader/tools/btl_host.py -v -i <COM_PORT> -d pic32cm -a 0x1000 -u even -f <harmony3_path>bootloader_apps_pic32cm_jh00_jh01\apps\uart_i2c_bootloader\test_app\firmware\pic32cm_jh01_curiosity_pro.X\dist\pic32cm_jh01_curiosity_pro\production\pic32cm_jh01_curiosity_pro.X.production.bin

Rev: G