wl12xx Calibration

The following page provides a description of the process required to calibrate the TI WL12xx devices as well as the tools and methods required for that purpose.

Overview

Calibration is a process of determining radio parameters for a chip per the chip. These configuration parameters are specific to the chip on the specific design and therefore are sent back to the driver to store in non-volatile memory for later use. Upon initialization, the wl12xx driver will load an NVS file where it expects to read those parameters and send them to the chip.

The NVS file contains 2 main parts - one stores the calibration parameters and the other one stores initialization information required for the wl12xx driver.

The steps

The process described below involves the following steps:

  1. Download the calibrator tool
  2. Build the calibrator executable
  3. Choose your INI file for the initialization data
  4. Use the calibrator to generate a reference NVS file
  5. Perform the first calibration
  6. Detailed description of the calibration process

Downloading the calibrator tool

The calibrator tool and all associated files are to be found at the following location:

git clone git://github.com/gxk/ti-utils.git

The build process

Make sure your kernel is configured to support nl80211 testmode commands (NL80211_TESTMODE=y). The calibrator tool requires the use of libnl v2.x package.

Set the following environment variables:

export NFSROOT=<path to roofs of a target where installed libnl library>
export CROSS_COMPILE=arm-none-linux-gnueabi-

Compile

make

Choose an INI file

It is important to select an INI file that matches the firmware in use. Sample INI files can be found under ini_files folder or here. The INI files are organized into 3 folders - for station, access-point or in development.

Here's a list of recommended INI files for different platforms.

Platform INI
Beagle Board with Beagle Toy TQS_S_2.6.ini

Generate a NVS reference file

Create NVS reference file

./calibrator set ref_nvs ./<ini file>

Copy newly created NVS file to the proper location

cp new-nvs.bin /lib/firmware/ti-connectivity/wl1271-nvs.bin

Perform the first calibration

Make sure the network interface is down. You can use ifconfig command to verify. If needed, reboot your system. Calibrate.

Note: You need to have CONFIG_NL80211_TESTMODE enabled in your kernel configuration.

./calibrator plt calibrate

Copy newly created file to the proper location

cp new-nvs.bin /lib/firmware/ti-connectivity/wl1271-nvs.bin

Reboot the system

Your newly created NVS will be used the next time the wl12xx driver loads.

Detailed instructions manual for the calibrator procedures

TxBip procedure

First make sure MAC address is assigned to an interface before the starting with this procedure. For example, 'ifconfig wlan0 hw ether xx:xx:xx:xx:xx:xx'

There are two modes of operation:

  1. Default mode - use default values
  2. Expert mode - all parameters need to be set manually

Default mode Use default values

calibrator plt calibrate

Expert mode

calibrator wlan0 plt power_mode on
calibrator wlan0 plt ref_point <voltage> <power> <subband>
calibrator wlan0 plt tx_bip <0|1> <0|1> <0|1> <0|1> <0|1> <0|1> <0|1> <0|1>
calibrator wlan0 plt power_mode off

The result of this procedure is a new NVS file created on the current working directory with the name ./new-nvs.bin. In order for the wl12xx driver to use it, the NVS file needs to be copied to /lib/firmware/wl1271-nvs.bin and the wl12xx driver needs to be reloaded.

TxCont procedure

calibrator wlan0 plt power_mode on
calibrator wlan0 plt tune_channel <band> <channel>
calibrator wlan0 plt tx_cont <delay> <rate> <size> <amount> <power> <seed> <pkt mode> <DC on/off> <gi> <preamble> <type> <scramble> <clpc> <seq nbr mode> <dest mac>
calibrator wlan0 plt tx_stop
calibrator wlan0 plt power_mode off

This test sends packets of data to the air. It receives several parameters as described below, to enable diversity of operational modes. It is mostly used to inspect Energy and the radio emissions. Content of packets can be random, or zozo (ie, zero, one, zero, one, etc).

Packets sent are configurable with the following parameters:

  • Delay between packets in microseconds

Use the following table to determine which value to use

Rate

Value

1 Mbps

0x00000001

2 Mbps

0x00000002

5.5 Mbps

0x00000004

6 Mbps

0x00000008

9 Mbps

0x00000010

11 Mbps

0x00000020

12 Mbps

0x00000040

18 Mbps

0x00000080

24 Mbps

0x00000200

36 Mbps

0x00000400

48 Mbps

0x00000800

54 Mbps

0x00001000

MCS0

0x00002000

MCS1

0x00004000

MCS2

0x00008000

MCS3

0x00010000

MCS4

0x00020000

MCS5

0x00040000

MCS6

0x00080000

MCS7

0x00100000

  • Size of data field in MPDU (in bytes, 0 - 2284)
  • Amount - number of packets in case of using series mode
  • Power - output power in dBm*1000
  • Seed - value for the scrambler
  • Packet mode - 0-single, 1-multipile, 3-continuos, 4-FCC
  • DC on/off - activate DCF
  • gi - guard interval on/off for 11n rates
  • Preamble
    • 1 Mbps - long preamble mode=0 2, 5.5, 11 Mbps - long preamble mode=0, short preamble mode=1 6, 9, 12, 18, 24, 36, 48, 54 Mbps - ofdm preamble mode=4 from MCS_0 to MCS_7 - n mixed mode preamble mode=6, greenfield preamble mode=7
  • Type is 0-data packet, 1-ack, 2-probe req, 3-random data, 4-user data
  • Scrambler - on/off
  • CLPC - range 0-100 is disable calibration
  • Sequence number mode (incremented or fixed)
  • Destination Mac address

RxStat procedure

There are two modes of operation:

  1. Default mode - use default values
  2. Expert mode - all parameters need to be set manually

Default mode In the default mode, the statistics will be reseted with every test.

calibrator plt rx_statistics

Expert mode

calibrator wlan0 plt power_mode on
calibrator wlan0 plt start_rx_statcs
calibrator wlan0 plt get_rx_statcs
calibrator wlan0 plt stop_rx_statcs
calibrator wlan0 plt power_mode off

If you want to reset the statistic run

calibrator wlan0 plt reset_rx_statcs

Update NVS file procedure

This procedure changes initialization information section within NVS file. It is mainly useful when calibration has already been performed and there is a need to change the initialization information inside the NVS file

calibrator set upd_nvs <ini file> [<nvs file>]

If NVS filename parameter not supplied, the current NVS file will be used from destination directory (usually /lib/firmware).

Miscellaneous procedures

  • Read MAC address from NVS file

calibrator get nvs_mac <nvs filename>
  • Set MAC address in NVS file

calibrator set nvs_mac <mac addr xx:xx:xx:xx:xx:xx> <nvs file>
  • Push local NVS to the system

calibrator phy <phyname> set push_nvs <nvs filename>
  • Dump NVS file

calibrator get dump_nvs [<nvs filename>]

Additional support

For any questions on the tool, please visit our IRC channel #wl12xx on freenode.net Alternatively, you can send an email to Gery Kahn (geryk <at> ti <dot> com) and CC linux-wireless@vger.kernel.org.