Ngôn ngữ UI

STM32 USB HID Keyboard

Project thực chiến xây dựng firmware bàn phím USB HID bằng STM32, tập trung vào endpoint, report descriptor và debug host-device communication.

2 tháng 5, 2026 4 phút đọc

Project info

Status

In Progress

1. Mục tiêu project

Project này dùng để học cách xây dựng một thiết bị USB HID keyboard bằng STM32.

Mục tiêu chính:

Hiểu USB descriptor.
Hiểu HID report descriptor.
Gửi key report từ device lên host.
Debug quá trình enumeration.
Tổ chức firmware theo hướng dễ mở rộng.

2. Bối cảnh kỹ thuật

USB HID keyboard là một ví dụ rất tốt để học embedded firmware vì nó có đủ các yếu tố quan trọng:

Device phải mô tả chính nó với host.
Host đọc descriptor để hiểu device là gì.
Firmware phải chuẩn bị report đúng format.
Dữ liệu được gửi qua endpoint IN.
Debug cần quan sát cả phía firmware và phía host.

Nói đơn giản, đây không chỉ là project “gửi phím lên máy tính”. Nó còn giúp hiểu cách firmware, USB stack và hệ điều hành giao tiếp với nhau.

3. Kiến trúc dự kiến

Key Matrix / Input Source
  ↓
Key Scan Layer
  ↓
HID Report Builder
  ↓
USB HID Class
  ↓
Endpoint IN
  ↓
Host PC

Luồng xử lý nên được chia thành nhiều lớp rõ ràng.

USB layer không nên xử lý quá nhiều logic phím. Ngược lại, key scan layer cũng không nên phụ thuộc trực tiếp vào chi tiết USB low-level.

4. Các module chính

Một cấu trúc đơn giản có thể bắt đầu như sau:

app/
├── key_scan.c
├── key_scan.h
├── hid_report.c
├── hid_report.h
├── usb_app.c
├── usb_app.h
└── debug_log.c

Ý tưởng chính:

key_scan.c chịu trách nhiệm đọc trạng thái phím.
hid_report.c chuyển trạng thái phím thành HID report.
usb_app.c gửi report qua USB endpoint.
debug_log.c dùng để ghi log phục vụ debug.

5. Ví dụ HID keyboard report

Một HID keyboard report cơ bản thường có dạng 8 bytes:

typedef struct
{
    uint8_t modifier;
    uint8_t reserved;
    uint8_t keycode[6];
} HidKeyboardReport_t;

Trong đó:

modifier dùng cho các phím như Ctrl, Shift, Alt, GUI.
reserved thường để 0.
keycode[6] chứa tối đa 6 phím thường được nhấn cùng lúc.

Ví dụ gửi phím A:

HidKeyboardReport_t report = {0};

report.keycode[0] = 0x04; // HID usage ID for 'A'

// Send report to host here

Sau khi gửi key press, firmware thường cần gửi thêm một report rỗng để biểu thị key release:

HidKeyboardReport_t releaseReport = {0};

// Send empty report to release key

6. Checklist triển khai

7. Lỗi thường gặp

Một số lỗi thường gặp khi làm USB HID keyboard:

Descriptor sai nên host không nhận device.
Report length không khớp với descriptor.
Gửi key press nhưng quên gửi key release.
Endpoint đang busy nhưng firmware vẫn cố gửi tiếp.
Gọi hàm blocking trong callback USB.
Logic key scan bị phụ thuộc quá chặt vào USB layer.

8. Ghi chú thiết kế

Với project thực tế, nên thiết kế theo hướng:

Input Layer
  ↓
Key Logic Layer
  ↓
HID Report Builder
  ↓
USB Transport Layer

Cách tách này giúp firmware dễ mở rộng hơn.

Ví dụ sau này nếu muốn thêm vendor command, custom HID interface hoặc debug command, ta không cần sửa quá nhiều vào phần key scan.

9. Kết luận

Project STM32 USB HID Keyboard phù hợp để học embedded firmware vì nó kết hợp nhiều kiến thức thực tế:

USB device.
HID protocol.
Descriptor.
Endpoint.
Firmware architecture.
Debug host-device communication.

Đây là project nền tảng tốt trước khi mở rộng sang custom HID, USB bulk transfer hoặc thiết bị POS keyboard phức tạp hơn.

10. Tài liệu tham khảo

Nội dung liên quan

Một số bài viết, ghi chú hoặc project có liên quan đến nội dung bạn vừa đọc.

Tiếp tục xem các project embedded

Các project thực chiến giúp biến ghi chú kỹ thuật thành kinh nghiệm.

Xem projects Đọc blog