发新帖我要提问
返回列表
打印
[研电赛技术支持]

【GD32H757Z海棠派使用手册】第十三讲 USB-虚拟键盘实验

[复制链接]
3061|2
手机看帖
扫描二维码
随时随地手机跟帖
跳转到指定楼层
楼主
聚沃科技|  楼主 | 2024-6-6 10:17 | 只看该作者 |只看大图 回帖奖励 |倒序浏览 |阅读模式
开发板, GD32, 键盘, 虚拟键盘, USB

13.1 实验内容
通过本实验主要学习以下内容：
• USB协议基本原理
• GD32H7xx USBHS的使用
• 虚拟键盘的协议原理及使用
13.2 实验原理
13.2.1 USB通信基础知识
USB的全称是Universal Serial Bus,通用串行总线。它的出现主要是为了简化个人计算机与外围设备的连接，增加易用性。USB支持热插拔，并且是即插即用的，另外，它还具有很强的可扩展性，传输速度也很快，这些特性使支持USB接口的电子设备更易用、更大众化。GD32H7系列MCU集成了USB2.0高速OTG模块。首先为大家介绍USB通信的一些基础知识，包括USB协议、枚举流程等，建议读者可以多多阅读USB协议，以更深入了解USB，USB官网链接如下，可参考：https://www.usb.org/
13.2.1.1 USB金字塔型拓扑结构
塔顶为USB主控制器和根集线器(Root Hub)，下面接USB集线器(Hub)，集线器将一个USB口扩展为多个USB口，USB2.0规定集线器的层数最多为6层，理论上一个USB主控制器最多可接127个设备，因为协议规定USB设备具有一个7 bit的地址(取值范围为0~127，而地址0是保留给未初始化的设备使用的)。
13.2.1.2 NRZI编码
USB采用差分信号传输，使用的是如上图所示的NRZI编码方式：数据为0时，电平翻转；数据为1时，电平不翻转。如果出现6个连续的数据1，则插入一个数据0，强制电平翻转，以便时钟同步。上面的一条线表示的是原始数据序列，下面的一条线表示的是经过NRZI编码后的数据序列。
13.2.1.3 USB数据协议
USB数据是由二进制数据串组成，首先由数据串构成包(packet)，包再构成事务(transaction)，事务最终构成传输(transfer)。
USB传输的最小单位为包，一个包被分成不同的域，根据不同类型的包，所包含的域是不一样的，但是不同的包有个共同的特点，就是以包起始(SOP)开始，之后是同步域(0x00000001)，然后是包内容，最后以包结束符(EOP)结束这个包。PID为标识域，由四位标识符加4位标识符反码构成，表明包的类型和格式。根据PID的不同，USB协议中规定的包类型有令牌包、数据包、握手包和特殊包等。
USB事务通常有两个或三个包组成：令牌包、数据包和握手包，令牌包用来启动一个事务，总是由主机发送；数据包用来传输数据；握手包由数据接收者进行发送，表明数据的接收情况。批量、同步和中断传输每次传输都是一个事务，控制传输包括三个阶段：建立过程、数据过程和状态过程。
针对不同的数据传输场景，USB分为四种数据传输模式，这四种传输模式分别由不同的包(packet)组成，并且有不同的数据处理策略。每种数据传输模式的流程示意图以及应用场景如下：
• 控制传输一般用于命令和状态的传输，分为控制读、控制写和无数据控制传输。在设备枚举的过程中，采用控制传输方式进行数据传输。
• 批量传输分为批量读和批量写，用于数据量大、对实时性要求不高的场合，如U盘。
• 中断传输用于数据量小的场合，保证查询频率，如鼠标、键盘。
• 同步传输用于数据量大、同时对实时性要求较高的场合，如音视频。不保证数据完整性，没有ACK/NAK应答包，不进行数据重传。
13.2.1.4 USB描述符
• 一个USB设备通常有一个或多个配置，但在同一时刻只能有一个配置；
• 一个配置通常有一个或多个接口；
• 一个接口通常有一个或多个端点；
在USB通信中，USB设备需要配置多个USB描述符用以枚举阶段将描述符返回给主机，用以主机的枚举以及识别。USB描述符包括设备描述符、配置描述符、接口描述符、端点描述符以及字符串描述符等。在GD32 USBD固件库中，针对各种描述符都按照USB协议定义了相关结构体，具体说明如下。
• 设备描述符
每个设备必须有一个设备描述符，设备描述符提供了关于设备的配置、设备所归属的类、设备所遵循的协议代码、VID、PID等信息，其相关结构体定义如下。
复制
C

