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 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)
the SoftDevice and the bootloader in a single process

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 0x3B800 and 0x40000 for the bootloader. 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.

Memory layout

The following table shows the memory ranges for the SoftDevices S210 (v4.0.0 and v4.0.1) and S310 (v2.0.0 and v2.0.1):

Usage	Memory Range S210	Memory Range S310
Master Boot Record (MBR)	0x00000 - 0x01000	0x00000 - 0x01000
SoftDevice	0x01000 - 0x0D000	0x01000 - 0x1D000
Application code (bank 0) and free/swap (bank 1)	0x0D000 - 0x3B800	0x1D000 - 0x3B800
DFU bootloader and data	0x3B800 - 0x40000	0x3B800 - 0x40000

The space between the SoftDevice and the bootloader is split into two memory banks of equal size. Thus, the bank size when using SoftDevice S210 is 0x17400. When using SoftDevice S310, the bank size is 0xF400.

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:

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.

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:

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 the current application can be preserved during the update process, thus if a dual-bank or single-bank update should be performed. If unknown, set to 0xFFFF; this ensures a single-bank update.

param_flags: A 32-bit bitfield containing control and status flags that can be used to initiate the bootloader from the application. The following fields are available:

Bits	Field	Values	Description
32-3	Reserved	All bits set to 1	Reserved
2-1	ENTER_BOOT	00 = Bypass bootloader mode done (reserved for internal use) 01 = Reserved 10 = Enter bootloader mode 11 = Bypass bootloader mode init (default after flash erase)	This field is used internally by the bootloader to determine whether bootloader mode will be bypassed on startup. If the application sets this field to 0x10, the device will start in bootloader mode after a reset. After the bootloader has run, it sets the field to 0x00. If the bootloader should run again, the application must set the field back to 0x10. Important: Applications should not set this field to any value other than 0x10.
0	PARAM_VALID	0 = Valid 1 = Invalid	This flag is used to indicate that the memory block for the ant_boot_settings is populated with valid values and can be interpreted by the bootloader.

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 project file of the example in the following folder: <InstallFolder>\Nordic\nrf51\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 http://www.thisisant.com/developer/ant-plus/ant-plus-basics/network-keys.

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_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 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 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 application from http://www.thisisant.com/resources/ota-updater/. Note that the application requires Microsoft .NET Framework 4.5.

Compile the bootloader code (make sure to set the ANT-FS network key) and program the device.
Connect the ANT USB dongle to your computer.
Start the OTA Updater application. The status bar at the bottom should indicate "Ready".
Optionally, configure the connection settings. If you use filtering, the parameters must match the ones that are configured in the bootloader.
Optionally, configure the authentication settings. The bootloader currently supports only pass-through authentication.
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 (S210 or S310). For S210, you can also use the provided project ota_tester (see Testing with the supplied test image (S210 only)). Compile the example project and select the resulting hex application file.
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.
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.
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".

Testing with the supplied test image (S210 only)

Close the OTA Updater application.
Make sure that the ANT USB dongle is connected to your computer.
Start ANTwareII.
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
Click "Auto-Open".
The USB dongle should start receiving broadcast data as in the following screenshot:

ANTwareII
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.
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.

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