RK3588 Linux USB Gadget：usb_config.sh 全解析

在瑞芯微RK3588的嵌入式开发中，USB功能的定制化是绕不开的核心需求——不管是做工业USB摄像头、音视频采集设备，还是边缘计算终端的远程调试与网络互通，都需要对USB Gadget进行精准配置。而usb_config.sh作为RK3588 Linux平台下原生的USB Gadget配置脚本，基于Linux内核configfs框架实现了UVC、UAC、RNDIS、ADB、DFU等功能的灵活组合，是开发者快速实现USB功能定制的核心工具。

 

本文将结合RK3588的硬件特性，从脚本核心逻辑、功能模块、实际使用到平台化优化，全方位解析这个脚本，让你轻松掌握RK3588的USB Gadget配置技巧。

 

 

一、前置基础：USB Gadget与configfs

 

 

首先简单科普两个核心概念，帮大家理解脚本的工作底层：

 

 

•USB Gadget：是Linux内核为嵌入式设备提供的USB从设备功能框架，让RK3588这类嵌入式芯片能模拟成U盘、摄像头、网卡、ADB调试设备等USB设备；

 

 

•configfs：是替代传统gadgetfs的内核态配置文件系统，采用“目录/文件”的方式配置USB Gadget参数，无需修改内核代码，仅通过脚本即可动态配置，是当前嵌入式USB Gadget开发的主流方式。

 

 

RK3588作为瑞芯微高端八核64位芯片，原生支持USB2.0/3.0，内核已默认开启USB Gadget与configfs支持，而usb_config.sh正是基于该框架，为RK3588定制了音视频、网络、调试等高频USB功能的配置模板，开箱即用。

 

 

二、脚本核心框架：全局配置与变量定义

 

 

脚本以#!/bin/sh编写，适配嵌入式Linux的POSIX Shell环境，开头的全局变量与开关配置是整个脚本的基础，也是开发者最易修改的部分，核心内容如下：

 

 

•  
•  
•  
•  
•  
•  
•  
•  
•  
•  

# 功能开关：默认ADB开启、DFU固件升级关闭ADB_EN=onDFU_EN=off# 第二个参数带"off"则强制关闭ADB，适配调试/量产场景if ( echo $2 |grep -q "off" ); thenADB_EN=offfi# USB功能/配置根目录，基于configfs的固定路径USB_FUNCTIONS_DIR=/sys/kernel/config/usb_gadget/rockchip/functionsUSB_CONFIGS_DIR=/sys/kernel/config/usb_gadget/rockchip/configs/b.1

RK3588专属注意：脚本中rockchip为瑞芯微平台的Gadget根目录命名，RK3588的Linux内核已默认创建该目录，无需额外修改路径，直接使用即可。

 

 

这部分的核心作用是统一功能开关与配置路径，开发者可根据量产/调试需求，直接修改ADB_EN/DFU_EN的默认值，或通过命令行参数动态控制ADB开关，无需改动脚本后续逻辑。

 

 

三、核心功能模块：RK3588的USB能力落地

 

 

usb_config.sh的核心价值，是为RK3588实现了音视频、音频、网络、调试、固件升级五大USB功能的模块化配置，其中UVC（USB视频类） 是脚本的核心模块，充分适配了RK3588的硬编解码能力。

 

 

3.1 核心中的核心：UVC视频配置，适配RK3588硬编解

 

 

RK3588内置强大的视频硬编解码单元，支持H264/H265硬编、MJPEG格式处理，而脚本的UVC模块正是为该特性量身定制，支持NV12、YUYV、MJPEG、H264、H265五种像素格式，以及多分辨率的定制化参数（帧率、码率、缓冲区大小）。

 

 

脚本通过多个分辨率配置函数实现格式区分，例如configure_uvc_resolution_mjpeg（MJPEG配置）、configure_uvc_resolution_h264（H264配置），所有函数遵循统一逻辑：创建分辨率目录→写入宽高/帧率/码率→配置像素位数/格式GUID→适配系统识别。

 

 

针对RK3588的硬件特性，UVC模块做了重点优化：

 

 

1.高分辨率支持：MJPEG格式最高支持2592x1944，适配RK3588的高清视频采集需求；

 

 

