【GD32F303红枫派开发板使用手册】第二十七讲 USB-虚拟键盘实验

27.1实验内容

通过本实验主要学习以下内容：

• USB协议基本原理
• GD32F303 USBD的使用
• 虚拟键盘的协议原理及使用

27.2实验原理

27.2.1USB通信基础知识

USB的全称是Universal Serial Bus,通用串行总线。它的出现主要是为了简化个人计算机与外围设备的连接，增加易用性。USB支持热插拔，并且是即插即用的，另外，它还具有很强的可扩展性，传输速度也很快，这些特性使支持USB接口的电子设备更易用、更大众化。GD32F303系列MCU集成了USB2.0全速设备USBD模块，可以满足作为USB设备与主机通信的需求。首先为大家介绍USB通信的一些基础知识，包括USB协议、枚举流程等，建议读者可以多多阅读USB协议，以更深入了解USB，USB官网链接如下，可参考：https://www.usb.org/

27.2.1.1USB金字塔型拓扑结构

塔顶为USB主控制器和根集线器(Root Hub)，下面接USB集线器(Hub)，集线器将一个USB口扩展为多个USB口，USB2.0规定集线器的层数最多为6层，理论上一个USB主控制器最多可接127个设备，因为协议规定USB设备具有一个7 bit的地址(取值范围为0~127，而地址0是保留给未初始化的设备使用的)。

27.2.1.2NRZI编码

USB采用差分信号传输，使用的是如上图所示的NRZI编码方式：数据为0时，电平翻转；数据为1时，电平不翻转。如果出现6个连续的数据1，则插入一个数据0，强制电平翻转，以便时钟同步。上面的一条线表示的是原始数据序列，下面的一条线表示的是经过NRZI编码后的数据序列。

27.2.1.3USB数据协议

USB数据是由二进制数据串组成，首先由数据串构成包(packet)，包再构成事务(transaction)，事务最终构成传输(transfer)。

USB传输的最小单位为包，一个包被分成不同的域，根据不同类型的包，所包含的域是不一样的，但是不同的包有个共同的特点，就是以包起始(SOP)开始，之后是同步域(0x00000001)，然后是包内容，最后以包结束符(EOP)结束这个包。PID为标识域，由四位标识符加4位标识符反码构成，表明包的类型和格式。根据PID的不同，USB协议中规定的包类型有令牌包、数据包、握手包和特殊包等。

USB事务通常有两个或三个包组成：令牌包、数据包和握手包，令牌包用来启动一个事务，总是由主机发送；数据包用来传输数据；握手包由数据接收者进行发送，表明数据的接收情况。批量、同步和中断传输每次传输都是一个事务，控制传输包括三个阶段：建立过程、数据过程和状态过程。

针对不同的数据传输场景，USB分为四种数据传输模式，这四种传输模式分别由不同的包(packet)组成，并且有不同的数据处理策略。每种数据传输模式的流程示意图以及应用场景如下：

• 控制传输一般用于命令和状态的传输，分为控制读、控制写和无数据控制传输。在设备枚举的过程中，采用控制传输方式进行数据传输。

• 批量传输分为批量读和批量写，用于数据量大、对实时性要求不高的场合，如U盘。

• 中断传输用于数据量小的场合，保证查询频率，如鼠标、键盘。

• 同步传输用于数据量大、同时对实时性要求较高的场合，如音视频。不保证数据完整性，没有ACK/NAK应答包，不进行数据重传。

27.2.1.4USB描述符

• 一个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 attribute */ 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;

27.2.1.5USB枚举过程

USB枚举实际上是host检测到device插入后，通过发送各种标准请求，请device返回各种USB描述符的过程。USB枚举的示意图如下：

27.2.2GD32 USBD模块简介

GD32F303系列MCU提供了一个USB2.0全速USBD接口模块，它内部包含了一个USB物理层而不需要额外的外部物理层芯片。USBD支持USB 2.0协议所定义的四种传输类型（控制、批量、中断和同步传输）。

主要特性如下：

◼ USB 2.0全速设备控制器；
◼最多支持8个可配置的端点；
◼支持双缓冲的批量传输端点/同步传输端点；
◼支持USB 2.0链接电源管理；
◼每个端点都支持控制，批量，同步或中断传输（端点0除外，端点0只支持控制传输） ；
◼支持USB挂起/恢复操作；
◼与CAN共享512字节的专用SRAM用于数据缓冲；
◼集成的USB物理层。

