hidapi：一个跨平台的 C 库，专门用来和 USB／BlE HID 类设备（如键盘、鼠标、游戏手柄、扫码枪、LED 控制器)

作者

 

什么是 hidapi？

hidapi（Human Interface Device API）是一个跨平台的 C 库，专门用来和 USB／Bluetooth HID 类设备（比如键盘、鼠标、游戏手柄、扫码枪、LED 控制器等）打交道。它的目标很明确：让你只写几行代码，就能在 Windows、Linux、FreeBSD、macOS 上无痛读写 HID 报文。

核心亮点

  • • 单文件（每个平台只要一个 .c + 一个 .h）即可快速嵌入项目。

  • • 支持四大后端：hid.dll（Windows）、hidraw（Linux 内核）、libusb（Linux/Unix）和 IOHidManager（macOS）。

  • • 既可以编译成共享库（.so/.dll/.dylib），也可以直接把源码拷进去“静态链接”。

它解决了哪些痛点？

传统痛点

hidapi 的解决方案
跨平台代码差异大

同一套 API 在四大系统上统一调用，免去 #ifdef 大海捞针。
底层驱动调用繁琐

hidapi 把 hidraw、libusb、IOHidManager 等封装成几条简单函数（hid_open、hid_read、hid_write …）。
权限访问难

提供示例 udev 规则，普通用户也能直接访问 USB HID 设备。
调试工具缺失

附带 hidapitester 控制台工具和历史遗留的 GUI（基于 Fox Toolkit）帮助快速验证硬件。
文档散乱、示例少

官方 README、Wiki、示例代码（hidtest.c）齐全，社区活跃。

简而言之，hidapi 把“硬件驱动的魔法”变成了“普通函数调用”，让硬件开发者把时间花在业务上，而不是驱动细节。

安装指南（一步到位）

使用系统包管理器（推荐）

系统

安装命令
Ubuntu / Debian sudo apt update && sudo apt install libhidapi-dev
Fedora sudo dnf install hidapi-devel
Arch Linux sudo pacman -S hidapi
macOS (Homebrew) brew install hidapi
FreeBSD pkg install hidapi

Tip：安装后会得到 libhidapi-hidraw.so 与 libhidapi-libusb.so 两个库，链接时任选其一即可。

2. 手动编译（适用于自定义需求）

git clone https://github.com/libusb/hidapi.git
cd hidapi
mkdir build && cd build
cmake .. -DBUILD_SHARED_LIBS=ON   # 生成共享库
make -j$(nproc)
sudo make install

最小示例：读写键盘灯

#include <stdio.h>
#include <wchar.h>
#include "hidapi.h"

int main(void) {
    hid_device *dev;
    unsigned char buf[65] = {0};

    // 初始化库
    hid_init();

    // 打开设备（VID=0x04D8, PID=0x003F）
    dev = hid_open(0x04D8, 0x003F, NULL);
    if (!dev) { printf("打开设备失败\n"); return 1; }

    // 读取制造商字符串
    wchar_t wstr[256];
    hid_get_manufacturer_string(dev, wstr, sizeof(wstr));
    wprintf(L"制造商: %ls\n", wstr);

    // 发送控制指令：打开 LED（假设报告号 0x01）
    buf[0] = 0x01;   // 报告号
    buf[1] = 0x01;   // 打开 LED
    hid_write(dev, buf, sizeof(buf));

    // 读取返回数据
    hid_read(fd, buf, sizeof(buf));
    printf("返回: %02X %02X\n", buf[0], buf[1]);

    // 关闭并释放资源
    hid_close(dev);
    hid_exit();
    return 0;
}

⚠️安全提示：只在设备手册明确的报告范围内写数据，随意 hid_write 可能导致设备死机或硬件损坏。

优缺点速评

优点

缺点
跨平台统一 API

，代码一次编写，四平台跑通。

 Bluetooth 支持不完整

（仅限 hidraw，不支持 libusb）。
体积小

（单文件）+ 可静态嵌入，适合嵌入式系统。

 Linux 需要额外 udev 规则

，否则普通用户无法访问。
社区活跃

，定期合并 bugfix，GitHub Issue 多。

 GUI 测试工具已停更

，若想用需自行编译 Fox Toolkit。
许可证宽松

，MIT/Apache 双许可，商用无忧。

 高级功能（如异步 I/O）缺失

，只能轮询或自行封装线程。

总结

hidapi 把硬件层的“繁琐细节”抽象成几行 C 代码，让 “会写代码的硬件爱好者” 能够快速上手 HID 设备的调试和开发。它的跨平台特性、轻量级实现以及友好的文档，使其在嵌入式、游戏外设、工业控制等领域成为首选。

如果你正准备开发自定义键盘、游戏手柄、或是做一个小玩具，只要把 hidapi 拉进项目，省去驱动适配的时间，直接把精力投入业务实现，这才是最靠谱的路线。

别忘了：代码写完后，给设备留点余地，不要随意发送非法报文，保持硬件安全。

项目地址： https://github.com/libusb/hidapi

 

发表评论