2.硬编格式适配：原生支持H264/H265，直接调用RK3588的硬编单元，降低CPU占用；

 

 

3.多帧率可选：基础格式默认30fps，高分辨率格式做了帧率适配，避免USB带宽溢出。

 

 

最终通过uvc_device_config函数完成UVC总配置，创建UVC功能目录、建立速率适配软链接（FS/HS/SS），并初始化默认分辨率：YUYV（640x480/1280x720）、MJPEG（640x4802592x1944）、H264（640x4801920x1080）。

 

 

3.2 UAC音频配置：单/双向音频采集与播放

 

 

脚本支持UAC1/UAC2两种USB音频类规范，为RK3588实现立体声音频采集与播放，核心配置uac1_device_config/uac2_device_config函数逻辑一致，适配不同的音频传输协议，关键参数如下：

 

 

•声道：立体声（声道掩码3），采样位深16位；

 

 

•采样率：8000/16000/44100/48000Hz，覆盖工业/民用音频场景；

 

 

•音量调节：播放端-20dB0dB，捕获端-12.5dB0dB，支持静音功能。

 

 

UAC1/UAC2的功能完全一致，开发者可根据对接的上位机（如Windows/macOS/工业主机）选择对应的规范，脚本已做好模块化封装，直接调用即可。

 

 

3.3 辅助功能：RNDIS网络与ADB调试

 

 

这两个功能是嵌入式开发的高频需求，脚本通过轻量的预运行函数实现，适配RK3588的远程调试与网络互通：

 

 

1.RNDIS网络：通过pre_run_rndis函数配置USB网卡usb0，默认IP为[172.16.110.6](172.16.110.6)，也可通过/data/uvc_xu_ip_save文件持久化自定义IP，让RK3588通过USB直连实现网络通信，无需额外网卡；

 

 

2.ADB调试：通过pre_run_adb函数挂载functionfs、启动adbd守护进程，以2000/2000的权限运行，适配RK3588的Android/Linux双系统调试需求。

 

 

3.4 量产必备：DFU固件升级

 

 

DFU（设备固件升级）是嵌入式量产的核心功能，脚本通过DFU_EN开关控制，开启后会自动将DFU功能链接到USB配置节点，并强制关闭ADB，避免量产过程中的调试风险，适配RK3588的固件批量烧录需求。

 

 

四、主流程执行：RK3588的USB配置落地步骤

 

 

脚本的主流程是将上述模块化功能，按环境初始化→设备标识配置→功能组合→绑定生效的步骤落地，全程基于configfs操作，无需重启内核，动态生效，完全适配RK3588的嵌入式开发特性，核心步骤如下：

 

 

步骤1：基础环境初始化

 

 

卸载并重新挂载configfs，启动回环网卡lo（保证ADB正常运行），创建USB功能挂载目录，为后续配置做准备；

 

 

步骤2：USB设备标识配置

 

 

写入瑞芯微专属厂商ID（0x2207）、产品ID（0x0017），以及设备版本、厂商名、产品名、硬件序列号（从/proc/cpuinfo读取RK3588的唯一Serial），同时配置Windows适配的OS描述符（MSFT100），保证RK3588模拟的USB设备能被Windows/macOS/ Linux正常识别；

 

 

步骤3：UVC初始化+清理默认配置

 

 

优先初始化UVC核心功能，同时清理内核默认的ADB配置，避免与自定义配置冲突（兼容瑞芯微老平台，RK3588可忽略此兼容逻辑）；

 

 

步骤4：参数化功能组合（核心）

 

 

脚本通过第一个命令行参数实现功能的灵活组合，这是最实用的部分，RK3588开发者可直接通过参数调用不同功能，无需修改脚本，核心组合如下：

 

 

执行参数	功能组合	适用场景
无参数	仅UVC	纯USB摄像头设备
rndis	UVC+RNDIS	带网络的高清视频采集终端
uac1/uac2	UVC+UAC1/UAC2	音视频一体采集设备
uac1_rndis/uac2_rndis	UVC+UAC+RNDIS	带网络的音视频采集终端

步骤5：DFU/ADB动态绑定

 

 

