USBNET功能¶

功能概述¶

USBNET是基于USB接口实现网络共享的技术统称，在Linux内核中对应USBNET驱动框架，支持ECM、NCM、RNDIS、MBIM等多种协议。其核心机制是在USB通信中模拟标准网络设备：主机的网络协议栈通过虚拟USB网络适配器与设备相连，设备作为网关将流量转发至移动网络，从而使主机能够通过设备的移动网络访问互联网。

基本要素¶

USB设备： 蜂窝模块或内置模块的终端设备。作为USB从设备，需实现特定的USB接口类型，向主机声明自身为网络适配器。
主机驱动： 运行在主机操作系统上的软件，用于识别USB设备并驱动其呈现的网络接口。不同的USBNET协议对应不同的驱动。
网络接口： 主机操作系统中呈现的虚拟网卡，操作系统通过此接口进行IP配置、路由配置和网络通信。
数据通道： USB设备与主机之间用于传输网络数据包的逻辑通道，通常通过USB批量传输端点交换数据。

流程概述¶

USBNET流程是指将设备的移动数据连接通过USB桥接并共享给主机的端到端过程，通常包含以下操作步骤：

设备枚举与识别：设备连接到主机后，主机查询其USB描述符，识别设备所属的设备类（通信设备类或特定厂商类），并加载对应驱动，完成网络适配器的注册。
接口初始化与连接：驱动与设备进行初始化握手，配置USB端点和通信参数。设备端USBNET服务激活后，开始从移动数据连接读取数据；主机端虚拟网络接口状态变为"已连接"。
IP配置：主机通过DHCP向设备请求IP配置。设备内嵌的DHCP服务器为主机分配私有IP地址并下发网关地址，主机完成IP和路由配置。
数据包转发：
下行：设备从移动网络接收IP数据包，通过USB通道发送至主机驱动，驱动解包后提交至主机网络协议栈。
上行：主机产生的IP数据包经虚拟网络接口和驱动，通过USB发送至设备，再由设备转发至移动网络。
连接断开：停止USBNET服务时，设备通知主机驱动，驱动将网络接口标记为断开，随后关闭数据通道并释放资源。

主机接收网络数据：

../../../../_images/image_SMJvbHKvEotuPAxSiPQcVK6PnLc.webp

主机发送数据到网络：

../../../../_images/image_HJp2belklolqlSxBiuKcGOCJnOh.webp

主要协议对比¶

协议	全称	性质与描述	优点	缺点	主要适用系统
RNDIS	Remote Network Driver Interface Specification	微软制定的私有协议，通过在USB上封装以太网帧实现通信，已成为Windows事实标准。	Windows兼容性最佳，即插即用，无需额外安装驱动。	协议复杂冗余；在Linux/macOS上需额外驱动或兼容层。	Windows
ECM	Ethernet Control Model	USB-IF官方标准。直接在USB上传输原始以太网帧，协议简洁。	跨平台标准，在Linux、macOS和现代Windows上支持良好、稳定。	在旧版本Windows上可能需要手动安装驱动。	Linux，macOS，现代Windows
NCM	Network Control Model	CDC ECM的增强版标准。核心改进是支持数据包聚合，将多个IP数据包聚合到一个USB传输中，提升效率。	高性能，在大带宽场景下吞吐量和效率显著高于ECM/RNDIS；跨平台兼容性好。	协议实现稍复杂，需驱动和设备端同时支持。	Linux，macOS，现代Windows（尤其适合4G/5G高速场景）
MBIM	Mobile Broadband Interface Model	微软与行业联合制定的现代标准。专为移动宽带设计，在USB上传输原始的、未封装的IP数据包，控制与数据分离。	架构现代高效，直接处理IP数据包，开销低；支持丰富的移动网络功能管理；是Windows 8+及5G时代的推荐标准。	协议相对复杂；在旧系统或非Windows平台上支持可能有限。	现代Windows (8+)，5G设备

数据结构¶

USBNET的实现依赖以下核心数据结构层次：

USB描述符层：
设备通过此层向主机声明身份。关键描述符包括设备描述符、配置描述符、接口描述符和端点描述符，它们共同定义了"通信接口类"和"数据接口"，后者关联的批量传输端点用于传输网络数据。
协议控制消息层（以RNDIS/MBIM为例）：
该层提供连接管理和参数协商功能，通过USB控制传输或中断传输端点交换带外控制消息。
RNDIS： 使用 RNDIS_INITIALIZE_MSG、RNDIS_QUERY_MSG 等控制消息。
MBIM： 使用 MBIM_COMMAND_MSG、MBIM_COMMAND_DONE 等结构化消息管理网络功能。
网络数据帧层：
传输实际用户网络数据的带内数据通道，封装格式因协议而异：
RNDIS： 以太网帧包裹在 RNDIS_PACKET_MSG 结构中传输。
ECM： 在USB端点上直接传输完整的以太网帧。
NCM： 传输NCM传输块，其中聚合了多个IP数据包，效率更高。
MBIM： 在USB端点上直接传输原始的IP数据包，无需额外的链路层封装，协议开销较低。

