USB¶

功能概述¶

USB（Universal Serial Bus，通用串行总线）是一种通用总线标准，用于连接主机和外设。主机通过USB接口与外设连接，实现数据传输、电源供给等功能。

USB-IF（USB Implementers Forum，USB开发者论坛）是USB标准的制定组织，定义了USB 1.1、USB 2.0、USB 3.0等版本的物理层、协议层及设备类规范。常见的设备类包括HID（Human Interface Device，人机接口设备）、MSC（Mass Storage Class，大容量存储设备）、CDC（Communication Device Class，通信设备）、Audio、Video等。

蜂窝通信模块具有USB接口，用于与主机设备（如微控制器或处理器）连接。

该接口主要实现以下功能：

数据通信：主机设备通过USB接口与蜂窝通信模块通信。
模块控制：主机设备通过USB接口发送AT命令至模块，进行网络通信、文件操作、硬件控制等。
固件下载：主机设备通过USB接口将新的固件下载到蜂窝通信模块。
USB网卡：某些蜂窝通信模块支持USB网卡模式。在该模式下，主机可将USB接口视为类似以太网的网络接口，通过USB直接进行网络通信（通常需要在主机上安装相应的驱动程序）。
诊断和调试：USB接口可用于获取模块的运行状态、抓取系统日志或执行特定测试命令，以辅助故障排查。
电源供应：USB接口通常也用于为蜂窝通信模块供电。

目前UniRTOS支持的带USB接口的模块均采用USB2.0协议。

USB 2.0标准中包含三种数据传输速率：

低速（Low-Speed）：最高传输速率1.5 Mbps（Megabits per second），主要用于鼠标和键盘等低带宽设备。
全速（Full-Speed）：最高传输速率12 Mbps，与USB 1.1最高速率一致，适用于USB摄像头、打印机等常规设备。
高速（High-Speed）：USB 2.0的主要新特性，最高传输速率480 Mbps，适用于外部硬盘、高分辨率摄像头、网络适配器等大数据量设备。

以上速率均为理论最高值，实际传输速率受USB控制器性能、设备性能、线缆质量及系统负载等因素影响，可能低于理论值。

USB API¶

头文件¶

qosa_usb.h

函数概览¶

函数	说明
qosa_usb_init()	初始化USB功能，需在调用其他USB函数之前使用
qosa_usb_deinit()	去初始化USB功能
qosa_usb_bind_vbus_cb()	绑定VBUS引脚中断的回调函数
qosa_usb_vbus_cb()	接收VBUS引脚状态变更通知的回调函数原型
qosa_usb_get_vbus_state()	获取VBUS引脚状态
qosa_usb_get_connect_state()	获取USB连接状态

函数详解¶

qosa_usb_init¶

功能描述
初始化USB功能，需在调用其他USB函数之前使用。
函数原型

qosa_usb_error_e qosa_usb_init(void);

参数说明
无
返回值说明
QOSA_USB_SUCCESS：函数执行成功
其他值（详见 qosa_usb_error_e）：函数执行失败

qosa_usb_deinit¶

功能描述
去初始化USB功能。
函数原型

qosa_usb_error_e qosa_usb_deinit(void);

参数说明
无
返回值说明
QOSA_USB_SUCCESS：函数执行成功
其他值（详见 qosa_usb_error_e）：函数执行失败

qosa_usb_bind_vbus_cb¶

功能描述
绑定VBUS引脚中断的回调函数。
函数原型

qosa_usb_error_e qosa_usb_bind_vbus_cb(qosa_usb_vbus_cb vbus_callback);

参数说明

参数名	输入/输出	类型	说明
vbus_callback	输入	qosa_usb_vbus_cb	VBUS引脚中断回调函数指针，用于接收VBUS引脚状态变化事件；详见 qosa_usb_vbus_cb

返回值说明
QOSA_USB_SUCCESS：函数执行成功
其他值（详见 qosa_usb_error_e）：函数执行失败

qosa_usb_vbus_cb¶

功能描述
接收VBUS引脚状态变更通知的回调函数原型。
函数原型

typedef qosa_uint32_t (*qosa_usb_vbus_cb)(qosa_usb_vbus_state_e state, void *ctx);

参数说明

参数名	输入/输出	类型	说明
state	输入	qosa_usb_vbus_state_e	当前VBUS引脚的状态；详见 qosa_usb_vbus_state_e
ctx	输入	void *	用户自定义上下文指针，可在注册回调时传入，用于传递私有数据，在回调中原样返回

返回值说明
0：函数执行成功
非零值：函数执行失败

qosa_usb_get_vbus_state¶

功能描述
获取VBUS引脚状态。
函数原型

qosa_usb_vbus_state_e qosa_usb_get_vbus_state(void);

