目錄

項目概述

RT-Thread 使用情況概述

硬件框架

軟件框架說明

軟件模塊說明

效果演示

代碼地址

總結

1 項目概述

1.1 實現功能

本項目基于 NXP FRDM-MCXA156 開發板，實現了一個標準的 USB HID 游戲手柄設備，主要功能包括：

16 個數字按鈕：通過 4x4 矩陣鍵盤實現 14 個按鈕 + 2 個搖桿按鍵

雙搖桿輸入：左右兩個模擬搖桿，各提供 X/Y 軸數據

USB HID 協議：標準 HID Gamepad 設備，即插即用，無需驅動

實時響應：10ms 掃描間隔，低延遲輸入

1.2 技術特點

2 RT-Thread使用情況概述

2.1 內核配置

#defineRT_THREAD_PRIORITY_MAX 32 // 32 級優先級#defineRT_TICK_PER_SECOND 1000 // 1ms 系統節拍#defineRT_USING_TIMER_SOFT // 軟件定時器#defineRT_USING_SEMAPHORE // 信號量#defineRT_USING_MUTEX // 互斥鎖#defineRT_USING_MAILBOX // 郵箱

2.2 使用的組件

2.3 線程設計

2.4 自動初始化

項目使用 RT-Thread 自動初始化機制：

INIT_BOARD_EXPORT(rt_hw_adc_init); // ADC 驅動初始化INIT_DEVICE_EXPORT(key_init); // 矩陣鍵盤初始化INIT_DEVICE_EXPORT(joystick_init); // 搖桿初始化INIT_COMPONENT_EXPORT(cherryusb_init); // USB 初始化INIT_APP_EXPORT(gamepad_app_start); // 應用層啟動

3 硬件框架

3.1 系統框圖

┌─────────────────────────────────────────────────────────────┐│ FRDM-MCXA156 ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐││ │ 4x4 矩陣 │ │ 雙搖桿模塊 │ │ USBDevice │││ │ 鍵盤 │ │ (帶按鍵) │ │ (FullSpeed) │││ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘││ │ │ │ ││ GPIOP2/P3 ADC0 CH0/1/8/13 USB0 ││ │ │ │ ││ ┌──────┴────────────────┴─────────────────────┴──────────┐││ │ MCXA156MCU │││ │ (Cortex-M33@ 96MHz) │││ └─────────────────────────────────────────────────────────┘│└─────────────────────────────────────────────────────────────┘

3.2 引腳分配

3.2.1 矩陣鍵盤 (4x4)

3.2.2 搖桿 ADC

3.2.3 搖桿按鍵

4 軟件框架說明

4.1 軟件框架

┌─────────────────────────────────────────────────────────────┐│ 應用層 (Application) ││ ┌─────────────────────────────────────────────────────────┐││ │ gamepad_app.c │││ │ (整合輸入設備，映射到USBHID報告) │││ └─────────────────────────────────────────────────────────┘│├─────────────────────────────────────────────────────────────┤│ 功能層 (Function) ││ ┌───────────────┐ ┌───────────────┐ ┌─────────────────┐ ││ │ key_app.c │ │ joystick_app.c│ │ usb_app.c │ ││ │ (矩陣鍵盤) │ │ (雙搖桿) │ │ (USBHID) │ ││ └───────────────┘ └───────────────┘ └─────────────────┘ │├─────────────────────────────────────────────────────────────┤│ 驅動層 (Driver) ││ ┌───────────────┐ ┌───────────────┐ ┌─────────────────┐ ││ │ drv_pin.c │ │ drv_adc.c │ │ CherryUSB │ ││ │ (GPIO) │ │ (ADC) │ │ (USBStack) │ ││ └───────────────┘ └───────────────┘ └─────────────────┘ │├─────────────────────────────────────────────────────────────┤│ RT-Thread內核 ││ (線程調度、IPC、設備框架、自動初始化) │├─────────────────────────────────────────────────────────────┤│ 硬件抽象層 (HAL) ││ NXPMCXSDK/CMSIS │└─────────────────────────────────────────────────────────────┘

4.2 數據流

矩陣鍵盤 ──? key_read() ──────────────────────────────────┐ │左搖桿 ADC ──? joystick_left_read() ──? apply_deadzone() ──┤ ├──? gamepad_thread右搖桿 ADC ──? joystick_right_read() ──? apply_deadzone() ──┤ │ │ ▼搖桿按鍵 ──? rt_pin_read() ────────────────────────────────┘ scale_axis() │ ▼ USB HID Report │ ▼ hid_gamepad_send_report() │ ▼ USBHost(PC)

