简介：针对 Linux 平台开发的 USB WiFi 模块驱动资源包，适配 RTL8733BU，兼容 RTL8733 与 RTL8731 芯片，并已针对 MC6810 芯片组完成适配，可在 Linux 4.9.138 内核上运行。面向嵌入式开发人员、系统集成工程师以及需要为特定硬件添加无线功能的用户，帮助解决驱动移植、内核版本匹配和无线模块调试等实际问题。压缩包共包含 1098 个文件，以 C 源码（.c）、头文件（.h）、编译生成的目标文件（.o）及配置脚本为主，另有 Makefile、Kconfig 等构建辅助文件，整体大小约 11.06MB。文件结构完整，覆盖驱动核心模块、MAC 层管理、cfg80211 接口、蓝牙共存处理及固件相关代码，便于开发者直接查阅或交叉编译。已有 678 人浏览学习，对于使用或评估 RTL8733BU 模组的开发者，这份资源提供了适配特定内核版本的参考实现，可缩短环境搭建与调试周期。
1. 拿到 rtl8733bu 那一刻：这个 USB WiFi 模块适配到底卡在哪
一块 mc6810（linux 4.9.138）的板子，一个 USB 接口的 rtl8733bu WiFi+蓝牙二合一模块，这是 BSP 工程师常接的活。芯片型号看着新，但工作量大头不在驱动本身——原厂源码包基本能跑，真正翻车的地方是内核 API 对齐、USB 枚举、蓝牙共存这三件事。适合谁看：板级 bringup、BSP、底层驱动开发。读完这篇，从选型到量产验证的一条完整链路就清楚了。
说实话，rtl8733bu 这类芯片能上场，靠的是单芯片同时出 WiFi 和蓝牙、USB 接口走线简单、驱动源码开放。但如果你拿到的 SDK 是 4.9 内核，而驱动源码是按 6.x 内核写的，编译那一关就会劝退一半人。选源码看什么、平台配置怎么改、dmesg 怎么定位，下面按实操顺序展开。
2. 驱动源码与内核版本的选型：为什么不能随手拿个驱动就编
拿到适配任务后，很多人的第一反应是上网找 rtl8733bu 的驱动源码，找到什么编什么。这个习惯在 4.9 内核上特别容易翻车。芯片原厂一般会提供按内核版本切分支的源码包，适配过 3.x/4.x/5.x 的版本往往处理过内核 API 差异；而那些只按最新内核做的包，放到 4.9 上一编就是几十个报错。选型这一步决定后面所有工作的量级。
2.1 rtl8733bu / rtl8733 / rtl8731 的关系：三个型号为啥共用一套源码
BU 后缀的含义：B 代表 Bluetooth，U 代表 USB 接口，也就是说这是一颗 WiFi+蓝牙二合一芯片的 USB 形态。rtl8733 是整个系列，rtl8731 是管脚兼容的简化版，rtl8733bu 是具体的 USB 型号。原厂驱动源码通常一个分支覆盖整个系列，在代码里通过 VID/PID 和 chip 类型判断来分发。
实际适配时，我一般会把 rtl8733、rtl8733a、rtl8731 这几个关键字的补丁都翻一遍。同一个分支里，这几个型号的差异往往只是 load firmware 时的一段 chip 判断，可能就十几行。如果你的模块丝印是 rtl8733bu，但板子量产想换料成 rtl8731，驱动不用重写，只是要多确认一遍 VID/PID 表里有没有新料的 ID。
# 进入驱动源码根目录，先确认三个型号的芯片判断是否全量覆盖 grep -rn "rtl8733\|RTL8733\|rtl8731\|RTL8731" --include="*.c" --include="*.h" | head -30 # 重点看芯片 ID / 固件名 / 版本判断，确认覆盖 rtl8733 与 rtl8731这段 grep 的意义在于提前发现缺料。如果分支条件里只覆盖了 rtl8733 没覆盖 rtl8731，后面换料就要自己补芯片判断。但这种补丁不建议乱改，先看原厂有没有专门的维护版本，否则容易把固件加载流程改坏。
2.2 linux 4.9.138 内核选驱动的两个硬指标
第一个硬指标：源码里对内核版本的分支判断。打开 include/osdep_service.h、include/rtw_security.h 这类头文件，搜 KERNEL_VERSION。如果能看到 KERNEL_VERSION(4, 9, 0) 或者 KERNEL_VERSION(4, 10, 0) 这类分支，说明源码维护者考虑过老内核，编过的概率大。
第二个硬指标：源码用的 cfg80211 API 是旧签名还是新签名。4.9 内核的 cfg80211 和后面 5.x、6.x 差别很大，典型的像 cfg80211_scan_done、cfg80211_connect_result 这类函数，参数和调用时机都被改过。如果源码是清一色新 API，4.9 上要自己做 API 回迁，工作量不是按小时计的。
# 在驱动源码里找 cfg80211 相关调用，确认用到哪些接口 grep -rn "cfg80211_scan_done\|cfg80211_connect_result\|cfg80211_roamed" --include="*.c" rtl8733bu/ | head -20这步的意义：先知道驱动对上层的依赖面。4.9 内核里这些符号如果找不到，后面 insmod 一定报 Unknown symbol，现在发现还能换源码包，等编完再发现就浪费时间了。
2.3 USB WiFi 驱动的四层结构：你真正要改的是哪一层
rtl8733bu 的驱动往下分四层。第一层是 USB 接入层，负责 usb_driver 结构体的注册、probe/disconnect、URB 收发；第二层是芯片/固件层，负责下载固件、初始化 MAC、RF 校准；第三层是 cfg80211 适配层，向上对接内核无线子系统，实现 scan、connect 这些回调；第四层是 BT 共存层，和蓝牙共用天线时做 PTA 或 GPIO 互斥。
在 mc6810 上做的适配，绝大多数时间是第一层和第三层：调 USB 的 URB 超时和 buffer，调 cfg80211 的回调返回值和注册流程。第二层基本不动，第四层取决于板子的蓝牙拓扑。很多新人把时间花在第二层上反复烧固件，其实那层原厂出厂就调好了。
这里要澄清一个常见误用：以为 rtl8733bu 依赖 mac80211，于是去内核里翻 mac80211 配置。这个芯片的驱动是典型的 fullmac 风格，它自己实现 MAC 管理，直接注册 wiphy，只依赖 cfg80211，不依赖 mac80211。内核配置时把 mac80211 打开也不会错，但没必要。
3. 在 mc6810 上交叉编译 rtl8733bu：从内核配置到 ko 生成
选好源码包之后，进入编译环节。交叉编译本身不复杂，但有两个前提没做好，后面就是白编：目标内核的配置必须开放 cfg80211，编译环境要和 SDK 自带的工具链对齐。这一章按我实际执行的顺序写，命令可以直接抄。
3.1 先确认内核不会挡路：cfg80211 与 USB 相关配置检查
在动驱动源码之前，先去目标内核的 .config 里确认几个开关。CONFIG_CFG80211 必须存在，建议 =y 内建；CONFIG_USB 和 CONFIG_USB_SUPPORT 必须开；CONFIG_WIRELESS 也要有。cfg80211 如果是 =m，也能用，但根文件系统里必须带 cfg80211.ko，并且加载顺序要在 rtl8733bu 之前。
# 以内核源码路径 /home/xxx/mc6810/kernel 为例 grep -E "CONFIG_(CFG80211|CFG80211_MODULE|USB|USB_SUPPORT|WIRELESS)" \ /home/xxx/mc6810/kernel/.config这个 grep 的输出里，CONFIG_CFG80211=y 是理想情况。如果整行不存在，说明内核裁剪时把无线子系统拿掉了，rtl8733bu 编出来也加载不了。常见做法是回到内核 make menuconfig 里打开 Networking support -> Wireless -> cfg80211，保存后全量重编，而不是只编驱动。
3.2 交叉编译环境的两个对齐点：工具链与内核头文件
工具链必须用 SDK 自带的，别用宿主机 gcc。mc6810 这类平台 SDK 一般会带 aarch64-linux-gnu- 工具链，路径在 SDK 的 toolchain 目录下。用错工具链最典型的症状是编出来的 ko 行为诡异，或者 vermagic 一致但指令集有差异导致 Oops。
第二个对齐点是 KSRC，也就是内核源码路径。不光路径要对，这个内核源码必须已经完整编译过，至少要有 .config、Module.symvers、include/config/kernel.release 这三个产物。特别是 Module.symvers，它记录内核导出的符号，驱动编译时链接阶段要靠它解析 undefined symbol。
export PATH=/opt/mc6810-toolchain/bin:$PATH export ARCH=arm64 export CROSS_COMPILE=aarch64-linux-gnu- export KSRC=/home/xxx/mc6810/kernel # 验证工具链能跑 aarch64-linux-gnu-gcc --version # 验证内核产物完整 ls -l $KSRC/Module.symvers $KSRC/include/config/kernel.release这里说清楚 ARCH 和 CROSS_COMPILE 的含义：ARCH 告诉编译系统的目标 CPU 架构，CROSS_COMPILE 是交叉编译工具链前缀。KSRC 是驱动 Makefile 里指向内核源码的变量名，不同源码包可能叫 KERNEL_SRC 或 KERNELDIR，编译前先看 Makefile 头部的变量定义，别照抄。
3.3 修改 Makefile 指定平台：ARCH、CROSS_COMPILE、KSRC 三个变量
rtl8733bu 的驱动源码 Makefile 里通常有一段平台选择逻辑，常见的是 CONFIG_PLATFORM_IOT、CONFIG_PLATFORM_ANDROID、CONFIG_PLATFORM_ARM64 这些分支。我们要么复用现成的 ARM64 分支，要么在 IOT 分支下改参数。我一般会在 IOT 分支上改，因为这类盒子方案默认就是 IOT 场景。
# 打开 Makefile，找到 CONFIG_PLATFORM_IOT = y 的位置，做如下修改或新增 CONFIG_PLATFORM_IOT = y # 在其 ifeq 分支里对齐以下三行（以实际源码包为准） ARCH := arm64 CROSS_COMPILE := aarch64-linux-gnu- KVER := 4.9.138 KSRC := /home/xxx/mc6810/kernel说明：ARCH 和 CROSS_COMPILE 和前面 export 的一致，只是这里写在 Makefile 里，编译时就不用每次带变量。KVER 这个变量主要是给模块安装路径用的，比如 make install 时拷贝到 /lib/modules/$(KVER)/extra 下。直接 insmod 的话，KVER 不是必须的，但填对了能让 modprobe 的自动查找更省事。
改完直接编：
make -j4 # 成功后应该生成 rtl8733bu.ko ls -l rtl8733bu.ko如果编不过，优先看第一个报错是不是内核头文件路径不对，而不是驱动源码有问题。交叉编译九成的编译失败都是 KSRC 指错或者内核没先编过，这类问题别去改源码。
提示：如果源码包自带 Makefile 里已经有针对 ARM64 的分支，优先复用，别自己新开分支。新开分支容易漏掉 EXTRA_CFLAGS 里的编译宏，导致同样的源码编出行为不同的 ko。
3.4 生成 rtl8733bu.ko 之后，先查 vermagic 再 insmod
拿到 ko 文件先别急着往板子上拷。第一步用 modinfo 看 vermagic，它必须和目标内核的版本完全一致；第二步用 nm 看它依赖的外部符号，特别是有没有 U 标记的 cfg80211 符号。
# 查看驱动的 vermagic modinfo rtl8733bu.ko | grep vermagic # 查看目标内核的 kernel.release cat /home/xxx/mc6810/kernel/include/config/kernel.release # 查看未定义符号，U 标记的就是运行时需要内核提供的 nm rtl8733bu.ko | grep ' U ' | grep -E "cfg80211|usb" | head -20vermagic 一致性是最基本的一关。如果 modinfo 显示的版本和你板子的内核版本不一致，insmod 会直接拒绝，报 version magic 错误。nm 的输出里，所有 U 前缀符号必须能在内核的 Module.symvers 里找到对应项，找不到的后面就是 Unknown symbol。
我第一次在 mc6810 上编译这个驱动时，就是栽在 cfg80211 的符号上：ko 编出来了，insmod 报 Unknown symbol cfg80211_get_channel，后来才发现内核的 Module.symvers 里根本没导出这个符号，因为 cfg80211 是后加进内核配置的，没跟着全量重编。这种黑匣子问题，只要按上面三步走一遍就能提前发现。
4. 设备树与 USB 枚举：为什么 insmod 之后看不到 wlan0
ko 加载成功不等于 wlan0 出现。rtl8733bu 是 USB 接口芯片，它能不能被系统识别，先看 USB 枚举，再看驱动的 probe 有没有跑通。在 mc6810 这类板子上，USB 口的供电、复位、以及 WiFi 和蓝牙的加载顺序，是三个最常见的变量。
4.1 USB 口供电与复位引脚的设备树写法
模块不是直接怼到标准 USB 口，而是通过 USB 信号线加独立供电接到板子上时，设备树要保证 USB host 控制器这个口有电、复位脚能拉到正确电平。常见做法是加一个 fixed-regulator 描述模块的供电，并在 USB 控制器节点里引用它。
&usbhost1 { status = "okay"; vbus-supply = <&wifi_vbus_reg>; }; wifi_vbus_reg: fixed-regulator { compatible = "regulator-fixed"; regulator-name = "wifi_vbus"; regulator-min-microvolt = <3300000>; regulator-max-microvolt = <3300000>; gpio = <&gpio2 5 GPIO_ACTIVE_HIGH>; enable-active-high; startup-delay-us = <100000>; };这段 dts 里，vbus-supply 让 USB 控制器在启动时把该供电打开；fixed-regulator 节点里的 gpio 是实际控制 3.3V 的引脚，enable-active-high 表示高电平使能；startup-delay-us 的 100ms 是等电源稳定后再让 USB 去枚举。这个延时不能省，有的板子省掉之后冷启动时模块偶发识别不到。
如果你的板子用的是主控自带的 USB PHY，不需要外部供电控制，那这段 dts 就不必加。判断依据很简单：把模块插上，dmesg 有没有 USB 枚举信息，没有就先怀疑供电和复位，而不是驱动。
4.2 dmesg 分三段看驱动有没有绑定成功
模块插好后，dmesg 的排查按三段看。第一段是 USB 枚举，比如 usb 1-1: new high-speed USB device number 6 出现，说明物理链路和供电都 OK。第二段是 VID/PID 识别，rtl8733bu 的 USB ID 通常以 0bda 打头，具体产品 ID 以模块实测为准。第三段是驱动绑定，probe 成功后会出现带 rtl8733bu 字样的日志。
# 看最近的 USB 枚举和设备识别日志 dmesg | tail -50 | grep -E "usb|rtl8733|wlan" # 列出当前 USB 设备，对比插模块前后的变化 ls /sys/bus/usb/devices/如果第一段都没有，先回头看供电；如果第一段有但第二段没有，说明模块没被正确识别为 USB 设备，可能是 USB 信号线布线问题；如果第二段有但第三段没有，说明驱动里的 usb_device_id 表没有覆盖你手里模块的 VID/PID。最后一种情况，去驱动的 id table 定义里加一组 ID，重新编一遍就好。
4.3 WiFi 与蓝牙的加载顺序问题
二合一芯片在 USB 枚举后通常会出现两个功能接口，一个给 WiFi，一个给蓝牙。芯片原厂源码里一般有 btcoex 逻辑，要求蓝牙侧先准备好，再让 WiFi 起来，否则共存配置拿不到蓝牙侧的握手信号。所以在 mc6810 上，我一般先加载蓝牙相关驱动，再 insmod rtl8733bu.ko。
# 先蓝牙后 WiFi 的常见加载顺序 modprobe btusb insmod /vendor/lib/modules/rtl8733bu.ko # 确认 wlan0 和蓝牙接口都出现 ls /sys/class/net/这里要区分两种情况：如果你的板子蓝牙是独立芯片，跟 rtl8733bu 没关系，加载顺序随便；如果蓝牙就是这颗芯片提供的，那顺序错了最典型的症状是 WiFi 起来了、蓝牙不掉，但蓝牙一连上 WiFi 就断。判断板子的拓扑，看原理图比看驱动日志更快。
5. 驱动适配避坑手册：在 mc6810 上把 rtl8733bu 调稳的 5 个教训
适配过程里踩过不少坑，挑 5 个最有代表性的记录在这。每一条都按现象、原因、解决三步写，你在自己板子上遇到同样的症状时可以直接对照。
5.1 坑一：编出来的 ko 一 insmod 就报 Unknown symbol 或 Oops
现象：make 顺利出 ko，insmod 时 dmesg 报 Unknown symbol cfg80211_xxx，或者直接 Oops 打印一堆栈信息。
原因：驱动引用了一个当前内核没有导出的符号。常见两种：一是 cfg80211 是后加进内核的，内核没全量重编，Module.symvers 里没有对应符号；二是驱动源码用了新内核才有的 API，而 4.9 里根本不存在这个符号。
解决：先按第 3 章的方法确认符号是否在内核的符号表里，再决定是重编内核还是回迁 API。
# 确认内核里有没有这个符号，没有就是 API 不匹配 grep "cfg80211_get_channel" /proc/kallsyms # 确认 Module.symvers 里有没有导出 grep "cfg80211_get_channel" /home/xxx/mc6810/kernel/Module.symvers # 都没有，说明源码是按新内核写的，换源码包或做 API 回迁5.2 坑二：能扫描到好几个 AP，连上之后却 ping 断或者掉线
现象：iw dev wlan0 scan 能看到周边热点，wpa_supplicant 也能连上，但 DHCP 一直拿不到 IP，或者 ping 几分钟就断一次。
原因：最常见的是天线问题，模块的焊盘或 IPEX 座接触不良，导致 RSSI 很低；其次是 USB 供电不足，传输大流量时电压跌落；再就是 regulatory 区域设置不对，信道功率被限制。
解决：先看信号强度再谈其他。iw dev wlan0 link 看 signal 值，如果连上后 RSSI 低于 -75dBm，先解决天线；供电可以用独立 3.3V 电源给模块供电排除；regulatory 用 iw reg set 设置对应国家区域。
# 看关联后的信号与速率 iw dev wlan0 link # 设置 regulatory，解除信道功率限制（CN 仅为示例，按实际区域修改） iw reg set CN # 持续 ping 观察抖动 ping -i 0.2 192.168.1.1 | tee ping.log5.3 坑三：蓝牙一开，WiFi 吞吐立刻掉到 0
现象：不开蓝牙时 iperf3 能正常跑，蓝牙一连，WiFi 就断流或者吞吐直接归零。
原因：2.4G 频段 WiFi 和蓝牙共用天线，驱动靠 PTA 或 GPIO 做时分复用。如果设备树没把共存的 GPIO 脚配好，或者驱动源码的 btcoex 默认配置和实际接线不一致，两个射频就会互相踩。
解决：确认板子是不是二合一方案，然后再查两件事：设备树里 BT_WAKE / HOST_WAKE / WIFI_WAKE 这些 GPIO 的 pinctrl 是否对上原理图；驱动源码里 CONFIG_BT_COEXIST 是否打开。
# 确认驱动是否带 btcoex grep -rn "BT_COEXIST\|btcoex" /home/xxx/mc6810/kernel/drivers/net/wireless/rtl8733bu/Makefile | head -10 # 有的源码会在 /proc/net/rtl8733bu/ 下提供 btcoex 调试节点 ls /proc/net/rtl8733bu/蓝牙和 WiFi 共存的调试有时候比较玄学，现象一样但原因完全不同。我一般先让硬件同事确认 GPIO 接线，再改驱动，顺序反了会白调好几个小时。
5.4 坑四：系统休眠唤醒后 wlan0 消失
现象：echo mem > /sys/power/state 之后唤醒，ifconfig wlan0 报 no such device，只能重启恢复。
原因：USB 设备在休眠时被挂起，唤醒后驱动的 resume 回调没有把 URB 重新提交，或者 USB 控制器侧把设备重新枚举了但驱动没感知到。usbcore 的 autosuspend 默认配置在这种二合一芯片上很容易触发。
解决：第一步先临时关闭 autosuspend 验证方向，如果关了之后恢复正常，再去驱动里处理 resume 路径，或加 quirk 禁用 hub initiated LPM。
# 临时关闭 autosuspend 验证（重启恢复默认值） echo -1 > /sys/module/usbcore/parameters/autosuspend # 也可以单独设置某个 USB 口的电源控制策略 echo on > /sys/bus/usb/devices/1-1/power/control如果是量产固件，我不建议依赖这种手动 echo。做法是把 autosuspend 参数写进系统默认配置里，或者在驱动 suspend 回调里直接禁止 autosuspend。至于 URB 提交失败，用 usbmon 抓一下唤醒后的 URB 错误码，比瞎猜快。
5.5 坑五：同一份源码编出的 ko 拿到另一块板子上 insmod 失败
现象：两块板子看着配置一样，这块板子调好的 ko 拿到另一块就报版本不符，或者加载后 wlan0 起不来。
原因：两块板子的内核 .config 有差异，驱动在编译时会根据内核头文件里的 config 宏调整行为，比如 CONFIG_PM、CONFIG_HAS_EARLYSUSPEND 这类，ko 里固化的配置和当前内核不一致。vermagic 相同但内部 struct 布局不同，就会出这种怪问题。
解决：每块板子对应一套完整编译产物，镜像和 ko 一起整体烧写，不要混搭。同一批板子在量产时用同一个固件包，别临时在产线上单独换一个 ko 文件，这是血泪教训。
6. 验证与量产：从 ping 通到稳定出货还差哪些测试
ko 能加载、wlan0 能出 IP，只是起点。rtl8733bu 在 mc6810 上要走到量产，我习惯至少补三类测试：吞吐量、AP 兼容性、掉电与自加载。
6.1 吞吐量测试：iperf3 双向与不同信道
iperf3 双向、TCP/UDP 分开测。按这个系列的定位，模块常见是 2.4G 单频 WiFi4，802.11n 40MHz 理论 150Mbps，实测 60-90 属正常，低于 40 就要查天线和共存配置。
# 板子上起服务端 iperf3 -s # PC 上跑反向测试，测下行 iperf3 -c 板子IP -t 60 -R # 再正向跑一次，测上行；然后换信道 1/6/11 各测一遍6.2 兼容性测试：不同 AP、不同加密组合
拿市面上常见的家用路由、商用 AP 各几台，覆盖 WPA2/WPA3、2.4G 频段不同带宽配置，跑一轮连接和持续传输。重点看 DHCP 获取速度和长时间 ping 丢包率。
6.3 量产集成：ko 打包、开机自加载与掉电测试
量产固件里把 rtl8733bu.ko 放到固定模块目录，开机脚本里先加载蓝牙再加载 WiFi，用 modprobe 而不是 insmod，配合 depmod 生成依赖关系。最后做 50 次以上的断电重启，统计识别成功率。
# 开机脚本示例 modprobe btusb modprobe rtl8733bu sleep 2 # 检查 wlan0 出现，没出现则重试一次我现在的习惯是，驱动调稳之后把 dmesg 的启动日志、ko 的 vermagic、内核 .config 三个东西一起存档，换板子或换批次先比这三样，再谈排查。希望帮到你。
本文还有配套的精品资源，点击获取
