5.6 Creating an Application for AVR® Devices

This section demonstrates how to configure a bootable application configuration for 8-bit AVR devices.

Description: With the bootloader code built and configured to the needed specifications, configure the target application to work alongside the bootloader instead of erasing the bootloader code from the device and programming the new target application over it. MPLAB X IDE allows the user to set various project configuration properties to match the bootloader configuration. The first step for completing this task is to create a blinking LED project.

  1. Create a new MPLAB X IDE project.

    Figure 5-139. New Application Project
  2. MCC opens up automatically when a new project is created. If not, click the MCC button in the menu bar to start the MPLAB Code Configurator.
    Figure 5-140. Open MCC
  3. To keep the build configuration clean, it is suggested to create at least two project configurations for your application. One that can be used to prototype your application functionality (default) and another configuration that builds that application in the manner needed to load it through the bootloader (bootable).
    Figure 5-141. Open the Project Properties

    Navigate to Project Properties>Manage Configurations...

    With the default configuration highlighted, click the Duplicate button, and then Rename the new configuration to bootable’. Select OK to save the name.

    Figure 5-142. Create the New ‘bootable’ Configuration

    Set the bootable configuration as the active project by clicking Set Active and then click OK to close the menu.

    Figure 5-143. Activate the ‘bootable’ Configuration

  4. Configure the on-board LED by setting RC6 as an output using the Pin Grid View. Set the Custom Name to LED.

    Figure 5-144. LED Configuration

  5. Configure the on-board switch by setting RC7 as an input using the Pin Grid View. Set the Custom Name to BTN and enable Weak Pull-up.

    Figure 5-145. Switch Configuration
  6. Add the Delay driver from Device Resources>Drivers>Timer to the project.
    Figure 5-146. Delay Driver
  7. Add the RSTCTRL driver from Device Resources>System>RSTCTRL to the project.
    Figure 5-147. RSTCTRL Driver
  8. It is suggested to match the Configuration Bits and Clock settings in both the application and bootloader project. This will make the process of merging the functionality of both projects easier.

    Select the Configuration Bits module and set the BOOTSIZE FUSE to the same value that has been set in the bootloader.

    Figure 5-148. Set the Application Configuration Bits
    Figure 5-149. Set the Application Clock Settings
  9. Press the Generate button in the Project Resources tab to generate the project code.
    Tip: Matching the Configuration Bits and Clock settings in the application and bootloader will make merging the two applications easier.
    Figure 5-150. Generate Application Code
  10. For a blinking LED application, add the following code to main.c in Source Files under the project folder. The delay.h and the rstctrl.h header file must also be included in the main file.
    // if the BTN is pressed, reset the device.
if (BTN_GetValue() == 0U)
{
    RSTCTRL_reset();
}
LED_Toggle();
DELAY_milliseconds(200U);
    Figure 5-151. Update the Application Code
  11. Add the following code at the top of the main.c file before the main function. This reserves the last bytes to hold the Checksum value. The address presented below in the __at() is PROGMEM_SIZE - 2, since the Checksum hash size used is two bytes.
    Note: For Checksum, CRC16 and Check State Flag verification schemes, the hash size is two bytes. For CRC32, the hash size is four bytes.

    Checksum Verification Scheme

    #include <stdint.h> 
#ifdef __XC8__ 
#include <xc.h> 
#endif 
volatile const uint16_t 
#ifdef __XC8__ 
__at(0x1FFFE) 
#endif 
applicationFooter __attribute__((used, section("application_footer"))) = 0xFFFF;

    CRC32 Verification Scheme

    #include <stdint.h> 
#ifdef __XC8__ 
#include <xc.h> 
#endif 
volatile const uint32_t 
#ifdef __XC8__ 
__at(0x1FFFC) 
#endif 
applicationFooter __attribute__((used, section("application_footer"))) = 0xFFFFFFFF;

    CRC16 Verification Scheme

    #include <stdint.h> 
#ifdef __XC8__ 
#include <xc.h> 
#endif 
volatile const uint16_t 
#ifdef __XC8__ 
__at(0x1FFFE) 
#endif 
applicationFooter __attribute__((used, section("application_footer"))) = 0xFFFF;

    Check State Flag Verification Scheme

    #include <stdint.h> 
#ifdef __XC8__
#include <xc.h> 
#endif
volatile const uint8_t 
#ifdef __XC8__ 
__at(0x1FFFE) 
#endif 
applicationFooter __attribute__((used, section("application_footer"))) = 0x55;
    Figure 5-152. Add Verification Settings in main.c

  12. For AVR devices, a batch file execution is enabled in the Project Properties to fill the empty spaces in the application project with a given sequence. Follow the steps below to create the batch file.

    1. Right click the Important Files>New>Empty File....
      Figure 5-153. New Empty File
    2. In the File Name text box, enter postBuild.bat as the file name and click Finish.
      : If you are using a Mac or Linux operating system, you will need to create this file using the .sh file extension.
      Figure 5-154. New postBuild.bat File
    3. Add the following code to the postBuild.bat or postBuild.sh file to configure the application verification based on the verification scheme selected.
      CAUTION: The following example code blocks will demonstrate the post build operation for Checksum verification where the start address is 0x2000 and the end of the application space is 0x1FFFF. You may need to change these values.
      Windows Users (postBuild.bat)
      REM ---------------------------------------------------------------------------- 
REM - This file will be used to fill the application hex file with empty data
REM - and then calculate the required checksum on the application code.
REM - Script Arguments:
REM -   %1 - Debug mode flag. 'true' when building in debug mode.
REM -   %2 - Application project name.
REM -   %3 - Path to the build folder.
REM -   %4 - Image type being built.
REM ----------------------------------------------------------------------------