USBD模块框图如下所示。

27.2.3USBD固件库说明

USBD固件库框图如下所示。用户应用程序(User application)调用GD32全速USB设备固件库中的接口实现USB设备与主机之间的通信，架构的最底层为GD32 MCU开发板的硬件。其中，GD32全速USB设备固件库(GD32F30x_usbd_Library)分为两层，顶层为应用接口层，用户可以修改，包含main.c和USB相关设备类驱动；底层为USBD设备驱动层，不建议用户修改，该驱动层包含实现USB通信相关协议以及USBD底层模块操作。

USBD_Drivers设备驱动层(Firmware\GD32F30x_usbd_library\usbd)包含两个文件夹，分别为Include和Source，其中，Include为底层头文件，Source为底层源文件。

其中，usbd_lld_core.h/c文件中的库函数说明如下所示。

usbd_lld_int.h/.c文件中的库函数说明如下所示。

USBD_Device设备驱动层(Firmware\GD32F30x_usbd_library\device)包含两个文件夹，分别为Include和Source，其中，Include为底层头文件，Source为底层源文件。

其中，usbd_core.h/.c文件中的库函数说明如下所示。

usbd_enum.h/.c文件中的库函数说明如下所示。

usbd_pwr.h/.c文件中的库函数说明如下所示。

usbd_transc.h/.c文件中的库函数说明如下所示。

27.3硬件设计

GD32F303红枫派开发板的USB通信接口选择的是目前较为通用的Type C接口，读者手中的用于手机充电的Type C通信线即可使用。

USB的DP和DM线上使用22欧姆串阻，DP线通过1.5K电阻上拉到USBFS_CTL控制引脚，该引脚使用的是PD3引脚。

27.4代码解析

本例程主要实现通过按键向PC发送键值的现象，实现模拟键盘的效果。

本例程主函数如下所示，首先配置延迟初始化，历程中使用到了ms延迟，之后配置rcu、gpio、usbd、NVIC等相关外设，具体说明将在后续介绍。

C int main(void) { delay_init(); /* system clocks configuration */ rcu_config(); /* GPIO configuration */ gpio_config(); hid_itfop_register (&usb_hid, &fop_handler); /* USB device configuration */ usbd_init(&usb_hid, &hid_desc, &hid_class); /* NVIC configuration */ nvic_config(); usbd_connect(&usb_hid); while(USBD_CONFIGURED != usb_hid.cur_status){ } while (1) { fop_handler.hid_itf_data_process(&usb_hid); } }

rcu的配置如下，主要用于配置USB时钟，USB需要一个稳定的48M时钟，一般可通过系统时钟分频获取，由于有固定的分频系数，所以系统时钟一般选择48M、72M、96M或120M，历程中做了自动分频适配。另外如果使用IRC48Mhz时钟作为USB时钟，系统时钟大于24MHz即可。

C void rcu_config(void) { uint32_t system_clock = rcu_clock_freq_get(CK_SYS); /* enable USB pull-up pin clock */ rcu_periph_clock_enable(RCU_AHBPeriph_GPIO_PULLUP); if (48000000U == system_clock) { rcu_usb_clock_config(RCU_CKUSB_CKPLL_DIV1); } else if (72000000U == system_clock) { rcu_usb_clock_config(RCU_CKUSB_CKPLL_DIV1_5); } else if (96000000U == system_clock) { rcu_usb_clock_config(RCU_CKUSB_CKPLL_DIV2); } else if (120000000U == system_clock) { rcu_usb_clock_config(RCU_CKUSB_CKPLL_DIV2_5); } else { /* reserved */ } /* enable USB APB1 clock */ rcu_periph_clock_enable(RCU_USBD); }

gpio配置主要用于配置DP线的上拉电阻，dp线上拉主要用于控制USB设备接入主机的时机。本例程中使用PD3的引脚。

若读者的硬件使用其他的引脚作为dp线的上拉控制，修改上拉引脚的宏定义配置即可。

C void gpio_config(void) { /* configure usb pull-up pin */ gpio_init(USB_PULLUP, GPIO_MODE_OUT_PP, GPIO_OSPEED_50MHZ, USB_PULLUP_PIN); /* USB wakeup EXTI line configuration */ exti_interrupt_flag_clear(EXTI_18); exti_init(EXTI_18, EXTI_INTERRUPT, EXTI_TRIG_RISING); } #define USB_PULLUP GPIOD #define USB_PULLUP_PIN GPIO_PIN_3 #define RCU_AHBPeriph_GPIO_PULLUP RCU_GPIOD

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

