Device Firmware Update

group index

Overview

The purpose of the DFU middleware library is to provide an SDK for updating firmware images. The middleware allows creating two types of projects:

  1. An application loader receives the program and switch to the new application.

  2. A loadable application to be transferred and programmed.

A project can contain features of both first and second type.

General Description

Include cy_dfu.h to get access to all functions and other declarations in this library.

The DFU SDK has the following features:

  • Read firmware images from a host through a number of transport interfaces, e.g. BLE, USB, UART, I2C, SPI.

  • Program a firmware image to the specified address in internal flash, XIP region, or any external memory that supports the DFU API.

  • Copy applications.

  • Validate applications.

  • Safe Update: updates at a temporary location, validates, and if valid, overwrites a working image.

  • Switches applications. Passes parameters in RAM when switching applications.

  • Supports encrypted image files. Transfers encrypted images without decrypting in the middle.

  • Supports many application images, the number of which is limited only by the metadata size. Each image can be an application loader. For example, 512-byte metadata supports up to 63 applications.

  • Supports customization.

  • Supports the CRC-32 checksum to validate data.

Quick Start Guide

The DFU SDK is used to design updating applications of arbitrary flexibility and complexity. Cypress DFU middleware can be used in various software environments. Refer to RELEASE.md file for details. To quick start, use the Code Examples. Cypress Semiconductor continuously extends its portfolio of code examples at Cypress Semiconductor website and Cypress Semiconductor GitHub.

The Quick Start Guide (QSG) assumes ModusToolbox 2.2 is installed with all needed tools.

The following steps are to set up and build a basic DFU loader and loadable applications. The DFU loader application uses the I2C transport interface. The steps assume that the user builds an application for CY8CKIT-062-WIFI-BT or CY8CKIT-149 kits based on a starter Hello_World ModusToolbox project.

STEP 0: Projects preparation.

  1. Create a project for CY8CKIT-062-WIFI-BT or CY8CKIT-149 with the DFU loader application using the Hello_World starter application. Name it QSG_DFU_App0_I2C. See the ModusToolbox 2.2 IDE Quick Start Guide for the detail steps.

  2. Create a project for the DFU loadable application in the same way and name it QSG_DFU_App1_Hello_World.

  3. Include the DFU middleware into each project using the ModusToolbox Library Manager or download it from GitHub and copy it to the project manually. When Library Manager is used, it is recommended to check Shared checkbox against DFU middleware, so it will be downloaded once and then shared between all applications in the workspace.

  4. Include a DFU header in main.c of each project to get access to DFU API:

    #include "cycfg.h"
    #include "cy_dfu.h"
    

STEP 1: Setup Loader Application QSG_DFU_App0_I2C

  1. Copy the configuration files dfu_user.c and dfu_user.h from the DFU config folder and put them near main.c:

    • For CY8CKIT-062-WIFI-BT kit:

      • copy dfu_user.h file from ..\mtb_shared\dfu\[VERSION]\config

      • copy dfu_user.c file from ..\mtb_shared\dfu\[VERSION]\config\CAT1A

    • For CY8CKIT-149 kit:

      • copy dfu_user.h file from ..\mtb_shared\dfu\[VERSION]\config

      • copy dfu_user.c file from ..\mtb_shared\dfu\[VERSION]\config\CAT2

  2. Copy the transport files from the config directory and put them near main.c. In our case, I2C requires transport_i2c.h and transport_i2c.c, which are located in the following directories:

    • For CY8CKIT-062-WIFI-BT kit: ..\mtb_shared\dfu\[VERSION]\config\CAT1A

    • For CY8CKIT-149 kit: ..\mtb_shared\dfu\[VERSION]\config\CAT2

  3. Copy the app0 linker script files and put them near main.c:

    • For CY8CKIT-062-WIFI-BT kit:

      ..\mtb_shared\dfu\[VERSION]\linker_scripts\CAT1A\TOOLCHAIN_<COMPILER>\dfu_cm4_app0.[ext]

    • For CY8CKIT-149 kit:

      ..\mtb_shared\dfu\[VERSION]\linker_scripts\CAT2\TOOLCHAIN_<COMPILER>\dfu_cm0p_app0.[ext]

    For example, for CY8CKIT-062-WIFI-BT kit and GCC ARM compiler, copy ..\mtb_shared\dfu\[VERSION]\linker_scripts\CAT1A\TOOLCHAIN_GCC_ARM\dfu_cm4_app0.ld file.

    note

    For ARM compiler, copy additional dfu_common.h and dfu_elf_symbols.c files to the project. Those files are located in the same folder as the selected linker file.

  4. Copy folder from ..\mtb_shared\TARGET_[KIT_NAME]\[VERSION]\COMPONENT_BSP_DESIGN_MODUS to the project root and rename it to DFU_DESIGN_MODUS.

  5. Update project’s Makefile to use Generated sources, created in DFU_DESIGN_MODUS folder: locate DISABLE_COMPONENTS variable and add BSP_DESIGN_MODUS:

    DISABLE_COMPONENTS=BSP_DESIGN_MODUS 
    

  6. Open DFU_DESIGN_MODUS\design.modus file and configure SCB for I2C communication using ModusToolbox Device Configurator.

    For CY8CKIT-062-WIFI-BT use SCB 3, which is connected to the KitProg. For CY8CKIT-149, SCB 1 is connected to the KitProg.

    SCB parameter name

    value

    Personality

    I2C

    Name

    DFU_I2C

    Mode

    Slave

    Data Rate (kbps)

    100

    Slave Address (7-bit)

    12

    warning

    SCB personality must be I2C and name must be DFU_I2C.

    See

    Use of ModusToolbox’s tools for HW initialization../../../../_images/dfu_basic_i2c.png

