| 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 Shared Channels
This example requires the following SoftDevice: S332

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

The ANT Auto Shared Channels Example shows how to use ANT Auto Shared Channels (ASC) to create extensible low power ANT networks.

# Description

This example application demonstrates how to interconnect two ASC masters ("hubs"), allowing for a multi-node network that relays commands and status information between hubs, peripherals, and remote control devices such as phones. The example can be extended to support more than two hubs.

Remote control devices can be phones or PCs and can connect to the hub over ANT or BLE. If ANT is used, multiple remote control devices can connect to any of the hubs. If BLE is used, only a single remote control device can connect to a hub at a time. An ANT remote and BLE remote can run concurrently if required.

Hub-2-hub network topology

On reset or power-up, each hub goes into DISCOVERY state (for a maximum of 20 seconds) and starts searching for nearby hubs to connect to. This process uses relative proximity. Therefore, hubs must be brought close to each other to be discovered. A connection is made by establishing a single ANT channel between the hubs. The hub with the higher device number (for example, 0x4E20) becomes the master of the connection. The hub with the lower device number (for example, 0x04D2) becomes the slave. The device number of the newly established channel will be a combination of the device numbers of the two hubs, with the LSB of the master hub's device number (20 in the example) becoming the MSB and the LSB of the slave hub's device number (D2 in the example) becoming the LSB of the new channel. The device number of the new channel would then be 0x20D2, for example.

The Auto Shared Channel capability allows each hub to assign a unique shared channel address to a peripheral device when it is added to the network. See the application note ANT Auto Shared Channel for information about the basic handshaking procedure. This example application can be configured to support single-byte or two-byte shared channel addressing. By default, single-byte addressing is used, which allows up to 253 peripheral devices to be connected to a single ASC master endpoint.

Peripheral devices automatically register with the hub after power-up. However, they must be brought into close proximity of the hub because relative proximity is used in the pairing process.

When the connections are established and hubs are in CONNECTED state, commands that are received over the ANT or BLE remote channels are relayed to the destination hub or peripherals. With this mechanism, any node in the network can be controlled from a single remote control device, like a phone, over the remote interface channel.

The following table (Table 1) lists the ANT channel parameters for the remote interface channel (numbers in parentheses denote the parameters that should be used to set the values):

Parameter | Remote control interface channel
--- | ---
Channel type | Master (0x10)
Extended assignment | N/A
Network | Public
Frequency | 2466 MHz
Period | 4 Hz (8192)
Device number | Serial number
Device type | 3
Transmission type | 5

See ANT Message Protocol and Usage for detailed information about shared channels and other channel parameters.

# Message format

The remote control interface channel on the hub sends status information to the remote control and can also accept commands to control the state of each of the peripherals. The hub can also forward commands to other hubs as appropriate depending on the destination hub that is stated in the command.

The following table (Table 2) shows the message format of the device availability status message that the hub sends to the remote control:

Byte | Description
--- | ---
0 | Page number = 2 (DEVICE_AVAILABILITY_PID)
1-2 | Device number of the connected neighbor hub (little endian)
3-7 | Reserved (set to 0xFF)

The following table (Table 3) shows the message format of the peripheral status message that the hub sends to the remote control:

Byte | Description
--- | ---
0 | Page number = 3 (UPDATE_DATA_PID)
1 | Shared address of the peripheral to which the message pertains (1-253)
2 | Reserved (set to 0xFF)
3-4 | Device number of the hub that sends the message (little endian)
5-6 | Reserved (set to 0xFF)
7 | Peripheral state: 0 = OFF 1 = ON

The following table (Table 4) shows the message format of the state command message that an ANT remote control sends to the hub to control one of the peripheral devices:

Byte | Description
--- | ---
0 | Page number = 4 (UPDATE_DATA_PID)
1 | Shared address of the peripheral to which the command is addressed (1-253)
2 | Reserved (set to 0xFF)
3-4 | Device number of the hub to which the command is sent (little endian)
5 | Bits 0-3: Reserved (0) Bits 4-7: Group (0-15)
6 | Reserved (set to 0xFF)
7 | Command: 0 = OFF 1 = ON 2 = Assign to group 3 = Assign to additional group 4 = Assign to all groups 5 = Clear from group 6 = Clear from all groups 7 = Reporting mode off 8 = Reporting mode on (default)

