Vendor Manufacturing Tools Table of Contents Introduction Installation Manufacturing Tools Laird Connectivity Manufacturing Utility (LMU) Regulatory Tools Laird Connectivity Regulatory Utility (LRU) Bluetooth Laird Connectivity Regulatory Utility (LRU) Script Support Application Interface Troubleshooting Error Messages Library Dependencies Introduction Ezurio supports a set of vendor tools for use during the manufacturing and regulatory certification processes. 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 vendor tool package. Table 1: Package Names Platform Name arm soft-float mfg60n-arm-eabi-<version>.sh arm hard-float mfg60n-arm-eabihf-<version>.sh arm aarch64 mfg60n-arm-eabiaarch64-<version>.sh x86 32-bit mfg60n-x86-<version>.sh x86 64-bit mfg60n-x86-64-<version>.sh PowerPC 64-bit mfg60n-powerpc64-e5500-<version>.sh Other Contact Ezurio and provide toolchain so tools can be cross-compiled for desired platform. When invoked, each vendor tool in this package will search the sysfs to find the first appropriate device to use. If the tool is unable to determine the appropriate device, it defaults to using wlan0 for Wi-Fi devices and hci0 for Bluetooth devices. Note: To specify a Wi-Fi interface other than the default, use the -i <interface> option when invoking the vendor tool from the command console. Installation To install the vendor tools copy the mfg60n-<arch>-<version>.sh to the device and invoke it passing the paramater install. '# ./mfg60n-arm-eabihf-7.1.0.9.sh install' Installing lmu to /usr/bin/lmu Installing lru to /usr/bin/lru Installing btlru to /usr/bin/btlru Installing libedit.lrd.so.0.0.58 to /usr/lib/libedit.lrd.so.0.0.58 Installing 88W8997_mfg_pcie_uart_v16.80.205.170.bin to /lib/firmware/lrdmwl/88W8997_... Installing 88W8997_mfg_pcie_usb_v16.80.205.170.bin to /lib/firmware/lrdmwl/88W8997_... Installing 88W8997_mfg_sdio_sdio_v16.80.205.170.bin to /lib/firmware/lrdmwl/88W8997_... Installing 88W8997_mfg_sdio_uart_v16.80.205.170.bin to /lib/firmware/lrdmwl/88W8997_... Installing 88W8997_mfg_usb_uart_v16.80.205.170.bin to /lib/firmware/lrdmwl/88W8997_... Installing 88W8997_mfg_usb_usb_v16.80.205.170.bin to /lib/firmware/lrdmwl/88W8997_... The install script will copy the tools and necessary supporting items to the proper location on the device. Depending on the tool run, there may be additional tool specific configuration steps that need to be done (see tool dependencies). If after following these steps the tool still won’t run, see the Troubleshooting section for additional suggestions to resolve the issue. To uninstall the vendor tools, invoke the mfg60n-<arch>-<version>.sh passing it the parameter uninstall. '# ./mfg60n-arm-eabihf-6.0.0.125.sh uninstall' Manufacturing Tools Laird Connectivity Manufacturing Utility (LMU) This tool is used by vendors to set the Wi-Fi radio’s regulatory domain. The following regulatory domains are supported: FCC United States IC Industry Canada ETSI Europe (without ETSI EN 300 440 support) EN440 Europe (with ETSI EN 300 440 support) KCC Korea JP Giteki CN China AU Australia WW World Mode (without ETSI EN 300 440 support) WW440 World Mode (with ETSI EN 300 440 support) Note: Each time the regulatory domain is changed, it is burnt into OTP and thus has limited cycles (~10) so use restraint when deciding to update the domain. Note: WW440 Is relevant only with Summit Radios that deploy adaptive world mode, otherwise WW and WW440 are functionally equal. Dependencies In addition to the dependencies listed in Table 2 and Table 3, LMU requires that protocol firmware, rather than manufacturing firmware, be loaded. To ensure that protocol firmware is being used, verify that the firmware on the host machine is named or symlinked properly (i.e. 88W8997_<bus>.bin), and that the manufacturing symbolic link is not present (i.e. 88W8997_<bus>_mfg.bin). If changes are necessary, make the changes and reboot the device before running LMU. Usage To set the Wi-Fi radio’s regulatory domain invoke lmu from the command console, specifying the appropriate domain using the reg option. '# lmu -reg FCC' Regulatory domain FCC successfully set. You must reboot for changes to take effect. '# lmu' Syntax (v7.1.0.9): lmu <-option> [argument]: options -reg [FCC | IC | ETSI | EN440 | KCC | JP | CN | AU | WW | WW440] -i <interface> Regulatory Tools Laird Connectivity Regulatory Utility (LRU) This tool is used by vendors to enable Wi-Fi regulatory certification testing. Dependencies In addition to the dependencies listed in Table 2 and Table 3, LRU requires that special manufacturing firmware be used. To enable the use of manufacturing firmware, perform the following steps: Open a ssh/command console with the device cd /lib/firmware/lrdmwl ln -sf 88W8997_mfg_<wifi bus>_<bt bus>_<ver>.bin 88W8997_<wifi bus>_mfg.bin Reboot device Usage 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 the commands and parameters used to run regulatory tests. '# lru' 'lru :> ?' lru :> <command> <option> [argument] commands: tx -> Continuous Transmit cw -> Carrier Wave rx -> Continuous Receive cfg -> Configuration Sub Menu off -> Off s -> Current configuration ? -> Help x -> Exit options: -c [1-14 |36-165] -> Channel Number -b [20 | 40 | 80] -> Bandwidth -r [1-54 | h0-h15 | v0-v9] -> Data Rate -w [1-900] -> Script mode wait time (sec) -i <interface> -> Interface Ver 7.1.0.9: Before starting any testing, verify that the domain, antenna and if necessary Antenna Adjust configuration is set properly. This can be done by issuing the cfg command. 'lru :> cfg' WiFi Configuration Menu: Domain: FCC Antenna: Main & Aux Antenna Adjust: 0x00000000 cfg :> To adjust these settings, use the appropriate option(s) to change. If changes are accepted LRU will reflect the new settings in its status and help commands. When done use x to return to the previous menu. Note: Main and Aux antenna port location/definition can be obtained from the hardware schematic located on ezurio.com. Note: Antenna Adjust can be used to attenuate the transmit power if necessary to meet regulatory limits. If this feature is used to pass regulatory testing it must also be configured on the platform to maintain compliance under normal operating conditions. See the Antenna Adjust app note for more details. 'cfg :> ?' Configuration menu options: -d [FCC | IC | ETSI | EN440 | KCC | JP | CN | AU ] -> Set Domain -a [MAIN | AUX | BOTH] -> Set Antenna -p <value> -> Antenna Adjust power attenuation x -> Return to previous menu WiFi Configuration Menu: Domain: FCC Antenna: Main & Aux Antenna Adjust: 0x00000000 'cfg :>-d ETSI -a MAIN' WiFi Configuration Menu: Domain: ETSI Antenna: Main Antenna Adjust: 0x00000000 'cfg :>x' lru :> Once the domain and antenna set is verified, any of the other LRU commands (tx, rx, cw) and parameters may be used to start regulatory testing. When finished, exit LRU (x), remove the manufacturing firmware symbolic link and reboot. Examples: Note: When transmitting using a 40/80 bandwidth specify the 20 Mhz primary channel and bandwith, and LRU will determine the appropriate secondary channel(s) to use. See following example. Continuous Transmit Channel 38 40 MHz, VHT rate MCS4 'lru :>tx -c 36 -b 40 -r v0' Running Test: Continuous Tx Radio Type M2 Bandwidth: 40 MHz Antenna: Main & Aux Channel: 36 Rate: vht mcs4 Reg Domain FCC Antenna Adjust: 0x00000000 Tx Power: 15 dBm Continuous Transmit Channel 1 20 MHz, CCK Rate 5.5 'lru :>tx -c 1 -b 20 -r 5' Running Test: Continuous Tx Radio Type SIP Bandwidth: 20 MHz Antenna: Main Channel: 1 Rate: 5 Reg Domain: FCC Antenna Adjust: 0x00000000 Tx Power: 18 dBm Note: When configured for two antennae, append a -1 after the VHT MCS number to specify a single spatial stream. See following example. Continuous Transmit Channel 40 20 MHz, VHT rate MCS0, 1 Spatial Stream 'lru :>tx -c 40 -b 20 -r v0-1' Running Test: Continuous Tx Radio Type SOM Bandwidth: 20 MHz Antenna: Main & Aux Channel: 40 Rate: vht mcs0 (1ss) Reg Domain: FCC Antenna Adjust: 0x00000000 Tx Power: 16 dBm Bluetooth Laird Connectivity Regulatory Utility (BTLRU) While the 60 Bluetooth module supports the necessary HCI commands required to enable DB/EDR Test Mode and BLE Direct Test Mode, this tool may be used by vendors to enable, or used in conjunction with other test tools, Bluetooth regulatory certification testing. Dependencies In addition to the dependencies listed in Table 2 and Table 3, BTLRU requires that protocol firmware be loaded. To ensure that protocol firmware is being used, verify that the firmware on the host machine is named or symlinked properly (i.e. 88W8997_<bus>.bin) and that the manufacturing symbolic link is not present (i.e. 88W8997_<bus>_mfg.bin). If changes are necessary, make the changes and reboot the device before running BTLRU. Furthermore the Bluetooth device must be attached to the BlueZ stack, or equivalent, and powered up. How this is done depends on Bluetooth stack and product being used (i.e. SIP/M2, IG60, or SOM60). BlueZ Bluetooth initialization: IG60/SOM60 Attach to BlueZ stack The bluetoothd dameon automatically attaches the device to the BlueZ stack. Power Up bluetoothctl power on SIP/M2 Module Attach to BlueZ stack USB and No Flow Control hciattach /dev/ttyUSB0 any 3000000 1 UART with Flow Control hciattach /dev/ttymxc1 any -s 3000000 3000000 flow dtron Power Up hciconfig hci0 up Usage 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. '# btlru' btlru :>? btlru :> <command> <option> [argument] commands: tm -> Enable BD/EDR test mode tx -> Continuous BT Transmit rx -> Continuous BT Receive cfg -> Configuration Sub Menu off -> Off s -> Current configuration ? -> Help x -> Exit BT cmd options: -c [0 - 78] -> BT Channel Number -r [DM[1,3,5], DH[1,3,5], 2DH[1,3,5], 3DH[1,3,5] -> BT rates -p [0, 1, PN9, AA, F0] -> BT payload pattern -l [-1, 0-255] -> BT Payload Length -n [0-0xFFFF] -> BT RX Frame Count -a [xx-xx-xx-xx-xx-xx] -> BT RX Tx Bd Address -w [1-900] -> Script mode wait time (sec) -i <interface> -> BT Interface name Ver 7.1.0.9: Before starting any testing, verify that the Bluetooth mode is set properly. This can be done by issuing the cfg command. 'btlru :>cfg' BT Configuration Menu: Mode: BT cfg :> To change the mode, use the -m option with the appropriate mode. If the changes are accepted, BTLRU will reflect the new mode in status and help commands. When done use x to return to the previous menu. 'cfg :> ?' Configuration menu options: -m [BT | LE] -> BT mode x -> Return to previous menu BT Configuration Menu: Mode: BT 'cfg :>-m LE' BT Configuration Menu: Mode: BLE 'cfg :>x' btlru :> Once the mode is verified, any of the other BTLRU commands (tx, rx, tm) and parameters may be used to start regulatory testing. Examples: Continuous Transmit Channel 1, Rate DM1 'btlru :>tx -c 1 -r DM1' Running Test: Continuous Tx Channel: 1 Mode: BT Rate: DM1 Pattern: PN9 Length: -1 Continuous Receive Channel 1, start sequence counter at 0 'btlru :>rx -c 1 -n 0' Channel: 1 Mode: BT Rate: DM1 Pattern: PN9 Length: -1 Frame Count: 0 BD: 00-00-88-C0-FF-EE Display Receive results: 'btlru :>rx' RX Count 138 Script Support 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 -d IC -w 10' Using wireless device wlan0 (6) Running in script mode... Running Test: Continuous Tx Bandwidth: 20 MHz Antenna: Main & Aux Channel: 1 Rate: 6 Reg Domain: IC Antenna Adjust: 0x00000000 Tx Power: 16 dBm Regulatory testing complete. # Application Interface 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, the user should disable all daemons and applications not required to run the regulatory test. Application Mitigation Network Manager killall NetworkManager WPA Supplicant killall wpa_supplicant Summit Supplicant killall sdcsupp Adaptive World Mode killall adaptive_ww IG60 Config systemctl disable igconfd.service (reboot) 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 intferface” Verify that the bluetooth interface is powered on. Library Dependencies Many times if a vendor tool fails to run, it is because a library dependency is missing. In many cases this can 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-* -rwxr-xr-x 1 root root 14324 Nov 27 2018 libnl-genl-3.so.200.26.0 ln -sf libnl-genl-3.so.200.26.0 libnl-genl-3.so.200 ls -al libnl-genl-* 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.0 Table 2: Tool Platform Library Dependencies Platform Library arm soft-float ld-linux.so.3 arm hard-float ld-linux-armhf.so.3 arm aarch64 ld-linux-aarch64.so.1 x86 32 bit ld-linux.so.2 x86 64 bit ld-linux-x86-64.so.2 PowerPC ld64.so.1 Table 3: Tool Library Dependencies Tool Library LMU libnl-genl-3.so.200 libnl-route-3.so.200 libnl-3.so.200 LRU libnl-genl-3.so.200 libnl-route-3.so.200 libnl-3.so.200 libedit.so.0 BTLRU libedit.so.0 libbluetooth.so.3 Note: Some embedded platforms do not include libedit, therefore the mfg60n installation package installs a version of the shared object under /lib/libedit.lrd.so.0.0.58. To use create the appropriate symbolic link.