STEP 2: Update Loader QSG_DFU_App0_I2C main.c

  1. Include a DFU reset handler to start the appropriate application after a reset:

    /*******************************************************************************
    * Function Name: Cy_OnResetUser
    ********************************************************************************
    *
    *  This function is called at the start of Reset_Handler(). 
    *  DFU requires it to call Cy_DFU_OnResetApp0() in app#0.
    *
    *******************************************************************************/
    void Cy_OnResetUser(void)
    {
        Cy_DFU_OnResetApp0();
    }
    

  2. Initialize the variables and call the DFU initialization function:

        /*
        * Used to count seconds
        */
        uint32_t count = 0;
    
        /* Status codes for DFU API */
        cy_en_dfu_status_t status;
    
        /*
        * DFU state, one of the:
        * - CY_DFU_STATE_NONE
        * - CY_DFU_STATE_UPDATING
        * - CY_DFU_STATE_FINISHED
        * - CY_DFU_STATE_FAILED
        */
        uint32_t state;
    
        /* Timeout for Cy_DFU_Continue(), in milliseconds */
        const uint32_t paramsTimeout = 20u;
        
        /* Buffer to store DFU commands */
        CY_ALIGN(4) static uint8_t buffer[CY_DFU_SIZEOF_DATA_BUFFER];
    
        /* Buffer for DFU data packets for transport API */
        CY_ALIGN(4) static uint8_t packet[CY_DFU_SIZEOF_CMD_BUFFER ];
    
        /* DFU params, used to configure DFU */
        cy_stc_dfu_params_t dfuParams;
    
        /* Initialize dfuParams structure */
        dfuParams.timeout          = paramsTimeout;
        dfuParams.dataBuffer       = &buffer[0];
        dfuParams.packetBuffer     = &packet[0];
    
        status = Cy_DFU_Init(&state, &dfuParams);
        
        /* Stop program execution if DFU init failed */
        CY_ASSERT(CY_DFU_SUCCESS == status);
        
        /* Set up the device based on configurator selections */
        init_cycfg_all();
    
        /* enable interrupts */
        __enable_irq();
    

  3. Initialize the DFU transport layer:

        /* Initialize DFU communication */
        Cy_DFU_TransportStart();
    

  4. Update the main loop with the Host Command/Response protocol processing:

            status = Cy_DFU_Continue(&state, &dfuParams);
            ++count;
    
            if (state == CY_DFU_STATE_FINISHED)
            {
               /* Finished loading the application image */
    
               /* Validate DFU application, if it is valid then switch to it */
               status = Cy_DFU_ValidateApp(1u, &dfuParams);
               if (status == CY_DFU_SUCCESS)
               {
                   Cy_DFU_TransportStop();
                   Cy_DFU_ExecuteApp(1u);
               }
               else if (status == CY_DFU_ERROR_VERIFY)
               {
                   /*
                   * Restarts loading, an alternatives are to Halt MCU here
                   * or switch to the other app if it is valid.
                   * Error code may be handled here, i.e. print to debug UART.
                   */
                   status = Cy_DFU_Init(&state, &dfuParams);
                   Cy_DFU_TransportReset();
               }
            }
            else if (state == CY_DFU_STATE_FAILED)
            {
               /* An error has happened during the loading process */
               /* Handle it here */
    
               /* In this Code Example just restart loading process */
               status = Cy_DFU_Init(&state, &dfuParams);
               Cy_DFU_TransportReset();
            }
            else if (state == CY_DFU_STATE_UPDATING)
            {
               uint32_t passed5seconds = (count >= (5000ul/paramsTimeout)) ? 1u : 0u;
               /*
               * if no command has been received during 5 seconds when the loading
               * has started then restart loading.
               */
               if (status == CY_DFU_SUCCESS)
               {
                   count = 0u;
               }
               else if (status == CY_DFU_ERROR_TIMEOUT)
               {
                   if (passed5seconds != 0u)
                   {
                       count = 0u;
                       Cy_DFU_Init(&state, &dfuParams);
                       Cy_DFU_TransportReset();
                   }
               }
               else
               {
                   count = 0u;
                   /* Delay because Transport still may be sending error response to a host */
                   Cy_SysLib_Delay(paramsTimeout);
                   Cy_DFU_Init(&state, &dfuParams);
                   Cy_DFU_TransportReset();
               }
            }
    

  5. Update the main loop with a routine to switch to the loaded QSG_DFU_App1_Hello_World application:

    For example, to switch by pressing the kit user button:

    • In the Device Configurator, enable pin 0[4] for CY8CKIT-062-WIFI-BT and pin 3[7] for CY8CKIT-149 and name it PIN_SW

    • Set/check the pin configuration:

      Parameter name

      Value

      Driver Mode

      Resistive Pull-Up. Input buffer on

      Initial Drive State

      High(1)

      ../../../../_images/dfu_qsg_btn.png

    • Add the following routine:

              /* If Button clicked - Switch to App1 if it is valid */
              if (Cy_GPIO_Read(PIN_SW_PORT, PIN_SW_PIN) == 0u)
              {
                 /* 50 ms delay for button debounce on button press */
                 Cy_SysLib_Delay(50u);
      
                 if (Cy_GPIO_Read(PIN_SW_PORT, PIN_SW_PIN) == 0u)
                 {
                     while (Cy_GPIO_Read(PIN_SW_PORT, PIN_SW_PIN) == 0u)
                     {   /* 50 ms delay for button debounce on button release */
                         Cy_SysLib_Delay(50u);
                     }
      
                     /* Validate and switch to App1 */
                     status = Cy_DFU_ValidateApp(1u, &dfuParams);
      
                     if (status == CY_DFU_SUCCESS)
                     {
                         Cy_DFU_TransportStop();
                         Cy_DFU_ExecuteApp(1u);
                     }
                 }
              }
      

  6. Update the application to turn on the kit blue LED to indicate successful DFU initialization:

    • In the Device Configurator, enable pin 11[1] for CY8CKIT-062-WIFI-BT and pin 3[4] for CY8CKIT-149 and name it PIN_LED

    • Set/check the pin configuration:

      Parameter name

      Value

      Driver Mode

      Strong Drive. Input buffer off

      Initial Drive State

      High(1)

    • Add the following code before the main loop:

          Cy_GPIO_Write(PIN_LED_PORT, PIN_LED_PIN, 0U);
      

