nRF5 SDK v15.0.0
Experimental: ANT Bootloader/DFU
This example requires the following SoftDevice: S212, S332

Important: Before you run this example, make sure to program a SoftDevice.

The ANT Bootloader/DFU Example shows how to perform Over-the-Air (OTA) updates for a SoftDevice, bootloader, or application using ANT File Share (ANT-FS) technology.

ANT-FS is a session-based transport mechanism designed to securely and automatically transfer data files between two ANT enabled devices. See the ANT-FS Technical Specification for a detailed description of ANT-FS, and the application note Over the Air Firmware Updates Using ANT-FS for details about the update process as defined by ANT-FS, including the format of files exchanged.

Description

The ANT Bootloader/DFU Example implements an ANT-FS client. You can use the OTA Updater tool as ANT-FS host customized for performing OTA updates out of the box. This tool automates all of the interactions between host and client to query device information and transfer new images to the device.

The example supports SoftDevice S212 v0.9.1 (or later). It can be used to update either of the following:

If you want to update both the bootloader and the SoftDevice, you should always do so in a single process. Use a combined image of bootloader and SoftDevice to ensure that the versions of both components are compatible.

Warning
  • New SoftDevices might introduce compatibility issues (for example changed API calls). Always review the release notes for new SoftDevices and test application and bootloader to make sure that they are compatible with the new SoftDevice.
  • When you update the SoftDevice, any existing application is deleted. After updating the SoftDevice, you must install an application again.

Memory Layout

The ANT Bootloader/DFU example reserves the flash region between 0x79000 and 0x80000 for the bootloader. The region between 0x0000 and 0x1000 is reserved for the Master Boot Record (MBR).

The SoftDevice uses the flash region starting immedately after MBR, with a size depending on the specific SoftDevice. The remaining space is divided into two memory banks of equal size: bank 0 (starting after the SoftDevice) and bank 1 (ending before the bootloader). The application, if present, is placed in the space right after the SoftDevice. Depending on its size, it occupies part or all of bank 0 and might extend into bank 1, up to the end of bank 1.

ant_dfu_bootloader.svg
Memory layout

The following table shows the memory ranges for the SoftDevices S210 (v5.0.0) and S212 (v0.5.1.alpha):

Usage Memory Range S210 Memory Range S212
Master Boot Record (MBR) 0x00000 - 0x01000 0x00000 - 0x03000
SoftDevice 0x01000 - 0x0E000 0x03000 - 0x15000
Application code (bank 0) and free/swap (bank 1) 0x0E000 - 0x3B800 0x15000 - 0x79000
DFU bootloader and data 0x3B800 - 0x40000 0x79000 - 0x80000

The space between the SoftDevice and the bootloader is split into two memory banks. Thus, the bank size when using SoftDevice S210 is 0x16C00. When using SoftDevice S212, the bank size is 0x32000.

Dual-bank mode and single-bank mode

If an application is present and neither the old nor the new application exceeds the bank size, the example code preserves the existing application during the update process. In this case, the new image is stored on bank 1 and swapped to its destination location on activation. This process is called a dual-bank update, in comparison to a single-bank update, where the image is received on bank 0, overwriting the existing application.

The example code automatically selects dual-bank or single-bank mode. By default, dual-bank updates are used, except if any of the following conditions apply:

Passing parameters between application and bootloader

To determine the size of the existing application, the example code checks the app_size parameter that is stored in a reserved memory block located towards the end of the flash memory page. This memory block allows to pass parameters between application and bootloader, even across power cycles, and is used to share information about the application and for initiating bootloader mode. The following parameters are stored in the structure ant_boot_settings_t:

OTA Update Information file

The ANT Bootloader/DFU example demonstrates the use of an Over the Air Update Information file to provide information about the current application, bootloader, and SoftDevice versions that are installed on the device. The version string for the SoftDevice is populated by the bootloader, queried from the SoftDevice using sd_ant_version_get. The version string for the bootloader is hard coded and can be configured in version.c. The version string for the application version must be configured from the application, using ant_boot_settings_api.

To implement the interaction between the bootloader and application, use the ant_boot_settings_api. See the ota_tester project for an example of the API usage.

Configuration options

You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\dfu\experimental_ant_bootloader

Before you compile the example code, edit antfs.c and set ANTFS_NETWORK_KEY to your ANT-FS network key, which can be obtained at thisisant.com.

The following compile time configuration options are available:

