Software Guide🔗

Introduction🔗

The PAN9019A requires the host processor to run the Wi-Fi® and Bluetooth® drivers to operate the device. Linux® offers a range of different applications and utilities to configure and control the Wi-Fi and Bluetooth devices.

As an evaluation platform you can use the NXP® i.MX 93 Evaluation Kit (i.MX93EVK) in conjunction with the PAN9019A M.2 device.

You can check out the i.MX 93 Evaluation Kit guide for step-by-step instructions on how to setup the evaluation platform. But you may notice that the explanations are rather short and might be hard to fully understand because of this.

This Software Guide tries to fill this gap and provide explanations and in-depth and background information.

Wi-Fi Driver🔗

The Wi-Fi driver for the PAN9019A is an out-of-tree driver that supports a range of NXP based devices.

The source code is hosted on the mwifiex repository on GitHub® and receives quarterly updates as part of the consolidated releases of the Linux BSP from NXP.

The required firmware binaries are hosted on the imx-firmware repository on GitHub and are part of the consolidated releases as well.

Minimum Required Driver / Firmware Version

The PAN9019A is fully supported from release lf-6.1.55_2.2.0 of the driver and firmware binaries upwards.

Make sure to use at least the branch with the name lf-6.1.55_2.2.0 or newer of the mwifiex and imx-firmware repositories when integrating them into your system.

File Overview🔗

Besides the Wi-Fi driver modules a couple files like the firmware binaries that are downloaded at runtime and configuration files must be available in the root filesystem for operating the PAN9019A.

/
└── lib
    ├── firmware
    │   └── nxp
    │       ├── sduart_nw61x_v1.bin.se
    │       ├── sd_w61x_v1.bin.se
    │       ├── uartspi_n61x_v1.bin.se
    │       ├── rgpower_WW.bin
    │       ├── rgpower_US.bin
    │       └── wifi_mod_para.conf
    └── modules
        └── <kernel_version>
            └── extra
                ├── mlan.ko
                └── moal.ko

Filename	Description / Source
`sduart_nw61x_v1.bin.se`	Wi-Fi, Bluetooth and Thread secure firmware binary
`sduart_nw61x_v1.bin.se`	Hosted on GitHub `imx-firmware` repository
`sd_w61x_v1.bin.se`	Wi-Fi only secure firmware binary
`sd_w61x_v1.bin.se`	Hosted on GitHub `imx-firmware` repository
`uartspi_n61x_v1.bin.se`	Bluetooth and Thread secure firmware binary
`uartspi_n61x_v1.bin.se`	Hosted on GitHub `imx-firmware` repository
`rgpower_WW.bin`	Tx power and regulatory settings configuration file (World Wide)
`rgpower_WW.bin`	Provided by Panasonic. Also see rgpower Files
`rgpower_US.bin`	Tx power and regulatory settings configuration file (US)
`rgpower_US.bin`	Provided by Panasonic. Also see rgpower Files
`wifi_mod_para.conf`	Configuration file for setting the module parameters for the Wi-Fi driver. Also see Driver Configuration
`wifi_mod_para.conf`	Hosted on GitHub `imx-firmware` repository
`mlan.ko`	Wi-Fi driver kernel module for firmware download and command, data and event handling
`mlan.ko`	Source Code hosted on GitHub `mwifiex` repository
`moal.ko`	Wi-Fi driver kernel module for handling interactions with the Linux Wi-Fi subsystem and network stack
`moal.ko`	Source Code hosted on GitHub `mwifiex` repository

Driver Configuration🔗

You have to set a couple of parameters that the Wi-Fi driver then uses. The parameters are specified in the wifi_mod_para.conf file located in /lib/firmware/nxp.

The file is made up of multiple sections that contain individual sets of parameters for the different NXP chips that are supported by the driver.

For the PAN9019A the relevant section is called SDIW612. The minimum required configuration looks as follows:

[...]
SDIW612 = {
    cal_data_cfg=none
    fw_name=nxp/sduart_nw61x_v1.bin.se
    cntry_txpwr=2
}
[...]

Parameter	Value	Description
`cal_data_cfg`	`none`	The PAN9019A has the calibration data already stored in its One-Time-Programmable memory (OTP) therefore this parameter shall be set to `none`.
`fw_name`	`nxp/sduart_nw61x_v1.bin.se`	The path for the secure firmware binary that the driver downloads to the PAN9019A (in this case the Wi-Fi, Bluetooth and Thread combo firmware). This path is relative to `/lib/firmware`.
`cntry_txpwr`	`2`	This parameter specifies the mechanism that is used for configuring the Tx power levels and regulatory parameters. The value `2` means that the rgpower files are used to provide the Tx power levels and regulatory paramters.

