5.2 Creating an Application for PIC® Devices

This section demonstrates how to configure a bootable application configuration for 8-bit PIC® 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.

Create a new MPLAB X IDE project.

Figure 5-39. New Application Project
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-40. Open MCC
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 and another configuration that builds that application in the manner needed to bootload it.
Figure 5-41. 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’. Click OK.
Figure 5-42. Create the New ‘bootable’ Configuration
Set the ‘bootable’ configuration as the active project by click Set Active and then click OK to close the menu.
Figure 5-43. Activate the ‘bootable’ Configuration
Configure the on-board LED by setting the RF3 pin. Set the Custom Name to LED.

Figure 5-44. LED Configuration
Configure the on-board Switch by setting the RB4 pin. Set the Custom Name to BTN and enable Weak Pull-ups.

Figure 5-45. BTN Configuration
Add the Delay driver from Device Resources>Drivers>Timer to the project.

Figure 5-46. Delay Driver
Press the Generate button in the Project Resources tab to generate the project code.

Important: Make sure to match the Clock Control and Configuration Bits settings to the bootloader project settings.

Figure 5-47. Generate Application Code
For a blinking LED application, add the following code to main.c in Source Files under the project folder. The delay.h header file must also be included in the main file.
```
// if the BTN is pressed, reset the device.
if (BTN_GetValue() == 0U)
{
    RESET();
}
LED_Toggle();
DELAY_milliseconds(200U);
```
Figure 5-48. Update the Application Code

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 and we are locating the end of the application to be the end of Flash. This address may be different for your device.

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-49. Add Verification Settings in `main.c`

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

Figure 5-50. Set Project Properties

Configure the linker setting for the used verification scheme.

Compiler and Linker Settings

The following section is intended to provide an explanation of the compiler and linker settings utilized in the PIC18F57Q43 end application project. The example below uses the Checksum verification scheme for demonstration.

Navigate to the Project Properties>XC8 Linker>Additional options. Enter the application start address into the Codeoffset and enter the algorithm information into the Checksum box that corresponds with the below verification scheme

Table 5-1. Checksum Example
Project Setting Input
Codeoffset 0x2000
Checksum 2000-1FFFD@1FFFE,width=-2,algorithm=2

Table 5-1. Checksum Example
Project Setting	Input
Codeoffset	0x2000
Checksum	2000-1FFFD@1FFFE,width=-2,algorithm=2

For the above Checksum option, the algorithm arguments can be understood as:


Argument	Start-End@Store,width=-Width,algorithm=-Algorithm,offset=Offset,polynomial=Polynomial
Start Address	2000 in the above example is the start address of the hash calculation. Changing the start address of the application will require this value to also be changed.
End Address	1FFFD in the above example is the end address of the hash calculation. Changing the end address of the application partition will require this value to also be scaled. You must never include the location of the hash data in the calculation of the check sum. This value must be lower than the Store Address.
Store Address	1FFFE is the location of the check sum data after hexmate perform the calculation. This address must not be considered for being included in the check sum calculation and must always be greater than the Address 1.
Data Width	-2 in the above command represents a 2 byte check sum size that will be stored in little endian byte order
Hexmate Algorithm	2 in the above command is the algorithm being used for the hexmate operation. Refer to the Hexmate documentation for more information on the algorithm descriptions.
CRC Polynomial	The polynomial entry is not shown in the above example but it is used to set the polyniomial used for the CRC16 and CRC32 verification algorithms. Refer to the Verification Schemes section for more information.
CRC Offset	The offset entry is not shown in the above example but it is used to set the remainder value used in the CRC16 and CRC32 calculations.

Refer to the table below for the Checksum setting for each verification scheme:


Verification Scheme	Checksum Algorithm
CRC16	2000-1FFFD@1FFFE,width=-2,algorithm=5,offset=FFFF,polynomial=1021
CRC32	2000-1FFFB@1FFFC,width=-4,algorithm=-5,offset=FFFFFFFF,polynomial=04C11DB7
Checksum	2000-1FFFD@1FFFE,width=-2,algorithm=2

Warning: For PIC16 devices, you must include ,code=3F to the end of all of the commands listed above. Example: 2000-1FFFD@1FFFE,width=-2,algorithm=2,code=3F

Figure 5-51. Project Properties - Checksum Configuration

Open File>Project Properties. Add the below settings to the XC8 Linker>Fill Flash Memory. These steps enable the mentioned constant to fill all the unused memory space in the generated hex file. Set the Memory address range to: 0x<Application Start Address>:0x<End of Flash Memory>.

Important: For PIC16 devices, the value in the Constant field must be 0x3FFF and the addresses are the word addresses.

Figure 5-52. XC8 Linker - Fill Flash Memory

Click Apply and OK to close the project properties. Then, click Clean and Build to the build the project hex file.

Image File Generation