typedef struct _usb_desc_dev {

    usb_desc_header header;               /*!< descriptor header, including type and size */



    uint16_t bcdUSB;                      /*!< BCD of the supported USB specification */

    uint8_t  bDeviceClass;                /*!< USB device class */

    uint8_t  bDeviceSubClass;             /*!< USB device subclass */

    uint8_t  bDeviceProtocol;             /*!< USB device protocol */

    uint8_t  bMaxPacketSize0;             /*!< size of the control (address 0) endpoint's bank in bytes */

    uint16_t idVendor;                    /*!< vendor ID for the USB product */

    uint16_t idProduct;                   /*!< unique product ID for the USB product */

    uint16_t bcdDevice;                   /*!< product release (version) number */

    uint8_t  iManufacturer;               /*!< string index for the manufacturer's name */

    uint8_t  iProduct;                    /*!< string index for the product name/details */

    uint8_t  iSerialNumber;               /*!< string index for the product's globally unique hexadecimal serial number */

    uint8_t  bNumberConfigurations;       /*!< total number of configurations supported by the device */

} usb_desc_dev;
• 配置描述符
每个USB设备都至少具有一个配置描述符，在设备描述符中规定了该设备有多少种配置，每种配置都有一个描述符，其相关结构体定义如下。
复制
C

typedef struct _usb_desc_config {

    usb_desc_header header;               /*!< descriptor header, including type and size */



    uint16_t wTotalLength;                /*!< size of the configuration descriptor header,and all sub descriptors inside the configuration */

    uint8_t  bNumInterfaces;              /*!< total number of interfaces in the configuration */

    uint8_t  bConfigurationValue;         /*!< configuration index of the current configuration */

    uint8_t  iConfiguration;              /*!< index of a string descriptor describing the configuration */

    uint8_t  bmAttributes;                /*!< configuration attributes */

    uint8_t  bMaxPower;                   /*!< maximum power consumption of the device while in the current configuration */

} usb_desc_config;
• 接口描述符
接口描述符用以描述接口信息，接口描述符不能单独返回，必须附着在配置描述符后一并返回，其相关结构体定义如下。
复制
C

typedef struct _usb_desc_itf {

    usb_desc_header header;               /*!< descriptor header, including type and size */



    uint8_t bInterfaceNumber;             /*!< index of the interface in the current configuration */

    uint8_t bAlternateSetting;            /*!< alternate setting for the interface number */

    uint8_t bNumEndpoints;                /*!< total number of endpoints in the interface */

    uint8_t bInterfaceClass;              /*!< interface class ID */

    uint8_t bInterfaceSubClass;           /*!< interface subclass ID */

    uint8_t bInterfaceProtocol;           /*!< interface protocol ID */

    uint8_t iInterface;                   /*!< index of the string descriptor describing the interface */

} usb_desc_itf;
• 端点描述符
端点描述符用以描述端点信息，端点描述符不能单独返回，必须附着在配置描述符后一并返回，其相关结构体定义如下。
复制
C

typedef struct _usb_desc_ep {

    usb_desc_header header;               /*!< descriptor header, including type and size. */



    uint8_t  bEndpointAddress;            /*!< logical address of the endpoint */

    uint8_t  bmAttributes;                /*!< endpoint attributes */

    uint16_t wMaxPacketSize;              /*!< size of the endpoint bank, in bytes */

    uint8_t  bInterval;                   /*!< polling interval in milliseconds for the endpoint if it is an INTERRUPT or ISOCHRONOUS type */

} usb_desc_ep;
• 字符串描述符
字符串描述符可含有指向描述制造商、产品、序列号、配置和接口的字符串的索引。类和制造商专属描述符可含有指向额外字符串描述符的索引。对字符串描述符的支持是可选的，有些类可能会需要它们。
复制
C