STEP 3: Build and Program Loader QSG_DFU_App0_I2C

  1. Update the project Makefile to use the previously copied DFU linker script by setting the LINKER_SCRIPT variable.

    • CY8CKIT-062-WIFI-BT + GCC_ARM:

      LINKER_SCRIPT=dfu_cm4_app0.ld 
      

    • CY8CKIT-149 + GCC_ARM:

      LINKER_SCRIPT=dfu_cm0p_app0.ld 
      

  2. Add a post-build step to sign the ELF file or sign it manually after the build: <MCUELFTOOL> sign <app>.elf output <app_signed>.elf hex <app_signed>.hex.

    For the macOS/Linux platform:

    POSTBUILD=$(CY_MCUELFTOOL_DIR)/bin/cymcuelftool --sign $(CY_CONFIG_DIR)/$(APPNAME).elf --hex $(CY_CONFIG_DIR)/$(APPNAME).hex
    
    For the Windows platform:
    POSTBUILD="$(CY_MCUELFTOOL_DIR)/bin/cymcuelftool.exe" --sign $(CY_CONFIG_DIR)/$(APPNAME).elf --hex $(CY_CONFIG_DIR)/$(APPNAME).hex
    

  3. Connect your kit to the computer. Build and program the device.

  4. Observe the kit blue LED on.

