USB Host 网卡配置指南#
功能概述#
K230 RT-Smart 使用 CherryUSB Host 驱动 USB 网卡，并将识别到的接口注册到 lwIP 和 RT-Thread netdev。当前支持的主要设备类型如下：
设备 |
USB 驱动 |
典型用途 |
|---|---|---|
RTL8152 及兼容网卡 |
RTL8152 专用驱动 |
USB 有线网卡 |
CH397 |
CDC ECM 或 CDC NCM |
USB 有线网卡 |
LTE 模组 |
CDC ECM 或 CDC NCM |
EC200、ML307 等模组的数据网口 |
USB 网卡按探测顺序使用第一个空闲名称，范围为 eth0 到 eth9。接口名不与
芯片型号绑定；同时使用多个网络设备时，应先通过 ifconfig 确认实际名称。
备注
本文配置的是 USB Host 侧的网络接口。LTE 模组的 SIM 卡、APN、驻网和拨号参数 仍需按模组厂商文档配置，并确保模组当前 USB 组合模式会枚举出 ECM 或 NCM 接口。
公共配置#
先在 SDK 根目录加载目标板配置，再进入 RT-Smart 配置界面：
make <board>_defconfig
make rtsmart-menuconfig
进入以下路径：
Components Configuration
-> Enable CherryUSB
-> Enable CherryUSB Host
完成以下公共设置：
打开
Enable CherryUSB Host。在
CherryUSB Host Use Device中选择网卡实际连接的 USB 控制器。打开
Enable CherryUSB Host Class Driver。打开
Enable USB Host for CanMV(Some USB Host Drivers)。
最后一项不仅选择部分 CanMV USB 驱动，还会让 app_canmv 初始化 Host 控制器，
因此在非 OTG 配置中不能省略。该选项会自动选择 RTL8152 驱动，所以仅使用
ECM/NCM 设备时，在最终配置中看到 RTL8152 选项同时开启属于正常现象。
如果固件还启用了 USB Device，Host 与 Device 必须选择不同的控制器。开发板的
USB 接口、控制器编号和 VBUS 使能 GPIO 均与硬件设计有关，应保留目标板
defconfig 中已有的 CanMV USB Host Power Control GPIO 设置，不能直接套用其他
开发板的 GPIO 值。
选择网卡驱动#
RTL8152#
在 Enable CherryUSB Host Class Driver 下打开：
Enable net RTL8152
-> Enable Link Down Check
Enable USB Host for CanMV(Some USB Host Drivers) 已自动选择
Enable net RTL8152。建议同时打开 Enable Link Down Check，使插拔网线后的
链路状态可以及时同步到 netdev。
对应的关键配置项为：
CONFIG_CHERRY_USB_HOST_ENABLE_CLASS_NET_RTL8152=y
CONFIG_CHERRY_USB_RTL8152_LINKCHECK=y
CH397#
CH397（USB VID/PID 1a86:5397）提供 Vendor、ECM 和 NCM 三套 USB
configuration。Host 驱动会根据 CH397 Mode 选择其中一套，因此所选模式必须和
编译进固件的 CDC 驱动一致。
推荐优先使用 ECM：
Enable CherryUSB Host Class Driver
-> Enable cdc ECM
-> CH397 Mode
-> ECM
对应配置为：
CONFIG_CHERRY_USB_HOST_ENABLE_CLASS_CDC_ECM=y
CONFIG_CHERRY_USB_HOST_CH397_MODE_ECM=y
如需使用 NCM，则打开 Enable cdc NCM，并在 CH397 Mode 中选择 NCM：
CONFIG_CHERRY_USB_HOST_ENABLE_CLASS_CDC_NCM=y
CONFIG_CHERRY_USB_HOST_CH397_MODE_NCM=y
不能只切换 CH397 Mode 而不启用对应的 CDC ECM/NCM 驱动。ECM 与 NCM 驱动可以
同时编译，但 CH397 每次枚举只能选择其中一种模式。
LTE 模组#
先确认模组当前 USB 组合模式所提供的网络接口类型，然后启用对应驱动：
模组枚举接口 |
需要打开的选项 |
配置项 |
|---|---|---|
CDC ECM |
|
|
CDC NCM |
|
|
EC200、ML307 等模组常见配置使用 ECM，但同一系列不同固件或 USB 组合模式可能
不同，应以实际 USB 描述符和厂商手册为准。CH397 Mode 只对 VID/PID 为
1a86:5397 的 CH397 生效，不会改变 LTE 模组的模式。
若还需要通过 AT 口设置 APN、查询驻网状态或切换 USB 组合模式，可同时打开：
Enable CherryUSB Host Class Driver
-> Enable SERIAL
-> Enable serial EC200M/A7680C or Other Compatible
兼容的 Vendor Serial 端口通常注册为 /dev/ttyUSBx。如果模组提供标准 CDC ACM
端口，则还需打开 Enable cdc ACM，设备通常注册为 /dev/ttyACMx。串口驱动与
ECM/NCM 网络驱动相互独立；打开串口驱动本身不会建立蜂窝数据连接。
网络栈配置#
USB 网卡依赖 lwIP 和 netdev。确认配置中已经启用：
CONFIG_RT_USING_LWIP=y
CONFIG_RT_LWIP_DHCP=y
CONFIG_RT_USING_NETDEV=y
CONFIG_NETDEV_USING_IFCONFIG=y
RT_USING_NETDEV 通常由 SAL 自动选择，DHCP 和 ifconfig 默认开启。需要手动
检查时，可在 menuconfig 中搜索上述配置项。
保存配置后重新编译并烧录固件。若要把修改固化到目标板 defconfig，再按 SDK
的板级配置维护流程执行 make savedefconfig。
运行验证#
插入设备后先检查 USB 枚举日志。成功绑定时会出现 RTL8152、CDC ECM 或 CDC NCM 类驱动的注册信息，随后出现类似日志：
registered LAN interface as eth0
执行以下命令查看链路、地址、网关和 DNS：
ifconfig
启用 RT_LWIP_DHCP 后，接口注册时会启动 DHCP。若链路建立后仍没有地址，可按
ifconfig 显示的实际接口名重新触发 DHCP：
ifconfig eth0 dhcp
也可以临时配置静态 IPv4 地址：
ifconfig eth0 <ip-address> <gateway-address> <netmask>
最后验证网关和外部地址：
ping <gateway-address>
ping <external-ip-address>
多网卡环境中，ifconfig 标记为 Default 的接口承担默认路由。不要假定 USB
网卡始终为 eth0 或默认接口；应用可通过 NetMgmt 的 RT_NET_DEV_LAN 查询 LAN
接口。
故障排查#
USB 设备完全没有枚举：确认选择了实际连接的 Host 控制器，检查 VBUS 供电、线缆以及板级
CANMV_USB_PWR_PIN配置。有 USB VID/PID，但没有
ethN：确认打开了与设备描述符匹配的 RTL8152、 CDC ECM 或 CDC NCM 驱动，以及Enable USB Host for CanMV。CH397 枚举后没有绑定网络驱动：检查
CH397 Mode与启用的 ECM/NCM 驱动 是否一致。枚举日志中的The device selects config 1表示 ECM，config 2表示 NCM。LTE 模组只有串口、没有网卡：模组当前 USB 组合模式未提供 ECM/NCM，或 蜂窝数据会话尚未建立。先通过 AT 口核对 USB 模式、SIM、APN 和驻网状态。
接口有链路但没有 IPv4 地址：确认 DHCP 已启用，执行
ifconfig ethN dhcp，并检查上游路由器或 LTE 模组是否提供 DHCP 服务。插拔网线后状态不更新：RTL8152 打开
Enable Link Down Check；ECM/NCM 设备还需确认其 USB notification 正确上报网络连接状态。
源码位置#
USB Host 配置：
src/rtsmart/rtsmart/kernel/bsp/maix3/components/KconfigRT-Smart 网卡适配：
src/rtsmart/rtsmart/kernel/bsp/maix3/components/canmv_usb/CherryUSB Class 驱动：
src/rtsmart/rtsmart/kernel/bsp/maix3/components/CherryUSB/class/