| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Experimental: ANT Bootloader/DFU
This example requires one of the following SoftDevices: 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) and SoftDevice S332 v0.9.1 (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 S212 to S332 or S332 to S212)
- 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

On nRF52 Series ICs, 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.

Memory layout

The following table shows the memory ranges for the SoftDevices S212 (v0.9.1), and S332 (v0.9.1):

Usage | Memory Range S212 | Memory Range S332
--- | --- | ---
Master Boot Record (MBR) | 0x00000 - 0x01000 | 0x00000 - 0x01000
SoftDevice | 0x01000 - 0x12000 | 0x01000 - 0x27000
Application code (bank 0) and free/swap (bank 1) | 0x12000 - 0x79000 | 0x27000 - 0x79000
DFU bootloader and data | 0x79000 - 0x80000 | 0x79000 - 0x80000

The space between the SoftDevice and the bootloader is split into two memory banks. Thus, the bank size when using SoftDevice S212 is 0x33800. When using SoftDevice S332, the bank size is 0x29000.

## 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 0 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 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 ANT stack 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:
   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.