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. In addition, the example provides the OTA Updater tool, a computer application that implements an 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 S210 v4.0.0 (or later) and SoftDevice S310 v2.0.0 (or later). It can be used to update either of the following:

the application code (with or without an existing application on the device)
the bootloader (if the start address of the new bootloader matches that of the existing bootloader)
the SoftDevice (either to a newer version of the same SoftDevice, or from S210 to S310 or S310 to S210)

If you want to update both the bootloader and the SoftDevice, you can do so in a single session. 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 starting at address 0x3B800 for the bootloader, with size 0x4800. The region between 0x0000 and 0x1000 is reserved for the Master Boot Record. The SoftDevice uses the flash region starting at address 0x1000, 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.

If an application is present and neither the old nor the new application exceeds the maximum 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:

The size of the existing application exceeds the bank size.
The size of the existing application is unknown.
The size of the new image (as reported in the header of the SUF file) exceeds the bank size.
A SoftDevice update was requested.

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 information to be shared between application and bootloader, even across power cycles. The following parameters are stored:

Parameter	Description
app_version	Application version string (UTF-8), as reported by the OTA Update Information file. The maximum length of this string is 16; any unused characters must be set to the null character.
app_size	Size of the current application, used to determine whether a dual-bank or single-bank update should be performed. If unknown, set to 0xFFFF; this ensures a single-bank update.
param_flags	Parameter flags that can be used to initiate the bootloader from the application.

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 version that are installed on the device. The version string for the SoftDevice is populated by the bootloader, queried from the SoftDevice. 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 project file of the example in the following folder: <InstallFolder>\Nordic\nrf51\examples\dfu\experimental_ant_bootloader

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 http://www.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_PASSKEY	Passkey for authentication, if using passkey authentication. By default, pass-through authentication is used and this option should not be set.	not set
ANTFS_CLIENT_SERIAL_NUMBER	Serial number of the device.	the 4 least significant bytes of the chip device identifier (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 http://www.thisisant.com/developer/ant-plus/ant-plus-basics/network-keys.	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 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	Derived from device 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

Connect the ANT USB dongle to your computer.
Start the OTA Updater application located at <InstallFolder>\Nordic\nrf51\examples\dfu\experimental_ota_updater_0.8\OTAUpdater.exe. The status bar at the bottom should indicate "Ready".
Configure the connection settings. If you use filtering, the parameters must match the ones that are configured in the bootloader.
Configure the authentication settings. The bootloader uses pass-through authentication by default. If using passkey authentication, the passkey must exactly match the one configured in the bootloader.
Browse for the image to use for the update, and make sure the corresponding checkbox is checked. Both binary and hex formats are supported.
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; to manually start the bootloader, press Button 1 and toggle the reset button.
Click "Connect to Device" in the OTA Updater tool. 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.
Click "Start Update". The update process will begin.
When the update is complete, the status bar will indicate "Image upload complete. Image will be activated, do not power down device".