Important: Before you run this example, make sure to program the SoftDevice.
The ANT Relay example demonstrates how to create a simple relay network. It uses the ANT multi-endpoint and proximity pairing capabilities to achieve this goal.
Description
In this example, the state of an LED is relayed to all boards in a network. The boards are connected in a daisy chain layout to form the nodes of the network. There is no limitation on the number of nodes.
If the state of the LED on one board changes, this change is relayed to all other nodes in the network, so that the state of the LEDs on all boards change. The change can be initiated by pressing a button on one of the boards or by connecting to one of the nodes wirelessly, by using a mobile or PC application.
This example can be extended to fixed topologies that report status or accept commands, and require range extension through relay. This network configuration is appropriate for coin-cell operated networks and applications that require a mobile interface.
After startup or reset, each ANT node opens two master channels: one that is used for the relay network and one that allows for connections to a mobile or PC application, for example ANTware II.
The following table lists the channel parameters for the two master channels. Numbers in parentheses denote the parameters that should be used to set the values.
| Parameter | Relay channel | Mobile channel |
|---|---|---|
| Channel type | Master (0x10) | Master (0x10) |
| Network | Public | Public |
| Frequency | 2472 MHz | 2477 MHz |
| Period | 4 Hz (8192) | 4 Hz (8192) |
| Device number | Serial number | Serial number |
| Device type | 1 | 2 |
| Transmission type | 5 | 5 |
This example uses proximity pairing to establish a connection between the boards. Boards can be paired by pressing a button or by sending a pairing command over the mobile channel (see Message format for computer or mobile applications). Boards must be brought very close (< 10 centimeters) to each other to pair because the proximity bin setting is 1. After a connection to a node in the network is established, the state of the LED on the added board is relayed to all boards in the network.
If a slave channel loses connection with the master, to which it is connected, for longer than 30 seconds, it will close its channel and re-initialize the search proximity bin setting. To re-initialize the connection, press the appropriate button or send a pairing command over the mobile channel.
Message format
The relay channel is bidirectional, which means that the slave endpoint sends a status message back to the master for every message that it receives.
The following table lists the message format of the 8-byte message that is used to relay information between devices, both from master to slave and from slave to master:
| Byte | Description |
|---|---|
| 0 | Page number = 1 (ANT_RELAY_MAIN_PAGE) |
| 1 | LED status (1 = ON, 0 = OFF) |
| 2-5 | Counter (4 bytes, unsigned, little endian) that increases every time when the state of an LED changes. When the counter changes, the node changes the state of its LED to reflect the change. |
| 6 | Reserved = 0xFF |
| 7 | State of the slave channel (0 = unassigned, 1 = assigned, 2 = searching, 3 = tracking) |
Whenever the state of the LED changes, the counter will increase. All boards will then update the state of their LED to reflect the new state. The state of the LED can be changed by pressing a button on any of the boards or by sending the appropriate command over the mobile channel.
Message format for computer or mobile applications
Instead of pressing buttons on a board to pair devices or to change the state of an LED, you can also send commands from a computer or a mobile application. The following table lists the message format that must be used to send commands to the boards:
| Byte | Description |
|---|---|
| 0 | Page number = 2 (ANT_MOBILE_COMMAND_PAGE) |
| 1 | Reserved = 0xFF |
| 2 | Command (1 = pair, 2 = LED on, 3 = LED off) |
| 3-7 | Reserved = 0xFF |
Commands can be sent using broadcast messages or acknowledged messages. If possible, you should always use acknowledged messages because this message type returns a notification stating whether the command was received or not.
The status message that is sent on the mobile channel to a computer or mobile application is almost identical to the status message that is sent on the relay channel. However, it does not use a counter.
The following table lists the message format of the status message that is sent on the mobile channel:
| Byte | Description |
|---|---|
| 0 | Page number = 1 (ANT_MOBILE_MAIN_PAGE) |
| 1 | LED status (1 = ON, 0 = OFF) |
| 2-6 | Reserved = 0xFF |
| 7 | State of the slave channel (0 = unassigned, 1 = assigned, 2 = searching, 3 = tracking) |
Setup
You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\ant\ant_relay_demo
At least two development boards are required to use the ANT relay example. Optionally, if you want to use a mobile channel, an ANT USB dongle and ANTware II are required.
The following table lists the function of the buttons and LEDs on the development board:
| Hardware | Function |
|---|---|
| Button 1 | Toggle the state of LED 1. |
| Button 2 | Start pairing mode. |
| LED 1 | Toggled by Button 1. |
| LED 2 | Default: off. It is turned on when the slave endpoint receives a message. |
Testing
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.
Test the ANT Relay example application by performing the following steps:
- Compile and program the application and toggle the power or reset each of the boards. The master channels will start transmitting at the channel period, but the boards will not be connected. This means that pressing Button 1 on a board will affect the state of LED 1 of that board, but not of the other boards. LED 2 is off because no messages have been received on the slave endpoint.
- To pair the boards, press Button 2 on the board that you want to add as a new node. This will open the slave endpoint, and the board will begin searching for other devices in the proximity pairing zone.
- Bring the board that you want to add close to the other board or, if you have already connected several boards, to the last board that was added to the network. When the slave endpoint of the new board receives data from the other board, LED 2 will be turned on. After the boards are connected, they will continue communicating even if they are moved further apart.
Pairing node B with node A - You can add more boards to the network by repeating steps 2 and 3. Make sure to connect the boards in a chain.
- Press Button 1 on one of the boards in the network. The state of the LED 1 will toggle on all connected boards. There will be a slight latency while the message is sent across the relay.
Optionally, perform the following steps to test the relay network by using a mobile channel:
- Run ANTware II. From the available devices, select your ANT PC dongle (for example, ANTUSB-m). Configure the device channel by loading the device profile configuration from the following file:
<InstallFolder>\examples\ant\ant_relay_demo\ant_relay_demo_test.xml. Alternatively, you can configure the device channels manually:- Set the channel assignment to slave.
- Set the channel ID to 0, 2, 5.
- Set the radio frequency to 77.
- Keep the default values for all other settings.
To turn the LED on, run the following command as described in Message format for computer or mobile applications:
02-FF-02-FF-FF-FF-FF-FF
Use acknowledged messages to send commands.
To turn the LED off, run the following command:
02-FF-03-FF-FF-FF-FF-FF
To initiate pairing, run the following command:
02-FF-01-FF-FF-FF-FF-FF