hidapi

Windows、Linux、FreeBSD 和 macOS 的 HIDAPI 库

CI 实例	状态
`Linux/macOS/Windows (master)`
`Windows (master)`
`BSD, 最新构建 (分支/PR)`
`Coverity Scan (最新)`

HIDAPI 是一个多平台库，允许应用程序在 Windows、Linux、FreeBSD 和 macOS 上与 USB 和蓝牙 HID 类设备进行交互。HIDAPI 可以构建为共享库（.so、.dll 或 .dylib），也可以通过添加单个源文件（每个平台）和单个头文件直接嵌入目标应用程序中。<br> 有关直接嵌入到构建系统中的说明，请参阅 remarks。

HIDAPI 库最初由 Alan Ott（signal11）开发。

为了合并重要的错误修复并继续开发该库，它于 2019 年 6 月 4 日被移至 libusb/hidapi。

关于

HIDAPI 有四个后端：

Windows（使用 hid.dll）
Linux/hidraw（使用内核的 hidraw 驱动程序）
libusb（使用 libusb-1.0 - Linux/BSD/其他类 UNIX 系统）
macOS（使用 IOHidManager）

在 Linux 上，可以使用 hidraw 或 libusb 后端。它们各有利弊，支持的功能略有不同。默认情况下，两者都会被构建。链接到 hidapi 的应用程序可以在链接时通过链接到 libhidapi-libusb 或 libhidapi-hidraw 来选择后端。

请注意，您需要在应用程序中安装 udev 规则文件，以便非特权用户能够使用 hidapi 访问 HID 设备。请参考 udev 目录中的 69-hid.rules 文件作为示例。

Linux/hidraw（`linux/hid.c`）：

此后端使用 Linux 内核中的 hidraw 接口，支持 USB 和蓝牙 HID 设备。它需要至少 2.6.39 版本的内核才能构建。此外，它只能与具有关联 hidraw 节点的设备通信。键盘、鼠标和其他被列入黑名单的设备没有 hidraw 节点，因此无法工作。幸运的是，对于 hidraw 的绝大多数用途来说，这不是问题。

Linux/FreeBSD/libusb（`libusb/hid.c`）：

此后端使用 libusb-1.0 直接与 USB 设备通信。这个后端当然不适用于蓝牙设备。

测试 GUI

HIDAPI 还附带一个测试 GUI。测试 GUI 是跨平台的，使用 Fox Toolkit http://www.fox-toolkit.org。它可以在 HIDAPI 支持的每个平台上构建。由于它依赖于第三方库，构建它是可选的，但在调试硬件时很有用。

注意：基于 Fox Toolkit 的测试 GUI 不再由 HIDAPI 团队积极开发或支持。它被保留作为历史产物。它可能在某些时候或某些平台上仍然可以工作，但不会获得任何新功能或错误修复。

不提供在每个平台上安装 Fox-Toolkit 的说明。如果您选择使用它，请确保使用 Fox-Toolkit v1.6。

控制台测试应用

如果你想在开始使用HIDAPI进行开发之前尝试你的HID设备，而且使用GUI应用程序不是你的选择，你可以试试hidapitester。

这个应用程序为HIDAPI库支持的大多数功能提供了控制台界面。

API是什么样的？

该API提供了最常用的HID功能，包括发送和接收输入、输出和特征报告。下面是一个与Microchip USB通用HID示例的高度修改版本通信的示例程序（为了简单起见，省略了错误检查）：

警告：只运行你理解的代码，并且只在符合设备规格时运行。随意向HID设备写入数据（hid_write）可能会损坏它们。

#include <stdio.h> // printf
#include <wchar.h> // wchar_t

#include <hidapi.h>

#define MAX_STR 255

int main(int argc, char* argv[])
{
	int res;
	unsigned char buf[65];
	wchar_t wstr[MAX_STR];
	hid_device *handle;
	int i;

	// 初始化hidapi库
	res = hid_init();

	// 使用VID、PID和可选的序列号打开设备
	handle = hid_open(0x4d8, 0x3f, NULL);
	if (!handle) {
		printf("无法打开设备\n");
		hid_exit();
 		return 1;
	}

	// 读取制造商字符串
	res = hid_get_manufacturer_string(handle, wstr, MAX_STR);
	printf("制造商字符串：%ls\n", wstr);

	// 读取产品字符串
	res = hid_get_product_string(handle, wstr, MAX_STR);
	printf("产品字符串：%ls\n", wstr);

	// 读取序列号字符串
	res = hid_get_serial_number_string(handle, wstr, MAX_STR);
	printf("序列号字符串：(%d) %ls\n", wstr[0], wstr);

	// 读取索引字符串1
	res = hid_get_indexed_string(handle, 1, wstr, MAX_STR);
	printf("索引字符串1：%ls\n", wstr);

	// 切换LED（命令0x80）。第一个字节是报告编号（0x0）。
	buf[0] = 0x0;
	buf[1] = 0x80;
	res = hid_write(handle, buf, 65);

	// 请求状态（命令0x81）。第一个字节是报告编号（0x0）。
	buf[0] = 0x0;
	buf[1] = 0x81;
	res = hid_write(handle, buf, 65);

	// 读取请求的状态
	res = hid_read(handle, buf, 65);

	// 打印返回的缓冲区
	for (i = 0; i < 4; i++)
		printf("buf[%d]: %d\n", i, buf[i]);

	// 关闭设备
	hid_close(handle);

	// 结束hidapi库
	res = hid_exit();

	return 0;
}