typedef struct _usb_desc_str {

    usb_desc_header header;               /*!< descriptor header, including type and size. */

    uint16_t unicode_string[64];          /*!< unicode string data */

} usb_desc_str;
13.2.1.5 USB枚举过程
USB枚举实际上是host检测到device插入后，通过发送各种标准请求，请device返回各种USB描述符的过程。USB枚举的示意图如下：
13.2.2 GD32 USBHS模块简介
GD32H7系列MCU提供了最多两个USB2.0高速USBHS接口模块，USBHS包含了一个内部的USB PHY，可以配置成全速或高速，并且不再需要外部PHY芯片。USBHS可以支持USB 2.0协议所定义的所有四种传输方式（控制传输、批量传输、中断传输和同步传输）。  
USBHS主要特性如下：
n 支持USB 2.0高速（480Mb/s） /全速（12Mb/s） /低速（1.5Mb/s）主机模式；
n 支持USB 2.0高速（480Mb/s） /全速（12Mb/s）设备模式；
n 支持遵循HNP（主机协商协议）和SRP（会话请求协议）的OTG协议；
n 支持所有的4种传输方式：控制传输、批量传输、中断传输和同步传输；
n 支持高带宽中断和同步传输；
n 在主机模式下，包含USB事务调度器，用于有效地处理USB事务请求；
n 包含一个4KB的FIFO RAM；
n 在主机模式下，支持16个通道；
n 在主机模式下，包含2个发送FIFO（周期性发送FIFO和非周期性发送FIFO）和1个接收
FIFO（由所有的通道共享）；
n 在设备模式下，包含8个发送FIFO（每个IN端点一个发送FIFO）和1个接收FIFO（由所有
的OUT端点共享）；
n 在主机模式下，若在高速模式下操作，支持PING协议；
n 在设备模式下，支持8个OUT端点和8个IN端点；
n 在设备模式下，支持远程唤醒功能；
n 包含一个支持USB OTG协议的USB PHY；
n 包含一个内部DMA调度器和引擎，每个应用请求都可在USBHS和系统之间执行数据拷贝；
n 在主机模式下， SOF的时间间隔可动态调节；
n 可将SOF脉冲输出到PAD；
n 可检测ID引脚电平和VBUS电压；
n 在主机模式或者OTG A设备模式下，需要外部部件为连接的USB设备提供电源；
n 支持1.2版电池充电规范中描述的电池充电检测（ BCD）；
n 支持2.0版USB OTG补充协议中描述的附加检测协议（ADP）；
n 支持USB 2.0链路层电源管理附录和USB2.0工程变更通知单勘误表中描述的链路电源管理（LPM）。  
USBD模块框图如下所示，该系列有两个USB HS模块（USB_HS0和USB_HS1），均支持ULPI接口，允许外部HS收发器高速传输USB的数据。  
GD32H7 USBHS使用注意事项可通过以下文档学习：
https://www.gd32mcu.com/data/documents/applicationNote/AN117_GD32H7xx_USBHSshiyongzhuyishixiang_Rev1.0.pdf
13.2.3 USBFS固件库说明
USBFS 固件库使用指南可以参考官网相关文档，下载地址如下：https://www.gd32mcu.com/data/documents/userManual/AN050_GD32_USBFS_USBHS_Firmware_Library_User_Guide_Rev1.0_CN.pdf
13.3 硬件设计
GD32H757海棠派开发板的USB通信接口选择的是目前较为通用的Type C接口，读者手中的用于手机充电的Type C通信线即可使用。
13.4 代码解析
本例程主要实现通过按键向PC发送键值的现象，实现模拟键盘的效果。
本例程主函数如下所示。
复制
C

int main(void)