The following table (Table 5) shows the message format of the BLE service command message that a BLE remote control sends to the hub to control one of the peripheral devices:

Byte | Description
--- | ---
0 | Op_code = 0
1 | Command: 0 = REPORTING_MODE_OFF 1 = REPORTING_MODE_ON 2 = REPORTING_MODE_WARNINGS 3 = PERI_ON 4 = PERI_OFF
2 | Shared address of the peripheral to which the command is addressed (1-253)
3 | Group (0-15)
4-5 | Device number of the hub to which the command is sent (little endian)

# Setup

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

The ANT Auto Shared Channels Example requires at least four development boards: two hubs with one assigned peripheral per hub. Up to 253 peripheral devices can be added to each hub if required.

The example does not use any buttons. It uses the following LEDs:

- LED 1: Toggles on startup. ON when BLE advertising, OFF otherwise.
- LED 2: ON when hubs are connected and when a BLE master is connected to the hub.

A computer is used as remote control to connect to the hubs over ANT and BLE. For testing the ANT connection, an ANT USB dongle and ANTware II are required. For testing the BLE connection, a BLE dongle and Master Control Panel are required.

# Testing

Connect the devices by performing the following steps:

1. Compile and program the ant_shared_channel_master_to_master application to the two hub devices. If you want to test the BLE remote control connection, make sure that the S3xx SoftDevice is programmed and that the S3xx build configuration is selected in the build environment.
2. Compile and program the ant_shared_channel_slave application to the peripheral devices.
3. Power off all devices.
4. Turn on the two hub devices and bring them close to each other (about 10 cm distance). This must happen within 20 seconds.
5. Wait until LED 2 turns on for both hubs. If LED 2 does not turn on for both hubs, repeat the procedure, but bring the devices closer.
6. When the hubs are paired, separate them so that you can add peripherals (about 1 m distance).
7. Turn on a peripheral and bring it close to one of the hubs (about 10 cm distance). When the peripheral is connected to the hub, the peripheral's LED 2 will turn on. LED 1 should be off.
8. Repeat step 7 for all peripherals.

Test the ANT remote control connection of the ANT Auto Shared Channels Example application by performing the following steps:

1. Ensure that an ANT USB dongle is connected to the computer.
2. Start ANTware II and configure the channel according to the information shown in Table 1, but configure it to be a slave channel. Set the device number to 0 to connect to either of the hubs in the network.
3. Observe that the state of each peripheral, including the hub it is connected to, is indicated in the broadcast messages that are received in ANTware II. The format of this message is described in Table 3. For example, the message 03-01-FF-12-B9-FF-FF-00 indicates that the peripheral with assigned shared address 1 is connected to hub 47378 (0xB912) and that it is in OFF (0) state.
4. Send a command to any of the connected peripherals. The format of the command is described in Table 4. Use the acknowledged message type to see whether the message was sent successfully. For example, send the command 04-01-FF-12-B9-00-FF-01 to turn on the peripheral with assigned shared address 1. As a result, LED 1 on the peripheral should turn on.
5. Repeat steps 3 and 4 to check the other peripherals in the network.

Test the BLE remote control connection of the ANT Auto Shared Channels Example application by performing the following steps:

1. Ensure that an BLE USB dongle is connected to the computer.
2. Start Master Control Panel and click "Start discovery".
3. Click on either of the discovered hubs (name "LightDemo") and click "Select device".
4. Click "Service discovery" to list the services and characteristics that are available on the selected hub.
5. Click "Enable services" to enable the services on the hub.
6. Send a command to any of the connected peripherals. The format of the command is described in Table 5. Write to the second BLE characteristic (the one with a "write" property). For example, send the command 00-04-01-00-12-B9-00-00 to turn off the peripheral with assigned shared address 1. As a result, LED 1 on the peripheral should turn off.
7. Repeat step 6 to check the other peripherals in the network.