cntry_txpwr Parameter

The cntry_txpwr shall be set to the value 2 for the modular approval of the PAN9019A to be valid!

For more information please refer to the Module Integration Guide.

Driver Loading🔗

After booting the Linux system the Wi-Fi driver modules are not loaded into the kernel yet. Since the Wi-Fi drivers are built as out-of-tree modules, you have to manually load them into the kernel prior to operation and also provide the location of the parameter file wifi_mod_para.conf.

To load the required kernel modules execute the following instructions.

Load the mlan and moal kernel modules and provide the correct parameter file.

insmod /lib/modules/$(uname -r)/extra/mlan.ko
insmod /lib/modules/$(uname -r)/extra/moal.ko mod_para=nxp/wifi_mod_para.conf

Check the kernel messages from the Linux kernel ring buffer.

dmesg

The output should look something like this:

wlan: Loading MWLAN driver
wlan: Register to Bus Driver...
vendor=0x0471 device=0x0205 class=0 function=1
Attach moal handle ops, card interface type: 0x109
rps set to 0 from module param
SDIW612: init module param from usr cfg
card_type: SDIW612, config block: 0
cal_data_cfg=none
fw_name=nxp/sduart_nw61x_v1.bin.se
cntry_txpwr = 2
SDIO: max_segs=128 max_seg_size=65535
rx_work=1 cpu_num=4
Enable moal_recv_amsdu_packet
Attach mlan adapter operations.card_type is 0x109.
wlan: Enable TX SG mode
wlan: Enable RX SG mode
Request firmware: nxp/sduart_nw61x_v1.bin.se
Wlan: FW download over, firmwarelen=1004248 downloaded 916048
WLAN FW is active
on_time is 17142553331228
VDLL image: len=88200
fw_cap_info=0x487cff03, dev_cap_mask=0xffffffff
uuid: 5f8a2a30c9205a90968ea595f001b00e
max_p2p_conn = 8, max_sta_conn = 16
Trying download country_power_tble: nxp/rgpower_WW.bin
Request firmware: nxp/rgpower_WW.bin
call regulatory_set_wiphy_regd WW
call regulatory_set_wiphy_regd WW
Register NXP 802.11 Adapter mlan0
wlan: uap%d set max_mtu 2000
Register NXP 802.11 Adapter uap0
call regulatory_set_wiphy_regd WW
Register NXP 802.11 Adapter wfd0
wlan: version = SDIW612---18.99.2.p66.17-MM6X18437.p3-GPL-(FP92) 
wlan: Register to Bus Driver Done
wlan: Driver loaded successfully

As indicated by the line Request firmware: nxp/rgpower_WW.bin the world wide rgpower file is loaded.

Execute the following command to check if the Wi-Fi interfaces have been created.

ip addr list

The output should look something like this:

[...]
4: mlan0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether 34:32:e6:34:41:30 brd ff:ff:ff:ff:ff:ff
5: uap0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether 36:32:e6:34:42:30 brd ff:ff:ff:ff:ff:ff
6: wfd0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN group default qlen 1000
    link/ether 36:32:e6:34:41:30 brd ff:ff:ff:ff:ff:ff

The mlan0 (station), uap0 (access point) and wfd0 (Wi-Fi Direct) interfaces are now available.

Note

For further information please refer to the user manual UM11490 - Feature Configuration Guide for NXP-based Wireless Modules on i.MX 8M Quad EVK, which is available under the Documentation section on the IW612 product page.

Please note that you need an account for the NXP Homepage to be able to access this document.

rgpower Files🔗

The PAN9019A is a so-called self-managed device. It manages it set of regulatory rules by itself rather than depending on the rules of the host system that are specified by the regulatory.db database (/lib/firmware/regulatory.db).

Because of this the Wi-Fi driver loads so-called rgpower files at runtime to configure the channel tables and regulatory parameters of the PAN9019A for a specific region it operates in.

The rgpower files provide the following configurations for the PAN9019A during runtime:

Which channels are activated including the respective maximum Tx power level.
Whether the PAN9019A is allowed to run active scans on a specific channel or only passive scans are permitted.
The country code that is used.
Whether a channel is a Dynamic Frequency Selection (DFS) channel and therefore the PAN9019A has to use radar detection.
Whether adaptivity is being used

To gain access to the rgpower files you have to go through an uncomplicated approval process that you can find directly on the following pages.

Warning

The PAN9019A is a radio certified module. There are conditions on hardware and software which must be met for the modular approval to be valid.

For detailed information please refer to the PAN9019A Module Integration Guide at