{

    driver_init();       /* 延时和公共驱动部分初始化 */

        

    bsp_uart_init(&BOARD_UART);     /* 打印串口初始化 */ 



    bsp_led_group_init();           /* 初始化LED组 */     



#ifdef USE_ULPI_PHY

    usb_gpio_config();

#endif /* USE_ULPI_PHY */



    usb_rcu_config();



    usb_timer_init();



    hid_itfop_register (&hid_keyboard, &fop_handler);



#ifdef USE_USBHS0



#ifdef USE_USB_FS

    usb_para_init (&hid_keyboard, USBHS0, USB_SPEED_FULL);

#endif



#ifdef USE_USB_HS

    usb_para_init (&hid_keyboard, USBHS0, USB_SPEED_HIGH);

#endif



#endif /* USE_USBHS0 */



#ifdef USE_USBHS1



#ifdef USE_USB_FS

    usb_para_init (&hid_keyboard, USBHS1, USB_SPEED_FULL);

#endif



#ifdef USE_USB_HS

    usb_para_init (&hid_keyboard, USBHS1, USB_SPEED_HIGH);

#endif



#endif /* USE_USBHS1 */



    usbd_init (&hid_keyboard, &hid_desc, &usbd_hid_cb);



#ifdef USE_USB_HS

    #ifndef USE_ULPI_PHY

        #ifdef USE_USBHS0

            pllusb_rcu_config(USBHS0);

        #elif defined USE_USBHS1

            pllusb_rcu_config(USBHS1);

        #else

        #endif

    #endif /* !USE_ULPI_PHY */

#endif /* USE_USB_HS */



    usb_intr_config();



    /* check if USB device is enumerated successfully */

    while (USBD_CONFIGURED != hid_keyboard.dev.cur_status) {

    }



    while (1) {

        fop_handler.hid_itf_data_process(&hid_keyboard);

    }

}
rcu的配置如下，主要用于配置USB时钟，USB需要一个稳定的48M时钟，历程中根据相关宏定义开关进行选择配置。
复制
C

void usb_rcu_config(void)

{

    pmu_usb_regulator_enable();

    pmu_usb_voltage_detector_enable();

    while (pmu_flag_get(PMU_FLAG_USB33RF) != SET) {

    }



#ifdef USE_USB_FS



#ifndef USE_IRC48M



#ifdef USE_USBHS0

    rcu_usb48m_clock_config(IDX_USBHS0, RCU_USB48MSRC_PLL0R);

#endif /* USE_USBHS0 */



#ifdef USE_USBHS1

    rcu_usb48m_clock_config(IDX_USBHS1, RCU_USB48MSRC_PLL0R);

#endif /* USE_USBHS1 */



#else

    /* enable IRC48M clock */

    rcu_osci_on(RCU_IRC48M);



    /* wait till IRC48M is ready */

    while (SUCCESS != rcu_osci_stab_wait(RCU_IRC48M)) {

    }



#ifdef USE_USBHS0

    rcu_usb48m_clock_config(IDX_USBHS0, RCU_USB48MSRC_IRC48M);

#endif /* USE_USBHS0 */



#ifdef USE_USBHS1

    rcu_usb48m_clock_config(IDX_USBHS1, RCU_USB48MSRC_IRC48M);

#endif /* USE_USBHS1 */



#endif /* USE_IRC48M */



#endif /* USE_USB_FS */



#ifdef USE_USBHS0

    rcu_periph_clock_enable(RCU_USBHS0);

#endif /* USE_USBHS0 */



#ifdef USE_USBHS1

    rcu_periph_clock_enable(RCU_USBHS1);

#endif /* USE_USBHS1 */



#ifdef USE_ULPI_PHY

#ifdef USE_USBHS0

    rcu_periph_clock_enable(RCU_USBHS0ULPI);

#endif



#ifdef USE_USBHS1

    rcu_periph_clock_enable(RCU_USBHS1ULPI);

#endif

#endif /* USE_ULPI_PHY */

}
Usb timer的配置如下，主要用于延迟。
复制
C

void usb_timer_init (void)

{

    /* configure the priority group to 2 bits */

    nvic_priority_group_set(NVIC_PRIGROUP_PRE2_SUB2);



    /* enable the TIM2 global interrupt */

    nvic_irq_enable((uint8_t)TIMER2_IRQn, 1U, 0U);



    rcu_periph_clock_enable(RCU_TIMER2);

}
注册HID接口操作函数如下所示。在该代码清单中，注册了HID接口操作的配置以及数据处理函数句柄，用于后续函数调用。
复制
C

