AIC8800 Wi-Fi Driver Usage Guide#
Overview#
RT-Smart has integrated the AIC8800 series WLAN offload driver, supporting both USB and SDIO transports.
The driver handles firmware loading, STA/SoftAP registration, and data transmission and reception, while continuing to use RT-Thread WLAN,
lwIP, the wifi command, and NetMgmt as upper-layer interfaces.
The supported range is as follows:
Transport |
Chip Series |
Description |
|---|---|---|
USB |
AIC8800/AIC8801, AIC8800D80/D40, AIC8800D80X2, AIC8800DC/DW/DL |
Supports firmware downloading; some combination devices can also provide BLE HCI |
SDIO |
AIC8801, AIC8800D80, AIC8800DC/DW/DL |
Supports Wi-Fi; DC/DW/DL use function 1 data channel and function 2 control/message channel |
Different modules have different frequency bands, bandwidths, and BLE capabilities, so they cannot be identified solely by the “AIC8800” product name.
For example, AIC8800D40 and D80 may use the same USB ID; D40 boards must enable
AIC8800_WIFI_USB_LIMIT_40MHZ.
Source Code and Firmware#
The driver source code is located at:
src/rtsmart/rtsmart/kernel/bsp/maix3/drivers/extdrv/aic8800/
The firmware is a separate subrepository managed by a manifest:
src/rtsmart/rtsmart/kernel/bsp/maix3/drivers/extdrv/aic8800/firmware/
When running repo sync, ensure that this subrepository has been checked out. The firmware is subject to separate licensing terms; before distributing images, read
the README.md and license notices in the firmware repository.
The current firmware is synchronized from AIC aic8800d_linux_sdk_V5.0_2026_0123_5f7be68d, corresponding to vendor
repository commit df4c783b663eba1956579c681acd5e45f25c671d. USB D80X2 includes both U03
and U05 revision files. The additional D80N and D80X2 SDIO files in the vendor SDK are not packaged
because the current RT-Smart SDIO driver has not yet implemented the boot and calibration
paths required by these families. The README.md of the firmware subrepository should be updated simultaneously during subsequent synchronizations; this file is the
authoritative record of the firmware source.
The build system installs the firmware into /bin/firmware. When only one transport is enabled, the family directory
of the selected transport is installed directly to this path; when both USB and SDIO are enabled, the usb/ and sdio/ directory levels are retained to
prevent firmware with the same name from overwriting each other. Do not replace a USB FMAC file with an SDIO file of the same name.
USB Device IDs#
The Wi-Fi USB IDs currently supported by the driver are as follows:
Chip Series |
Boot ID |
Runtime ID |
|---|---|---|
AIC8800/AIC8801 |
|
|
AIC8800D80 |
|
|
AIC 88M80 |
|
|
AIC8800D40 |
|
|
AIC8800D80X2 |
|
|
AIC8800DC/DW/DL |
|
|
1111:1111 has been verified on an actual 88M80 device, but it is not a USB-IF identity assigned by AIC; it is a
generic placeholder used when the module leaves the factory. The driver claims this ID and sends the 88M80 private
SCSI mode-switch command only when AIC8800_WIFI_USB_MODESWITCH_PLACEHOLDER_ID=y is set; products that do not use the 88M80 should disable this option to avoid claiming other mass-storage devices that use
the same placeholder.
a69c:5721 is the MSC identifier used by the DC family before entering runtime mode. The current vendor firmware no longer provides a
separate aic8800dc_fc patch branch; after the device exits MSC and is re-enumerated as 88dc/88dd, the
driver selects the standard or H-version file in aic8800DC based on the actual silicon revision.
SDIO Device IDs#
The AIC SDIO IDs currently supported by the driver are as follows:
Chip Series |
function |
manufacturer:product |
Purpose |
|---|---|---|---|
AIC8801 |
1 |
|
Wi-Fi data and control |
AIC8800D80 |
1 |
|
Wi-Fi |
AIC8800DC/DW/DL |
1 |
|
Wi-Fi data |
AIC8800DC/DW/DL |
2 |
|
Firmware control and messages |
AIC8800DC/DW/DL must enumerate both function 1 and function 2; the driver starts firmware initialization only when the IDs of both match.
c8a1:c18d is the message function required by the WLAN transport and does not register a
Bluetooth HCI device. The SDIO transport currently does not provide a Bluetooth HCI backend.
The DC/DW/DL driver reads the silicon chip ID, sub-ID, and MCU ID, and automatically selects the standard U02 or H
U02 firmware. DL has no separate device ID or firmware filename and shares aic8800DC with DC/DW.
When USB and SDIO are enabled simultaneously, the files should be located in
/bin/firmware/sdio/aic8800DC; when only SDIO is enabled, they should be located in
/bin/firmware/aic8800DC. Do not manually rename the standard and H-version files to the same filename.
Both USB and SDIO perform matching DPD calibration according to the vendor process; calibration failures for either the standard or H version will
terminate firmware initialization; the driver no longer provides Kconfig options to force or skip DPD.
Configuration#
First select the target board configuration, then enter RT-Smart configuration:
make <board>_defconfig
make rtsmart-menuconfig
Enable RT_USING_AIC8800_WIFI, then select at least one transport:
AIC8800_WIFI_TRANSPORT_USB: Depends on CherryUSB Host;AIC8800_WIFI_TRANSPORT_SDIO: Depends on RT-Thread SDIO;Both can be enabled simultaneously, and each physical device detected will be registered as an independent radio.
In Firmware Packaging, select the firmware series according to the actual hardware:
Configuration option |
Packaged content |
|---|---|
|
AIC8800/AIC8801 |
|
AIC8800D80/D40 and compatible D8x devices |
|
AIC8800D80X2, USB only |
|
AIC8800DC/DW/DL |
Common configuration options are as follows:
Configuration option |
Description |
|---|---|
|
Initializes the STA and AP interfaces after the device is mounted; enabled by default |
|
Firmware installation root directory; defaults to |
|
Two-character country code; defaults to |
|
Uses the country table as a hard firmware transmit power limit; disabled by default. When disabled, the country table still restricts channels and is used for reporting |
|
Publishes 5 GHz channels; should be disabled for 2.4 GHz-only modules |
|
Firmware STA power saving; disabled by default. Enable only when idle power consumption is more important and after stress testing |
|
Must be enabled for AIC8800D40L USB modules |
|
USB composite devices register |
|
Registers the |
After updating DC/DW/DL transports, the performance-related defaults are as follows:
Configuration option |
Default value |
|---|---|
|
4 for descriptor DMA, 20 for other modes |
|
1 for descriptor DMA, 20 for other modes |
|
2 |
|
Disabled |
|
0 ms |
Descriptor DMA completion handling is generated only when the last descriptor of a
non-periodic descriptor chain completes. Traffic on the dedicated message endpoint is
relatively sparse, so only one message RX URB is kept armed by default to prevent command
replies from being delayed by idle chains. Modifying AIC8800_WIFI_MESSAGE_RX_URBS is not
recommended unless diagnosing a specific controller or firmware.
Firmware station power save was changed from enabled to disabled because DC/DW firmware may stop processing the best-effort TX queue under sustained traffic and trigger an AC1 timer assertion. USB RX queue depth and SDIO aggregate wait have also changed; board defconfigs that rely on the old configuration should explicitly pin the required values. Do not increase the USB TX URB merely to improve throughput, as the CherryUSB DWC2 URB/QTD pool is shared by all devices and endpoints on the controller.
SDIO modules also require selecting the actual host in SDIO Wi-Fi Board Bus and configuring
BSP_WIFI_SDIO_REG_ON_PIN according to the board wiring. The driver uses four-wire SDIO
high-speed at up to 50 MHz; do not force the link to 100 MHz before completing UHS tuning.
k230_canmv_01studio_defconfig enables both AIC8800 USB and SDIO,
k230_canmv_01studio_emmc_defconfig and k230_canmv_lckfb_defconfig enable USB, and
k230_canmv_v3p0_defconfig enables SDIO host 0. The effective SDIO Wi-Fi configuration for
01Studio is host 1 and REG_ON GPIO 53. Other board configurations must be enabled as
required by the hardware. AIC8800DC is a 2.4 GHz-only module, so AIC8800_WIFI_5GHZ should
be disabled when using this card.
Device Naming and Selection#
Each physical radio registers a set of dynamically assigned names:
Type |
Example name |
|---|---|
WLAN management device |
|
lwIP netdev |
|
Offload control device |
|
Numbering depends on detection order, so do not assume that AIC8800 will always be wlan0 in applications. Use the following command
to view the model, bus, role, and dynamic netdev:
wifi devices
When multiple Wi-Fi devices are present, you can select one by bus, or pass a management device or netdev name:
wifi -i usb scan
wifi -i sdio join <ssid> <password>
wifi -i wlan0 status
Native RT-Smart applications should use NetMgmt to select the physical transport, then call the existing STA/AP interfaces:
netmgmt_wlan_select_device(NETMGMT_WLAN_DEVICE_SDIO,
RT_NET_DEV_WLAN_STA);
netmgmt_wlan_sta_connect_with_ssid("my-ap", "12345678");
Selection and subsequent operations are two independent calls; when multiple threads share NetMgmt, the application must serialize the “select and operate” combination.
STA and SoftAP#
Basic verification procedure:
wifi devices
wifi -i auto scan
wifi -i auto join <ssid> <password>
wifi -i auto status
ifconfig
ping <gateway-address>
STA supports open, WEP, WPA/WPA2 Personal, and the restricted WPA3-SAE Personal path. WPA3 currently uses SAE group 19, hunting-and-pecking, and BIP-CMAC-128; SAE H2E, Enterprise/802.1X, and other modes require a full external supplicant.
SoftAP supports open networks and WPA2-PSK/CCMP:
wifi -i auto ap <ssid>
wifi -i auto ap <ssid> <password> 2g 6
wifi -i auto ap <ssid> <password> 5g 149
wifi -i auto list_sta
wifi -i auto ap_stop
AIC firmware has only one channel context. When STA and AP run concurrently, they must use the same primary channel; requesting a different primary channel returns busy and does not silently interrupt the other interface. SoftAP does not support WPA3, Enterprise, WPS, DFS/CAC, or dynamic VLAN.
Bandwidth and Throughput Validation#
clock=50000 kHz in the SDIO host log indicates the SDIO bus clock between the K230 and the module,
and is not the same parameter as the 20/40/80 MHz Wi-Fi RF channel width. When determining 80 MHz support and the actual connection
bandwidth, distinguish between the following two log messages:
ME capabilities ... max-bw=80 MHz: The maximum capability reported to the host by the chip/firmware;association channel ... width=80 MHz: The actual RF bandwidth used for this STA association.
wifi status shows current link information. When AIC8800_WIFI_DEBUG_STATS is enabled, you can also run
aic8800_stat to view USB, SDIO, WLAN, RX reorder, and firmware rate-control statistics.
This option adds per-frame statistics and ICMP checksum diagnostics, and should usually remain disabled in performance benchmark images.
Short tests immediately after a cold boot do not represent stable throughput. If the first round of results is low but recovers after waiting approximately 20 seconds, first run a 30–60 second test and record throughput, retransmissions, and RSSI per second before comparing USB/SDIO transports or firmware versions. The mere fact that a connection has been established and throughput subsequently stabilizes does not prove that DPD calibration has failed; an actual DPD failure prints an error during firmware initialization and prevents WLAN registration.
BLE#
After the USB transport enables AIC8800_WIFI_BLE, the Bluetooth interface registers as a dynamic /dev/hciN.
It provides an H:4 controller transport but does not include a GAP/GATT protocol stack; RT-Smart applications can use NimBLE,
while CanMV firmware can enable its MicroPython NimBLE module. SCO audio is not implemented.
See the Bluetooth HCI and NimBLE Usage Guide for complete host/controller configuration and limitations.
Troubleshooting#
wifi devicesdoes not show an AIC device: First check the USB/SDIO host, power supply, and corresponding transport configuration.The log indicates that the firmware file does not exist: Confirm that the firmware subrepository has been synchronized and check the
/bin/firmwarelayout in the image.The log shows functions 1/2 as
c8a1:c08d,c8a1:c18d, but subsequently reportsno driver for SDIO function: The current image still uses the old driver and must be rebuilt and the RT-Smart system image updated.DC/DW/DL enumerates only one function: Check the module power supply, reset, SDIO signals, and host configuration; the driver initializes only when both functions are present.
DC/DW/DL patch or calibration firmware fails to load: Depending on the enabled transport, check
/bin/firmware/sdio/aic8800DCor/bin/firmware/aic8800DC. If the log explicitly shows DPD calibration failure, also check the power supply, reset timing, and silicon revision in the log.D40 can connect but has an abnormal rate: Confirm that
AIC8800_WIFI_USB_LIMIT_40MHZ=y.CRC errors occur on SDIO: First restore the 50 MHz, four-wire high-speed configuration and check the routing.
USB stress tests are abnormal: Enable
AIC8800_WIFI_DEBUG_STATSand viewaic8800_stat; do not blindly increase the URB and queue depths first.Throughput is low only in the first round immediately after association: Extend the test and record the results in segments. If it returns to normal after 20 seconds, investigate firmware rate control and the AP negotiation process before modifying DPD or the SDIO host clock.
For diagnostic methods involving the underlying offload control device, see WLAN Offload Control Example.