USB 开发指导_Rev1.2

修订记录

版本	日期	作者	修订内容
Rev1.0	23-09-06	SXX	创建文档
Rev1.1	24-03-25	SXX	更改文档名称
Rev1.2	25-04-18	ZH	增加系列常见问题

1 简介

本文档介绍 LTE-EC71X USB 接口 API 情况， API 接口位于 components/kernel/lierda_api/liot_usb/liot_usb.h 文件声明。

在使用 USB API 之前，需安装 USB 驱动，请参考 USB 驱动安装指南。

LTE-EC71X 系列模组支持 USB2.0 接口，USB 输入/输出信号兼容 USB2.0 接口规范，接口支持最 480Mbps（HS）和 12Mbps（FS）数据传输自动适配。

NT26FCNB10WNA USB 引脚原理图

引脚定义如下表所示。

引脚名	I/0	描述	备注
USB DP	AIO	USB 差分数据（+）	不用则悬空
USB DM	AIO	USB 差分数据（-）
USB_VBUS	AI	外部 USB 5V 输入	可选，不用则悬空

引脚号可能会随版本变化，具体引脚可参考硬件资料

新增

2 API 函数概览

函数	说明
`liot_usb_bind_hotplug_cb`	注册 USB 事件回调函数
`liot_usb_get_hotplug_state`	获取 USB 插拔状态
`liot_usb_drv_is_enabled`	获取 USB 初始化状态
`liot_usb_drv_enable`	初始化 USB 驱动
`liot_usb_drv_disable`	去初始化 USB 驱动

3 类型说明

3.1 liot_usb_errcode_e

USB API 执行结果错误码。

定义

typedef enum
{
    LIOT_USB_SUCCESS,               /*  operating is successful  */
    LIOT_USB_INVALID_PARAM,         /*  invalid input param  */
    LIOT_USB_SYS_ERROR,             /*  system error  */
    LIOT_USB_DETECT_SAVE_NV_ERR,    /*  save detect time to NV failed */
    LIOT_USB_NO_SPACE,              /*  no space to store data  */
    LIOT_USB_NOT_SUPPORT,           /*  current operation not support   */
} liot_usb_errcode_e;

参数
LIOT_USB_SUCCESS ：函数执行成功。
LIOT_USB_INVALID_PARAM：传入参数错误。
LIOT_USB_SYS_ERROR：系统级错误。
LIOT_USB_DETECT_SAVE_NV_ERR：系统检查保存数据到 NV 错误。
LIOT_USB_NO_SPACE：系统空间不足。
LIOT_USB_NOT_SUPPORT：操作不支持。

3.2 liot_usb_hotplug_e

USB 热拔插事件通知类型。

定义

typedef enum
{
    LIOT_USB_HOTPLUG_OUT = 0,    //USB in plug out state
    LIOT_USB_HOTPLUG_IN  = 1       //USB was inserted
 } liot_usb_hotplug_e;

参数

LIOT_USB_HOTPLUG_OUT ：USB 拔出事件。
LIOT_USB_HOTPLUG_IN ：USB 插入事件。

3.3 liot_usb_hotplug_cb

USB 热拔插回调函数类型。

定义

typedef int(*liot_usb_hotplug_cb)(liot_usb_hotplug_e state, void *ctx);

参数

state：热拔插状态。
ctx：用户在注册回调时，传入的上下文参数。

返回值

liot_usb_errcode_e 类型转 int 类型数值。

4 API 函数详解

4.1 liot_usb_bind_hotplug_cb

注册 USB 热拔插事件回调函数。

声明

liot_usb_errcode_e liot_usb_bind_hotplug_cb(liot_usb_hotplug_cb hotplug_callback);

参数

hotplug_callback：[in] 需要注册的回调函数，若为 NULL，则取消注册 callback。

返回值

liot_usb_errcode_e：执行结果码，请参考 3.1。

4.2 liot_usb_get_hotplug_state

获取 USB 插拔状态

声明

liot_usb_hotplug_e liot_usb_get_hotplug_state(void);

参数

无。

返回值

liot_usb_hotplug_e ：热拔插状态，请参考 3.2。

4.3 liot_usb_drv_is_enabled

查询 USB 驱动是否已经完成初始化。

声明
```
bool liot_usb_drv_is_enabled(void);
```
参数

无。
返回值

bool：true: 已完成初始化 usb。flase: 未进行初始化 usb。

4.4 liot_usb_drv_enable

初始化 USB 驱动。

声明

liot_usb_errcode_e liot_usb_drv_enable(void);

参数

无。

返回值

liot_usb_errcode_e：执行结果码，请参考 3.1。

4.5 liot_usb_drv_disable

去初始化 USB 驱动。

声明

liot_usb_errcode_e liot_usb_drv_disable(void);

参数

无。

返回值

liot_usb_errcode_e：执行结果码，请参考 3.1。

5 代码示例

示例代码参考 examples/demo/src/demo_usb.c 文件。

#include "liot_usb.h"
#include "liot_os.h"
#include "liot_type.h"
#include <stdio.h>
#include <string.h>

int liot_usb_notify_cb(LIOT_USB_HOTPLUG_E state, void *ctx)
{
    liot_trace("USB change hotplug state(%d)", state);
    return 0;
}

void liot_usb_demo_thread(void *arvg)
{
    bool usbisenabled=FALSE;
    // 注册 USB 热拔插回调函数
    liot_usb_bind_hotplug_cb(liot_usb_notify_cb);
    while(1)
    {
        liot_rtos_task_sleep_ms(1000);
        //获取USB热拔插状态
        liot_trace("USB get hotplug state(%d)", liot_usb_get_hotplug_state());
        //查询USB驱动是否初始化
        usbisenabled = liot_usb_drv_is_enabled();
        liot_trace("usbisenabled:%d", usbisenabled);
        liot_rtos_task_sleep_ms(10000);
        //关闭USB驱动
        liot_usb_drv_disable();
        liot_trace("usbisenabled:%d", usbisenabled);
        //打开USB驱动
        liot_usb_drv_enable();
        liot_trace("usbisenabled:%d", usbisenabled);
    }
}

运行结果：