REM - create variables from given arguments
set isDebug=%1
set appHexFile=%3\%2.X.%4.hex

if %isDebug% == false (
    REM - Fill the empty application data
    hexmate r0-FFFFFFFF,%appHexFile% -O%appHexFile% -FILL=w1:0xFF@0x2000:0x1FFFF
    
    REM - Calculate the checksum over the application space 
    hexmate %appHexFile% -O%appHexFile% +-CK=2000-1FFFD@1FFFEg2w-2
) else (
    REM - When building in debug mode we cannot run hexmate operations
    echo "Warning - Post Build Process was Skipped."
    echo "Warning - Application is being built in Debug mode."
)
      Mac or Linux (postBuild.sh) 
      # ---------------------------------------------------------------------------- 
# - This file will be used to fill the application hex file with empty data
# - and then calculate the required checksum on the application code.
# - Script Arguments:
# -   $1 - Debug mode flag. 'true' when building in debug mode.
# -   $2 - Application project name.
# -   $3 - Path to the build folder.
# -   $4 - Image type being built.
# ----------------------------------------------------------------------------

isDebug=$1
appHexFile=$3\$2.X.$4.hex

if [ $isDebug = false ]; then
    # - Fill the empty application data
    hexmate r0-FFFFFFFF,$appHexFile -O$appHexFile -FILL=w1:0xFF@0x2000:0x1FFFF

    # - Calculate the checksum over the application space
    hexmate $appHexFile -O$appHexFile +-CK=2000-1FFFD@1FFFEg2w-2
else
    # - When building in debug mode we cannot run hexmate operations
    echo "Warning - Post Build Process was Skipped."
    echo "Warning - Application is being built in Debug mode."
fi
      • Reset Vector and Status Byte verification do not require any of the below calculation commands. However, fill the empty application space in the hex file.
      • For the other verification schemes, perform the required calculations on the application data by referring to the table below.
        CAUTION: The following example code blocks will demonstrate the post build operation for Checksum verification where the start address is 0x2000 and the end of the application space is 0x1FFFF. You may need to change these values.
        Table 5-2. Verification Calculation Commands
        Verification SchemeHexmate Command Example
        Checksumhexmate %appHexFile% -O%appHexFile% +-CK=2000-1FFFD@1FFFEg2w-2
        CRC-16hexmate %appHexFile% -O%appHexFile% +-CK=2000-1FFFD@1FFFE+FFFFg5w-2p1021
        CRC-32hexmate %appHexFile% -O%appHexFile% +-CK=2000-1FFFB@1FFFC+FFFFFFFFg-5w-4p04C11DB7
        : When using Mac or Linux, you will need to use the argument format `$X` instead of `%X%` in the above commands.
      Figure 5-155. postBuild.bat or postBuild.sh File
    4. With the postBuild script created, open Project Properties>Building. Enable the “Execute this line after build” checkbox. Add the following lines in the text box below it.

      postBuild${ShExtension} ${IsDebug} ${ProjectName} ${ImageDir} ${IMAGE_TYPE}

      Figure 5-156. Setup Post Build Execution

  13. Configure the project properties. Go to File>Project Properties and select AVR128DA48 Curiosity Nano under Connected Hardware Tool, DFP version under Packs and the XC8 or GCC version under Compiler Toolchain.

    Figure 5-157. Setup Project Properties
  14. Linker and Compiler setting will be divided by the compiler being used.

    AVR - XC8 Compiler

    Open Project Properties>XC8 Global Options>XC8 Linker>Additional Options. In the “Extra linker options” text box, add 
    -Ttext=<Application Start Address> -Wl,-u,applicationFooter
    Figure 5-158. XC8 Linker Settings - Additional Options

    In XC8 Compiler-Preprocessing and messages, make sure to enable “Use CCI Syntax”.

    Figure 5-159. XC8 Compiler Settings - Preprocessing and Messages
    In XC8 Global Options>Global options, make sure to enable “Enabled access to const variables directly from flash”.
    Figure 5-160. XC8 Compiler Settings - Global Options

    AVR - GCC Compiler

    Open Project Properties>Avr GCC (Global Options)>avr-ld>Memory Settings. In the “FLASH segment” text box, add .text=0x<Application Start Address in WORDS>.
    Figure 5-161. GCC Linker Settings - Memory Settings

    Open Project Properties>Avr GCC (Global Options)>avr-ld>Memory Settings. In the “FLASH segment” text box, add application_footer=0x<Application Footer Address in WORDS>.

    Figure 5-162. GCC Linker Settings - Footer Section Settings

  15. Click Clean and Build to the generate the project hex file.

    Figure 5-163. Clean and Build
Image File Generation

With the bootloader client and the application projects created, the image file can be generated by using the Firmware Image Builder ( pyfwimagebuilder) tool by combining the bootloader_configuration.toml file and the application hex file.

Note: The toml file will be inside Booloader Project Folder>mcc_generated files>bootloader>configurations, and the hex file is present at Application Project Folder>dist>default>production.
Command: 
pyfwimagebuilder build -i AVR128DA48_App.X.production.hex -c bootloader_configuration.toml -o output.img
Figure 5-164. Image File Generation

End Application Programming

The newly-generated application image can be transferred to the target device using the Microchip Device Firmware Update (pymdfu) tool.

Command:
pymdfu update --tool serial --image output.img --baudrate 9600 --port COM20
Figure 5-165. pymdfu Execution
Note: The above command is for UART communication. For SPI, refer to the pymdfu section.