网络激活管理¶

参照：DataCall拨号

USBNET API¶

头文件¶

qosa_usbnet.h

函数概览¶

函数	说明
qosa_usbnet_get_type()	获取USBNET应用协议类型
qosa_usbnet_set_type()	设置USBNET应用协议类型
qosa_usbnet_set_config()	设置USBNET连接配置项
qosa_usbnet_get_config()	获取USBNET连接配置项
qosa_usbnet_start()	启动USBNET连接
qosa_usbnet_stop()	停止USBNET连接

函数详解¶

qosa_usbnet_get_type¶

功能描述
获取USBNET应用协议类型。
函数原型

qosa_usbnet_err_e qosa_usbnet_get_type(qosa_uint8_t simid, qosa_usbnet_type_e *type)

参数说明

参数名	输入/输出	类型	说明
simid	输入	qosa_uint8_t	SIM卡ID；范围：0~1 0：卡槽1 1：卡槽2
type	输出	qosa_usbnet_type_e*	协议类型；详见 qosa_usbnet_type_e

返回值说明
QOSA_USBNET_ERR_OK：函数执行成功
其他值(详见 qosa_usbnet_err_e)：函数执行失败

qosa_usbnet_set_type¶

功能描述
设置USBNET应用协议类型。
函数原型

qosa_usbnet_err_e qosa_usbnet_set_type(qosa_uint8_t simid, qosa_usbnet_type_e type)

参数说明

参数名	输入/输出	类型	说明
simid	输入	qosa_uint8_t	SIM卡ID；范围：0~1 0：卡槽1 1：卡槽2
type	输入	qosa_usbnet_type_e	协议类型；详见 qosa_usbnet_type_e

返回值说明
QOSA_USBNET_ERR_OK：函数执行成功
其他值(详见 qosa_usbnet_err_e)：函数执行失败

备注

设置的USBNET应用协议类型在设备重启后生效。

qosa_usbnet_set_config¶

功能描述
设置USBNET连接配置项。
函数原型

qosa_usbnet_err_e qosa_usbnet_set_config(qosa_uint8_t simid, qosa_usbnet_config_t *config)

参数说明

参数名	输入/输出	类型	说明
simid	输入	qosa_uint8_t	SIM卡ID；范围：0~1 0：卡槽1 1：卡槽2
config	输入	qosa_usbnet_config_t*	连接配置项；详见 qosa_usbnet_config_t

返回值说明
QOSA_USBNET_ERR_OK：函数执行成功
其他值(详见 qosa_usbnet_err_e)：函数执行失败

qosa_usbnet_get_config¶

功能描述
获取USBNET连接配置项。
函数原型

qosa_usbnet_err_e qosa_usbnet_get_config(qosa_uint8_t simid, qosa_usbnet_config_t *config)

参数说明

参数名	输入/输出	类型	说明
simid	输入	qosa_uint8_t	SIM卡ID；范围：0~1 0：卡槽1 1：卡槽2
config	输出	qosa_usbnet_config_t*	连接配置项；详见 qosa_usbnet_config_t

返回值说明
QOSA_USBNET_ERR_OK：函数执行成功
其他值(详见 qosa_usbnet_err_e)：函数执行失败

qosa_usbnet_start¶

功能描述
启动USBNET连接，进行网络共享。
函数原型

qosa_usbnet_err_e qosa_usbnet_start(qosa_uint8_t simid, usbnet_callback_t cb, void *ctx)

参数说明

参数名	输入/输出	类型	说明
simid	输入	qosa_uint8_t	SIM卡ID；范围：0~1 0：卡槽1 1：卡槽2
cb	输入	usbnet_callback_t	启动USBNET连接，返回状态的回调函数
ctx	输入	void *	回调函数上下文

返回值说明
QOSA_USBNET_ERR_OK：函数执行成功
其他值(详见 qosa_usbnet_err_e)：函数执行失败

qosa_usbnet_stop¶

功能描述
停止USBNET连接，断开网络共享。
函数原型

qosa_usbnet_err_e qosa_usbnet_stop(qosa_uint8_t simid, usbnet_callback_t cb, void *ctx)

参数说明

参数名	输入/输出	类型	说明
simid	输入	qosa_uint8_t	SIM卡ID；范围：0~1 0：卡槽1 1：卡槽2
cb	输入	usbnet_callback_t	停止USBNET连接，返回状态的回调函数
ctx	输入	void *	回调函数上下文

返回值说明
QOSA_USBNET_ERR_OK：函数执行成功
其他值(详见 qosa_usbnet_err_e)：函数执行失败

usbnet_callback_t¶

函数原型

typedef void (*usbnet_callback_t)(void *ctx, void *argv);

参数说明

参数名	输入/输出	类型	说明
ctx	输入	void *	用户上下文指针
argv	输入	void *	回调参数指针

结构体定义¶

qosa_usbnet_config_t¶

配置USBNET连接参数的结构体定义如下：