STEP 4: Setup Loadable QSG_DFU_App1_Hello_World

  1. Copy the configuration file dfu_user.h from the ..\mtb_shared\dfu\[VERSION]\config directory and put it near main.c in the project root.

    warning

    Do not copy dfu_user.c to avoid duplication of the metadata structures.

  2. Copy the app1 linker script file and put them near the main.c. Linker script files are located at:

    • CY8CKIT-062-WIFI-BT kit:

      ..\mtb_shared\dfu\[VERSION]\linker_scripts\CAT1A\TOOLCHAIN_<COMPILER>\dfu_cm4_app1.[ext]

    • CY8CKIT-149 kit:

      ..\mtb_shared\dfu\[VERSION]\linker_scripts\CAT2\TOOLCHAIN_<COMPILER>\dfu_cm0p_app1.[ext] For the GCC ARM compiler, copy dfu_cm4_app0.ld (CY8CKIT-062-WIFI-BT kit) of dfu_cm0p_app0.ld file (CY8CKIT-149 kit).

      note

      For the ARM compiler, copy additional dfu_common.h and dfu_elf_symbols.c files to the project. Those files are located in the same folder as the selected linker file.

STEP 5: Update Loadable QSG_DFU_App1_Hello_World main.c

  1. Update the main.c file with the .cy_app_signature section

    CY_SECTION(".cy_app_signature") __USED static const uint32_t cy_dfu_appSignature[1];
    

STEP 6: Build and Program Patch

  1. Update the project Makefile to use previously copied DFU linker script by setting the LINKER_SCRIPT variable.

    • CY8CKIT-062-WIFI-BT + GCC_ARM:

      LINKER_SCRIPT=dfu_cm4_app1.ld 
      

    • CY8CKIT-149 + GCC_ARM:

      LINKER_SCRIPT=dfu_cm0p_app1.ld 
      

  2. Add the post build step to run CyMCUElfTool to generate a patch file in the *.cyacd2 format (see CyMCUElfTool User Guide):

    • Update the application ELF with a CRC checksum: <MCUELFTOOL> sign app.elf CRC output app_crc.elf

    • Generate a patch file: <MCUELFTOOL> -P app_crc.elf output app.cyacd2

    Generate a *.cyacd2 file in the project root.

    For the macOS/Linux platform:

    POSTBUILD=$(CY_MCUELFTOOL_DIR)/bin/cymcuelftool --sign $(CY_CONFIG_DIR)/$(APPNAME).elf CRC --output $(APPNAME)_crc.elf && \
           $(CY_MCUELFTOOL_DIR)/bin/cymcuelftool -P $(APPNAME)_crc.elf --output $(APPNAME)_crc.cyacd2
    
    For the Windows platform:
    POSTBUILD="$(CY_MCUELFTOOL_DIR)/bin/cymcuelftool.exe" --sign $(CY_CONFIG_DIR)/$(APPNAME).elf CRC --output $(APPNAME)_crc.elf && \
           "$(CY_MCUELFTOOL_DIR)/bin/cymcuelftool.exe" -P $(APPNAME)_crc.elf --output $(APPNAME)_crc.cyacd2
    

  3. Build a project.

  4. Open the DFU Host Tool. Connect to the device. Select the generated .cyacd2 in the project root and program it to the device. ../../../../_images/dfu_qsg_hti2c.png

  5. QSG_DFU_App1_Hello_World application should start after successful programming. Observe the LED blinking and UART output.

  6. Update the QSG_DFU_App1_Hello_World application (e.g. change blinking led frequency or UART output) and build it.

  7. Press the kit reset button to return to the loader application and program the updated QSG_DFU_App1_Hello_World. Observe the project updated behavior.

    note

    Current application can be changed from the firmware by calling the Cy_DFU_ExecuteApp function.

Configuration Considerations

Linker scripts

The DFU SDK projects linker scripts differ from the default startup linker scripts.

The DFU middleware contains two sets of linker script files for the CAT1A and CAT2-based devices. The DFU linker scripts include the following files:

  • CAT1A:

    • dfu_cm4_app0.{ld, icf, scat}, dfu_cm4_app1.{ld, icf, scat} for ARM GCC, IAR, and ARM compilers.

    • dfu_common.h and dfu_elf_symbols.c for the ARM compiler.

  • CAT2:

    • dfu_cm0p_app0.{ld, icf, scat}, dfu_cm0p_app1.{ld, icf, scat} for ARM GCC, IAR, and ARM compilers.

    • dfu_common.h and dfu_elf_symbols.c for the ARM compiler.

These files define the symbols for the memory layout for each application inside the device.

This part of the GCC linker script files must have the same memory layout across all the application projects in the designed device. Any changes made to any application must be copied to other applications linker script files.

Memory layout of GCC_ARM linker scripts (dfu_{cm0p, cm4}_{app0, app1}.ld)

