Calibrator Tool¶
Using Calibrator Tool¶
Overview¶
The CC33xx Linux driver provides the calibrator tool to configure the CC33xx device for various transmit and receive operations enabling measurement of RF performance of the device-under-test. The calibrator tool also provides an easy way to select the desired channel and power level. This enables the RF verification both in the lab and at certification test houses to perform the regulatory conformance tests and measure spectrum mask on the final product that is running the CC33xx driver on a Linux platform. The Calibrator tool can also be used for production line testing.
Prerequisites¶
In order for the calibrator tool to operate, kernel and modules must be compiled with
CONFIG_NL80211_TESTMODE=y. This can be verified using the below command:root@am335x-evm:/usr/share/cc33xx# zcat /proc/config.gz | grep NL80211_TESTMODEThe command output should be:
CONFIG_NL80211_TESTMODE=y
If the configuration is not enabled in the driver, the kernel and kernel modules need to be recompiled and installed to the device. For more information on how to enable this flag and integrate the changes, see the Getting Started Guide in the CC33xx Linux Software Package.
The
wlan0interface must be shut down. If the interface is already running then runifconfig wlan0 down
to disable the
wlan0interface. Verify thewlan0interface is disabled by running theifconfigcommand again. Thewlan0interface should no longer be part of the output.
Commands¶
Enable PLT Mode¶
Before running any of the commands, the device and the driver needs to be configured in Production Line Test (PLT) mode. Use the following commands to configure the device to PLT mode:
calibrator wlan0 plt power_mode on
To exit PLT Mode use the below command:
calibrator wlan0 plt power_mode off
Tune Channel¶
The purpose of the tune_channel command is to configure the CC33xx device to operate in a specific Wi-Fi
band and channel. The tune_channel command can be called using the following format:
calibrator wlan0 cc33xx_plt tune_channel <CHAN> <BAND> <BANDWIDTH>
Where each argument is defined as the following:
| Parameter | Option | Description |
| CHAN | 1 - 13 | 2.4 GHz Wi-Fi Channels |
| 36 - 165 | 5 GHz Wi-Fi Channels | |
| BAND | 0 | 2.4 GHz Wi-Fi Band |
| 1 | 5 GHz Wi-Fi Band | |
| BANDWIDTH | 0 | Bandwidth Allocation |
Note
Channel tune must be executed before any other calibrator activities. There is are no default channel tune parameters, thus they must be set before executing anything else.
Example
The following tune_channel command configures the chip to operate in the 2.4 GHz band on channel 6:
calibrator wlan0 cc33xx_plt tune_channel 6 0 0
Manual Calibration¶
The set_manual_calib command triggers the calibration process to optimize PHY performance and should be run after the tune_channel command. This should be rerun any time the tune_channel command
is rerun and prior to running the commands that set parameters.
calibrator wlan0 cc33xx_plt set_manual_calib -tx <TX> -rx <RX>
| Parameter | Option | Description |
| TX | 0 | Don’t Trigger TX Calibration |
| 1 | Trigger TX Calibration | |
| RX | 0 | Don’t Trigger RX Calibration |
| 1 | Trigger RX Calibration |
Transmit Chain Parameters¶
TX Parameters¶
The set_tx command can control the entire TX datapath and front-end on the CC33xx device. This command is
able to set preamble types, phy datarates, output power, control the number of data packets to transmit and the
data value within the packets, and many other functions.
Default TX settings are described in default_set_tx_table and can be enabled with the command:
calibrator wlan0 cc33xx_plt set_tx -default 0
The full command format is provided below. Please note that it is not necessary
to include every argument in the set_tx command.
calibrator wlan0 cc33xx_plt set_tx -preamble_type <PREAMBLE_TYPE> -phy_rate <PHY_RATE> -tx_power <TX_POWER> -gi_ltf_type <GI_LTF_TYPE> -dcm <DCM> -length <LENGTH> -delay <DELAY> -pkt_mode <PACKET_MODE> -num_pkts <NUM_PACKETS> -data_mode <DATA_MODE> -data_const_val <DATA_VALUE> -cca <CCA> -bss_color <BSS_COLOR> -su_er_bw <SU_ER_BW> -partial_aid <PARTIAL_AID> -src_addr <SRC_ADDR> -dst_addr <DST_ADDR> -nominal_pkt_ext <PKT_EXT> -feed_status <FEED_STATUS> -aid <AID> -group_id <G_ID>
The arguments are defined in the table below:
| Parameter | Options | Description |
|---|---|---|
| PREAMBLE_TYPE | 0 | 11b short preamble |
| 1 | 11b long preamble | |
| 2 | 11a/g legacy OFDM | |
| 3 | 11n mixed mode | |
| 4 | 11n GF (not supported) | |
| 5 | 11ax SU | |
| 6 | 11ax MU (not supported) | |
| 7 | 11ax SU ER | |
| 8 | 11ax TB | |
| 9 | 11ax TB NDP FB | |
| 10 | 11ac VHT (5 GHz Only) | |
| PHY_RATE | 1 | 1 Mbps |
| 2 | 2 Mbps | |
| 3 | 5.5 Mbps | |
| 4 | 11 Mbps | |
| 5 | 6 Mbps | |
| 6 | 9 Mbps | |
| 7 | 12 Mbps | |
| 8 | 18 Mbps | |
| 9 | 24 Mbps | |
| 10 | 36 Mbps | |
| 11 | 48 Mbps | |
| 12 | 54 Mbps | |
| 13 | MCS0 | |
| 14 | MCS1 | |
| 15 | MCS2 | |
| 16 | MCS3 | |
| 17 | MCS4 | |
| 18 | MCS5 | |
| 19 | MCS6 | |
| 20 | MCS7 | |
| TX_POWER | 0-31 | Integer value with a range of -10 dBm to 21 dBm with 1 dB steps |
| GI_LTF_TYPE | 0 | 1xLTF + 1.6 µs GI |
| 1 | 2xLTF + 1.6 µs GI | |
| 2 | 4xLTF + 3.2 µs GI | |
| 3 | 2xLTF + 0.8 µs GI | |
| 4 | 1xLTF + 0.8 µs GI | |
| 5 | 4xLTF + 0.8µs GI | |
| DCM | 0 | Disable DCM |
| 1 | Enable DCM | |
| LENGTH: range <start_length> <end_length> | 100-3500 | Number of data bytes excluding MAC 802.11 header. “Range” string in LENGTH requires arguments of <start_length> and <end_length>. This is only supported in Continuous Mode or PACKET_MODE <0>. -length range 0 100 |
| LENGTH: const packet <length> | Non MCS rate: 0 - 3500 MCS rate: 0 - 16000 | Number of data bytes excluding MAC 802.11 header. The “const packet” string in LENGTH requires argument of <length> -length const packet 2000 |
| DELAY | 50 - 1000000 | Delay between packets (µs) |
| PACKET_MODE | 0 | Continuous mode - transmits packets continuously until TX_STOP command is sent |
| 1 | Transmits a single packet | |
| 2 | <NUM_PKTS> is required if using this packet mode Transmits <NUM_PKTS> packets | |
| NUM_PACKETS | 1 - 10000 | Used when <PKT_MODE> = 2 Specifies number of packets to send |
| DATA_MODE | 0 | <DATA_VAL> is required if using this data mode Constant value |
| 1 | Increment value | |
| 2 | Random value | |
| DATA_VALUE | 0 - 255 | Required if <DATA_MODE> is 0 Data value used in all packets |
| CCA | 0 | Disable CCA |
| 1 | Enable CCA | |
| BSS_COLOR | 0 - 63 | This field is relevant for HE_SU and HE_SU_ER |
| SU_ER_BW | 0 | 242-tone RU |
| 1 | 106-tone RU | |
| PARTIAL_AID | 0 - 1023 | This relevant for VHT transmission |
| SRC_ADDR | xx:xx:xx:xx:xx:xx | Source MAC Address |
| DEST_ADDR | xx:xx:xx:xx:xx:xx | Destination MAC Address |
| PKT_EXT | 0 | 0 µs |
| 1 | 8 µs | |
| 2 | 16 µs | |
| FEED_STATUS | 0 / 1 | Indicates the value of the one bit used to modulate the tones in each tone set. This field is relevant for HE TB NDP FB transmissions only. |
| AID | 0 - 16383 | AID of station can be up to 16383 (14 bits) |
| G_ID | 0 | (not supported) |
Set_TX Default Parameters¶
| Parameter | Value | Description |
|---|---|---|
| PREAMBLE_TYPE | 2 | 11a/g legacy OFDM |
| PHY_RATE | 5 | 6 Mbps |
| TX_POWER | 0 | -10 dBm |
| GI_LTF_TYPE | 2 | 4xLTF + 3.2 µs GI |
| DCM | 0 | Disable DCM |
| LENGTH | 100 | 100 data bytes |
| DELAY | 3000 | 3000 µs delay between packets |
| PACKET_MODE | 0 | Continuous mode |
| NUM_PACKETS | 300 | N/A when PACKET_MODE = 0 (Continuous Mode) |
| DATA_MODE | 2 | Random Value |
| DATA_VALUE | 0x55 | N/A when DATA_MODE = 2 (Random Value) |
| CCA | 1 | Enable CCA |
| BSS_COLOR | 13 | |
| SU_ER_BW | 0 | 242-tone RU |
| P_AID | 15 | |
| SRC_ADDR | 0x665544332222 | |
| DEST_ADDR | 0x060504030202 | |
| PACKET_EXT | 1 | 8 µs |
| FEED_STATUS | 0 | |
| AID | 11 | |
| G_ID | 0 |
TX Trigger-Based Parameters¶
The set_tb_tx command is used to set the trigger based transmission parameters in the CC33xx device.
The set_tb_tx command is formatted as such:
calibrator wlan0 cc33xx_plt set_tb_tx -he_ltf_num <NUM_HE_LTF> -ru_alloc <RU_ALLOC> -ul_bw <UL_BW> -tb_auto <TB_AUTO>
The arguments are defined below:
| Parameter | Option | Description |
|---|---|---|
| NUM_HE_LTF | 0 | 1 HE LTF |
| 1 | 2 HE LTF | |
| 2 | 4 HE LTF | |
| 3 | 6 HE LTF | |
| 4 | 8 HE LTF | |
| RU_ALLOC | 0 - 60 | Resource Unit Allocation |
| UL_BW | 0 | 20 MHz |
| 1 | 40 MHz | |
| 2 | 80 MHz | |
| TB_AUTO | 0 | Disabled |
| 1 | Enabled |
TX Tone Start and Stop¶
The purpose of the tx_start_tone command is to create and transmit a carrier wave that can be modulated
with a fixed tone. The tx_tone_stop command can be used to stop the continuous wave transmission.
The tx_start_tone command is formatted as such:
calibrator wlan0 cc33xx_plt tx_start_tone <MODE> <OFFSET>
| Parameter | Option | Description |
| MODE | 2 | Single tone: TX chain is on and a sinusoidal signal is outputted |
| OFFSET | -40 - 40 | Integer value with range of -10 MHz to +10 MHz with steps of 0.25 MHz |
The tx_tone_stop command is formatted as such:
calibrator wlan0 cc33xx_plt tx_tone_stop
Examples
The below section provides examples of using the commands for different modes of transmission and TX channel occupancy.
calibrator wlan0 plt power_mode on calibrator wlan0 cc33xx_plt tune_channel 6 0 0 calibrator wlan0 cc33xx_plt set_manual_calib -tx 1 calibrator wlan0 cc33xx_plt set_tx -default 0 calibrator wlan0 cc33xx_plt set_tx -preamble_type 3 -phy_rate 20 -num_pkts 1000 -pkt_mode 2 -src_addr 04:05:05:05:05:04 -dst_addr 06:07:07:07:07:06 calibrator wlan0 cc33xx_plt start_tx calibrator wlan0 cc33xx_plt stop_tx calibrator wlan0 cc33xx_plt set_tx -length const packet 500 calibrator wlan0 cc33xx_plt start_tx calibrator wlan0 cc33xx_plt stop_tx
This is an example for using calibrator tool in autonomous trigger based operation.
calibrator wlan0 plt power_mode on calibrator wlan0 cc33xx_plt switch_ant 1 calibrator wlan0 cc33xx_plt tune_channel 1 0 0 calibrator wlan0 cc33xx_plt set_manual_calib -tx 1 calibrator wlan0 cc33xx_plt set_tx -default 0 calibrator wlan0 cc33xx_plt set_tx -preamble_type 8 -phy_rate 13 -tx_power 31 -length const packet 30 -delay 1100 calibrator wlan0 cc33xx_plt set_tb_tx -he_ltf_num 2 -ru_alloc 4 -ul_bw 0 -tb_auto 1 calibrator wlan0 cc33xx_plt start_tx calibrator wlan0 cc33xx_plt stop_tx
Receive Chain Parameters¶
Enable/Start RX Statistics Test¶
Similar to TX commands there are RX commands that can be used to receive the packets and obtain statistics on the same. The CC33xx device’s firmware is able to capture packets from the air and report RF statistics. This feature can be used to ensure the calibration, antennas, and radio on the device are working properly. This section shows how to use the RX statistics command for receiver (RX) testing.
Use the start_rx command to start the receive RF chain:
calibrator wlan0 cc33xx_plt start_rx -source_mac <SRC_ADDR> -ack_enable <ACK_ENABLE>
To print out the received statistics, use the get_rx_stats command:
calibrator wlan0 cc33xx_plt get_rx_stats
After receiving packets, this command will print statistics of the received packets to the command in a format similar to the following:
Total Received Packets: 0 FCS Errors: 0 MAC Mismatch: 0 Good Packets: 0 Average RSSI (SOC): 45 Average RSSI (ANT): 0 status: 19 PER: N/A # PER = Total Bad / Total Received
The following is an example sequence of how to start collecting packets with the receiver:
calibrator wlan0 plt power_mode on calibrator wlan0 cc33xx_plt tune_channel 6 0 0 calibrator wlan0 cc33xx_plt set_manual_calib -rx 1 calibrator wlan0 cc33xx_plt start_rx -source_mac 04:05:05:05:05:04 -ack_enable 1 calibrator wlan0 cc33xx_plt get_rx_stats
Disable/Stop RX Statistics Test¶
The following command will stop the RX statistics test. It is crucial to finish the test with this command:
calibrator wlan0 cc33xx_plt stop_rx
BLE Testing¶
BLE testing can done be through calibrator tool as well. The device must first be
put into the BLE testing mode. Users can then execute HCI vendor specific commands
to control the BLE radio. Use the ble_plt command to put the CC33xx device into
BLE testing mode.
calibrator wlan0 cc33xx_plt ble_plt
I/O Commands¶
Set I/O Pin Configuration¶
The set_io_conf command allows for configuration of the I/O pins on the cc33xx device.
There are 18 pins, listed below, that can be configured as either input or output.
If a pin is to be configured as output, then the pin state can also be configured as high or low.
calibrator wlan0 cc33xx_plt set_io_conf <IO_ID> <DIR> <STATE>
| Parameter | Option | Description |
| IO_ID | 0 | SLW_CLK_IN |
| 1 | SDIO_CLK | |
| 2 | SDIO_CMD | |
| 3 | SDIO_D0 | |
| 4 | SDIO_D1 | |
| 5 | SDIO_D2 | |
| 6 | SDIO_D3 | |
| 7 | HOST_IRQ_WL | |
| 8 | UART1_TX | |
| 9 | UART1_RX | |
| 10 | UART1_CTS | |
| 11 | UART1_RTS | |
| 12 | COEX_PRIO | |
| 13 | COEX_REQ | |
| 14 | COEX_GRANT | |
| 15 | HOST_IRQ_BLE | |
| 16 | FAST_CLK_REQ | |
| 17 | ANT_SEL | |
| DIR | 0 | Input |
| 1 | Output | |
| STATE | 0 | High |
| 1 | Low |
Get I/O Pin Configuration¶
The get_io_conf command allows for printing the configuration of the I/O pins on the cc33xx device.
calibrator wlan0 cc33xx_plt get_io_conf <IO_ID>
| Parameter | Option | Description |
| IO_ID | 0 | SLW_CLK_IN |
| 1 | SDIO_CLK | |
| 2 | SDIO_CMD | |
| 3 | SDIO_D0 | |
| 4 | SDIO_D1 | |
| 5 | SDIO_D2 | |
| 6 | SDIO_D3 | |
| 7 | HOST_IRQ_WL | |
| 8 | UART1_TX | |
| 9 | UART1_RX | |
| 10 | UART1_CTS | |
| 11 | UART1_RTS | |
| 12 | COEX_PRIO | |
| 13 | COEX_REQ | |
| 14 | COEX_GRANT | |
| 15 | HOST_IRQ_BLE | |
| 16 | FAST_CLK_REQ | |
| 17 | ANT_SEL |
Debug Commands¶
The rts_th_cfg command allows the user to manually set the RTS packet size threshold. When the device is getting ready to transmit a packet beyond
a certain threshold, then an RTS packet will be transmitted first to make sure the air is clear. This command allows the user to manually set the packet size
threshold that will require an RTS packet to be sent. The command will be formatted as such:
calibrator wlan0 CC33xx_debug rts_th_cfg <RTS_THRESHOLD> <ROLE_ID>
| Parameter | Option | Description |
| RTS_THRESHOLD | 0-2347 | Packet size (bytes) threshold for when RTS packet will be sent |
| ROLE_ID | 1 | STA-STA Mode |
| 2 | STA-AP Mode |
The beacon_rssi command displays the RSSI of the last beacon received. The command will be formatted as such:
calibrator wlan0 CC33xx_debug beacon_rssi
The psm command is used to configure the powersave mode. For more information regarding the psm command please see
calibrator-psm. The format and parameters are provided below:
calibrator wlan0 CC33xx_debug psm <INDEX> <VALUE>
| Parameter | Option | Description | Parameter | Option | Description |
| INDEX | 0 | ACTIVE_MODE_RX_TH | VALUE | 0 - 255 | RX Threshold value |
| 1 | ACTIVE_MODE_TX_TH | 0 - 255 | TX Threshold value | ||
| 2 | ACTIVE_MODE_RX_TO | RX Timeout Value (microseconds) | |||
| 3 | ACTIVE_MODE_TX_TO | TX Timeout Value (microseconds) | |||
| 4 | FORCE_POWER_MODE | 0, 1, 2 | 0 - No Force 1 - Force Active 2 - Force Power Save |
Note that the index and value on the same row should be used in conjuction. For example if using ACTIVE_MODE_RX_TH then a RX Threshold value must be selected. An example of how this command would be formatted is below:
calibrator wlan0 CC33xx_debug psm 0 200
The ba_session command is used to enable/disable the RX and TX Block Acknowledgments. A 1 inputted for a parameter
will enable the RX or TX Block Acknowledgements respectively. A 0 will disable them. The command will be formatted as such:
calibrator wlan0 CC33xx_debug ba_session <BLOCK_ACK_RX> <BLOCK_ACK_TX>
The tb_only command is used to enable/disable trigger based only transmission. This is a Wi-Fi 6 features and could
be used to evaluate Wi-Fi 6 only performance as other Wi-Fi versions would be disabled. The command will be formatted as such:
calibrator wlan0 CC33xx_debug tb_only <ENABLE>
Acronyms¶
| Acronym | Definition |
|---|---|
| PLT | Production Line Testing |
| MAC | Medium Access Layer |
| WLAN | Wireless LAN |
| LAN | Local Area Network |
| TX | Transmit |
| RX | Receive |
| MIMO | Multiple Input Multiple Output |
| PER | Packet Error Rate |
| OFDM | Orthogonal Frequency-Division Multiplexing |
| LTF | Long Training Field |
| GI | Guard Interval |
| DCM | Dual Carrier Modulation |
| CCA | Clear Channel Assessment |
| SU ER BW | Single User Extended Range Bandwidth |
| VHT | Very High Throughput |
| AID | Association ID |
| HE TB NDP FB | High Efficiency Trigger Based Null Data Packet Feedback |
Power Save Mode in Calibrator¶
Overview¶
Based on IEEE802.11 standards a station (STA) can communicate two different power save modes to an AP that it is connected to:
- Active Mode - In this power mode the STA remains awake and the AP is able to send traffic to it at any time.
- Power Save Mode - In this power mode the STA changes between going to sleep and being awake without notifying the AP. As such the AP cannot send traffic to the STA without utilizing a power save deliver protocol that use a variety of elements such as delivery traffic indication messages (DTIM) and Power Save Polling (PS-Poll) packets.
When there is a heavy amount of traffic it is more efficient for the STA to remain active as power save mode can introduce latency in that case. However, during low traffic periods it is can be advantageous for the STA to be in power save mode to conserve as much power as possible by returning to sleep at the earliest opportunity.
By default, the CC33xx switches between these modes dynamically based on the following parameters:
- RX TIMEOUT - Time since last rx packet
- TX TIMEOUT - Time since last tx packet
- RX THRESHOLD - Number of rx packets
- TX THRESHOLD - Number of tx packets
For example if the CC33xx is in active mode, then if the TX or RX TIMEOUT threshold is reached the device will transition to power save mode. Likewise, if the CC33xx is in power save mode, then after sending a TX THRESHOLD number of packets or receiving an RX THRESHOLD number of packets it will transition to active mode.
Default Values¶
If the device is in active mode then it will use the below RX and TX TIMEOUT by default as the threshold to decide when it will switch to power save mode.
- RX TIMEOUT - 40000 microseconds
- TX TIMEOUT - 5000 microseconds
If the device is in power save mode then it will use the below RX and TX THRESHOLDS by default as the threshold to decide when enough packets have received or transmitted that it is more efficient to be in active mode.
- RX THRESHOLD - 4 packets
- TX THRESHOLD - 2 packets
Configuring the Timeouts and Threshold¶
The default values can be changing using the PSM debug command as described in calibrator-tool.
Building Calibrator Tool¶
Overview¶
The calibrator tool is used to configure the CC33xx device in order to better measure RF performance under specific conditions. Further description of the use of the calibrator tool can be found in calibrator-tool. The purpose of this document is to explain how to build the calibrator tool for different targets using the calibrator sources provided in the CC33XX SDK in the folder ‘calibrator_src’. This folder includes all the required sources along with a Makefile and a build script which will be the main subject of this document.
Building¶
To build the calibrator tool on a different target, the user must first edit and run the build_calibrator.sh script in ‘calibrator_src’ after configuring and building the libnl library. In the script it is necessary for the toolchain that is used for cross-compiling to be specified as well as the compiler being used. These arguments will be entered as seen below as a parameter for TOOLCHAIN_PATH and CROSS_COMPILE respectively. Once these arguments have been entered the script can be run and calibrator tool will be built for the required target.
Building Libnl¶
The libnl library is used to provide APIs for netlink protocol based Linux kernel interfaces.
Create directory for where files can be compiled for libnl target.
mkdir libnl_target
Create and navigate to a directory for the libnl source libraries.
mkdir libnl_src cd libnl_srcClone the git repository for libnl source. Note that version 3.5.0 is supported.
git clone --depth 1 --branch libnl3_5_0 https://github.com/thom311/libnl.gitExport the paths necessary for cross compilation (PATH, ARCH, CC). These should be found in the host processor SDK as they will be processor specific.
Run the script autogen.sh which will generate the configure file.
./autogen.sh
Then run the command to configure the environment?
./configure --host={ARCH} --prefix=<path to libnl target directory> CC=compiler
Run the make command and then
make -j12 #adjust processor number (12) based on machine make install
Building Calibrator¶
Go to the calibrator_src directory
cd ~/<SDK Path>/cc33xx/calibrator_srcEdit the build_calibrator.sh script on the following lines.
line 5: Set NL_HEADERS equal to the absolute path to where the headers are located, this should be an absolute path to libnl_target/include/libnl3 line 6: Set NL_LIB equal to the absolute path to the directory where libnl-genl-3.a can be found in the compiled libnl_target line 9: Set TOOLCHAIN_PATH equal to path specified by host processor SDK line 10: Set CROSS_COMPILE equal to the compiler prefix that is specified in the SDK of the host processor line 11: Set ARCH equal to the CPU architecture
Example using AM335x¶
Terminal Commands¶
#go to cc33xx_rootfs path cd ti-processor-sdk-linux-am335x-evm-08.02.00.24/cc33xx/cc33xx_rootfs/usr #create directory for libnl source code mkdir libnl_src #create directory for libnl target code mkdir libnl_target #create directory for libnl source code mkdir libnl_src #create directory for libnl target code mkdir libnl_target #clone libnl version 3.5.0 to libnl source code directory cd libnl_src git clone --depth 1 --branch libnl3_5_0 https://github.com/thom311/libnl.git export PATH="ti-processor-sdk-linux-am335x-evm-09.xx.xx.xx/linux-devkit/sysroots/x86_64-arago-linux/usr/bin:$PATH" export ARCH=arm export CC=arm-none-linux-gnueabihf- ./autogen.sh #note that --prefix needs the absolute directory without '~' ./configure --host=arm --prefix=~/ti-processor-sdk-linux-am335x-evm-09.xx.xx.xx/cc33xx/cc33xx_rootfs/usr/ CC=arm-none-linux-gnueabihf-gcc make -j12 make install #building calibrator tool cd ~/ti-processor-sdk-linux-am335x-evm-09.xx.xx.xx/cc33xx/calibrator_src vi build_calibrator.sh
Script “build_calibrator.sh” Changes¶
In the build_calibrator.sh script the following varibales should be configured:
# compiled libnl library - in this directory there should be include/libnl3 and lib/libnl-genl-3.a
NL_HEADERS=/home/user/libnl_target/include/libnl3
NL_LIB=/home/user/libnl_target/lib
# the toolchain path is specific to the SDK
export TOOLCHAIN_PATH=/home/user/ti-processor-sdk-linux-am335x-evm-08.02.00.24/linux-devkit/sysroots/x86_64-arago-linux/usr/bin/
# compiler prefix (arm-linux-gnueabihf- or similar)
export CROSS_COMPILE=arm-none-linux-gnueabihf-
OTP Configuration¶
Introduction¶
The CC33XX devices have One Time Programming (OTP) bits that a user can program to store certain information permanently to the device. These OTP bits can be used to store the following information:
- Custom Base MAC Address
- Configuration Key
- Country Code
- OTP Lock
In order to use the OTP calibrator commands, customers must use a specific firmware. This firmware can be found in the tools/otp_programming folder and needs to be temporarily installed to the target’s /lib/firmware/ti-connectivity/ folder. This firmware should only be used for OTP programming purposes.
Warning
The OTP fields can only be written to once and cannot be undone!
Warning
The OTP fields need to be locked after they are set to prevent any possible rewriting or changes.
Note
Writing to the OTP bits will require a TOKEN_ID, which will not be mentioned in this document. To request TOKEN_ID, consult TI via e2e.ti.com.
Custom Base MAC Address¶
Users may elect to program the device with their own MAC address. The MAC address that is programmed should be the BASE MAC address, as the CC33xx FW will use this base address to calculate two incremental addresses. For a detailed explanation, see MAC Address Allocation. Therefore, users should ensure that each CC33xx is allocated 3 total MAC addresses.
The MAC Address can be programmed with the following:
calibrator wlan0 cc33xx_plt set_efuse -mac_addr xx:xx:xx:xx:xx:xx -token <TOKEN_ID>
Configuration Key¶
Some users will require the ability to ensure that the cc33xx-conf.bin loaded into the device is generated only by the original user. This way end-users will not have the ability to change the cc33xx-conf.bin and only use those intended by the original user.
The configuration key (referred to as “conf_key”) is a 32-bit decimal value determined by the user, like a password. After this value is set into the OTP bits, the firmware will then use value as a seed number. The seed value is then used to calculate a checksum number (CRC) based on particular parameters from the cc33xx-conf.bin. This same CRC must also be set in the cc33xx-conf.bin. The parameter to set the CRC in cc33xx-conf.bin is crc_conf.user_checksum.
Once the conf_key is burned into the device, and after loading the firmware and cc33xx-conf.bin, the CRC value calculated from the conf_key and relevant parameters must match the checksum number in the cc33xx-conf.bin. Otherwise, the device will halt execution.
The parameters that affect the calculated CRC are as follows:
- PowerLimitArray
- InsertionLoss_2_4GHz
- InsertionLoss_5GHz
- AntGain_2_4GHz
- AntGain_5GHz
- BleChLim1M
- BleChLim2M
- RegDomain
- CountryCode
Warning
It is NOT possible to read back the conf_key once it is fused!
The configuration key can be programmed with the following:
calibrator wlan0 cc33xx_plt set_efuse -conf_key <32-bit hexadecimal value> -token <TOKEN_ID>
An example conf_key could be written as “0x01234567”.
Country Code¶
Setting the country code bits has no effect on the RF performance or regulatory behavior of the device. It can be used solely to ensure an additional step of certainty that the device can be used within a particular region. The country code below can be any two letters of the user’s choosing.
calibrator wlan0 cc33xx_plt set_efuse -country_code XX --token <TOKEN_ID>
For users who would like to lock the country code to the cc33xx-conf.bin, the country_code_restriction field can be enabled. The device will not boot unless the same country code is supplied in the cc33xx-conf.bin.
OTP Lock¶
To protect the OTP bits from being programmed further, the user is required to lock the OTP section. This is done by the following command:
calibrator wlan0 cc33xx_plt lock_efuse -token <TOKEN_ID>