Setup and run ANTware software to send and receive data
|Platform||Test Tools||SAM3U2 Firmware||nRF51422 Firmware||Software|
ANT USB Module
USB RS-232 Converter
MPG1 Board Test
MPG2 Board Test
Having the right tools and understanding how to use those tools is very important for engineering. Radio communications are particularly difficult to debug as finding out what may be broken may be anywhere between a host processor and radio transmitter sending data and the radio receiver and host processor receiving data. Having at least one known working endpoint is essential.
For the ANT radio system we use an ANT USB Module with the ANTware II software package that provides everything required to test a system in an easy-to-use graphical user interface. The goal of this module is to demonstrate the features you will need to use in ANTware and also introduce some preliminary concepts of the ANT radio. All details of the ANT protocol can be found in the ANT Message Protocol and Usage document.
Refer to the following image when configuring ANTware:
- Open ANTware
- Plug in the ANT USB stick to an available USB port and click “Refresh” in ANTware
- Click the down-arrow to select the ANT module that appears under Available Devices
- Under the Info/Net tab, check “Enable Ext Msg Details on Receive” then click Set Network 0
Channel ID, Channel Period, Radio Frequency
ANT uses a Master-Slave relationship for all connections. Once synchronized, they are said to have “paired” and will continue to exchange data until at least one of the two closes the channel. Knowledge of a device’s role is required to properly configure a node. Every ANT node is fundamentally defined by its channel ID: a 2-byte Device Number, a 1-byte Device Type, and a 1-byte Transmission Type. The MSB of the Device Type is designated the “Pairing bit” for an additional level of control when establishing a connection. The Channel ID is different than the Channel Number. The ANT USB device supports 8 Channels (0 – 7) — these are accessed with the tabs along the top of the screen. Each Channel can have a different Channel Assignment and Channel ID, and can communicate with different devices.
A Master device must have its Channel ID fully defined and always broadcasts with these parameters. A Slave device can use 0 values (wildcards) for any or all of the Channel ID parameters to listen for different Masters. Once a Master and Slave pair with each other, they will communicate exclusively. If the Master stops broadcasting for a certain amount of time, the Slave will drop back to scanning for the Channel ID that it paired with.
The Channel Period is the rate at which the system sends messages and this is typically 4Hz (one message every 250ms). Each message can carry 8 bytes of data. 32 bits-per-second is not very impressive, but the primary objective of a very low power wireless systems like ANT is of course to be low power. ANT is not intended to transmit a ton of data quickly. Data throughput can be increased by increasing the Channel Period or by using Burst messages. In both cases, average power consumption goes up. The theoretical maximum data rate for ANT is about 60,000bps but would require the transmitter and received to be on essentially full time and thus consume milliamps (mA) of current compared to microamps (uA) of current.
Both the Master and Slave MUST be broadcasting at the same radio frequency. We will usually set the program development boards on channel 50 (2450MHz).
- Select Slave in the drop down and click “Assign”
- Open the Channel ID drawer and set all to 0 then click “Set ID”
- Enter 8192 (or 4Hz) and click Set Channel Period
- Enter 50 (MHz) and click Set Radio Frequency to configure 2450MHz communication
Opening the Channel
For communication to occur between ANT nodes both devices have to activate their radios. This is called opening the channel. Once the Master channel is open, it ALWAYS sends out an 8-byte data packet at the Channel Period. This is how ANT maintains channel synchronization and is possibly the hardest thing to get used to about the ANT protocol. These transmissions are precisely timed and are what keep the channel synchronized. The Master will continuously send the 8-byte data that it was last told to send. The default is 00-00-00-00-00-00-00-00. Slave devices must have their receivers on regularly in case a Master happens to send some data. The Slave does not broadcast any data while it is waiting to hear a Master. If a Slave has paired with a Master, then it is able to turn on its receiver at just the right moment to hear the Master and thus also run in a very low power state. If the Slave has not paired, then it is searching using a receiver duty cycle such that pairing will take 2-3 seconds (at 4Hz Channel Period) but still be relatively low power.
If an application requires near-instantaneous connections, the Slave can be configured as a “Scanning Channel” where the receiver is forced on 100% of the time. In this state it is pulling a relatively large amount of current continuously (about 10mA), but it will always hear a broadcasting Master immediately. A Scanning Channel does not pair with a particular Master, so it is will hear any Master that meets the Slave’s configured Channel ID including wildcards. This is the mode we will use for the exercise to ensure we can see our Master(s). Note that when a Scanning Channel is active, no transmit data from the Slave can be initiated since only the receiver is on.
- Click the Advanced tab
- Click Open Scan Mode. If there are no Masters in the area, then nothing will appear to happen but the receiver is active and ANT is looking for a Master. The window on the right is where data messages will appear.
Broadcasting from the Master
In the ANTware configuration above, any Master device sending on the same frequency will be heard by the Slave Scanning Channel. The Boardtest firmware can be used to test this as it runs the ANT radio in Master mode. It sends a predictable message that incrementally counts the number of messages sent between the two devices. This is easy to see in the data window to help us identify the different parts of the data message.
- Open the Boardtest firmware in IAR, connect to the J-Link and start the debugger to flash the firmware.
- Attach the board to a PC via the serial debug port. Use TeraTerm at 115200-8-N-1 no flow control.
- Run the code and wait for the boot sequence.
- Press BUTTON1 to open the Master Channel. You should see data streaming in to ANTware.
- Press BUTTON1 to stop transferring data.
Interpreting the data
The data above should look similar to the data that your system is receiving.
- :: 4e, is the start of a message line with the Message ID (0x4e) for “Broadcast Data”
- 00-00-00-00-00-00-00-00-07 (last line in example): the left-most byte is the channel number and the subsequent 8-bytes is the data payload. In this case, the development board is incrementing a 3-byte counter with every message. The three bytes are the right-most bytes
- 80-34-12-60-01: This is the “Extended Message” data. This is not extra data sent over the air, but it is extra information forwarded by the ANT protocol interpreter in the reported message. It is especially useful with scanning channels to identify the Channel ID parameters of any Master device the Slave is listening to.
- 0x80 is a flag byte (the MSB indicates the extended message includes channel data)
- 0x34 and 0x12 are the LSb and MSb of the two byte device ID. 0x1234 is our configured default value.
- 0x60 is the configured Device Type
- 0x01 is the configured Transmission Type
Open mpgl1_board_test.h and enter your ID number on lines 27-29. You must convert your number to hex and then break up the hex number into a low byte and high byte. The default value is 0x1234 (decimal 4660) so the “HI” byte is 0x12 and the “LO” byte is 0x34 (“HI” and “LO” are short for “high” and “low”). Working byte-wise with numbers like this in embedded systems is extremely common. Also update the u32 decimal value – this is printed on the debug port when the board starts. It should match the hex value (e.g 0x1234 = 4660).
#define ANT_DEVICEID_LO_BOARDTEST (u8)0x34 #define ANT_DEVICEID_HI_BOARDTEST (u8)0x12 #define ANT_DEVICEID_DEC_BOARDTEST (u32)4660
- Rebuild the code and repeat the transmission test using the Scanning Channel to observe the difference in the message that is being sent.
- In ANTware, close the channel and modify the Channel ID to specifically match your device. This will ensure that you are only listening to your development board.
- Click Set ID and open the channel to make sure you see your broadcast data.
If you can do all of this successfully, you now have the skills to use ANTware to monitor ANT communications. As long as all of the channel parameters are configured correctly, you can use ANTware to sniff any ANT communications taking place.
Use the following resources to learn more about ANT:
2017-APR-20: Update Device ID definitions to match new ANT API naming
2017-JAN-30: Update images to remove “Shared” channel selection
2017-JAN-15: Fix Device ID entry from configuration.h to mpgl1_board_test.h.
2016-MAR-02: First release.