| 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
ANT-FS Client
This example requires the following SoftDevice: S212

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

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.

The ANT-FS client device simulator example illustrates the basic operations of an ANT-FS client. The example supports all three methods of authentication defined in the ANT-FS specification: pairing, passkey, and pass-through. It also supports the simulation of downloading, uploading, and erasing files. Other functionality that is not defined in the ANT-FS specification, such as file system implementation and data decoding/encoding, are outside of the scope of this implementation.

Note
  This example does not implement the client undiscoverable mode as defined by the ANT-FS specification.

The general architecture of the ANT-FS client device simulator is illustrated in the following picture:

Architecture overview

You can find the source code and the project file of the example in the following folder: `<InstallFolder>\examples\ant\ant_fs\client`

# ANT-FS specific configuration options

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.

This example implements the pairing, pass key, and pass-through authentication methods, which can be enabled using compile switches. All three authentication methods are enabled by default. Upload functionality can also be enabled through a compile switch and it is by default turned on.

To establish communication, the host and client devices shall have corresponding configurations. The host device may wish to wildcard any of the fields in the channel ID and client identifier by setting them to zero, but the Network Key and RF channel frequency shall be the same. The channel period of the client need not match the channel period of the host.

A simple user interface exists consisting of 2 keypad buttons that are active during pairing authentication for the user to accept or reject the authentication, and 2 LEDs that are active during reception of EVENT_TX and pairing authentication mode. LED 1 is being toggled for every EVENT_TX received from the ANT stack. LED 2 is turned on when in pairing authentication mode. The LEDs can be configured in the `leddriver.c` file.

# General operation

The ANT-FS client device simulator executes automatically through each ANT-FS layer, as per the commands received from the ANT-FS host. User interaction is only required when using pairing authentication, to confirm or reject a pairing request.

Once an ANT-FS host detects a client with ANT channel and ANT-FS client parameters matching its search criteria, it will send a Link command to the client, specifying the Link RF channel frequency and channel period. The client will automatically switch to the new frequency and channel period and indicate in its beacon that it has moved to the authentication stage.

# Authenticate

Once both the ANT-FS client and host are in the authentication layer, the host can send a request to the client device for pairing. The ANT-FS client example supports three methods of authentication: pairing, passkey, and pass-through. When using the passkey and pass-through authentication methods, the client will automatically accept or reject the authentication as outlined by the ANT-FS specification. Intervention from the user is only required when using the pairing authentication method. If the client receives a pairing request from the host, it will turn on an LED to let the user know that a host device wishes to pair with it. The user can accept or reject the pairing request by pressing one of the appropriate buttons. If no response from the user is received before the pairing time-out expires, the request will be rejected.

# Download

A sample directory structure is implemented in this example, however, no actual files or file systems are present in the example. The client will send the directory to the host if it receives a request to download the directory (file index0). When the host requests a download for any other files, the client will check if the file exists in its directory and if there is permission to download that file. If the file can be downloaded, the client will simulate a file by sending sequential data with size matching the requested file size; otherwise, it will reject the download.

# Upload

When the host requests an upload, the client will check if the file index exists in its directory, if there is permission to write on that file, and if there is enough space to write the requested data. Once the client sends a response accepting the upload request, the host can start uploading data. The device simulator does not include actual files, so data is not written to memory; however, the client keeps track of the CRC of the received data to verify the integrity of the upload.

# Erase

If the client receives a request to erase a file, it will check in its directory to see if the file exists and if there is permission to erase that file. As there are no actual files to delete in this example, if the file can be erased, the client will simply send a response to the host indicating the file was erased; otherwise, it will reject the request.

# Test host tool

For testing purposes, the ANT-FS PC Host tool can be used as counterpart. This tool interfaces directly to the ANTFSHost class in the ANT Common Library. This class uses lower-level functionality made available by other library files and classes.

The ANT-FS PC Host tool works with a USB ANT dongle (for example, ANTUSB-m). It is available for download from thisisant.com.

Note
  This example requires ANT FS Network Key. Go to thisisant.com to access the ANT FS Network Key.