参数说明
无
返回值说明
详见 qosa_usb_vbus_state_e

qosa_usb_get_connect_state¶

功能描述
获取USB连接状态。
函数原型

qosa_usb_state_e qosa_usb_get_connect_state(void);

返回值说明
详见 qosa_usb_state_e

qosa_usb_config_hid¶

功能描述
配置 USB HID功能模式（鼠标或键盘）。
函数原型

qosa_int32_t qosa_usb_config_hid(qosa_usb_hid_mode_e mode);

参数说明

参数名	输入/输出	类型	说明
mode	输入	qosa_usb_hid_mode_e	HID功能模式选择；详见 qosa_usb_hid_mode_e

返回值说明
QOSA_USB_SUCCESS：函数执行成功
其他负值：错误码，表示配置失败的具体原因（如参数无效、硬件不支持等）。

枚举定义¶

qosa_usb_error_e¶

USB操作相关的错误码枚举定义如下：

#define QOSA_USB_ERRCODE_BASE (QOSA_COMPONENT_API_USB << 16)

typedef enum
{
    QOSA_USB_SUCCESS = 0,
    QOSA_USB_EXECUTE_ERR = 1 | QOSA_USB_ERRCODE_BASE,
    QOSA_USB_MEM_ADDR_NULL_ERR,
    QOSA_USB_INVALID_PARAM,
    QOSA_USB_SYS_ERROR,
    QOSA_USB_NO_SPACE,
    QOSA_USB_NOT_SUPPORT,
    QOSA_USB_REOPEN_ERR,
} qosa_usb_error_e;

成员	说明
QOSA_USB_SUCCESS	操作成功
QOSA_USB_EXECUTE_ERR	USB操作执行失败
QOSA_USB_MEM_ADDR_NULL_ERR	内存地址为空
QOSA_USB_INVALID_PARAM	输入参数无效
QOSA_USB_SYS_ERROR	系统错误
QOSA_USB_NO_SPACE	存储空间不足
QOSA_USB_NOT_SUPPORT	当前操作不支持
QOSA_USB_REOPEN_ERR	USB重新打开错误

备注

QOSA_COMPONENT_API_USB 为USB组件ID，定义于 qosa_def.h 中。

qosa_usb_vbus_state_e¶

USB VBUS引脚连接状态枚举定义如下：

typedef enum
{
    QOSA_USB_VBUS_NOT_SUPPORT = -1,
    QOSA_USB_VBUS_DISCONNECT = 0,
    QOSA_USB_VBUS_CONNECT
} qosa_usb_vbus_state_e;

成员	说明
QOSA_USB_VBUS_NOT_SUPPORT	VBUS检测功能不可用
QOSA_USB_VBUS_DISCONNECT	VBUS引脚断开连接
QOSA_USB_VBUS_CONNECT	VBUS引脚已连接

qosa_usb_state_e¶

USB连接状态枚举定义如下：

typedef enum
{
    QOSA_USB_STATE_NOT_SUPPORT = -1,
    QOSA_USB_DISCONNECT = 0,
    QOSA_USB_CONNECT         
} qosa_usb_state_e;

成员	说明
QOSA_USB_STATE_NOT_SUPPORT	USB功能不可用
QOSA_USB_DISCONNECT	USB断开连接
QOSA_USB_CONNECT	USB已连接

qosa_usb_hid_mode_e¶

USB HID设备模式枚举定义如下：

typedef enum 
{
    QOSA_USB_HID_MODE_KEYBOARD = 1,     
    QOSA_USB_HID_MODE_MOUSE,            
    QOSA_USB_HID_MODE_MOUSE_AND_KEYBOARD,
} qosa_usb_hid_mode_e;

成员	说明
QOSA_USB_HID_MODE_KEYBOARD	USB仅列出键盘
QOSA_USB_HID_MODE_MOUSE	USB仅列出鼠标
QOSA_USB_HID_MODE_MOUSE_AND_KEYBOARD	USB同时列出鼠标和键盘

应用逻辑流程图¶

示例代码¶

完整示例代码请查看 https://github.com/UniRTOS/UniRTOS-Doc-Examples/blob/main/peripheral/usb/usb_demo.c

USB¶

功能概述¶

USB API¶

头文件¶

函数概览¶

函数详解¶

qosa_usb_init¶

qosa_usb_deinit¶

qosa_usb_bind_vbus_cb¶

qosa_usb_vbus_cb¶

qosa_usb_get_vbus_state¶

qosa_usb_get_connect_state¶

qosa_usb_config_hid¶

枚举定义¶

qosa_usb_error_e¶

qosa_usb_vbus_state_e¶

qosa_usb_state_e¶

qosa_usb_hid_mode_e¶

应用逻辑流程图¶

示例代码¶

目录

本页