嚴格遵守了 感知 --> 認知 --> 控制 系統設計模式

5 軟件模塊說明

5.1 key_app 模塊（矩陣鍵盤）

文件:applications/key_app.c, applications/key_app.h

功能:4x4 矩陣鍵盤掃描

核心函數:

rt_uint8_tkey_read(void); // 返回0-15表示按鍵索引，0xFF 表示無按鍵

掃描原理:

逐列輸出低電平

讀取所有行引腳狀態

檢測到低電平表示該交叉點按鍵被按下

5.2 joystick_app 模塊（搖桿）

文件:applications/joystick_app.c, applications/joystick_app.h

功能:雙搖桿 ADC 讀取與按鍵檢測

數據結構:

typedefstruct { int16_tx; // X軸: -32768 ~ 32767 int16_ty; // Y軸: -32768 ~ 32767 boolbtn; // 按鍵: true=按下}joystick_data_t;

核心函數：

rt_err_tjoystick_left_read(joystick_data_t*data);rt_err_tjoystick_right_read(joystick_data_t*data);

5.3 usb_app 模塊（USB HID）

文件:applications/usb_app.c, applications/usb_app.h

功能:USB HID 游戲手柄設備實現

HID 報告結構 (9 字節):

typedefstruct __attribute__((packed)) { uint16_tbuttons; // 16 個按鈕 int8_tleft_x; // 左搖桿 X (-127 ~ 127) int8_tleft_y; // 左搖桿 Y int8_tright_x; // 右搖桿 X int8_tright_y; // 右搖桿 Y uint8_tleft_trigger; // 左扳機 (0-255) uint8_tright_trigger;// 右扳機 (0-255) uint8_that; // 方向鍵 (0-8)}usb_gamepad_report_t;

USB 描述符配置:

VID: 0x045E (Microsoft)

PID: 0x02FF (Generic Gamepad)

端點: 0x81 (IN), 中斷傳輸

輪詢間隔: 1ms

5.4 gamepad_app 模塊（應用層）

文件: applications/gamepad_app.c, applications/gamepad_app.h

功能: 整合所有輸入設備，映射到 USB HID 報告

核心特性:

死區處理: 消除搖桿中心位置的抖動

變化檢測: 只有狀態變化時才發送報告

發送重試: USB 忙碌時保留報告，下次重試

按鍵映射:

5.5 drv_adc 模塊（ADC 驅動）

文件:Libraries/drivers/drv_adc.c

功能:LPADC 驅動，支持多通道 ADC 讀取

關鍵修改:

修復了多通道初始化覆蓋問題

添加了超時保護，防止系統死鎖

優化了命令槽分配（4 個通道使用 4 個獨立命令槽）

6 演示效果

6.1 啟動日志

KEY OKjoystick:initOK[USB] Initializing HID Gamepad...[USB] HID Gamepad initialized successfully[USB] VID:0x045EPID:0x02FF[GAMEPAD] Started (interval:10ms)System Start[GAMEPAD] Thread started[USB] Device Configured - Gamepad Ready!

6.2 Windows 測試

1.設備連接后，在”設備管理器”中顯示為 “USB Gamepad HID”

2.使用 joy.cpl（游戲控制器）可測試所有按鈕和搖桿

3.使用https://gamepad-tester.com/ 在線平臺課測試所有按鈕和搖桿

6.3功能演示

16 個按鈕正常響應

左右搖桿 X/Y 軸正常

搖桿按鍵正常

低延遲響應

7 代碼地址

Git 倉庫:https://github.com/Rolmoland/Project_GamepadMi

主要文件:

applications/├── main.c # 主入口├── gamepad_app.c/h # 游戲手柄應用層├── key_app.c/h # 矩陣鍵盤模塊├── joystick_app.c/h # 搖桿模塊└── usb_app.c/h # USB HID 模塊board/├── MCUX_Config/board/pin_mux.c # 引腳配置└── ports/cherryusb/ # CherryUSB 適配Libraries/drivers/└── drv_adc.c # ADC 驅動（已修改）

8 總結

本項目成功實現了基于 RT-Thread 的 USB HID 游戲手柄，具有以下特點：

模塊化設計: 硬件層、功能層、應用層分離，易于維護

實時性好: 基于 RT-Thread 實時內核，10ms 掃描周期

兼容性強: 標準 HID 協議，Windows/Linux/macOS 免驅

可擴展: 可方便添加震動反饋、LED 指示等功能