根据DFU_EN/ADB_EN开关，动态将DFU/ADB链接到USB配置节点，自动计算节点编号，避免冲突，开启后会更新配置名（如uvc→uvc_adb/uvc_dfu）；

 

 

步骤6：绑定UDC生效

 

 

读取RK3588的USB设备控制器（UDC）名称，写入Gadget根目录的UDC文件，这一步是配置生效的关键，写入后RK3588立即模拟成配置好的USB设备；

 

 

步骤7：RNDIS网络初始化

 

 

若参数包含rndis，自动配置usb0网卡IP并启动，实现USB网络互通。

 

 

整个主流程无需人工干预，一键执行即可完成USB配置，完全适配RK3588的嵌入式自动化开发需求。

 

 

五、RK3588实战：脚本使用命令示例

 

 

结合实际开发场景，给大家整理了RK3588下usb_config.sh的常用执行命令，直接在终端运行即可，建议将脚本放到/etc/init.d/目录，设置开机自启，实现USB功能的开机即有。

 

 

•  
•  
•  
•  
•  
•  
•  
•  
•  
•  

# 场景1：纯USB摄像头（仅UVC，ADB开启，调试用）./usb_config.sh# 场景2：纯USB摄像头（仅UVC，ADB关闭，量产用）./usb_config.sh off# 场景3：UVC+RNDIS（高清视频采集+USB网络，远程调试）./usb_config.sh rndis# 场景4：UVC+UAC2（音视频一体采集，工业摄像头）./usb_config.sh uac2# 场景5：UVC+UAC2+RNDIS（音视频采集+USB网络，边缘计算终端）./usb_config.sh uac2_rndis

六、RK3588平台专属优化建议

 

 

原脚本是瑞芯微通用平台脚本，针对RK3588的硬件特性，我们可以做一些轻量化优化，让USB功能更贴合RK3588的性能，同时提升脚本的健壮性：

 

 

1. 合并UAC1/UAC2冗余代码

 

 

原脚本中UAC1/UAC2函数逻辑完全一致，可合并为一个函数，通过参数区分，减少脚本体积，适配RK3588的小型根文件系统；

 

 

2. 适配USB3.0，调整UVC最大数据包

 

 

RK3588支持USB3.0，可将UVC的streaming_maxpacket从3072调整为10240，提升视频传输带宽，避免高清视频卡顿；

 

 

3. 增加H265高分辨率定制配置

 

 

原脚本H265仅支持基础帧率，可基于RK3588的H265硬编能力，添加1920x1080/2560x1440的H265分辨率配置；

 

 

4. 添加错误处理，提升健壮性

 

 

原脚本缺少mkdir/echo等操作的失败检查，可添加set -e或if [ $? -ne 0 ]，避免配置中断导致的USB功能异常；

 

 

5. 实现配置持久化

 

 

将ADB/DFU开关、RNDIS IP等配置写入/etc/usb_gadget.conf配置文件，脚本读取该文件实现参数化配置，无需修改脚本本身，适配量产化管理；

 

 

6. 关闭无用兼容逻辑

 

 

原脚本包含RK1808 4.4内核的兼容代码，RK3588的Linux内核为5.10+/6.1+，可直接删除该兼容逻辑，简化脚本。

 

 

七、总结

 

 

usb_config.sh是RK3588 Linux平台下USB Gadget开发的最佳实践模板，它基于configfs框架，将UVC、UAC、RNDIS、ADB、DFU等高频功能做了模块化封装，通过简单的命令行参数即可实现功能组合，无需深入内核开发，极大降低了RK3588 USB功能的定制门槛。

 

 

对于RK3588开发者而言，掌握这个脚本的核心逻辑，不仅能快速实现音视频、网络、调试等USB功能，还能基于RK3588的硬件特性做二次优化，让USB功能充分发挥RK3588的性能优势。无论是做工业摄像头、音视频采集终端，还是边缘计算设备，这个脚本都是不可或缺的核心工具。

 

 

最后，如果你在RK3588的USB Gadget配置中遇到了问题，比如UVC识别失败、RNDIS网络不通、ADB无法连接等，欢迎在评论区留言交流，一起解锁RK3588的USB更多玩法！