1. 从一次“设备能枚举但读不到数据”说起:libusb 与 hidapi 的分工
在 Linux 上接 USB HID 设备,libusb 和 hidapi 是两个很典型的代码开发工具库:一个负责通用 USB 设备枚举与传输,一个把 HID 设备的打开和读写包了一层。我第一次把这两套库放在一起用时,遇到的现象很具体:libusb 能把设备列表和 VID/PID 打出来,hidapi 却在 hid_open 或 hid_read 上卡住,程序看起来“初始化成功”,实际一包数据都读不到。
这篇内容适合两类人:一类是刚要在 Linux 下编译 libusb、hidapi,并用 C 写一个 HID 测试程序的人;另一类是已经跑通过一次,但换设备或换机器就翻车,想知道编译顺序、链接参数、动态库缓存和设备枚举到底哪一步出了问题的人。下面按“先装 libusb、再装 hidapi、再写测试程序、最后排错”的顺序走一遍,命令和代码都能直接对照着改。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 编译 libusb 与 hidapi:先 libusb 后 hidapi 的顺序不能反
2.1 libusb 负责什么,hidapi 为什么依赖它
libusb 是操作 USB 设备的通用库,设备列表、描述符、总线号、设备地址这些信息都从它这里拿。hidapi 则专门面向 HID 设备,比如鼠标、键盘、触摸屏这一类“人类输入设备”,打开设备、读报告、关闭设备都有更短的接口。材料里把两者的关系说得很直白:hidapi 依赖 libusb,并且专门针对 HID 设备。
这个依赖关系决定了编译顺序。libusb 没编译安装好,hidapi 的 ./configure 阶段就可能找不到头文件或库;即使侥幸编译过去,链接测试程序时也会缺 -lusb-1.0 对应的库。血泪经验是:不要两个源码目录同时开工,先把 libusb 走完 make install,再进 hidapi 目录做同样的事。
2.2 编译前要确认的源码目录与 bootstrap 脚本
两个库的编译方法一样,材料里给的命令是同一套:
bash复制./bootstrap
./configure
make
sudo make install
这四步的含义要分清。./bootstrap 用来生成 configure 脚本,源码包如果已经带了 configure,这一步可能被跳过或提示已存在;./configure 检查当前系统的编译器、头文件和依赖,生成 Makefile;make 按当前目录的规则编译;sudo make install 把头文件、动态库和 pkg-config 文件安装到系统目录,常见位置是 /usr/local/include 和 /usr/local/lib。
实际操作时,我会先进入 libusb 源码目录执行这一套,再进入 hidapi 源码目录执行同一套。路径不要写死成材料外的真实目录,换成自己放源码的位置即可:
bash复制cd /path/to/libusb
./bootstrap
./configure
make
sudo make install
cd /path/to/hidapi
./bootstrap
./configure
make
sudo make install
这里最容易踩的坑是“只 make 不 make install”。make 只在源码目录里生成库文件,测试程序用 -lusb-1.0 和 -lhidapi-libusb 链接时,链接器默认去系统库路径找,找不到就报 cannot find -lhidapi-libusb。所以安装这一步不能省。
2.3 动态库安装后为什么要 ldconfig
sudo make install 把库放到 /usr/local/lib 之后,动态链接器不一定立刻知道新库的位置。材料里专门写了:
bash复制sudo ldconfig
这条命令刷新系统动态库缓存。执行完之后,运行时加载器才能按库名找到刚安装的 libusb-1.0.so 和 libhidapi-libusb.so。如果跳过这一步,常见现象是编译阶段能过,运行阶段报 error while loading shared libraries,程序连 main 都没进去。
我一般会顺手做两个检查,确认库真的进了缓存:
bash复制ldconfig -p | grep usb-1.0
ldconfig -p | grep hidapi
输出里能看到对应库名和路径,再往下写测试程序。看不到就回到 make install 那一步,确认安装前缀和权限,不要急着改测试代码。编译顺序、安装、ldconfig 这三件事是连在一起的,缺一环都会在后面以“设备打不开”的形式表现出来。
3. 编译 hidtest:-lusb-1.0 与 -lhidapi-libusb 到底链了什么
3.1 测试程序的结构:先 libusb 枚举,再 hidapi 打开
材料里的测试程序叫 hidtest.c,结构分成两块:print_devs 用 libusb 打印设备列表,test_hidapi 用 hidapi 打开设备并读数据,main 负责初始化 libusb、遍历设备描述符、拿到 VID/PID 后交给 hidapi。下面这版在材料基础上做了最小整理,补了返回值检查和 vid/pid 初始化,逻辑没有换:
c复制#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <libusb-1.0/libusb.h>
#include <hidapi/hidapi.h>
static void print_devs(libusb_device **devs)
{
libusb_device *dev;
int i = 0;
while ((dev = devs[i++]) != NULL) {
struct libusb_device_descriptor desc;
int r = libusb_get_device_descriptor(dev, &desc);
if (r < 0) {
fprintf(stderr, "failed to get device descriptor\n");
return;
}
printf("%04x:%04x (bus %d, device %d)\n",
desc.idVendor, desc.idProduct,
libusb_get_bus_number(dev), libusb_get_device_address(dev));
}
}
static int test_hidapi(int vid, int pid)
{
printf("vid:%04X,pid:%04X\n", vid, pid);
int res;
hid_device *handle;
res = hid_init();
if (res != 0) {
printf("hid_init failed\n");
return 1;
}
handle = hid_open(vid, pid, NULL);
if (!handle) {
printf("Unable to open device\n");
hid_exit();
return 1;
}
printf("----------------请移动鼠标/触发HID设备-------------------\n");
while (1) {
unsigned char data[64];
int n = hid_read(handle, data, sizeof(data));
if (n < 0) {
printf("读取HID数据失败\n");
break;
}
printf("HID数据: ");
for (int i = 0; i < n; i++) {
printf("%02X ", data[i]);
}
printf("\n");
break; // 测试时读一包就退出,便于观察
}
hid_close(handle);
hid_exit();
return 0;
}
int main(void)
{
int r;
ssize_t cnt;
libusb_device **devs;
libusb_context *ctx = NULL;
struct libusb_device_descriptor desc;
int vid = -1, pid = -1;
r = libusb_init(&ctx);
if (r < 0) {
printf("failed to init libusb\n");
return 1;
}
cnt = libusb_get_device_list(NULL, &devs);
if (cnt < 0) {
printf("failed to get device list\n");
libusb_exit(ctx);
return 1;
}
print_devs(devs);
printf("----------------------libusb测试成功--------------------------------\n");
for (ssize_t i = 0; i < cnt; i++) {
r = libusb_get_device_descriptor(devs[i], &desc);
if (r < 0) {
fprintf(stderr, "无法获取设备描述符: %s\n", libusb_error_name(r));
continue;
}
printf("设备 VID: 0x%04X, PID: 0x%04X, CLASS:%d\n",
desc.idVendor, desc.idProduct, desc.bDeviceClass);
if (desc.bDeviceClass == 0) {
printf("---->候选设备 VID: 0x%04X, PID: 0x%04X\n",
desc.idVendor, desc.idProduct);
vid = desc.idVendor;
pid = desc.idProduct;
break;
}
}
libusb_free_device_list(devs, 1);
libusb_exit(ctx);
if (vid < 0 || pid < 0) {
printf("没有找到候选的 HID 设备,请改用目标设备的 VID/PID\n");
return 1;
}
test_hidapi(vid, pid);
return 0;
}
print_devs 里调用 libusb_get_device_descriptor,失败就打印错误并返回,避免后面拿脏数据。main 里 libusb_init(&ctx) 传入上下文指针的地址,退出时 libusb_exit(ctx) 对应释放;材料里直接写 libusb_init(ctx),如果 ctx 还是 NULL,实际更稳的写法是 &ctx 或 NULL。libusb_get_device_list(NULL, &devs) 拿到设备数组,使用完必须 libusb_free_device_list(devs, 1),第二个参数 1 表示同时释放数组里的设备引用。
test_hidapi 里 hid_init() 先初始化 hidapi,hid_open(vid, pid, NULL) 用 VID/PID 打开设备,第三个参数传 NULL 表示不按序列号筛选。hid_read 的第三个参数是缓冲区容量,示例里用 sizeof(data),也就是 64 字节。读到数据后打印十六进制并 break,是为了测试时只观察一包,不把程序卡在死循环里。实际产品代码会继续循环,并处理 hid_read 的返回值和设备拔出事件。
3.2 编译命令里的 -lusb-1.0 与 -lhidapi-libusb 分别做什么
编译测试程序用材料里的命令:
bash复制gcc hidtest.c -o test -lusb-1.0 -lhidapi-libusb
-lusb-1.0 告诉链接器去找 libusb-1.0 这个库,测试程序里用到的 libusb_init、libusb_get_device_list、libusb_get_device_descriptor 都由它提供。-lhidapi-libusb 告诉链接器去找 hidapi 的 libusb 后端库,hid_init、hid_open、hid_read 这些符号从这里来。
链接顺序值得注意。GCC 按从左到右处理库,如果 hidapi 的库本身依赖 libusb,有时把 -lhidapi-libusb 放在 -lusb-1.0 前面更稳。材料里的顺序是 -lusb-1.0 -lhidapi-libusb,可以先照这个跑;如果报 undefined reference to hid_*,先检查 hidapi 是否 make install,再尝试调换两个 -l 的顺序。不要一看到链接错误就去改 C 代码,多数时候是库没装到链接器找得到的位置。
3.3 运行前为什么要 sudo 或配置设备权限
编译完成后运行:
bash复制sudo ./test
材料里用 sudo 跑,是因为普通用户对 USB 设备节点不一定有读写权限。hid_open 返回 NULL 时,一个很常见的排除法就是先用 sudo 跑一次:如果 sudo 能打开、普通用户打不开,问题就落在权限上;如果 sudo 也打不开,再回去查 VID/PID 和设备是否被别的驱动占用。
sudo 只是排查手段,不是长期方案。实际部署时更合理的做法是给目标设备配 udev 规则,让固定用户组有访问权限。测试阶段先用 sudo 把“代码问题”和“权限问题”分开,能省很多来回。运行后程序会先打印 libusb 枚举到的设备列表,再打印候选 VID/PID,最后提示移动鼠标或触发 HID 设备;如果只看到 libusb 测试成功、没有 HID 数据,就进入下一章的参数检查和排错。
4. 用 libusb 枚举、用 hidapi 读数据:VID/PID 与缓冲区参数怎么定
4.1 用 libusb_get_device_list 拿到设备列表后看什么
libusb_get_device_list(NULL, &devs) 返回的是设备指针数组,print_devs 遍历到 NULL 为止。每个设备先取描述符,重点看三个字段:idVendor、idProduct、bDeviceClass。idVendor 和 idProduct 合起来就是后面 hid_open 要用的 VID/PID;libusb_get_bus_number 和 libusb_get_device_address 用来区分同一型号的多个设备。
材料里的循环把所有设备描述符都打印出来,然后在 desc.bDeviceClass == 0 时记录 VID/PID 并 break。这个写法适合快速找一个候选设备,但不适合直接当成“目标设备识别”。因为 bDeviceClass == 0 的意思是设备类在接口描述符里定义,很多复合设备、厂商自定义设备都会出现这个值;它不代表“这就是鼠标”,也不代表“这就是我要打开的 HID 设备”。
更稳的做法是:先用 print_devs 把总线号、设备地址、VID/PID 全部打出来,人工确认目标设备;再把 vid/pid 写成固定值,或者按接口描述符里的 HID 类过滤。测试阶段不要怕多打日志,设备一多,只看一个 CLASS:0 很容易选错。
4.2 bDeviceClass == 0 不代表就是目标 HID 设备
这是材料代码里最值得多看一眼的地方。bDeviceClass == 0 只说明设备描述符里的类字段是 0,具体类可能在接口描述符里。用这个条件找鼠标,可能发生三种情况:第一种,第一个 CLASS:0 的设备根本不是 HID,hid_open 返回 NULL;第二种,机器上插了多个 CLASS:0 设备,程序选中的不是你要的那个,hid_read 一直读不到;第三种,目标设备本身 bDeviceClass 不是 0,循环走完 vid/pid 还是初始值,hid_open 直接失败。
我一般会把候选条件收窄:先打印所有设备的 VID/PID 和 bus/device,确认目标设备后,把 vid 和 pid 写死;如果要按类过滤,再去看接口描述符里的 bInterfaceClass,而不是只盯设备描述符的 bDeviceClass。材料里的示例是为了演示 libusb 枚举流程,真正接设备时不要把“第一个 CLASS:0”当成通用规则。
参数表可以这样记:
| 参数/字段 | 取值来源 | 作用 | 常见误用 |
|---|---|---|---|
desc.idVendor |
libusb_get_device_descriptor |
厂商标识,传给 hid_open 的 vid |
和字符串形式的 VID 混用 |
desc.idProduct |
同上 | 产品标识,传给 hid_open 的 pid |
复制错设备行 |
desc.bDeviceClass |
设备描述符 | 设备类字段 | 以为 0 就是 HID |
vid/pid |
枚举结果 | hid_open(vid, pid, NULL) 的入参 |
未初始化就传,或找到后没 break |
data[64] |
栈上缓冲区 | 接收 HID 报告 | 缓冲区太小,或把长度写死成 64 但数组改小 |
sizeof(data) |
编译期计算 | 告诉 hid_read 最多写多少字节 |
传错成指针大小 |
4.3 hid_read 的缓冲区大小与返回长度
hid_read(handle, data, sizeof(data)) 的第三个参数是缓冲区容量,不是“期望读多少字节”。返回值 n 才是实际读到的字节数:n > 0 表示读到了一包数据,按 n 循环打印;n == 0 表示没有数据;n < 0 表示读失败。材料里的示例用 unsigned char data[64],对大多数 HID 报告够用,但不同设备报告长度不一样,缓冲区不要小于设备报告长度。
另一个细节是 hid_read 默认是阻塞的,没有数据时程序会停在那里。测试程序里读到一包就 break,是为了避免一直卡住;实际使用时如果不想阻塞,可以用 hid_read_timeout 并设置毫秒超时,或者把读取放在独立线程里。材料没有展开超时接口,这里只提醒:看到程序“没输出”不一定是读失败,可能只是 hid_read 在等数据。
hid_open 的第三个参数是序列号,传 NULL 表示不按序列号筛选。同一 VID/PID 插了多个设备时,传 NULL 可能打开到第一个匹配设备;要精确打开某个设备,需要把序列号读出来再传进去。测试阶段先用 NULL 跑通,再考虑多设备区分。
5. 避坑排查:动态库、权限与 HID 读取的四个翻车点
5.1 编译时报 cannot find -lhidapi-libusb
现象:gcc hidtest.c -o test -lusb-1.0 -lhidapi-libusb 报 cannot find -lhidapi-libusb,或者 hidapi.h 找不到。原因通常是 hidapi 还没 make install,或者只编译了 libusb 就急着编测试程序。hidapi 依赖 libusb,编译顺序反了,./configure 阶段就可能缺依赖;只 make 不 make install,链接器在系统库路径里找不到 libhidapi-libusb.so。
解决:回到 hidapi 源码目录,确认 libusb 已经安装,再执行 ./bootstrap、./configure、make、sudo make install,最后 sudo ldconfig。如果头文件找不到,检查 /usr/local/include/hidapi/hidapi.h 是否存在;如果库找不到,用 ldconfig -p | grep hidapi 确认缓存里有没有。不要用 -I 和 -L 临时绕,先把安装链路走通,否则换台机器还会复现。
5.2 运行时报 error while loading shared libraries
现象:编译通过,运行 ./test 直接报 error while loading shared libraries: libhidapi-libusb.so.0: cannot open shared object file。原因不是代码,而是动态库缓存没更新。sudo make install 把库放进了 /usr/local/lib,但加载器还没刷新缓存,运行时按库名找不到。
解决:执行 sudo ldconfig,再用 ldconfig -p | grep hidapi 和 ldconfig -p | grep usb-1.0 确认库已经进缓存。如果仍然找不到,检查安装前缀是不是 /usr/local,以及 /etc/ld.so.conf 是否包含 /usr/local/lib。临时可以用 LD_LIBRARY_PATH 指过去排查,但长期还是让 ldconfig 接管,不要在每个终端里手工设环境变量。
5.3 hid_open 返回 NULL
现象:程序打印 Unable to open device,hid_open 返回 NULL。原因有三类:VID/PID 不对,设备被内核 HID 驱动占用或权限不足,hidapi 初始化失败但没检查。材料里的代码先 hid_init() 再 hid_open,如果 hid_init 失败,后面也会打不开;另外 vid/pid 如果没初始化,可能传进随机值。
解决:先看 hid_init 的返回值,再确认 vid/pid 是从目标设备描述符里拿的。用 sudo ./test 排除权限;如果 sudo 能打开、普通用户不能,就配 udev 规则。还要确认设备没有被其他程序独占,测试时关掉可能占用 HID 的桌面工具。VID/PID 打印出来后,和 print_devs 里的设备列表对一遍,不要凭记忆填。
5.4 hid_read 一直阻塞或返回 -1
现象:hid_open 成功了,程序停在 hid_read 不动,或者返回 -1 打印“读取HID数据失败”。原因可能是打开的设备不是目标 HID,bDeviceClass == 0 选错了候选;也可能是设备没有产生报告,阻塞读自然等不到数据;还可能是缓冲区长度或报告长度不匹配。
解决:先把 print_devs 的完整列表打出来,确认 bus/device 和 VID/PID 对应的是正在操作的设备;再把 vid/pid 写死,避免循环选错。测试时主动触发设备,比如移动鼠标或按键,观察是否有数据。如果返回 -1,检查 hid_open 的句柄是否有效、设备是否被拔出。材料里的示例读到一包就退出,实际调试时可以加超时读取,避免程序看起来“死掉”。
6. 进阶验证:把一次跑通变成可重复的检查习惯
一次跑通不算完,换机器、换设备、换编译参数都可能翻车。我后来固定了一套检查顺序,先看库,再看依赖,再看设备,最后看数据。库这一层用 ldconfig -p | grep hidapi 和 ldconfig -p | grep usb-1.0 确认缓存;依赖这一层用 ldd ./test 看可执行文件解析到的 libusb 和 hidapi 路径;设备这一层用 sudo ./test 看枚举列表和候选 VID/PID;数据这一层再触发 HID 设备,看十六进制输出。
| 检查项 | 命令 | 预期 |
|---|---|---|
| libusb 缓存 | `ldconfig -p | grep usb-1.0` |
| hidapi 缓存 | `ldconfig -p | grep hidapi` |
| 可执行文件依赖 | ldd ./test |
libusb 和 hidapi 都解析到实际路径,没有 not found |
| 设备枚举 | sudo ./test |
打印 VID/PID、bus/device,并出现候选设备 |
| HID 读取 | 移动鼠标或触发设备 | 打印一包十六进制数据,程序正常退出 |
这套顺序的好处是把问题分层:ldd 报 not found 就是库没装好或缓存没刷新;枚举有设备但 hid_open 失败就是 VID/PID 或权限;hid_open 成功但 hid_read 没数据就是设备选错或没有报告。从那以后我每次编译完 libusb 和 hidapi,都先 sudo ldconfig,再 ldd ./test,最后才跑 sudo ./test,不再靠猜。希望帮到你。