Memory regions:

  • flash_app{X} - Code and data of the user application {X}.

  • flash_boot_meta - For the DFU SDK metadata. Cypress DFU SDK code examples place DFU SDK metadata inside this region.

  • ram_common - Shared between the DFU SDK applications. The user can place it anywhere inside the RAM, So, one app sets some values there, switches to another app. Then app may read or update the values.

  • ram_app{X} - data, stack, heap etc. for the user app{X}.

Also, the linker script files for CAT1A include the following memory regions:

  • flash_cm0p - Code and data of the default application CM0+ CPU.

  • sflash_user_data, eFuse, flash_toc, em_eeprom, xip - These regions are not used by typical DFU SDK code examples. They are kept because they may be used in user code.

ELF file symbols: CyMCUElfTool uses special ELF file symbols besides the command-line arguments for its configuration. These symbols are defined in each linker script.

  1. __cy_memory_{N}_start - Defines the start address of the memory region. __cy_memory_{N}_length - Defines the length of the memory region. __cy_memory_{N}_row_size - Defines the row size of the memory region.

    CyMCUElfTool uses these symbols to determine which memory regions to place into the output files. I.e. without these symbols, some data, like XIP may be absent in the output file. These symbols are critical for the .cyacd2 file generation, CyMCUElfTool must know the row size of all the data being exported to the .cyacd2 file. The updating is done by rows, and a row size may vary across the memory regions.

    E.g. The internal flash of PSoC6 devices start at address 0x1000_0000 and the length and row size may be device-dependent. For example, if the length and size are 512KB and 512 bytes, the memory symbols for the internal flash will be:

    __cy_memory_0_start    = 0x10000000;
    __cy_memory_0_length   = 512 * 1024;
    __cy_memory_0_row_size = 512;
    

    The number _{N}_ in the memory symbol indicates that there may be multiple memories.

  2. __cy_boot_metadata_addr and __cy_boot_metadata_length. These symbols are used by the DFU SDK internally to access the metadata.

  3. __cy_product_id - used by CyMCUElfTool to be placed in the .cyacd2 header. This value is used by the updating Host and DFU SDK firmware to confirm that the .cyacd2 file being updated is compatible with the device.

    E.g. The user may have two different devices with the same PSoC6 chip:

    • A coffee machine, with Product ID - 0x1000_0001.

    • A nuclear power plant control device with Product ID - 0x1000_0002. The user of a coffee machine tries to update firmware for a nuclear power plant control device, and the DFU Host will indicate that the device rejected this firmware because of the wrong Product ID.

  4. __cy_app{N}_verify_start, __cy_app{N}_verify_length. These symbols are used by the dfu_user.c file to initialize the metadata. Their value is automatically updated by the linker when the user updates the memory layout (memory regions).

    If the user decides to use a different mechanism for the SDK metadata initialization, these symbols can be removed.

  5. __cy_boot_signature_size. Used by the DFU SDK linker scripts only. It helps avoiding the magic number for a signature size to be scattered throughout all the linker scripts. E.g.

    • For the CRC-32C application signature, the value of this symbol is 4 (bytes).

    • For RSASSA-PCKS-1-v1.5 with RSA 2048, the value is 256 (bytes).

  6. __cy_checksum_type. The checksum type for the DFU transport packet verification used by CyMCUElfTool to generate a updating file. Must be aligned with CY_DFU_OPT_PACKET_CRC

This file is a linker script for the app0 for DFU SDK applications.

File dfu_{cm0p, cm4}_app0.ld

It is similar to the default startup GCC’s linker script but contains the following changes:

  1. The memory regions are separated between the CPU application 0 and CPU application 1 described above. For CAT1A devices, there is an additional region for the CM0+ application.

  2. The DFU-specific ELF file symbols are described above.

  3. __cy_app_id. These ELF file symbols are used by CyMCUElfTool to set an application ID in the .cyacd2 file header.

  4. __cy_app_verify_start, __cy_app_verify_length. These two symbols are used by CyMCUElfTool to generate an application signature. The first symbol provides a value of the start of signed memory and the second - the length of signed memory.

  5. Section “.cy_boot_noinit”. Used to place data to share between the applications. See the description of the ram_common memory region.

  6. Section “.cy_boot_metadata”. Contains the DFU SDK metadata. This section name is necessary only for CyMCUElfTool to sign the section with the CRC-32C checksum of this section data. If no CRC-32C at the end of the metadata is required, the section can be renamed.

  7. Section .cy_app_signature. This section is used to place an application signature. The signature is used by the DFU SDK to verify that the application is valid. Typically, CRC, SHA or any other hash of the application code and data is placed here. CyMCUElfTool updates this section in the post-build step. The memory for which the signature is calculated is defined by the following ELF file symbols: __cy_app_verify_start, __cy_app_verify_length.

