/filters:background_color(white)/2024-04/Sona%20TI351%20-%20Family%20%281%29.png)
Introduction
Ezurio supports a set of tools for use with the Sona TI351 during the regulatory certification process. This application note provides information on these tools and how to use them.
In order to support multiple platform architectures, Ezurio makes available several different versions of the regulatory tools package.
Table 1: PackageNames
| Platform | Name |
|---|---|
| arm soft-float | regTI351-arm-eabi-\<version>.sh |
| arm hard-float | regTI351-arm-eabihf-\<version>.sh |
| arm 64-bit | regTI351-aarch64-\<version>.sh |
| x86 32-bit | regTI351-x86-\<version>.sh |
| x86 64-bit | regTI351-x86_64-\<version>.sh |
| PowerPC 64-bit | regTI351-powerpc64-e5500-\<version>.sh |
| Other | Contact Ezurio and provide toolchain so tools can be cross-compiled for desired platform |
Installation
To install the regulatory tools copy regTI351-\<arch>-\<version>.sh to the target device and invoke it with the paramater install.
# ./regTI351-aarch64-x.x.x.x.sh install
Installing lru to /usr/bin/lru
Installing lru_ti to /usr/bin/lru_ti
Installing btlru to /usr/bin/btlru
Installing btlru_ti to /usr/bin/btlru_ti
Installing libedit.lrd.so.0.0.74 to /usr/lib/libedit.lrd.so.0.0.74
Installing libncurses.lrd.so.6 to /usr/lib/libncurses.lrd.so.6
Installing ti351-conf_AU.bin to /lib/firmware/ti-connectivity/ti351-conf_AU.bin
Installing ti351-conf_CA.bin to /lib/firmware/ti-connectivity/ti351-conf_CA.bin
Installing ti351-conf_EU.bin to /lib/firmware/ti-connectivity/ti351-conf_EU.bin
Installing ti351-conf_JP.bin to /lib/firmware/ti-connectivity/ti351-conf_JP.bin
Installing ti351-conf_US.bin to /lib/firmware/ti-connectivity/ti351-conf_US.binThe install script will copy the tools and necessary supporting items to the proper location on the device.
Note: Manual configuration of firmware files to support regulatory test mode is still required; see Setup for details.
If after following these steps the tools still won't run, see Troubleshooting for additional suggestions to resolve the issue.
To uninstall the regulatory tools, invoke regTI351-\<arch>-\<version>.sh with the parameter uninstall.
# ./regTI351-aarch64-x.x.x.x.sh uninstallNote: Firmware files must be manually changed back to production versions after the tools are uninstalled
Setup
The standard TI351 software release uses a World Wide (WW) configuration that is compliant in all countries supported by the TI351. See the regulatory release notes for a list of supported countries. Configurations optimized for use in specific countries are available from Ezurio upon request.
Regulatory compliance testing must use a country specific configuration instead of the WW configuration. This ensures that the product has been validated with the fully optmized values that could be used in a future update. The regulatory package contains country specific configuration files for use in regulatory testing only. These files are copied to the firmware directory during installation. The configuration files in the regulatory package are only for regulatory testing and should not be used in end product images. Again, if you want to ship with an optimized country specific configuration please contact Ezurio for support.
The country specific regulatory configuration file must be manually selected in place of the WW configuration file during testing. The cc33xx-conf.bin symbolic link in the ti-connectivity firmware directory points to the configuration file to be used. Whichever file this link points to when the driver loads is the one used.
Note: If you have worked with Ezurio to use a production level optimized country configuration you do not need to perform this step. Use the optimized country configuration file already on your product.
See the following for an example of changing the configuration file link:
cd /lib/firmware/ti-connectivity
ln -sf ti351-conf_US.bin cc33xx-conf.binReboot the device and then perform testing.
Note that the link must be changed back to ti351-conf_WW.bin after testing is complete.
Application Interference
When running any regulatory test, a user mode application could interfere with the test. For example, an application could request a channel scan from the radio while the radio is performing a continous transmit test. When this occurs, the radio may crash or stop transmitting resulting in a short burst of data. To prevent such interference, disable all daemons and applications not required to run the regulatory test.
The following table shows some user mode applications that must be disabled for the lru to operate properly.
| Application | Mitigation |
|---|---|
| Network Manager | killall NetworkManager |
| WPA Supplicant | killall wpa_supplicant |
| WPA Supplicant | killall sdcsupp |
| hostapd | killall hostapd |
Wi-Fi Regulatory Utility (lru)
The lru is used by OEMs to control the Wi-Fi portion of the radio during regulatory certification testing.
To use lru invoke lru from the command console. Once invoked successfully, the command prompt will change to lru :>. From there ? can be used to obtain information on available commands and parameters.
The lru will search sysfs during initialization to find the first appropriate device to use. If the lru is unable to determine the appropriate device, it defaults to using wlan0 for Wi-Fi devices.
Note: To specify a Wi-Fi interface other than the default, use the -i <interface> command line option when invoking the tool.
# lru
Ezurio Regulatory Utility
Using wireless device wlan0 (5)
Module type: TI351
Reg Domain: US
lru :>?
lru :> <command> <option> [argument]
commands:
tx -> Continuous Transmit
cw -> Carrier Wave
rx -> Continuous Receive
off -> Off
s -> Current configuration
? -> Help
x -> Exit
options:
-c [1-13 | 36-165] -> Channel Number
-r [1-54 | h0-h7 | e0-7] -> Data Rate
--ru [26|52|106|242]-<index> -> Partial RU config
-w [1-900] -> Script mode wait time (sec)
-i <interface> -> Interface
Ver x.x.x.x
lru :>Note: Before starting any testing verify the country code displayed in Reg Domain: is correct. See Setup for details.
Note: The radio will remain in a particular test mode until that test is turned off using the off command. Each test should be stopped using the off command before starting another test.
See Test Descriptions for test details and examples.
When finished, exit lru (x), change the configuration soft link back to the standard production WW file, and reboot.
Test Descriptions
Constant Transmit
The Constant Transmit (tx) test transmits a continuous stream of packets on the specified channel at the specified rate at the maximum power allowed for that combination in the configured regulatory domain. This is the test that will be required for most regulatory compliance and emissions screening.
Note: The TI351 is a 20MHz Only device. Bandwidth is not configurable.
See the following table for rate descriptions and valid specifiers used with the -r parameter:
| Rate Type | Specifier |
|---|---|
| Legacy (802.11b) | 1, 2, 5, 11 |
| Legacy (802.11a/g) | 6,9,12,18,24,36,48,54 |
| HT (802.11n) | h0-h7 |
| VHT (802.11ac) | v0-v7 |
| HE (802.11ax) | e0-e7 |
Continuous Transmit on channel 1 (20 MHz), legacy rate 5.5Mbps
lru :>tx -c 1 -r 5
Continuous Transmit on channel 36 (20 MHz), HT (802.11n) rate MCS7
lru :>tx -c 36 -r h7
Constant Transmit - OFDMA (Partial RU)
The Sona TI351 supports partial RU OFDMA transmissions. These transmissions are supported by the lru by additionally specifying RU size and index with --ru <size>-<index>.
See the following table for valid partial RU sizes and index values for each supported channel width:
20MHz Channel Width
| RU Size | RU Index Range |
|---|---|
| 26 | 1-9 |
| 52 | 1-4 |
| 106 | 1-2 |
| 242 | 1 |
Continuous Transmit on 5GHz channel 36 (20 MHz), HE (802.11ax) rate MCS0 with OFDMA partial RU size 26 at index 1
lru :>tx -c 36 -r e0 --ru 26-1
Carrier Wave
The Carrier Wave (cw) test transmits an unmodulated signal at the center frequency of the specified channel. This test is generally not required for regulatory compliance screening, but may be requested in some jurisdictions. This test requires only the channel and channel width.
Carrier Wave on channel 1 (20MHz)
lru :>cw -c 1 -b 20
Carrier Wave on channel 36 (20MHz)
lru :>cw -c 36
Bluetooth Regulatory Utility (btlru)
The Bluetooth regulatory utility (btlru) is used to support Bluetooth Low Energy (BLE) regulatory testing.
The Bluetooth Low Energy specification defines a standard Direct Test Mode with transmit and receive test commands that are initiated locally on the device. The btlru implements these commands.
Note: The btlru is only supported with the Linux BlueZ stack.
Setup
All configurations use the same Bluetooth power settings. There is no special Bluetooth manufacturing firmware required. The standard WW configuration, or the optimized country specific configurations can be used.
The Bluetooth device must be attached to the host BlueZ stack and powered up just as it is during regular operation. How this is done depends on the device type and tools available on the host platform. Devices with a UART Bluetooth interface that are not managed with serdev typically use btattach to attach to the BlueZ stack:
btattach -B /dev/<tty> -P h4 &
Devices with a UART Bluetooth interface that are managed by serdev are automatically attached to the Bluetooth stack during bus enumeration.
Note: The TI351 requires additional user space action to enable the Bluetooth UART. See the software integration guide for details.
Once attached, the Bluetooth device must be powered on before using the btlru:
bluetoothctl power on
To use btlru invoke btlru from the command console. Once invoked successfully, the command prompt will change to btlru :>. From there ? can be used to obtain information on the commands and parameters used to run regulatory tests.
The btlru will search sysfs during initialization to find the first HCI device to use. If the btlru is unable to find a device, it defaults to using hci0.
Note: To specify a Bluetooth interface other than the default, use the -i <interface> command line option when invoking btlru.
# btlru
Using bluetooth device hci0
btlru :>?
btlru :> <command> <option> [argument]
commands:
tx -> Continuous LE Transmit
rx -> Continuous LE Receive
off -> Off
s -> Current configuration
? -> Help
x -> Exit
LE cmd options:
-c [0 - 39] -> LE Channel Number
-t [1, 2, LR2, LR8] -> LE Phy Type 1M, 2M, LR/Coded S = 2, 8
-p [0, 1, P9, AA, F0, P15, 0F, 55] -> LE TX Payload Pattern
-l [0 - 255] -> LE TX Payload Length
-w [1-900] -> Script mode wait time (sec)
-i <interface> -> BT Interface Name
Ver x.x.x.x:
btlru :>Note: The radio will remain in a particular test mode until that test is turned off using the off command. Each test should be stopped using the off command before starting another test.
See Test Descriptions for test details and examples.
When finished, exit btlru (x) and reboot.
Test Descriptions
BLE - Constant Transmit
The BLE Constant Transmit (tx) test transmits a continuous stream of packets using the specified PHY and with specified data pattern at the maximum power allowed for that combination. This is a standard test defined by the Bluetooth Core specification. The packet length is maximum by default, but may be adjusted.
Note: BLE channels in btlru are numbered from 0-39, and sequentially map to 2MHz channels starting at 2402MHz. This differs from the official BLE physical channel index to RF Channel/frequency mapping.
The PHY types are specified with the -t parameter as follows:
| Parameter | Description |
|---|---|
| 1 | 1M PHY |
| 2 | 2M PHY |
| LR2 | Long Range/Coded PHY, S=2 |
| LR8 | Long Range/Coded PHY, S=8 |
Continuous Transmit test on channel 0 (2402MHz) with a PRBS9 data pattern using the 1M PHY
btlru :>tx -c 0 -p p9 -t 1
Continuous Transmit test on channel 39 (2480MHz) with a PRBS9 data pattern using the 2M PHY
btlru :>tx -c 39 -p p9 -t 2
Scripting
Both lru and btlru support the ability to be scripted. Whenever a cmd and set of paramters are passed in from the console command line, btlru/lru will run the test and then exit rather than transitioning into the btlru/lru command line. In order to run the test for a certain amount of time, include the -w <seconds> option to inform btlru/lru how long to run the test before turning the test off and exiting.
In addition when running in script mode, the config submenu options can be passed in from the console command line.
lru tx -c 1 -r 6 -w 10
Ezurio Regulatory Utility
Using wireless device wlan0 (5)
Module type: TI351
Reg Domain: US
Running in script mode...
Running Test: Continuous Tx
Reg Domain: ??
Antenna: ANT0
Channel: 0
Rate: 6
Bandwidth: 20 MHz
Regulatory testing complete.Troubleshooting
Error Messages
Receive msg failed -28
All vendor tools require administrative privileges. Try running again using 'sudo' or login with a user that has administrative privileges.
Failed to find BT hci interface
Verify that the bluetooth interface is powered on.
Library Dependencies
The TI351 regulatory tools depend on a small number of shared libaries on the host platform. These dependencies are listed in the following table.
*Table 9: Tool Library Dependencies
| Tool | Library |
|---|---|
| lru | |
| libnl-genl-3.so.200 | |
| libnl-3.so.200 | |
| libedit.so.0 | |
| btlru | |
| libedit.so.0 | |
| libbluetooth.so.3 |
Many times if a regulatory tool fails to run, it is because a library dependency is missing or has a different version number. This can often be overcome by adding a symbolic link that points to an appropriate library on the device. Typically these libraries are located under /usr/lib.
For example:
cd /usr/lib
ls -al libnl-genl-*Returns:
-rwxr-xr-x 1 root root 14324 Nov 27 2018 libnl-genl-3.so.200.26.0
Then:
ln -sf libnl-genl-3.so.200.26.0 libnl-genl-3.so.200
ls -al libnl-genl-*Returns:
lrwxrwxrwx 1 root root 24 Nov 27 2018 libnl-genl-3.so.200 -> libnl-genl-3.so.200.26.0
-rwxr-xr-x 1 root root 14324 Nov 27 2018 libnl-genl-3.so.200.26.0Note: Some embedded platforms do not include libedit, therefore the installation package includes a version of this shared library at /lib/libedit.lrd.so.0.0.xx. To use create the appropriate symbolic link.
Transmit Terminates Early or Fails to Start
Upper level network management daemons will interfere with both WiFi and Bluetooth testing. This can show up as early termination of a transmit test or a failure to start the test at all. See Application Interference for details.