typedef struct
{
    qosa_uint8_t         simid;  
    qosa_uint8_t         pdpid;  
    qosa_usbnet_method_e method; 
} qosa_usbnet_config_t;

参数	类型	说明
simid	qosa_uint8_t	SIM卡ID；范围：0~1 0：卡槽1 1：卡槽2
pdpid	qosa_uint8_t	PDP ID；范围：1~15
method	qosa_usbnet_method_e	连接方式；详见 qosa_usbnet_method_e

备注

仅当连接方式（method）为 0 时，配置文件ID（pdpid）才允许设置为 0。

枚举定义¶

qosa_usbnet_type_e¶

协议类型枚举定义如下：

typedef enum
{
    QOSA_USBNET_TYPE_ECM = 1,   
    QOSA_USBNET_TYPE_MBIM = 2,  
    QOSA_USBNET_TYPE_RNDIS = 3, 
    QOSA_USBNET_TYPE_NCM = 5,   
} qosa_usbnet_type_e;

成员	说明
QOSA_USBNET_TYPE_ECM	ECM协议
QOSA_USBNET_TYPE_MBIM	MBIM协议
QOSA_USBNET_TYPE_RNDIS	RNDIS协议
QOSA_USBNET_TYPE_NCM	NCM协议

qosa_usbnet_method_e¶

连接方式枚举定义如下：

typedef enum
{
    QOSA_USBNET_METHOD_DISABLE = 0,  
    QOSA_USBNET_METHOD_ONE_SHOT = 1, 
    QOSA_USBNET_METHOD_AUTO_CONNECT
        = 3, 
} qosa_usbnet_method_e;

成员	说明
QOSA_USBNET_METHOD_DISABLE	禁用
QOSA_USBNET_METHOD_ONE_SHOT	单次连接
QOSA_USBNET_METHOD_AUTO_CONNECT	PDP连接断开或上电等情况下USBNET将自动重新连接，重连间隔逐渐增大

qosa_usbnet_err_e¶

USBNET模块的结果码枚举定义如下：

typedef enum usbnet_err
{
    QOSA_USBNET_ERR_OK = 0,

    QOSA_USBNET_ERR_OPERATION_NOT_ALLOWED   = 3 | QOSA_ERRCODE_USBNET_BASE,
    QOSA_USBNET_ERR_OPERATION_NOT_SUPPORTED = 4 | QOSA_ERRCODE_USBNET_BASE,
    QOSA_USBNET_ERR_MEMORY_FULL             = 20 | QOSA_ERRCODE_USBNET_BASE,
    QOSA_USBNET_ERR_MEMORY_FAILURE          = 23 | QOSA_ERRCODE_USBNET_BASE,
    QOSA_USBNET_ERR_INVALID_PARAM           = 53 | QOSA_ERRCODE_USBNET_BASE,
    QOSA_USBNET_ERR_EXECUTE                 = 1 | (QOSA_ERRCODE_USBNET_BASE + QOSA_AT_ERR_OFS),
    QOSA_USBNET_ERR_BUSY                    = 2 | (QOSA_ERRCODE_USBNET_BASE + QOSA_AT_ERR_OFS),
    QOSA_USBNET_ERR_ALREADY_CONNECTED       = 3 | (QOSA_ERRCODE_USBNET_BASE + QOSA_AT_ERR_OFS),
} qosa_usbnet_err_e;

成员	说明
QOSA_USBNET_ERR_OK	操作成功
QOSA_USBNET_ERR_OPERATION_NOT_ALLOWED	操作不被允许
QOSA_USBNET_ERR_OPERATION_NOT_SUPPORTED	操作不被支持
QOSA_USBNET_ERR_MEMORY_FULL	内存已满
QOSA_USBNET_ERR_MEMORY_FAILURE	内存故障
QOSA_USBNET_ERR_INVALID_PARAM	无效参数
QOSA_USBNET_ERR_EXECUTE	操作执行
QOSA_USBNET_ERR_BUSY	模块忙
QOSA_USBNET_ERR_ALREADY_CONNECTED	已连接

应用逻辑流程图¶

../../../../_images/board_QinCw2MxyhuoQobsmRkcRh6Unbb.jpg

示例代码¶

完整示例代码请查看https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/network/nic/usbnet/usbnet_demo.c

USBNET功能¶

功能概述¶

基本要素¶

流程概述¶

主要协议对比¶

数据结构¶

网络激活管理¶

USBNET API¶

头文件¶

函数概览¶

函数详解¶

qosa_usbnet_get_type¶

qosa_usbnet_set_type¶

qosa_usbnet_set_config¶

qosa_usbnet_get_config¶

qosa_usbnet_start¶

qosa_usbnet_stop¶

usbnet_callback_t¶

结构体定义¶

qosa_usbnet_config_t¶

枚举定义¶

qosa_usbnet_type_e¶

qosa_usbnet_method_e¶

qosa_usbnet_err_e¶

应用逻辑流程图¶

示例代码¶

目录

本页