hidapi 0.14.0

hidapi 0.14.0

×

由Ihor Dutchak、Vitaly Samoylik 维护。

hidapi 0.14.0

  • 作者
  • Alan Ott、Ludovic Rousseau和libusb/hidapi团队

适用于Windows、Linux、FreeBSD和macOS的HIDAPI库

CI实例 状态
Linux/macOS/Windows (master) GitHub Builds
Windows (master) Build status
BSD，最后构建（分支/PR） builds.sr.ht status
Coverity Scan（最后） Coverity Scan

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

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 来选择链接时的后端。

注意，为了让无权的用户能够通过 hidapi 访问 HID 设备，您需要为应用程序安装一个 udev 规则文件。请参考 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设备，您可能想尝试使用hidapitester。

该应用程序具有控制台接口，可以支持HIDAPI库的大部分功能。

API看起来像什么？

该API提供了最常用的HID功能，包括发送和接收输入、输出和功能报告。以下是与经过大量修改的Microchip USB Generic 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;

	// Initialize the hidapi library
	res = hid_init();

	// Open the device using the VID, PID,
	// and optionally the Serial number.
	handle = hid_open(0x4d8, 0x3f, NULL);
	if (!handle) {
		printf("Unable to open device\n");
		hid_exit();
 		return 1;
	}

	// Read the Manufacturer String
	res = hid_get_manufacturer_string(handle, wstr, MAX_STR);
	printf("Manufacturer String: %ls\n", wstr);

	// Read the Product String
	res = hid_get_product_string(handle, wstr, MAX_STR);
	printf("Product String: %ls\n", wstr);

	// Read the Serial Number String
	res = hid_get_serial_number_string(handle, wstr, MAX_STR);
	printf("Serial Number String: (%d) %ls\n", wstr[0], wstr);

	// Read Indexed String 1
	res = hid_get_indexed_string(handle, 1, wstr, MAX_STR);
	printf("Indexed String 1: %ls\n", wstr);

	// Toggle LED (cmd 0x80). The first byte is the report number (0x0).
	buf[0] = 0x0;
	buf[1] = 0x80;
	res = hid_write(handle, buf, 65);

	// Request state (cmd 0x81). The first byte is the report number (0x0).
	buf[0] = 0x0;
	buf[1] = 0x81;
	res = hid_write(handle, buf, 65);

	// Read requested state
	res = hid_read(handle, buf, 65);

	// Print out the returned buffer.
	for (i = 0; i < 4; i++)
		printf("buf[%d]: %d\n", i, buf[i]);

	// Close the device
	hid_close(handle);

	// Finalize the hidapi library
	res = hid_exit();

	return 0;
}

你也可以将hidtest/test.c作为你应用程序的起点。

许可证

HIDAPI可以使用三个许可证之一，具体请参阅LICENSE.txt。

安装HIDAPI

如果你想使用HIDAPI构建自己的应用程序，你还需要得到HIDAPI开发包。

根据你的开发环境，HIDAPI可能由你的包管理器提供。

例如，在Ubuntu上，HIDAPI可以通过APT提供

sudo apt install libhidapi-dev

其他系统/软件包管理器的HIDAPI软件包名称可能不同。请检查你的包管理器的文档/软件包列表。

从源码构建

详细信息请参见BUILD.md。