Used to create linker scripts for application #2, .. #N It is similar to dfu_{cm0p, cm4}_app0.ld linker script, but contains the following changes:

  • Region alias for flash and ram are flash_app1 and ram_app1

  • Application ID __cy_app_id = 1

  • For CAT1A devices, removed section for CM0+ CPU as it is allocated only once in scope of the linker script dfu_cm4_app0.ld

File dfu_{cm0p, cm4}_app1.ld

These files are the linker scripts for the IAR and ARM compilers for the DFU SDK applications.

Files dfu_{cm0p, cm4}_{app0, app1}.{icf, scat}

Their difference from the default startup linker scripts is similar to the DFU SDK GCC’s linker scripts described above.

Use of ModusToolbox’s tools for HW initialization

The following section describes the communication interfaces settings in the Device Configurator, required to use the included with DFU middleware communication files with the DFU Host tool.

note

The personality alias name must be DFU_USB_CDC

../../../../_images/dfu_usb_cdc.png
I2C

Parameter name

value

Personality alias name

DFU_I2C

Mode

Slave

Data Rate

Any, I2C speed in DFU Host tool should be the same

Use TX FIFO

True

Use RX FIFO

True

Slave Address

Any, I2C address in DFU Host tool should be the same

SPI

Parameter name

value

Personality alias name

DFU_SPI

Mode

Slave

Sub Mode

Motorola

SCLK Mode

Any, Sub Mode in DFU Host tool should be the same

Data Rate

Any, Clock speed in DFU Host tool should be the same

Bit Order

Any, Shift direction in DFU Host tool should be the same

RX Data Width

8

TX Data Width

8

SS Polarity

Active Low

UART

Parameter name

value

Personality alias name

DFU_UART

Com Mode

Standard

Baud Rate

Any, Baud Rate in DFU Host tool should be the same

Bit Order

LSB first

Data Width

8 bits

Parity

Any, Parity in DFU Host tool should be the same

Stop Bits

Any, Stop Bits in DFU Host tool should be the same

USB CDC

For a setup of the USB device personality in the ModusToolbox Device Configurator for the USB CDC DFU transport for CY8CKIT-062-WIFI-BT, see the screenshot below. For other kits, verify the USB pins.

../../../../_images/dfu_ble.png

BLE

For a setup of the BLE device personality in the ModusToolbox Device Configurator for the BLE DFU transport, see the screenshot below.

Design Considerations

Firmware Update via I2C

See Quick Start Guide for steps how to set up a DFU project that upgrades an application via a I2C transport interface.

Firmware Update via UART

See Quick Start Guide for basic steps how to setup a DFU project. Specific steps for the UART transport support:

  • Include transport_uart.c and transport_uart.h in the project build flow. For example, copy from the \config\CAT1A or \config\CAT2 or directory to the directory with the main.c file. Ensure that other transport files are not included in the build flow.

  • Select and configure the SCB block using the ModusToolbox Device Configurator see Use of ModusToolbox’s tools for HW initialization or manually using the configuration structures.

  • Add the post-build step to sign the ELF file or sign it manually after the build

    <MCUELFTOOL> --sign app.elf --output app_signed.elf
    

  • Build and program a project into the device.

  • Open the DFU Host Tool. Select the UART interface. Set the UART baud rate according to the SCB UART setup in the previous step.

  • Select the *.cyacd2 application image and upload to the device.

Firmware Update via SPI

See Quick Start Guide for basic steps how to set up a DFU project. The steps for the SPI transport support:

  • Include transport_spi.c and transport_spi.h in the project build flow. For example, copy them from the \config\CAT1A or \config\CAT2 directory to the directory with the main.c file. Ensure that other transport files are not included in the build flow.

  • Select and configure the SCB block. This could be done using ModusToolbox Device Configurator see Use of ModusToolbox’s tools for HW initialization or manually using the configuration structures.

  • Add the post-build step to sign the ELF file or sign it manually after the build

    <MCUELFTOOL> --sign app.elf --output app_signed.elf
    

  • Build and program a project into the device.

  • Open the DFU Host Tool. Select the SPI interface. Set SPI mode, shift the direction and speed according to the SCB SPI setup in the previous step.

  • Select the *.cyacd2 application image and upload to the device.

Firmware Update via USB CDC

