STM32F103C8T6 uses a USB interface as an HID Keyboard.
Author: Asterism Date: 2026.2.14
Introduction
我有一个STM32F103C8T6开发板，我想通过MicroUSB线连接到电脑，让开发板输出键盘信号给电脑。当我在芯片中配置了固定的程序，那么每次接入电脑，就可以自动输入固定的内容。
USB Full-Speed USB Full-Speed (FS) 是 USB 规范中定义的一种传输速率，提供最高 12 Mbps 的数据传输速率。它主要用于连接低带宽外部设备，如鼠标、键盘、打印机和摄像头等。USB FS 是 USB 1.0 和 USB 1.1 版本中的一种传输模式，确保设备和主机之间的正确通信。
用STM32CubeMX创建的USB HID项目默认是为鼠标模式，需要修改部分代码来适配键盘模式
当STM32F103C8T6选择USB HID模式时，默认模拟USB信号输出的是PA11和PA12
准备工作
硬件
- STM32F103C8T6开发板
- MicroUSB数据线
- ST-LINK下载器
软件
- STM32CubeIDE
- STM32CubeMX
创建项目
打开STM32CubeMX，选择ACCESS TO MCU SELECTOR 
等待下载列表
下载完成后，根据筛选条件，选到STM32F103C8T6，双击
选择正确的时钟类型，High Speed Clock (HSE)–>Crystal/Ceramic Resonator
选择调试设备，Debug–>Serial Wire
在左侧栏中选择Connectivity–>USB，勾选Device(FS)
在左侧栏中选择Middleware and Software Packs–>USB_DEVICE
选择Class For FS IP–>Human Interface Device Class (HID)
可以选择修改一下PRODUCT_STRING
选择上方Clock Configuration，可以先点击yes，让它自动设置，然后再进行修改，最终数值如图
选择上方Project Manager，填写Project Name 选择Toolchain/IDE为STM32CubeIDE 在左侧栏中选择Code Generator，勾选Generate peripheral initialization as a pair of’.c/.h’ files per peripheral选项
点击上方GENERATE CODE，等待一会儿，然后选择open project，workspace随便，项目就创建好了！
修改代码
要修改的部分为3个文件：
- /Middlewares/ST/STM32_USB_Device_Library/Class/HID/Inc/usbd_hid.h
- /Middlewares/ST/STM32_USB_Device_Library/Class/HID/Src/usbd_hid.c
- /Core/Src/main.c
- keyboard_usage_table.h
/Middlewares/…/Inc/usbd_hid.h
在#define HID_MOUSE_REPORT_DESC_SIZE 74U后一行添加如下代码
#define HID_KEYBOARD_REPORT_DESC_SIZE 49U//定义键盘报告报文大小
/Middlewares/…/Src/usbd_hid.c
在函数USBD_HID_CfgFSDesc中，按照要求修改0x02, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/为
0x01, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/
在函数USBD_HID_CfgHSDesc中，按照要求修改0x02, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/为
0x01, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/
在函数USBD_HID_OtherSpeedCfgDesc中，按照要求修改0x02, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/为
0x01, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/
在函数USBD_HID_Desc中，替换HID_MOUSE_REPORT_DESC_SIZE为HID_KEYBOARD_REPORT_DESC_SIZE
在函数HID_MOUSE_ReportDesc的定义后添加如下代码
// 标准USB键盘HID报告描述符（47字节）
__ALIGN_BEGIN static uint8_t HID_Keyboard_ReportDesc[HID_KEYBOARD_REPORT_DESC_SIZE] __ALIGN_END = {
0x05, 0x01, // Usage Page (Generic Desktop)
0x09, 0x06, // Usage (Keyboard)
0xA1, 0x01, // Collection (Application)
// 修饰键（8个位，每个表示一个修饰键）
0x05, 0x07, // Usage Page (Key Codes)
0x19, 0xE0, // Usage Minimum (224 = 左Ctrl)
0x29, 0xE7, // Usage Maximum (231 = 右GUI)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x01, // Logical Maximum (1)
0x75, 0x01, // Report Size (1)
0x95, 0x08, // Report Count (8)
0x81, 0x02, // Input (Data,Var,Abs)
// 保留字节
0x95, 0x01, // Report Count (1)
0x75, 0x08, // Report Size (8)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x00, // Logical Maximum (0) // 重要：必须为0
0x81, 0x03, // Input (Cnst,Var,Abs) // 常量
// 6个键码（最多同时按6个键）
0x95, 0x06, // Report Count (6)
0x75, 0x08, // Report Size (8)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x65, // Logical Maximum (101)
0x05, 0x07, // Usage Page (Key Codes)
0x19, 0x00, // Usage Minimum (0)
0x29, 0x65, // Usage Maximum (101)
0x81, 0x00, // Input (Data,Arr,Abs)
0xC0 // End Collection
};
修改以下代码
case USB_REQ_GET_DESCRIPTOR:
if (req->wValue >> 8 == HID_REPORT_DESC)
{
len = MIN(HID_MOUSE_REPORT_DESC_SIZE, req->wLength);
pbuf = HID_MOUSE_ReportDesc;
}
为
case USB_REQ_GET_DESCRIPTOR:
if (req->wValue >> 8 == HID_REPORT_DESC)
{
len = MIN(HID_KEYBOARD_REPORT_DESC_SIZE, req->wLength);
pbuf = HID_Keyboard_ReportDesc;
}
/Core/Src/main.c
添加头文件
#include "usbd_hid.h"
在以下代码块中
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
/* USER CODE END Includes */
添加
#include "usbd_core.h"
#include "string.h"
#include "keyboard_usage_table.h"
在以下代码块中
/* Private user code ---------------------------------------------------------*/
/* USER CODE BEGIN 0 */
/* USER CODE END 0 */
中添加
extern USBD_HandleTypeDef hUsbDeviceFS;
// 字节0: 修饰键
// 字节1: 保留（必须为0）
// 字节2-7: 6个键码
uint8_t key_report[8] = {0, 0, 0, 0, 0, 0, 0, 0};
/*在keyboard_usage_table.h中定义
// USB键盘扫描码表
#define KEY_A 0x04
#define KEY_B 0x05
#define KEY_1 0x1E
#define KEY_ENTER 0x28
#define KEY_SPACE 0x2C
#define KEY_SHIFT 0x02 // 左Shift修饰键
*/
// 修正后的按键发送函数
void USB_Keyboard_Send_Key(uint8_t mod, uint8_t key)
{
// 发送按键按下
key_report[0] = mod; // 修饰键（Shift/Ctrl/Alt等）
key_report[1] = 0; // 保留字节，必须为0
key_report[2] = key; // 第一个键码
// key_report[3-7] 保持为0（其他键码）
uint8_t send_state;
send_state = USBD_HID_SendReport(&hUsbDeviceFS, key_report, 8);
//if(send_state == USBD_OK) HAL_Delay(10); // 稍微缩短延时
// 发送按键释放（全0报告）
memset(key_report, 0, 8);
USBD_HID_SendReport(&hUsbDeviceFS, key_report, 8);
//HAL_Delay(10); // 稍微缩短延时
}
keyboard_usage_table.h
宏定义键位的二进制值 放在最后的代码文件中
主函数
在main函数的while(1)中使用以下代码来发送A键
USB_Keyboard_Send_Key(0, KEY_A);
代码文件
/Middlewares/…/Inc/usbd_hid.h
/**
******************************************************************************
* @file usbd_hid.h
* @author MCD Application Team
* @brief Header file for the usbd_hid_core.c file.
******************************************************************************
* @attention
*
* <h2><center>© Copyright (c) 2015 STMicroelectronics.
* All rights reserved.</center></h2>
*
* This software component is licensed by ST under Ultimate Liberty license
* SLA0044, the "License"; You may not use this file except in compliance with
* the License. You may obtain a copy of the License at:
* www.st.com/SLA0044
*
******************************************************************************
*/
/* Define to prevent recursive inclusion -------------------------------------*/
#ifndef __USB_HID_H
#define __USB_HID_H
#ifdef __cplusplus
extern "C" {
#endif
/* Includes ------------------------------------------------------------------*/
#include "usbd_ioreq.h"
/** @addtogroup STM32_USB_DEVICE_LIBRARY
* @{
*/
/** @defgroup USBD_HID
* @brief This file is the Header file for usbd_hid.c
* @{
*/
/** @defgroup USBD_HID_Exported_Defines
* @{
*/
#define HID_EPIN_ADDR 0x81U
#define HID_EPIN_SIZE 0x08U
#define USB_HID_CONFIG_DESC_SIZ 34U
#define USB_HID_DESC_SIZ 9U
#define HID_MOUSE_REPORT_DESC_SIZE 74U
#define HID_KEYBOARD_REPORT_DESC_SIZE 49U
#define HID_DESCRIPTOR_TYPE 0x21U
#define HID_REPORT_DESC 0x22U
#ifndef HID_HS_BINTERVAL
#define HID_HS_BINTERVAL 0x07U
#endif /* HID_HS_BINTERVAL */
#ifndef HID_FS_BINTERVAL
#define HID_FS_BINTERVAL 0x0AU
#endif /* HID_FS_BINTERVAL */
#define HID_REQ_SET_PROTOCOL 0x0BU
#define HID_REQ_GET_PROTOCOL 0x03U
#define HID_REQ_SET_IDLE 0x0AU
#define HID_REQ_GET_IDLE 0x02U
#define HID_REQ_SET_REPORT 0x09U
#define HID_REQ_GET_REPORT 0x01U
/**
* @}
*/
/** @defgroup USBD_CORE_Exported_TypesDefinitions
* @{
*/
typedef enum
{
HID_IDLE = 0,
HID_BUSY,
}
HID_StateTypeDef;
typedef struct
{
uint8_t Protocol;
uint8_t IdleState;
uint8_t AltSetting;
HID_StateTypeDef state;
}
USBD_HID_HandleTypeDef;
/**
* @}
*/
/** @defgroup USBD_CORE_Exported_Macros
* @{
*/
/**
* @}
*/
/** @defgroup USBD_CORE_Exported_Variables
* @{
*/
extern USBD_ClassTypeDef USBD_HID;
#define USBD_HID_CLASS &USBD_HID
/**
* @}
*/
/** @defgroup USB_CORE_Exported_Functions
* @{
*/
uint8_t USBD_HID_SendReport(USBD_HandleTypeDef *pdev,
uint8_t *report,
uint16_t len);
uint32_t USBD_HID_GetPollingInterval(USBD_HandleTypeDef *pdev);
/**
* @}
*/
#ifdef __cplusplus
}
#endif
#endif /* __USB_HID_H */
/**
* @}
*/
/**
* @}
*/
/************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/
/Middlewares/…/Src/usbd_hid.c
/**
******************************************************************************
* @file usbd_hid.c
* @author MCD Application Team
* @brief This file provides the HID core functions.
*
* @verbatim
*
* ===================================================================
* HID Class Description
* ===================================================================
* This module manages the HID class V1.11 following the "Device Class Definition
* for Human Interface Devices (HID) Version 1.11 Jun 27, 2001".
* This driver implements the following aspects of the specification:
* - The Boot Interface Subclass
* - The Mouse protocol
* - Usage Page : Generic Desktop
* - Usage : Joystick
* - Collection : Application
*
* @note In HS mode and when the DMA is used, all variables and data structures
* dealing with the DMA during the transaction process should be 32-bit aligned.
*
*
* @endverbatim
*
******************************************************************************
* @attention
*
* <h2><center>© Copyright (c) 2015 STMicroelectronics.
* All rights reserved.</center></h2>
*
* This software component is licensed by ST under Ultimate Liberty license
* SLA0044, the "License"; You may not use this file except in compliance with
* the License. You may obtain a copy of the License at:
* www.st.com/SLA0044
*
******************************************************************************
*/
/* BSPDependencies
- "stm32xxxxx_{eval}{discovery}{nucleo_144}.c"
- "stm32xxxxx_{eval}{discovery}_io.c"
EndBSPDependencies */
/* Includes ------------------------------------------------------------------*/
#include "usbd_hid.h"
#include "usbd_ctlreq.h"
/** @addtogroup STM32_USB_DEVICE_LIBRARY
* @{
*/
/** @defgroup USBD_HID
* @brief usbd core module
* @{
*/
/** @defgroup USBD_HID_Private_TypesDefinitions
* @{
*/
/**
* @}
*/
/** @defgroup USBD_HID_Private_Defines
* @{
*/
/**
* @}
*/
/** @defgroup USBD_HID_Private_Macros
* @{
*/
/**
* @}
*/
/** @defgroup USBD_HID_Private_FunctionPrototypes
* @{
*/
static uint8_t USBD_HID_Init(USBD_HandleTypeDef *pdev,
uint8_t cfgidx);
static uint8_t USBD_HID_DeInit(USBD_HandleTypeDef *pdev,
uint8_t cfgidx);
static uint8_t USBD_HID_Setup(USBD_HandleTypeDef *pdev,
USBD_SetupReqTypedef *req);
static uint8_t *USBD_HID_GetFSCfgDesc(uint16_t *length);
static uint8_t *USBD_HID_GetHSCfgDesc(uint16_t *length);
static uint8_t *USBD_HID_GetOtherSpeedCfgDesc(uint16_t *length);
static uint8_t *USBD_HID_GetDeviceQualifierDesc(uint16_t *length);
static uint8_t USBD_HID_DataIn(USBD_HandleTypeDef *pdev, uint8_t epnum);
/**
* @}
*/
/** @defgroup USBD_HID_Private_Variables
* @{
*/
USBD_ClassTypeDef USBD_HID =
{
USBD_HID_Init,
USBD_HID_DeInit,
USBD_HID_Setup,
NULL, /*EP0_TxSent*/
NULL, /*EP0_RxReady*/
USBD_HID_DataIn, /*DataIn*/
NULL, /*DataOut*/
NULL, /*SOF */
NULL,
NULL,
USBD_HID_GetHSCfgDesc,
USBD_HID_GetFSCfgDesc,
USBD_HID_GetOtherSpeedCfgDesc,
USBD_HID_GetDeviceQualifierDesc,
};
/* USB HID device FS Configuration Descriptor */
__ALIGN_BEGIN static uint8_t USBD_HID_CfgFSDesc[USB_HID_CONFIG_DESC_SIZ] __ALIGN_END =
{
0x09, /* bLength: Configuration Descriptor size */
USB_DESC_TYPE_CONFIGURATION, /* bDescriptorType: Configuration */
USB_HID_CONFIG_DESC_SIZ,
/* wTotalLength: Bytes returned */
0x00,
0x01, /*bNumInterfaces: 1 interface*/
0x01, /*bConfigurationValue: Configuration value*/
0x00, /*iConfiguration: Index of string descriptor describing
the configuration*/
0xE0, /*bmAttributes: bus powered and Support Remote Wake-up */
0x32, /*MaxPower 100 mA: this current is used for detecting Vbus*/
/************** Descriptor of Joystick Mouse interface ****************/
/* 09 */
0x09, /*bLength: Interface Descriptor size*/
USB_DESC_TYPE_INTERFACE,/*bDescriptorType: Interface descriptor type*/
0x00, /*bInterfaceNumber: Number of Interface*/
0x00, /*bAlternateSetting: Alternate setting*/
0x01, /*bNumEndpoints*/
0x03, /*bInterfaceClass: HID*/
0x01, /*bInterfaceSubClass : 1=BOOT, 0=no boot*/
0x01, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/
0, /*iInterface: Index of string descriptor*/
/******************** Descriptor of Joystick Mouse HID ********************/
/* 18 */
0x09, /*bLength: HID Descriptor size*/
HID_DESCRIPTOR_TYPE, /*bDescriptorType: HID*/
0x11, /*bcdHID: HID Class Spec release number*/
0x01,
0x00, /*bCountryCode: Hardware target country*/
0x01, /*bNumDescriptors: Number of HID class descriptors to follow*/
0x22, /*bDescriptorType*/
HID_KEYBOARD_REPORT_DESC_SIZE,/*wItemLength: Total length of Report descriptor*/
0x00,
/******************** Descriptor of Mouse endpoint ********************/
/* 27 */
0x07, /*bLength: Endpoint Descriptor size*/
USB_DESC_TYPE_ENDPOINT, /*bDescriptorType:*/
HID_EPIN_ADDR, /*bEndpointAddress: Endpoint Address (IN)*/
0x03, /*bmAttributes: Interrupt endpoint*/
HID_EPIN_SIZE, /*wMaxPacketSize: 4 Byte max */
0x00,
HID_FS_BINTERVAL, /*bInterval: Polling Interval */
/* 34 */
};
/* USB HID device HS Configuration Descriptor */
__ALIGN_BEGIN static uint8_t USBD_HID_CfgHSDesc[USB_HID_CONFIG_DESC_SIZ] __ALIGN_END =
{
0x09, /* bLength: Configuration Descriptor size */
USB_DESC_TYPE_CONFIGURATION, /* bDescriptorType: Configuration */
USB_HID_CONFIG_DESC_SIZ,
/* wTotalLength: Bytes returned */
0x00,
0x01, /*bNumInterfaces: 1 interface*/
0x01, /*bConfigurationValue: Configuration value*/
0x00, /*iConfiguration: Index of string descriptor describing
the configuration*/
0xE0, /*bmAttributes: bus powered and Support Remote Wake-up */
0x32, /*MaxPower 100 mA: this current is used for detecting Vbus*/
/************** Descriptor of Joystick Mouse interface ****************/
/* 09 */
0x09, /*bLength: Interface Descriptor size*/
USB_DESC_TYPE_INTERFACE,/*bDescriptorType: Interface descriptor type*/
0x00, /*bInterfaceNumber: Number of Interface*/
0x00, /*bAlternateSetting: Alternate setting*/
0x01, /*bNumEndpoints*/
0x03, /*bInterfaceClass: HID*/
0x01, /*bInterfaceSubClass : 1=BOOT, 0=no boot*/
0x01, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/
0, /*iInterface: Index of string descriptor*/
/******************** Descriptor of Joystick Mouse HID ********************/
/* 18 */
0x09, /*bLength: HID Descriptor size*/
HID_DESCRIPTOR_TYPE, /*bDescriptorType: HID*/
0x11, /*bcdHID: HID Class Spec release number*/
0x01,
0x00, /*bCountryCode: Hardware target country*/
0x01, /*bNumDescriptors: Number of HID class descriptors to follow*/
0x22, /*bDescriptorType*/
HID_KEYBOARD_REPORT_DESC_SIZE,/*wItemLength: Total length of Report descriptor*/
0x00,
/******************** Descriptor of Mouse endpoint ********************/
/* 27 */
0x07, /*bLength: Endpoint Descriptor size*/
USB_DESC_TYPE_ENDPOINT, /*bDescriptorType:*/
HID_EPIN_ADDR, /*bEndpointAddress: Endpoint Address (IN)*/
0x03, /*bmAttributes: Interrupt endpoint*/
HID_EPIN_SIZE, /*wMaxPacketSize: 4 Byte max */
0x00,
HID_HS_BINTERVAL, /*bInterval: Polling Interval */
/* 34 */
};
/* USB HID device Other Speed Configuration Descriptor */
__ALIGN_BEGIN static uint8_t USBD_HID_OtherSpeedCfgDesc[USB_HID_CONFIG_DESC_SIZ] __ALIGN_END =
{
0x09, /* bLength: Configuration Descriptor size */
USB_DESC_TYPE_CONFIGURATION, /* bDescriptorType: Configuration */
USB_HID_CONFIG_DESC_SIZ,
/* wTotalLength: Bytes returned */
0x00,
0x01, /*bNumInterfaces: 1 interface*/
0x01, /*bConfigurationValue: Configuration value*/
0x00, /*iConfiguration: Index of string descriptor describing
the configuration*/
0xE0, /*bmAttributes: bus powered and Support Remote Wake-up */
0x32, /*MaxPower 100 mA: this current is used for detecting Vbus*/
/************** Descriptor of Joystick Mouse interface ****************/
/* 09 */
0x09, /*bLength: Interface Descriptor size*/
USB_DESC_TYPE_INTERFACE,/*bDescriptorType: Interface descriptor type*/
0x00, /*bInterfaceNumber: Number of Interface*/
0x00, /*bAlternateSetting: Alternate setting*/
0x01, /*bNumEndpoints*/
0x03, /*bInterfaceClass: HID*/
0x01, /*bInterfaceSubClass : 1=BOOT, 0=no boot*/
0x01, /*nInterfaceProtocol : 0=none, 1=keyboard, 2=mouse*/
0, /*iInterface: Index of string descriptor*/
/******************** Descriptor of Joystick Mouse HID ********************/
/* 18 */
0x09, /*bLength: HID Descriptor size*/
HID_DESCRIPTOR_TYPE, /*bDescriptorType: HID*/
0x11, /*bcdHID: HID Class Spec release number*/
0x01,
0x00, /*bCountryCode: Hardware target country*/
0x01, /*bNumDescriptors: Number of HID class descriptors to follow*/
0x22, /*bDescriptorType*/
HID_KEYBOARD_REPORT_DESC_SIZE,/*wItemLength: Total length of Report descriptor*/
0x00,
/******************** Descriptor of Mouse endpoint ********************/
/* 27 */
0x07, /*bLength: Endpoint Descriptor size*/
USB_DESC_TYPE_ENDPOINT, /*bDescriptorType:*/
HID_EPIN_ADDR, /*bEndpointAddress: Endpoint Address (IN)*/
0x03, /*bmAttributes: Interrupt endpoint*/
HID_EPIN_SIZE, /*wMaxPacketSize: 4 Byte max */
0x00,
HID_FS_BINTERVAL, /*bInterval: Polling Interval */
/* 34 */
};
/* USB HID device Configuration Descriptor */
__ALIGN_BEGIN static uint8_t USBD_HID_Desc[USB_HID_DESC_SIZ] __ALIGN_END =
{
/* 18 */
0x09, /*bLength: HID Descriptor size*/
HID_DESCRIPTOR_TYPE, /*bDescriptorType: HID*/
0x11, /*bcdHID: HID Class Spec release number*/
0x01,
0x00, /*bCountryCode: Hardware target country*/
0x01, /*bNumDescriptors: Number of HID class descriptors to follow*/
0x22, /*bDescriptorType*/
HID_KEYBOARD_REPORT_DESC_SIZE,/*wItemLength: Total length of Report descriptor*/
0x00,
};
/* USB Standard Device Descriptor */
__ALIGN_BEGIN static uint8_t USBD_HID_DeviceQualifierDesc[USB_LEN_DEV_QUALIFIER_DESC] __ALIGN_END =
{
USB_LEN_DEV_QUALIFIER_DESC,
USB_DESC_TYPE_DEVICE_QUALIFIER,
0x00,
0x02,
0x00,
0x00,
0x00,
0x40,
0x01,
0x00,
};
__ALIGN_BEGIN static uint8_t HID_MOUSE_ReportDesc[HID_MOUSE_REPORT_DESC_SIZE] __ALIGN_END =
{
0x05, 0x01,
0x09, 0x02,
0xA1, 0x01,
0x09, 0x01,
0xA1, 0x00,
0x05, 0x09,
0x19, 0x01,
0x29, 0x03,
0x15, 0x00,
0x25, 0x01,
0x95, 0x03,
0x75, 0x01,
0x81, 0x02,
0x95, 0x01,
0x75, 0x05,
0x81, 0x01,
0x05, 0x01,
0x09, 0x30,
0x09, 0x31,
0x09, 0x38,
0x15, 0x81,
0x25, 0x7F,
0x75, 0x08,
0x95, 0x03,
0x81, 0x06,
0xC0, 0x09,
0x3c, 0x05,
0xff, 0x09,
0x01, 0x15,
0x00, 0x25,
0x01, 0x75,
0x01, 0x95,
0x02, 0xb1,
0x22, 0x75,
0x06, 0x95,
0x01, 0xb1,
0x01, 0xc0
};
// 标准USB键盘HID报告描述符（47字节）
__ALIGN_BEGIN static uint8_t HID_Keyboard_ReportDesc[HID_KEYBOARD_REPORT_DESC_SIZE] __ALIGN_END = {
0x05, 0x01, // Usage Page (Generic Desktop)
0x09, 0x06, // Usage (Keyboard)
0xA1, 0x01, // Collection (Application)
// 修饰键（8个位，每个表示一个修饰键）
0x05, 0x07, // Usage Page (Key Codes)
0x19, 0xE0, // Usage Minimum (224 = 左Ctrl)
0x29, 0xE7, // Usage Maximum (231 = 右GUI)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x01, // Logical Maximum (1)
0x75, 0x01, // Report Size (1)
0x95, 0x08, // Report Count (8)
0x81, 0x02, // Input (Data,Var,Abs)
// 保留字节
0x95, 0x01, // Report Count (1)
0x75, 0x08, // Report Size (8)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x00, // Logical Maximum (0) // 重要：必须为0
0x81, 0x03, // Input (Cnst,Var,Abs) // 常量
// 6个键码（最多同时按6个键）
0x95, 0x06, // Report Count (6)
0x75, 0x08, // Report Size (8)
0x15, 0x00, // Logical Minimum (0)
0x25, 0x65, // Logical Maximum (101)
0x05, 0x07, // Usage Page (Key Codes)
0x19, 0x00, // Usage Minimum (0)
0x29, 0x65, // Usage Maximum (101)
0x81, 0x00, // Input (Data,Arr,Abs)
0xC0 // End Collection
};
/**
* @}
*/
/** @defgroup USBD_HID_Private_Functions
* @{
*/
/**
* @brief USBD_HID_Init
* Initialize the HID interface
* @param pdev: device instance
* @param cfgidx: Configuration index
* @retval status
*/
static uint8_t USBD_HID_Init(USBD_HandleTypeDef *pdev, uint8_t cfgidx)
{
/* Open EP IN */
USBD_LL_OpenEP(pdev, HID_EPIN_ADDR, USBD_EP_TYPE_INTR, HID_EPIN_SIZE);
pdev->ep_in[HID_EPIN_ADDR & 0xFU].is_used = 1U;
pdev->pClassData = USBD_malloc(sizeof(USBD_HID_HandleTypeDef));
if (pdev->pClassData == NULL)
{
return USBD_FAIL;
}
((USBD_HID_HandleTypeDef *)pdev->pClassData)->state = HID_IDLE;
return USBD_OK;
}
/**
* @brief USBD_HID_Init
* DeInitialize the HID layer
* @param pdev: device instance
* @param cfgidx: Configuration index
* @retval status
*/
static uint8_t USBD_HID_DeInit(USBD_HandleTypeDef *pdev,
uint8_t cfgidx)
{
/* Close HID EPs */
USBD_LL_CloseEP(pdev, HID_EPIN_ADDR);
pdev->ep_in[HID_EPIN_ADDR & 0xFU].is_used = 0U;
/* FRee allocated memory */
if (pdev->pClassData != NULL)
{
USBD_free(pdev->pClassData);
pdev->pClassData = NULL;
}
return USBD_OK;
}
/**
* @brief USBD_HID_Setup
* Handle the HID specific requests
* @param pdev: instance
* @param req: usb requests
* @retval status
*/
static uint8_t USBD_HID_Setup(USBD_HandleTypeDef *pdev,
USBD_SetupReqTypedef *req)
{
USBD_HID_HandleTypeDef *hhid = (USBD_HID_HandleTypeDef *) pdev->pClassData;
uint16_t len = 0U;
uint8_t *pbuf = NULL;
uint16_t status_info = 0U;
USBD_StatusTypeDef ret = USBD_OK;
switch (req->bmRequest & USB_REQ_TYPE_MASK)
{
case USB_REQ_TYPE_CLASS :
switch (req->bRequest)
{
case HID_REQ_SET_PROTOCOL:
hhid->Protocol = (uint8_t)(req->wValue);
break;
case HID_REQ_GET_PROTOCOL:
USBD_CtlSendData(pdev, (uint8_t *)(void *)&hhid->Protocol, 1U);
break;
case HID_REQ_SET_IDLE:
hhid->IdleState = (uint8_t)(req->wValue >> 8);
break;
case HID_REQ_GET_IDLE:
USBD_CtlSendData(pdev, (uint8_t *)(void *)&hhid->IdleState, 1U);
break;
default:
USBD_CtlError(pdev, req);
ret = USBD_FAIL;
break;
}
break;
case USB_REQ_TYPE_STANDARD:
switch (req->bRequest)
{
case USB_REQ_GET_STATUS:
if (pdev->dev_state == USBD_STATE_CONFIGURED)
{
USBD_CtlSendData(pdev, (uint8_t *)(void *)&status_info, 2U);
}
else
{
USBD_CtlError(pdev, req);
ret = USBD_FAIL;
}
break;
case USB_REQ_GET_DESCRIPTOR:
if (req->wValue >> 8 == HID_REPORT_DESC)
{
len = MIN(HID_KEYBOARD_REPORT_DESC_SIZE, req->wLength);
pbuf = HID_Keyboard_ReportDesc;
}
else if (req->wValue >> 8 == HID_DESCRIPTOR_TYPE)
{
pbuf = USBD_HID_Desc;
len = MIN(USB_HID_DESC_SIZ, req->wLength);
}
else
{
USBD_CtlError(pdev, req);
ret = USBD_FAIL;
break;
}
USBD_CtlSendData(pdev, pbuf, len);
break;
case USB_REQ_GET_INTERFACE :
if (pdev->dev_state == USBD_STATE_CONFIGURED)
{
USBD_CtlSendData(pdev, (uint8_t *)(void *)&hhid->AltSetting, 1U);
}
else
{
USBD_CtlError(pdev, req);
ret = USBD_FAIL;
}
break;
case USB_REQ_SET_INTERFACE :
if (pdev->dev_state == USBD_STATE_CONFIGURED)
{
hhid->AltSetting = (uint8_t)(req->wValue);
}
else
{
USBD_CtlError(pdev, req);
ret = USBD_FAIL;
}
break;
default:
USBD_CtlError(pdev, req);
ret = USBD_FAIL;
break;
}
break;
default:
USBD_CtlError(pdev, req);
ret = USBD_FAIL;
break;
}
return ret;
}
/**
* @brief USBD_HID_SendReport
* Send HID Report
* @param pdev: device instance
* @param buff: pointer to report
* @retval status
*/
uint8_t USBD_HID_SendReport(USBD_HandleTypeDef *pdev,
uint8_t *report,
uint16_t len)
{
USBD_HID_HandleTypeDef *hhid = (USBD_HID_HandleTypeDef *)pdev->pClassData;
if (pdev->dev_state == USBD_STATE_CONFIGURED)
{
if (hhid->state == HID_IDLE)
{
hhid->state = HID_BUSY;
USBD_LL_Transmit(pdev,
HID_EPIN_ADDR,
report,
len);
}
}
return USBD_OK;
}
/**
* @brief USBD_HID_GetPollingInterval
* return polling interval from endpoint descriptor
* @param pdev: device instance
* @retval polling interval
*/
uint32_t USBD_HID_GetPollingInterval(USBD_HandleTypeDef *pdev)
{
uint32_t polling_interval = 0U;
/* HIGH-speed endpoints */
if (pdev->dev_speed == USBD_SPEED_HIGH)
{
/* Sets the data transfer polling interval for high speed transfers.
Values between 1..16 are allowed. Values correspond to interval
of 2 ^ (bInterval-1). This option (8 ms, corresponds to HID_HS_BINTERVAL */
polling_interval = (((1U << (HID_HS_BINTERVAL - 1U))) / 8U);
}
else /* LOW and FULL-speed endpoints */
{
/* Sets the data transfer polling interval for low and full
speed transfers */
polling_interval = HID_FS_BINTERVAL;
}
return ((uint32_t)(polling_interval));
}
/**
* @brief USBD_HID_GetCfgFSDesc
* return FS configuration descriptor
* @param speed : current device speed
* @param length : pointer data length
* @retval pointer to descriptor buffer
*/
static uint8_t *USBD_HID_GetFSCfgDesc(uint16_t *length)
{
*length = sizeof(USBD_HID_CfgFSDesc);
return USBD_HID_CfgFSDesc;
}
/**
* @brief USBD_HID_GetCfgHSDesc
* return HS configuration descriptor
* @param speed : current device speed
* @param length : pointer data length
* @retval pointer to descriptor buffer
*/
static uint8_t *USBD_HID_GetHSCfgDesc(uint16_t *length)
{
*length = sizeof(USBD_HID_CfgHSDesc);
return USBD_HID_CfgHSDesc;
}
/**
* @brief USBD_HID_GetOtherSpeedCfgDesc
* return other speed configuration descriptor
* @param speed : current device speed
* @param length : pointer data length
* @retval pointer to descriptor buffer
*/
static uint8_t *USBD_HID_GetOtherSpeedCfgDesc(uint16_t *length)
{
*length = sizeof(USBD_HID_OtherSpeedCfgDesc);
return USBD_HID_OtherSpeedCfgDesc;
}
/**
* @brief USBD_HID_DataIn
* handle data IN Stage
* @param pdev: device instance
* @param epnum: endpoint index
* @retval status
*/
static uint8_t USBD_HID_DataIn(USBD_HandleTypeDef *pdev,
uint8_t epnum)
{
/* Ensure that the FIFO is empty before a new transfer, this condition could
be caused by a new transfer before the end of the previous transfer */
((USBD_HID_HandleTypeDef *)pdev->pClassData)->state = HID_IDLE;
return USBD_OK;
}
/**
* @brief DeviceQualifierDescriptor
* return Device Qualifier descriptor
* @param length : pointer data length
* @retval pointer to descriptor buffer
*/
static uint8_t *USBD_HID_GetDeviceQualifierDesc(uint16_t *length)
{
*length = sizeof(USBD_HID_DeviceQualifierDesc);
return USBD_HID_DeviceQualifierDesc;
}
/**
* @}
*/
/**
* @}
*/
/**
* @}
*/
/************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/
/Core/Src/main.c
/* USER CODE BEGIN Header */
/**
******************************************************************************
* @file : main.c
* @brief : Main program body
******************************************************************************
* @attention
*
* Copyright (c) 2026 STMicroelectronics.
* All rights reserved.
*
* This software is licensed under terms that can be found in the LICENSE file
* in the root directory of this software component.
* If no LICENSE file comes with this software, it is provided AS-IS.
*
******************************************************************************
*/
/* USER CODE END Header */
/* Includes ------------------------------------------------------------------*/
#include "usbd_hid.h"
#include "main.h"
#include "usb_device.h"
#include "gpio.h"
/* Private includes ----------------------------------------------------------*/
/* USER CODE BEGIN Includes */
#include "usbd_core.h"
#include "string.h"
#include "keyboard_usage_table.h"
/* USER CODE END Includes */
/* Private typedef -----------------------------------------------------------*/
/* USER CODE BEGIN PTD */
/* USER CODE END PTD */
/* Private define ------------------------------------------------------------*/
/* USER CODE BEGIN PD */
/* USER CODE END PD */
/* Private macro -------------------------------------------------------------*/
/* USER CODE BEGIN PM */
/* USER CODE END PM */
/* Private variables ---------------------------------------------------------*/
/* USER CODE BEGIN PV */
/* USER CODE END PV */
/* Private function prototypes -----------------------------------------------*/
void SystemClock_Config(void);
/* USER CODE BEGIN PFP */
/* USER CODE END PFP */
/* Private user code ---------------------------------------------------------*/
/* USER CODE BEGIN 0 */
extern USBD_HandleTypeDef hUsbDeviceFS;
// 字节0: 修饰键
// 字节1: 保留（必须为0）
// 字节2-7: 6个键码
uint8_t key_report[8] = {0, 0, 0, 0, 0, 0, 0, 0};
/*在keyboard_usage_table.h中定义
// USB键盘扫描码表
#define KEY_A 0x04
#define KEY_B 0x05
#define KEY_1 0x1E
#define KEY_ENTER 0x28
#define KEY_SPACE 0x2C
#define KEY_SHIFT 0x02 // 左Shift修饰键
*/
// 修正后的按键发送函数
void USB_Keyboard_Send_Key(uint8_t mod, uint8_t key)
{
// 发送按键按下
key_report[0] = mod; // 修饰键（Shift/Ctrl/Alt等）
key_report[1] = 0; // 保留字节，必须为0
key_report[2] = key; // 第一个键码
// key_report[3-7] 保持为0（其他键码）
uint8_t send_state;
send_state = USBD_HID_SendReport(&hUsbDeviceFS, key_report, 8);
//if(send_state == USBD_OK) HAL_Delay(10); // 稍微缩短延时
// 发送按键释放（全0报告）
memset(key_report, 0, 8);
USBD_HID_SendReport(&hUsbDeviceFS, key_report, 8);
//HAL_Delay(10); // 稍微缩短延时
}
/* USER CODE END 0 */
/**
* @brief The application entry point.
* @retval int
*/
int main(void)
{
/* USER CODE BEGIN 1 */
/* USER CODE END 1 */
/* MCU Configuration--------------------------------------------------------*/
/* Reset of all peripherals, Initializes the Flash interface and the Systick. */
HAL_Init();
/* USER CODE BEGIN Init */
/* USER CODE END Init */
/* Configure the system clock */
SystemClock_Config();
/* USER CODE BEGIN SysInit */
/* USER CODE END SysInit */
/* Initialize all configured peripherals */
MX_GPIO_Init();
MX_USB_DEVICE_Init();
/* USER CODE BEGIN 2 */
/* USER CODE END 2 */
/* Infinite loop */
/* USER CODE BEGIN WHILE */
while (1)
{
/* USER CODE END WHILE */
// 测试1：发送普通A键（无修饰键）
USB_Keyboard_Send_Key(0, KEY_A);
//HAL_Delay(10); // 1秒发送一次A键
// 测试2：发送大写A（左Shift+A，修饰键为KEY_SHIFT）
// USB_Keyboard_Send_Key(KEY_SHIFT, KEY_A);
// HAL_Delay(1000);
// 测试3：发送回车键
// USB_Keyboard_Send_Key(0, KEY_ENTER);
// HAL_Delay(2000);
/* USER CODE BEGIN 3 */
}
/* USER CODE END 3 */
}
/**
* @brief System Clock Configuration
* @retval None
*/
void SystemClock_Config(void)
{
RCC_OscInitTypeDef RCC_OscInitStruct = {0};
RCC_ClkInitTypeDef RCC_ClkInitStruct = {0};
RCC_PeriphCLKInitTypeDef PeriphClkInit = {0};
/** Initializes the RCC Oscillators according to the specified parameters
* in the RCC_OscInitTypeDef structure.
*/
RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE;
RCC_OscInitStruct.HSEState = RCC_HSE_ON;
RCC_OscInitStruct.HSEPredivValue = RCC_HSE_PREDIV_DIV1;
RCC_OscInitStruct.HSIState = RCC_HSI_ON;
RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
RCC_OscInitStruct.PLL.PLLMUL = RCC_PLL_MUL9;
if (HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK)
{
Error_Handler();
}
/** Initializes the CPU, AHB and APB buses clocks
*/
RCC_ClkInitStruct.ClockType = RCC_CLOCKTYPE_HCLK|RCC_CLOCKTYPE_SYSCLK
|RCC_CLOCKTYPE_PCLK1|RCC_CLOCKTYPE_PCLK2;
RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
RCC_ClkInitStruct.AHBCLKDivider = RCC_SYSCLK_DIV1;
RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV2;
RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV1;
if (HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_2) != HAL_OK)
{
Error_Handler();
}
PeriphClkInit.PeriphClockSelection = RCC_PERIPHCLK_USB;
PeriphClkInit.UsbClockSelection = RCC_USBCLKSOURCE_PLL_DIV1_5;
if (HAL_RCCEx_PeriphCLKConfig(&PeriphClkInit) != HAL_OK)
{
Error_Handler();
}
}
/* USER CODE BEGIN 4 */
/* USER CODE END 4 */
/**
* @brief This function is executed in case of error occurrence.
* @retval None
*/
void Error_Handler(void)
{
/* USER CODE BEGIN Error_Handler_Debug */
/* User can add his own implementation to report the HAL error return state */
__disable_irq();
while (1)
{
}
/* USER CODE END Error_Handler_Debug */
}
#ifdef USE_FULL_ASSERT
/**
* @brief Reports the name of the source file and the source line number
* where the assert_param error has occurred.
* @param file: pointer to the source file name
* @param line: assert_param error line source number
* @retval None
*/
void assert_failed(uint8_t *file, uint32_t line)
{
/* USER CODE BEGIN 6 */
/* User can add his own implementation to report the file name and line number,
ex: printf("Wrong parameters value: file %s on line %d\r\n", file, line) */
/* USER CODE END 6 */
}
#endif /* USE_FULL_ASSERT */
keyboard_usage_table.h
// ==================== USB HID 键盘扫描码表 ====================
// 注：这些是USB HID Usage ID值
/* ---------- 字母键 ---------- */
#define KEY_A 0x04
#define KEY_B 0x05
#define KEY_C 0x06
#define KEY_D 0x07
#define KEY_E 0x08
#define KEY_F 0x09
#define KEY_G 0x0A
#define KEY_H 0x0B
#define KEY_I 0x0C
#define KEY_J 0x0D
#define KEY_K 0x0E
#define KEY_L 0x0F
#define KEY_M 0x10
#define KEY_N 0x11
#define KEY_O 0x12
#define KEY_P 0x13
#define KEY_Q 0x14
#define KEY_R 0x15
#define KEY_S 0x16
#define KEY_T 0x17
#define KEY_U 0x18
#define KEY_V 0x19
#define KEY_W 0x1A
#define KEY_X 0x1B
#define KEY_Y 0x1C
#define KEY_Z 0x1D
/* ---------- 数字键（主键盘区） ---------- */
#define KEY_1 0x1E // 主键盘1
#define KEY_2 0x1F
#define KEY_3 0x20
#define KEY_4 0x21
#define KEY_5 0x22
#define KEY_6 0x23
#define KEY_7 0x24
#define KEY_8 0x25
#define KEY_9 0x26
#define KEY_0 0x27
/* ---------- 功能键 ---------- */
#define KEY_F1 0x3A
#define KEY_F2 0x3B
#define KEY_F3 0x3C
#define KEY_F4 0x3D
#define KEY_F5 0x3E
#define KEY_F6 0x3F
#define KEY_F7 0x40
#define KEY_F8 0x41
#define KEY_F9 0x42
#define KEY_F10 0x43
#define KEY_F11 0x44
#define KEY_F12 0x45
#define KEY_F13 0x68 // F13-F24通常用于特殊键盘
#define KEY_F14 0x69
#define KEY_F15 0x6A
#define KEY_F16 0x6B
#define KEY_F17 0x6C
#define KEY_F18 0x6D
#define KEY_F19 0x6E
#define KEY_F20 0x6F
#define KEY_F21 0x70
#define KEY_F22 0x71
#define KEY_F23 0x72
#define KEY_F24 0x73
/* ---------- 导航键 ---------- */
#define KEY_ENTER 0x28 // Enter/Return
#define KEY_ESC 0x29 // Escape
#define KEY_BACKSPACE 0x2A // Backspace
#define KEY_TAB 0x2B // Tab
#define KEY_SPACE 0x2C // Spacebar
#define KEY_CAPSLOCK 0x39 // Caps Lock
#define KEY_PRINTSCREEN 0x46 // Print Screen
#define KEY_SCROLLLOCK 0x47 // Scroll Lock
#define KEY_PAUSE 0x48 // Pause/Break
#define KEY_INSERT 0x49 // Insert
#define KEY_HOME 0x4A // Home
#define KEY_PAGEUP 0x4B // Page Up
#define KEY_DELETE 0x4C // Delete
#define KEY_END 0x4D // End
#define KEY_PAGEDOWN 0x4E // Page Down
/* ---------- 方向键 ---------- */
#define KEY_RIGHT 0x4F // Right Arrow
#define KEY_LEFT 0x50 // Left Arrow
#define KEY_DOWN 0x51 // Down Arrow
#define KEY_UP 0x52 // Up Arrow
/* ---------- 小键盘 ---------- */
#define KEY_NUMLOCK 0x53 // Num Lock
#define KEY_KP_SLASH 0x54 // Keypad /
#define KEY_KP_ASTERISK 0x55 // Keypad *
#define KEY_KP_MINUS 0x56 // Keypad -
#define KEY_KP_PLUS 0x57 // Keypad +
#define KEY_KP_ENTER 0x58 // Keypad Enter
#define KEY_KP_1 0x59 // Keypad 1
#define KEY_KP_2 0x5A // Keypad 2
#define KEY_KP_3 0x5B // Keypad 3
#define KEY_KP_4 0x5C // Keypad 4
#define KEY_KP_5 0x5D // Keypad 5
#define KEY_KP_6 0x5E // Keypad 6
#define KEY_KP_7 0x5F // Keypad 7
#define KEY_KP_8 0x60 // Keypad 8
#define KEY_KP_9 0x61 // Keypad 9
#define KEY_KP_0 0x62 // Keypad 0
#define KEY_KP_DOT 0x63 // Keypad . (点)
/* ---------- 符号键 ---------- */
#define KEY_MINUS 0x2D // - (减号/下划线)
#define KEY_EQUAL 0x2E // = (等号/加号)
#define KEY_LEFTBRACE 0x2F // [ (左大括号)
#define KEY_RIGHTBRACE 0x30 // ] (右大括号)
#define KEY_BACKSLASH 0x31 // \ (反斜杠)
#define KEY_HASHTILDE 0x32 // # ~ (非美国键盘)
#define KEY_SEMICOLON 0x33 // ; (分号)
#define KEY_APOSTROPHE 0x34 // ' (单引号)
#define KEY_GRAVE 0x35 // ` (反引号/波浪号)
#define KEY_COMMA 0x36 // , (逗号)
#define KEY_DOT 0x37 // . (点/句号)
#define KEY_SLASH 0x38 // / (斜杠)
/* ---------- 修饰键 ---------- */
// 注意：这些值用于修饰键字节的位掩码，不是Usage ID
// 修饰键字节的位定义：
#define KEY_MOD_LCTRL 0x01 // 左Ctrl (位0)
#define KEY_MOD_LSHIFT 0x02 // 左Shift (位1) - 你之前定义为0x02，这是正确的
#define KEY_MOD_LALT 0x04 // 左Alt (位2)
#define KEY_MOD_LGUI 0x08 // 左GUI/Win键 (位3)
#define KEY_MOD_RCTRL 0x10 // 右Ctrl (位4)
#define KEY_MOD_RSHIFT 0x20 // 右Shift (位5)
#define KEY_MOD_RALT 0x40 // 右Alt/AltGr (位6)
#define KEY_MOD_RGUI 0x80 // 右GUI/Win键 (位7)
/* ---------- 特殊键 ---------- */
#define KEY_MENU 0x65 // Application/Context Menu键
#define KEY_POWER 0x66 // Power
#define KEY_KP_EQUAL 0x67 // Keypad =
#define KEY_EXECUTE 0x74 // Execute
#define KEY_HELP 0x75 // Help
#define KEY_SELECT 0x77 // Select
/* ---------- 多媒体键 ---------- */
#define KEY_MUTE 0x7F // Mute
#define KEY_VOLUMEUP 0x80 // Volume Up
#define KEY_VOLUMEDOWN 0x81 // Volume Down
#define KEY_STOP 0x78 // Stop
#define KEY_PREVTRACK 0x90 // Previous Track
#define KEY_NEXTTRACK 0x91 // Next Track
#define KEY_PLAYPAUSE 0xCD // Play/Pause
/* ---------- 系统控制键 ---------- */
#define KEY_SYSRQ 0x9A // System Request
#define KEY_CANCEL 0x9B // Cancel
#define KEY_CLEAR 0x9C // Clear