On the root filesystem of the host system a set of two rgpower files shall be placed in the /lib/firmware/nxp directory.

The rgpower_WW.bin is loaded initially before a specific country code is configured. It only enables the channels 1 - 11 in the 2.4 GHz band with reduced output power levels. This file is also used as a fallback in case loading the region-specific rgpower file fail.

The region-specific rgpower file has the country code for the specific region in its name. For example the rgpower file for the US is called rgpower_US.bin.

The driver downloads this file in a second step once the country code was configured. The region-specific rgpower files enable the other channels to be used that are allowed in that region.

To set the country code for a region (in this case the US) and enable the region-specific configuration execute the following steps.

Set the country code to US.
```
iw reg set US
```
The following messages indicate that the according rgpower_US.bin file is downloaded by the driver.

The output should look something like this:
```
Trying download country_power_tble: nxp/rgpower_US.bin
Request firmware: nxp/rgpower_US.bin
call regulatory_set_wiphy_regd US
```
The driver discloses the updated set of regulatory rules that is derived from the settings in rgpower_US.bin to the host.

To check whether the download of rgpower_US.bin worked execute the command iw reg get.

iw reg get

The output should look something like this:

[...]
phy#0 (self-managed)
country US: DFS-FCC
        (2402 - 2427 @ 20), (N/A, 19), (N/A)
        (2412 - 2462 @ 40), (N/A, 19), (N/A)
        (2447 - 2472 @ 20), (N/A, 19), (N/A)
        (5170 - 5250 @ 80), (N/A, 19), (N/A)
        (5250 - 5330 @ 80), (N/A, 19), (0 ms), DFS, PASSIVE-SCAN
        (5490 - 5730 @ 80), (N/A, 19), (0 ms), DFS, PASSIVE-SCAN
        (5735 - 5815 @ 80), (N/A, 19), (N/A)
        (5815 - 5835 @ 20), (N/A, 19), (N/A)

The PAN9019A is listed second as a self-managed device with the correct country code set.

EU rgpower File

For use in EU the country code DE (Germany) shall be used. The rgpower file is named rgpower_DE.bin accordingly.

For more information please refer to the Module Integration Guide.

Bluetooth Driver🔗

Since Linux kernel version 6.4 the Bluetooth driver btnxpuart is the preferred way to interact with the Bluetooth functionality of the PAN9019A.

In the Linux BSP from NXP this Bluetooth driver is available starting with release 6.1.22_2.0.0.

The btnxpuart driver supports the following features.

Supports the power safe feature that automatically places the device into sleep state after 2000 ms of inactivity.
Can be used to download the Bluetooth-only firmware binary (parallel firmware download, not described in this guide).
Automatically switches to a secondary baud rate of 3 Mbaud from the initial baudrate of 115200 baud.
No longer requires the hciattach daemon to be run in userspace.

Driver Integration🔗

The btnxpuart driver is based on the Linux serial device bus (serdev). If you want to integrate it into your custom platform, you have to add a bluetooth sub node to your UART node in the device tree as follows.

[...]
&uartX {
    pinctrl-names = "default";
    pinctrl-0 = <&pinctrl_uartX>;
    status = "okay";

    bluetooth {
        compatible = "nxp,88w8987-bt";
    };
};
[...]

For the PAN9019A you have to use the value nxp,88w8987-bt for the compatible property. You can compile the driver as a module by setting CONFIG_BT_NXPUART=m in your kernel configuration.

Note

Since the btnxpuart driver uses the serdev subsystem, the UART peripheral is not made available as a serial device to the userspace.

Driver Loading🔗

The Bluetooth subsystem requires the btnxpuart driver to be loaded manually into the kernel prior to operation as well. This only works after you have loaded the Wi-Fi driver and the firmware of the PAN9019A has been initialized.

To bring up the Bluetooth interface you have to execute the following steps.

Load the btnxpuart module by executing the following command.
```
modprobe btnxpuart
```
Bring up the hci0 interface.
```
hciconfig hci0 up
```

To check the status of the hci0 interface execute the following command.

hciconfig

The output should look something like this:

hci0:   Type: Primary  Bus: UART
      BD Address: 34:32:e6:34:41:31  ACL MTU: 1016:5  SCO MTU: 60:12
      UP RUNNING 
      RX bytes:1456 acl:0 sco:0 events:86 errors:0
      TX bytes:1238 acl:0 sco:0 commands:86 errors:0

The hci0 device is ready for operation.

Note

For further information please refer to the user manual UM11490 - Feature Configuration Guide for NXP-based Wireless Modules on i.MX 8M Quad EVK, which is available under the Documentation section on the IW612 product page.

Please note that you need an account for the NXP Homepage to be able to access this document.