See Quick Start Guide for basic steps how to setup a DFU project. Specific steps for the USB CDC transport support:

  • Include transport_usb_cdc.c and transport_usb_cdc.h in the project build flow. For example, copy them from the \config\CAT1A directory to the directory with the main.c file. Ensure that other transport files are not included in the build flow.

  • Enable and configure the USB Device block using the ModusToolbox Device Configurator see Use of ModusToolbox’s tools for HW initialization or manually using the configuration structures.

  • Generate USB descriptors and USB Middleware structures using the USB Configurator. Open the USB configuration file (cycfg_usb_cdc.cyusbdev) in the DFU \config\CAT1A folder, then click Save to generate configuration files (cycfg_usbdev.c and cycfg_usbdev.h). These files must be included in the build flow (see USB Middleware API Reference More Information).

  • Add the post-build step to sign the ELF file or sign it manually after the build

    <MCUELFTOOL> --sign app.elf --output app_signed.elf
    

  • Build and program a project into the device. Connect your Host to the USB device.

  • Open the DFU Host Tool. Select the UART interface, because the Host recognizes the USB device as a virtual UART (the name is DFU USB CDC transport). UART settings: baud rate - 115200, data bits - 8, stop bits - 1, parity - None.

  • Select the *.cyacd2 application image and upload to the device.

Firmware Update via BLE (Over-the-Air)

See Quick Start Guide for basic steps how to set up a DFU project. Also, see code example CE216767 Specific steps for the USB BLE transport support:

  • Include transport_ble.c and transport_ble.h in the project build flow. For example, copy them from the \config\CAT1A directory to the directory with the main.c file. Ensure that other transport files are not included in the build flow.

  • Enable and configure the BLE Device block using the ModusToolbox Device Configurator see Use of ModusToolbox’s tools for HW initialization or manually using the configuration structures.

  • Generate BLE Middleware configuration structures. Open the BLE configuration file (cycfg_ble.cybt) in Bluetooth Configurator. The file is located in the DFU \config\CAT1A folder. Then click Save to generate configuration files (cycfg_ble.c and cycfg_ble.h). These files must be included in the build flow (BLE Middleware API Reference More Information).

  • Add the post build step to sign the ELF file or sign it manually after the build

    <MCUELFTOOL> --sign app.elf --output app_signed.elf 
    

  • Build and program the project into the device.

  • Open CySmart. There are two versions: for Windows PC platforms and mobile application see More Information). Scan for devices and select your BLE device in the list (should be OTA DFU).

  • Click Update Firmware -> Application only update. Select the *.cyacd2 application image and upload to the device

Change checksum types

DFU supports two types of checksums:

  • transport packet checksum

  • application image checksum.

For a packet, DFU supports 2 types of checksums: Basic summation and CRC-16CCITT. The basic summation checksum is computed by adding all the bytes (excluding the checksum) and then taking the 2’s complement. CRC-16CCITT - the 16-bit CRC using the CCITT algorithm. The packet checksum type is selected with a macro CY_DFU_OPT_PACKET_CRC in dfu_user.h file: 0 - basic summation (default), 1 - for CRC-16.

For an application image, DFU supports 2 types of checksums: CRC-32 and SHA1. SHA1 is calculated with a crypto hardware block, which is available only on CAT1A devices. The default application checksum is CRC-32. The steps to set the SHA1 checksum for an application image:

  • Set CY_DFU_OPT_CRYPTO_HW macro to 1 in dfu_user.h file to enable the SHA1 calculation.

  • Symbol __cy_checksum_type = 0x01 in Linker scripts for each application for ARM GCC and IAR compiler. Set macro CY_CHECKSUM_TYPE to 1 in dfu_common.h for the ARM compiler.

  • Symbol __cy_boot_signature_size = 20 in Linker scripts for each application for the ARM GCC and IAR compilers. Set macro CY_BOOT_SIGNATURE_SIZE to 20 in dfu_common.h for the ARM compiler.

  • Configure and start crypto a server and crypto client (see PDL API Reference in More Information) in the loader application main routine.

  • Allocate the “.cy_app_signature” section with a 20-byte array in the main of the loading application.

Multi-application DFU project

