3. Building the SUOTA Multipart Image

This section will guide you step by step on how to build a multipart binary image which can be upgraded via Dialog’s SUOTA to an upgraded firmware version. Please make sure you have installed all required dependencies listed in the “Before You Start” section.

3.1. Getting started

For this tutorial we will use the Proximity Reporter software example which is located in the projects/target_apps/ble_examples/prox_reporter/ directory of your SDK installation. We will demonstrate how we can configure an application to run from a secondary bootloader and how we can send firmware updates over the air.

3.1.1. Hardware configuration

We will use the DA145xx Pro Development Kit in this example with the bootloader residing in the external SPI flash. You can see in the graphic below the configuration of the jumpers on the board to connect the SPI flash and the debugger.

ble_app_profile

Figure 1 DA145xx Pro Dev Kit jumper configuration

3.1.2. Description of some important files

You can find some a brief description of some important SDK files for the SUOTA procedure.

File Description
user_profiles_config.h Defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. Each header file denotes the respective BLE profile. Be sure to #define the CFG_PRF_PXPR and CFG_PRF_SUOTAR, so that the proximity reporter profile and the SUOTA custom service will be included.
user_periph_setup.h Holds hardware related settings relative to the used development kit.
user_periph_setup.c Source code file that handles peripheral (GPIO, UART, SPI, etc.) configuration and initialization relative to the development kit.
app_suotar.c Source code file that is implemented as SUOTA reporter application entry point.
app_suotar_task.c Source code file that is implemented as SUOTA receiver application Message Handlers.
app_proxr.c Source code file that is implemented as Proximity reporter application entry point.
app_proxr_task.c Source code file that is implemented as Proximity reporter application task implementation.

3.1.3. Building the firmware

  • Open the prox_reporter.uvprojx project file, located in /projects/target_apps/ble_examples/prox_reporter/Keil_5 under your SDK installation folder.
  • In the Build Toolbar, select the device you want to build the firmware for from the drop-down box.
Proximity reporter select target

Figure 2 Select your target device

  • Change the default Bluetooth Device Address. You will have to modify the CFG_NVDS_TAG_BD_ADDRESS in the user_config/da1458x_config_advanced.h file, for example
#define CFG_NVDS_TAG_BD_ADDRESS             {0x19, 0x00, 0x00, 0x00, 0x00, 0x19}
  • Navigate to file user_config/user_modules_config.h and undefine the EXCLUDE_DLG_SUOTAR macro. This way you will include the SUOTA module in your firmware.
#define EXCLUDE_DLG_SUOTAR     (0)   /* included */
  • Check that CFG_PRF_SUOTAR is defined in the user_config/user_profiles_config.h file.
#define CFG_PRF_SUOTAR
  • Change the advertising data. First make sure that the UUID of the SUOTA service is included in the advertising data.
#define USER_ADVERTISE_DATA         ("\x09"\
                                    ADV_TYPE_COMPLETE_LIST_16BIT_SERVICE_IDS\
                                    ADV_UUID_LINK_LOSS_SERVICE\
                                    ADV_UUID_IMMEDIATE_ALERT_SERVICE\
                                    ADV_UUID_TX_POWER_SERVICE\
                                    ADV_UUID_SUOTAR_SERVICE\
                                    "\x10"\
                                    ADV_TYPE_URI\
                                    "\x16\x2F\x2F\x77\x77\x77\x2E\x69\x61\x6E\x61\x2E\x6F\x72\x67")

and change the device name to a more descriptive one, for example:

#define USER_DEVICE_NAME        "SUOTA-1"

Since we will need a few files to create the multipart image, we recommend to create a folder called input and collect all these files there.

  • You can now go ahead and build the firmware. Once the build is complete, copy the output hex file to the input folder. This is located in the proximity reporter project folder, under Keil_5/out_DA145xx/Objects/, where the last part is your target device, with the name prox_reporter_5xx.hex. Rename the copied file to fw_1.hex.
  • For the second firmware, change the device name in the user_config/user_config.h file.
#define USER_DEVICE_NAME        "SUOTA-2"
  • Rebuild the firmware. Again, after the build is complete, copy the output file prox_reporter_5xx.hex to a file named fw_2.hex in the input folder.

At this point we have created the two single images that we will use for the SUOTA multipart image creation.

3.1.4. Create a secondary bootloader

The code that is run when the device boots up is called a bootloader and its purpose is to set up the device so that the scheduler and the user code can run properly. For a software update to occur, every embedded device needs a way to assert if there is an updated firmware during boot up and apply the update.

For this purpose, we will also create a secondary bootloader which will do this check.

  • Navigate to the /utilities/secondary_bootloader/ folder and open the secondary_bootloader.uvprojx project file.
  • Open the file includes/bootloader.h. You will find a macro definition that reads
#define PRODUCT_HEADER_POSITION     0x38000

This is the memory location that the product header will reside. You can leave it as it is, or you can change it to a location that suits better your application needs.

  • Open the file src/decrypt.c. Check the encryption key and vector. Note these values, as we will use them in the following steps. By default you will see
const uint8_t Key[16]= {0x06,0xa9,0x21,0x40,0x36,0xb8,0xa1,0x5b,0x51,0x2e,0x03,0xd5,0x34,0x12,0x00,0x06};
const uint8_t IV[16] = {0x3d,0xaf,0xba,0x42,0x9d,0x9e,0xb4,0x30,0xb4,0x22,0xda,0x80,0x2c,0x9f,0xac,0x41};
  • Select the device you want to build the firmware for from the drop-down box.
Secondary bootloader select target

Figure 3 Select your target device

  • Build the code. Depending on your target, you should see output folder which includes the output binaries, for example out_DA14531/Objects/. Locate the binary image, in our case secondary_bootloader_531.hex, and copy it to the input folder.

At this point we have created all the binary images that we will use to program our device. In the next section we will load the multipart image to the SPI flash and upgrade it using the Dialog SUOTA mobile app.