uint8_t hid_itfop_register(usb_dev *udev, hid_fop_handler *hid_fop)

{

    if(NULL != hid_fop) {

        udev->dev.user_data = (void *)hid_fop;



        return USBD_OK;

    }



    return USBD_FAIL;

}
USBD内核初始化函数如下所示。在该代码清单中，首先配置设备类callback函数，之后创建字符串，配置USB以及初始化USB内核，断开USB连接，初始化USB设备模式，之后设置USB连接，将USB连接状态配置为DEFAULT默认状态，启动状态机。
复制
C

void usbd_init(usb_core_driver *udev, usb_desc *desc, usb_class_core *class_core)

{

    udev->dev.desc = desc;



    /* class callbacks */

    udev->dev.class_core = class_core;



    /* create serial string */

    serial_string_get(udev->dev.desc->strings[STR_IDX_SERIAL]);



    /* configure USB capabilities */

    (void)usb_basic_init(&udev->bp, &udev->regs);



    /* initializes the USB core*/

    (void)usb_core_init(udev->bp, &udev->regs);



    /* set device disconnect */

    usbd_disconnect(udev);



    /* initializes device mode */

    (void)usb_devcore_init(udev);



    /* set device connect */

    usbd_connect(udev);



    udev->dev.cur_status = (uint8_t)USBD_DEFAULT;

}
配置USB中断函数如下。
复制
C

void usb_intr_config(void)

{

    nvic_priority_group_set(NVIC_PRIGROUP_PRE2_SUB2);



#ifdef USE_USBHS0

    nvic_irq_enable((uint8_t)USBHS0_IRQn, 3U, 0U);

#endif /* USE_USBHS0 */



#ifdef USE_USBHS1

    nvic_irq_enable((uint8_t)USBHS1_IRQn, 3U, 0U);

#endif /* USE_USBHS0 */



    /* enable the power module clock */

    rcu_periph_clock_enable(RCU_PMU);



#ifdef USE_USBHS0

    /* USB wakeup EXTI line configuration */

    exti_interrupt_flag_clear(EXTI_31);

    exti_init(EXTI_31, EXTI_INTERRUPT, EXTI_TRIG_RISING);

    exti_interrupt_enable(EXTI_31);



    nvic_irq_enable((uint8_t)USBHS0_WKUP_IRQn, 1U, 0U);

#endif /* USE_USBHS0 */



#ifdef USE_USBHS1

    /* USB wakeup EXTI line configuration */

    exti_interrupt_flag_clear(EXTI_32);

    exti_init(EXTI_32, EXTI_INTERRUPT, EXTI_TRIG_RISING);

    exti_interrupt_enable(EXTI_32);



    nvic_irq_enable((uint8_t)USBHS1_WKUP_IRQn, 1U, 0U);

#endif /* USE_USBHS1 */



#ifdef USB_DEDICATED_EP1_ENABLED



#ifdef USE_USBHS0

    nvic_irq_enable((uint8_t)USBHS0_EP1_OUT_IRQn, 1U, 0U);

    nvic_irq_enable((uint8_t)USBHS0_EP1_IN_IRQn, 1U, 0U);

#endif /* USE_USBHS0 */



#ifdef USE_USBHS1

    nvic_irq_enable((uint8_t)USBHS1_EP1_OUT_IRQn, 1U, 0U);

    nvic_irq_enable((uint8_t)USBHS1_EP1_IN_IRQn, 1U, 0U);

#endif /* USE_USBHS1 */



#endif /* USB_DEDICATED_EP1_ENABLED */

}
内部上拉电阻被上拉后，主机将会对设备进行枚举，设备端采用while (USBD_CONFIGURED != hid_keyboard.dev.cur_status) 语句进行等待。当USB设备状态变为USBD_CONFIGURED状态时，表明设备枚举完成。
枚举完成之后，程序将进入主循环中，在主循环中，循环调用HID USB模拟键盘数据处理函数，在该函数中，首先判断上次传输是否完成，完成之后通过扫描按键的方式查看按键是否被按下，若按键被按下，则通过hid_report_send()函数发送键盘报告数据。
复制
C