C uint8_t hid_itfop_register (usb_dev *udev, hid_fop_handler *hid_fop) { if (NULL != hid_fop) { udev->user_data = (void *)hid_fop; return USBD_OK; } return USBD_FAIL; }

USBD内核初始化函数如下所示。在该代码清单中，首先配置USB内核基本属性参数，然后初始化USBD描述符、设备类内核以及设备类处理函数指针，之后初始化端点事务函数数组，配置电源管理以及USB挂起状态使能，最后调用设备类内核初始化函数完成USBD内核初始化。

C void usbd_init (usb_dev *udev, usb_desc *desc, usb_class *usbc) { /* configure USBD core basic attributes */ usbd_core.basic.max_ep_count = 8U; usbd_core.basic.twin_buf = 1U; usbd_core.basic.ram_size = 512U; usbd_core.dev = udev; udev->desc = desc; udev->class_core = usbc; udev->drv_handler = &usbd_drv_handler; udev->ep_transc[0][TRANSC_SETUP] = _usb_setup_transc; udev->ep_transc[0][TRANSC_OUT] = _usb_out0_transc; udev->ep_transc[0][TRANSC_IN] = _usb_in0_transc; /* configure power management */ udev->pm.power_mode = (udev->desc->config_desc[7] & 0x40U) >> 5; /* enable USB suspend */ udev->pm.suspend_enabled = 1U; /* USB low level initialization */ udev->drv_handler->init(); /* create serial string */ serial_string_get((uint16_t *)udev->desc->strings[STR_IDX_SERIAL]); }

NVIC配置函数如下所示。在该代码清单中首先对NVIC分组进行配置，其中1位用于抢占优先级，3位用于次优先级。之后使能USBD低优先级中断和唤醒中断。

C void nvic_config(void) { /* 2 bits for preemption priority, 2 bits for subpriority */ nvic_priority_group_set(NVIC_PRIGROUP_PRE1_SUB3); /* enable the USB low priority interrupt */ nvic_irq_enable((uint8_t)USBD_LP_CAN0_RX0_IRQn, 1U, 0U); /* enable the USB Wake-up interrupt */ nvic_irq_enable((uint8_t)USBD_WKUP_IRQn, 0U, 0U); }

然后调用usbd_connect(&usb_hid);函数将上拉引脚电平进行上拉，并将USB设备状态udev->cur_status设置为连接状态USBD_CONNECTED。

C __STATIC_INLINE void usbd_connect (usb_dev *udev) { udev->drv_handler->dp_pullup(SET); udev->cur_status = (uint8_t)USBD_CONNECTED; }

上拉电阻被上拉后，主机将会对设备进行枚举，设备端采用while(USBD_CONFIGURED != usb_hid.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->class_data[USBD_HID_INTERFACE]; if (hid->prev_transfer_complete) { switch (key_state()) { case CHAR_A: hid->data[2] = 0x04U; break; case CHAR_B: hid->data[2] = 0x05U; break; case CHAR_C: hid->data[2] = 0x06U; 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, uint16_t len) { standard_hid_handler *hid = (standard_hid_handler *)udev->class_data[USBD_HID_INTERFACE]; /* check if USB is configured */ hid->prev_transfer_complete = 0U; usbd_ep_send(udev, HID_IN_EP, report, len); return USBD_OK; }

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

C static void hid_data_in_handler (usb_dev *udev, uint8_t ep_num) { standard_hid_handler *hid = (standard_hid_handler *)udev->class_data[USBD_HID_INTERFACE]; if (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; } }

在该例程中通过hid->prev_transfer_complete数据流程标志位进行数据发送控制，读者可使用该标志位用于对数据发送的控制，当该标志位为0的时候，表明数据已被填送到USB缓冲区，但还没有发送给主机，此时MCU不能继续调用发送函数向缓冲区中填数据，否则可能导致数据覆盖丢失，正确做法是等待该标志位置位，表明上一包数据已被主机读取，然后再继续发送后续数据。

27.5实验结果

将本例程烧录到红枫派开发板中，通过Type C数据线连接开发板和PC，之后按下ROCKER_KEY、K1、K2按键，将会向PC发送A、B、C键值。

本教程由GD32 MCU方案商聚沃科技原创发布，了解更多GD32 MCU教程，关注聚沃科技官网