Configuration option Description Value used by the example
ANTFS_CLIENT_DEV_TYPE 2-byte value providing information about the device type (for example model number). This value is managed by each manufacturer. 1
ANTFS_CLIENT_MANUF_ID 2-byte value identifying the manufacturer of the device. Manufacturer ID values are managed by ANT+. The current list of manufacturer ID values can be found in the FIT.xls profile (available within the FIT SDK at thisisant.com). New manufacturers must be members of the ANT+ Alliance to be added to this list; contact the ANT+ Alliance for details. The value 255 (0x00FF) has been reserved as a development ID and may be used by manufacturers that have not yet been assigned a value. 255
ANTFS_CLIENT_NAME UTF-8 string containing a human readable descriptor of the device. The string length can be customized with ANTFS_FRIENDLY_NAME_MAX. It is highly encouraged to customize this string, especially if using the development manufacturer ID. "ANTFS OTA Update"
ANTFS_CLIENT_SERIAL_NUMBER Serial number of the device. the 4 least significant bytes of the chip device identifier in FICR
ANTFS_FRIENDLY_NAME_MAX Maximum string length of ANTFS_CLIENT_NAME. The length should not exceed 256. 16
ANTFS_NETWORK_KEY ANT-FS network key, which can be obtained at thisisant.com. must be set
OTA_INFO_HARDWARE_VERSION Hardware version of the device in the OTA Update Information file. The value is managed by the manufacturer, and is set to 0 by default. 0
OTA_INFO_REGION_PRODUCT_ID Manufacturer-specific 1-byte field providing additional information about the type of device to be updated. For example, this field can be used to identify region-specific versions of a product or different SKUs based on the same hardware. This field is included in the OTA Update Information file. 0

Channel parameters

The following default channel parameters are used for communication between host and client, thus the OTA Updater tool and the bootloader:

Parameter Value
Channel type Master
Radio frequency 2450 MHz
Network key ANT-FS managed network key
Device type 16
Transmission type 5
Device number The 2 least significant bytes of ANTFS_CLIENT_SERIAL_NUMBER
Channel period 8192 (4 Hz)

To establish communication, channel parameters must match in the host and client devices. The OTA Updater tool is preconfigured with the correct channel parameters required to interface with the ANT Bootloader/DFU example. The only change that you must make is to set the ANTFS_NETWORK_KEY configuration option in the code (see Configuration options).

Performing an OTA update

Before you start, download the OTA Updater tool. Note that the application requires Microsoft .NET Framework 4.5.

  1. Compile the bootloader code (make sure to set the ANT-FS network key) and program the device.
  2. Connect the ANT USB dongle to your computer.
  3. Start the OTA Updater tool. The status bar at the bottom should indicate "Ready".
  4. Optionally, configure the connection settings. If you use filtering, the parameters must match the ones that are configured in the bootloader.
  5. Optionally, configure the authentication settings. The bootloader currently supports only pass-through authentication.
  6. Browse for the image to use for the update, and make sure that the corresponding checkbox (for application, bootloader, or wireless stack) is checked. The OTA Updater application does not validate whether the selected image corresponds to the selected image type, so you must ensure to select the correct image for the type, or the update will not work correctly. Both binary and hex formats are supported. To test the process, you can use any of the SDK examples for the installed SoftDevice (S212 or S332). You can also use the provided project ota_tester (see Testing with the supplied test image). Compile the example project and select the resulting hex application file.
  7. Start the bootloader on the device. If no application is present on the device, the ANT Bootloader/DFU will run automatically. If a valid application is present, the application will run. The application might request to enter bootloader mode (see parameter flags). Otherwise, you must manually start the bootloader by pressing Button 1 and toggling the reset button.
  8. Click "Connect to Device" in OTA Updater. When the bootloader is discovered, the device information panel shows information about the current device: manufacturer ID, product ID, serial number, and versions of images currently installed.
  9. Click "Start Update". The update process will begin.
  10. When the update is complete, the status bar will indicate "Image upload complete. Image will be activated, do not power down device".

Testing with the supplied test image

Note: You can use a custom channel or encryption when running any of the ANT examples. When adding a new channel or encryption, remember to update SoftDevice ANT event handler configuration.

Note
It's assumed that ota_tester application is running on the board.
  1. Close the OTA Updater application.
  2. Make sure that the ANT USB dongle is connected to your computer.
  3. Start ANTwareII.
  4. Configure a channel with the following parameters:
    Parameter Value
    Network Public (default)
    Channel type Slave (Receive)
    Radio frequency 50
    Device type 32
    Transmission type 0
    Device number 0
    Channel period 4 Hz
  5. Click "Auto-Open".
  6. The USB dongle should start receiving broadcast data as in the following screenshot:
    ant_dfu_screen.jpg
    ANTwareII
  7. To start the bootloader again, send the following payload: 02-FF-FF-FF-FF-FF-FF-01
    The device will then start bootloader mode, and ANTwareII will lose communication with it.
  8. While the device is in bootloader mode, you can perform another update. To do so, close ANTware II so that the OTA Updater application can access the ANT USB dongle. If no update is initiated within two minutes, the application will start.

Documentation feedback | Developer Zone | Subscribe | Updated