static void hid_key_data_send(usb_dev *udev)

{

    standard_hid_handler *hid = (standard_hid_handler *)udev->dev.class_data[USBD_HID_INTERFACE];



    if (hid->prev_transfer_complete) {

        switch (key_state()) {

        case CHAR_A:

            printf_log("Press A on the keyboard\r\n");

            bsp_led_toggle(&LED1);

            hid->data[2] = 0x04U;

            break;

        case CHAR_B:

            printf_log("Press B on the keyboard\r\n"); 

            bsp_led_toggle(&LED2);

            hid->data[2] = 0x05U;

            break;

        default:

            break;

        }



        if (0U != hid->data[2]) {

            hid_report_send(udev, hid->data, HID_IN_PACKET);

        }

    }

}
报文发送函数定义如下，该函数包含三个参数，udev为初始化后的设备操作结构体；report为发送报告缓冲区地址；len为发送报告的长度。在该函数中，如果设备已经被枚举成功，则首先将prev_transfer_complete标志位设置为0，表明接下来将进行发送数据，数据并未发送完成，之后，调用usbd_ep_send()将需要发送的报告拷贝到USB外设缓冲区中并设置端点为有效状态，等待主机发送IN令牌包，USB设备将外设缓冲区中的数据发送给主机。
复制
C

uint8_t hid_report_send(usb_dev *udev, uint8_t *report, uint32_t len)

{

    standard_hid_handler *hid = (standard_hid_handler *)udev->dev.class_data[USBD_HID_INTERFACE];



    hid->prev_transfer_complete = 0U;



    usbd_ep_send(udev, HID_IN_EP, report, len);



    return USBD_OK;

}
当数据发送完成，USB设备将调用hid_data_in()函数进行数据处理。该函数程序如下所示。在该函数中，首先判断hid->data[2]的数据是否为0x00，如果不为0x00表明上次发送的为按键按下的键值，还需发送按键松开的键值，如果为0x00表明上次按键按下和松开的键值均已发送完成，之后将prev_transfer_complete设置为1，表明上一次的按键数据传输完成，可进行下次按键数据传输。
复制
C

static uint8_t hid_data_in(usb_dev *udev, uint8_t ep_num)

{

    standard_hid_handler *hid = (standard_hid_handler *)udev->dev.class_data[USBD_HID_INTERFACE];



    if(0U != hid->data[2]) {

        hid->data[2] = 0x00U;



        usbd_ep_send(udev, HID_IN_EP, hid->data, HID_IN_PACKET);

    } else {

        hid->prev_transfer_complete = 1U;

    }



    return USBD_OK;

}
在该例程中通过hid->prev_transfer_complete数据流程标志位进行数据发送控制，读者可使用该标志位用于对数据发送的控制，当该标志位为0的时候，表明数据已被填送到USB缓冲区，但还没有发送给主机，此时MCU不能继续调用发送函数向缓冲区中填数据，否则可能导致数据覆盖丢失，正确做法是等待该标志位置位，表明上一包数据已被主机读取，然后再继续发送后续数据。
13.5 实验结果
将本例程烧录到海棠派开发板中，通过Type C数据线连接开发板和PC，之后分别按下WKUP和USER按键，将会向PC发送A、B键值。

本教程由GD32 MCU方案商聚沃科技原创发布，了解更多GD32 MCU教程，关注聚沃科技官网，GD32MCU技术交流群：859440462

使用特权

评论回复 赏
沙发
硕r| | 2024-7-31 17:04 | 只看该作者

使用特权

评论回复 赏
板凳
小小蚂蚁举千斤| | 2024-7-31 21:22 | 只看该作者
USB程序非常不错的案例分析

使用特权

评论回复 赏
返回列表
发新帖 我要提问
高级模式
B Color Image Link Quote Code 收费 Smilies
您需要登录后才可以回帖 登录 | 注册

本版积分规则

聚沃科技

170

主题

190

帖子

10

粉丝