# USB

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# 功能概述

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接口，用于与主机设备（如微控制器或处理器）连接。

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

1. **数据通信**：主机设备通过USB接口与蜂窝通信模块通信。

2. **模块控制**：主机设备通过USB接口发送AT命令至模块，进行网络通信、文件操作、硬件控制等。

3. **固件下载**：主机设备通过USB接口将新的固件下载到蜂窝通信模块。

4. **USB网卡**：某些蜂窝通信模块支持USB网卡模式。在该模式下，主机可将USB接口视为类似以太网的网络接口，通过USB直接进行网络通信（通常需要在主机上安装相应的驱动程序）。

5. **诊断和调试**：USB接口可用于获取模块的运行状态、抓取系统日志或执行特定测试命令，以辅助故障排查。

6. **电源供应**：USB接口通常也用于为蜂窝通信模块供电。

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

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

1. **低速（Low-Speed）**：最高传输速率1.5 Mbps（Megabits per second），主要用于鼠标和键盘等低带宽设备。

2. **全速（Full-Speed）**：最高传输速率12 Mbps，与USB 1.1最高速率一致，适用于USB摄像头、打印机等常规设备。

3. **高速（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函数之前使用。

- **函数原型**

```c
qosa_usb_error_e qosa_usb_init(void);
```

- **参数说明**  
  无

- **返回值说明**  
  *QOSA_USB_SUCCESS*：函数执行成功  
  其他值（详见 [*qosa_usb_error_e*](#qosausberror_e)）：函数执行失败

### qosa_usb_deinit

- **功能描述**  
  去初始化USB功能。

- **函数原型**

```c
qosa_usb_error_e qosa_usb_deinit(void);
```

- **参数说明**  
  无

- **返回值说明**  
  *QOSA_USB_SUCCESS*：函数执行成功  
  其他值（详见 [*qosa_usb_error_e*](#qosausberror_e)）：函数执行失败

### qosa_usb_bind_vbus_cb

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

- **函数原型**

```c
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*](#qosausbvbus_cb) |

- **返回值说明**  
  *QOSA_USB_SUCCESS*：函数执行成功  
  其他值（详见 [*qosa_usb_error_e*](#qosausberror_e)）：函数执行失败

#### qosa_usb_vbus_cb

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

- **函数原型**

```c
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*](#qosausbvbusstatee) |
| *ctx* | 输入 | void * | 用户自定义上下文指针，可在注册回调时传入，用于传递私有数据，在回调中原样返回 |

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

### qosa_usb_get_vbus_state

- **功能描述**  
  获取VBUS引脚状态。

- **函数原型**

```c
qosa_usb_vbus_state_e qosa_usb_get_vbus_state(void);
```

- **参数说明**  
  无

- **返回值说明**  
  详见 [*qosa_usb_vbus_state_e*](#qosausbvbusstatee)

### qosa_usb_get_connect_state

- **功能描述**  
  获取USB连接状态。

- **函数原型**

```c
qosa_usb_state_e qosa_usb_get_connect_state(void);
```

- **返回值说明**  
  详见 [*qosa_usb_state_e*](#qosausbstate_e)

### qosa_usb_config_hid

- **功能描述**  
  配置 USB HID功能模式（鼠标或键盘）。

- **函数原型**

```c
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*](#qosausbhidmodee) |

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

## 枚举定义

### qosa_usb_error_e

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

```c
#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重新打开错误 |

```{note}
*QOSA_COMPONENT_API_USB* 为USB组件ID，定义于 *qosa_def.h* 中。
```

### qosa_usb_vbus_state_e

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

```c
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连接状态枚举定义如下：

```c
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设备模式枚举定义如下：

```c
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同时列出鼠标和键盘 |

# 应用逻辑流程图

```{figure} images/board_MfrmwztLohV9crbe0DIc4MVUndh.jpg
:align: center
:alt: image
```

# 示例代码

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