hidapi

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

CI实例	地位
Linux/macOS/Windows (master)
Windows (master)
BSD, last build (branch/PR)
Coverity Scan (last)

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

HIDAPI 库最初由 Alan Ott (signal11) 开发。

它于 2019 年 6 月 4 日转移到 libusb/hidapi，以合并重要的错误修复并继续库的开发。

目录

• 关于
  • 测试图形用户界面
  • 控制台测试应用程序
• API 是什么样的？
• 执照
• 安装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 设备通信。该后端当然不适用于蓝牙设备。

测试图形用户界面

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

注意：HIDAPI 团队并未积极开发或支持基于 Fox Toolkit 的测试 GUI。它被作为历史文物保存下来。它甚至可能有时或在某些平台上工作，但它不会获得任何新功能或错误修复。

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

控制台测试应用程序

如果您想在开始使用 HIDAPI 进行任何开发之前先尝试一下 HID 设备，并且使用 GUI 应用程序不适合您，您可以尝试hidapitester 。

该应用程序有一个控制台界面，可实现 HIDAPI 库支持的大部分功能。

API 是什么样的？

API 提供最常用的 HID 功能，包括发送和接收输入、输出和功能报告。与 Microchip USB Generic HID 示例的严重破解版本进行通信的示例程序如下所示（为简单起见，删除了错误检查）：

警告：仅运行您理解的代码，并且仅当它符合设备规范时。向 HID 设备随机写入数据 ( hid_write ) 可能会破坏它们。

 #include  // printf
#include  // wchar_t

#include 

#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 devicen" );
		hid_exit ();
 		return 1 ;
	}

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

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

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

	// Read Indexed String 1
	res = hid_get_indexed_string ( handle , 1 , wstr , MAX_STR );
	printf ( "Indexed String 1: %lsn" , 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]: %dn" , 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

如果您想构建自己的使用 HID 设备和 HIDAPI 的应用程序，您需要获取 HIDAPI 开发包。

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

例如在 Ubuntu 上，HIDAPI 可通过 APT 获得：

sudo apt install libhidapi-dev

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

从源代码构建

检查 BUILD.md 了解详细信息。