The DFU design does not limit the number of applications but it is limited by memory size and metadata size. The maximum size of DFU metadata is limited to the size of the flash row, because metadata should be in a single flash row. For example, the 512-byte metadata supports up to 63 applications. An arbitrary number of applications can be protected from overwriting. Such a protected application is called “Golden Image”. See Quick Start Guide for a steps to setup basic 2 application DFU projects. The following steps show how to set up a 3rd application. The same approach can be used to setup 4th - Nth applications.

  • Define the sizes for each of the three applications and define the start and size of each memory region (flash, RAM) for each application.

  • Copy the linker script dfu_cm4_app1 from DFU linker_scripts folder according to the selected compiler and rename it (for example dfu_cm4_app2).

  • Add flash and RAM sections to the 3rd application. Name them flash_app2, ram_app2.

  • Update the size and start address for each section in each linker script based on the defined in the first step allocation.

  • Set __cy_app_id symbol to 2

  • Update the region aliases for flash and RAM to use flash_app2 and ram_app2 accordingly:

    REGION_ALIAS("flash", flash_app2);
    REGION_ALIAS("ram",     ram_app2);
    

  • Add symbols __cy_app2_verify_start and __cy_app2_verify_length for metadata initialization in the same way as for application 0 and 1.

  • Add a macro to the dfu_user.h CY_DFU_APP2_VERIFY_START and CY_DFU_APP2_VERIFY_LENGTH in the same way as for application 0 and 1

  • Add to the cy_dfu_metadata array of the dfu_user.c CY_DFU_APP2_VERIFY_START and CY_DFU_APP2_VERIFY_LENGTH to update the metadata with the 3rd application.

  • Update you build scripts to use the dfu_cm4_app2 linker script.

Protect the application image by setting parameters in the dfu_user.h file of the loader project: CY_DFU_OPT_GOLDEN_IMAGE set to 1 to enable the Golden Image functionality. CY_DFU_GOLDEN_IMAGE_IDS lists the number of images that to be protected.

Creation of the CYACD2 file

The .cyacd2 file contains downloadable application data created by CyMCUElfTool and used by host programs such as Cypress DFU Host Program and CySmart to send applications to the target DFU module (see More Information). Refer to the AN213924 DFU SDK User Guide for the .cyacd2 file format. See the Loadable Application Setup section of the Quick Start Guide for the steps to convert a general application into a DFU loadable application.

The steps to create a .cyacd2 file with a CRC application signature:

  1. Copy the path to the CyMCUElfTool binary. The path can be found in the folder with ModusToolbox tools (for example /ModusToolbox/tools_2.0/cymcuelftool-1.0/bin/cymcuelftool).

  2. Update the application ELF with a CRC checksum (<MCUELFTOOL> - the copied path to the binary):

    <MCUELFTOOL> --sign app.elf CRC --output app_crc.elf 
    

  3. Generate a .cyacd2 file:

    <MCUELFTOOL> -P app_crc.elf --output app.cyacd2 
    

These commands can be added as post build steps to the build Makefile.

For the SHA1 application signature, use command (Change checksum types):

<MCUELFTOOL> --sign app.elf SHA1 --output app_crc.elf 

Changelog

Version

Changes

Reason for Change

4.10

Added PSoC 4 devices support.

Extended device support.

Added MISRA-C:2012 compliance.

MISRA standard compliance.

Updated SPI communication timeout granularity.

Fixed SPI communication issue.

4.0

Updated the linker scripts to use the single pre-compiled CM0p image. The upgradeable part of the image is the CM4 application.

Support ModusToolbox v2.0 build flow.

Added the ARM compiler version 6 support (version 5 is not supported).

Added the USB interface (virtual COM port) transport template.

Removed the Secure Application Formats support.

Secure Application Formats is not supported in ModusToolbox v2.0 build flow.

Fixed the return value for the SYNC command processing.

The SYCN command returned fail after successful execution.

Updated the major and minor version defines to follow the naming convention.

3.10

Remove the function prototype from the MDK linker script include file.

Fix the linker error for the MDK compiler.

Add BLE transport templates.

Add BLE middleware support.

3.0

Bootloader SDK is renamed to the DFU (Device Firmware Update) SDK. All API prefixes and file names are renamed accordingly.
Added BWC macros to simplify migration.

Avoid the confusion with the device boot-up and OS load.

Flattened the organization of the driver source code into the single source directory and the single include directory.

Driver library directory-structure simplification.

2.20

Add check of application number in Set Application Metadata command processing routine.

Prevent incorrect usage of the Set Application Metadata command.

Minor documentation updates

Documentation improvement

2.10

Moved address and golden image checks from cy_dfu.c to Cy_DFU_WriteData() in dfu_user.c, so the checks can be customized based on application needs.

Allows receiving an update for the running app use case. Improvements made based on usability feedback. Documentation update and clarification.

2.0

  • Use the shared RAM for application switching instead of the BACKUP register.

  • Add support of secure application verification.

  • Add support of I2C/SPI/BLE transport protocols.

  • Linker scripts updated for PSoC6 Rev *A devices.

  • Made CRC default application checksum.

To increase functionality.

1.0

Initial version.

More Information