USB Development Guide_Rev1.2

中文

Revision History

Version	Date	Author	Revision Content
Rev1.0	23-09-06	SXX	Initial document creation
Rev1.1	24-03-25	SXX	Changed document name
Rev1.2	25-04-18	ZH	Added common issues section

1 Introduction

This document introduces the LTE-EC71X USB interface APIs. The API interfaces are declared in the file components/kernel/lierda_api/liot_usb/liot_usb.h.

Before using USB APIs, you need to install USB drivers. Please refer to USB Driver Installation Guide.

The LTE-EC71X series modules support USB 2.0 interface. USB input/output signals are compatible with USB 2.0 interface specifications. The interface supports automatic adaptation of 480Mbps (HS) and 12Mbps (FS) data transmission.

NT26FCNB10WNA USB Pin Schematic

Pin definitions are shown in the table below.

Pin Name	I/O	Description	Remarks
USB DP	AIO	USB differential data (+)	Leave floating if not used
USB DM	AIO	USB differential data (-)
USB_VBUS	AI	External USB 5V input	Optional, leave floating if not used

Pin numbers may vary with versions. For specific pins, please refer to hardware documentation

New Addition

2 API Function Overview

Function	Description
liot_usb_bind_hotplug_cb	Register USB event callback function
liot_usb_get_hotplug_state	Get USB plug/unplug status
liot_usb_drv_is_enabled	Get USB initialization status
liot_usb_drv_enable	Initialize USB driver
liot_usb_drv_disable	Deinitialize USB driver

3 Type Descriptions

3.1 liot_usb_errcode_e

USB API execution result error codes.

• Definition

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;

• Parameters

• LIOT_USB_SUCCESS: Function executed successfully.

• LIOT_USB_INVALID_PARAM: Invalid input parameter.

• LIOT_USB_SYS_ERROR: System-level error.

• LIOT_USB_DETECT_SAVE_NV_ERR: Failed to save detection data to NV.

• LIOT_USB_NO_SPACE: Insufficient system space.

• LIOT_USB_NOT_SUPPORT: Operation not supported.

3.2 liot_usb_hotplug_e

USB hot-plug event notification types.

1. Definition

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

2. Parameters

• LIOT_USB_HOTPLUG_OUT: USB unplug event.

• LIOT_USB_HOTPLUG_IN: USB plug-in event.

3.3 liot_usb_hotplug_cb

USB hot-plug callback function type.

1. Definition

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

2. Parameters

• state: Hot-plug status.

• ctx: Context parameter passed by user when registering callback.

3. Return Value

liot_usb_errcode_e type converted to int type value.

4 API Function Details

4.1 liot_usb_bind_hotplug_cb

Register USB hot-plug event callback function.

1. Declaration

liot_usb_errcode_e liot_usb_bind_hotplug_cb(liot_usb_hotplug_cb hotplug_callback);

2. Parameters

hotplug_callback: [in] Callback function to be registered. If NULL, unregister the callback.

3. Return Value

liot_usb_errcode_e: Execution result code, see 3.1 for reference.

4.2 liot_usb_get_hotplug_state

Get USB plug/unplug status.

1. Declaration

liot_usb_hotplug_e liot_usb_get_hotplug_state(void);

2. Parameters

None.

3. Return Value

liot_usb_hotplug_e: Hot-plug status, see 3.2 for reference.

4.3 liot_usb_drv_is_enabled

Query whether USB driver has been initialized.

1. Declaration

   bool liot_usb_drv_is_enabled(void);
   

2. Parameters

   None.

3. Return Value

bool: true: USB initialization completed. false: USB not initialized.

4.4 liot_usb_drv_enable

Initialize USB driver.

1. Declaration

liot_usb_errcode_e liot_usb_drv_enable(void);

2. Parameters

None.

3. Return Value

liot_usb_errcode_e: Execution result code, see 3.1 for reference.

4.5 liot_usb_drv_disable

Deinitialize USB driver.

1. Declaration

liot_usb_errcode_e liot_usb_drv_disable(void);

2. Parameters

None.

3. Return Value

liot_usb_errcode_e: Execution result code, see 3.1 for reference.

5 Code Example

Refer to the examples/demo/src/demo_usb.c file for sample code.

#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;
    // Register USB hot-plug callback function
    liot_usb_bind_hotplug_cb(liot_usb_notify_cb);
    while(1)
    {
        liot_rtos_task_sleep_ms(1000);
        // Get USB hot-plug status
        liot_trace("USB get hotplug state(%d)", liot_usb_get_hotplug_state());
        // Query whether USB driver is initialized
        usbisenabled = liot_usb_drv_is_enabled();
        liot_trace("usbisenabled:%d", usbisenabled);
        liot_rtos_task_sleep_ms(10000);
        // Disable USB driver
        liot_usb_drv_disable();
        liot_trace("usbisenabled:%d", usbisenabled);
        // Enable USB driver
        liot_usb_drv_enable();
        liot_trace("usbisenabled:%d", usbisenabled);
    }
}

Execution Result: