hidapi

Библиотека HIDAPI для Windows, Linux, FreeBSD и macOS

Экземпляр ЭК	Статус
Linux/macOS/Windows (master)
Windows (master)
BSD, last build (branch/PR)
Coverity Scan (last)

HIDAPI — это многоплатформенная библиотека, которая позволяет приложению взаимодействовать с USB- и Bluetooth-устройствами HID-класса в Windows, Linux, FreeBSD и macOS. HIDAPI может быть либо построен как общая библиотека ( .so , .dll или .dylib ), либо может быть встроен непосредственно в целевое приложение путем добавления одного исходного файла (для каждой платформы) и одного заголовка.
См. примечания по встраиванию непосредственно в вашу систему сборки.

Библиотека HIDAPI изначально была разработана Аланом Оттом (signal11).

Она была перенесена в libusb/hidapi 4 июня 2019 г., чтобы объединить важные исправления ошибок и продолжить разработку библиотеки.

Оглавление

• О
  • Тестовый графический интерфейс
  • Консольное тестовое приложение
• Как выглядит API?
• Лицензия
• Установка ХИДАПИ
• Сборка из исходного кода

О

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 вместе с вашим приложением, чтобы непривилегированные пользователи могли получить доступ к устройствам HID с помощью hidapi. Пример можно найти в файле 69-hid.rules в каталоге udev .

Linux/hidraw ( linux/hid.c ):

Этот серверный интерфейс использует интерфейс hidraw в ядре Linux и поддерживает устройства USB и Bluetooth HID. Для сборки требуется версия ядра не ниже 2.6.39. Кроме того, он будет взаимодействовать только с устройствами, с которыми связаны узлы hidraw. Клавиатуры, мыши и некоторые другие устройства, занесенные в черный список из-за наличия узлов hidraw, работать не будут. К счастью, почти для всех случаев использования hidraw это не проблема.

Linux/FreeBSD/libusb ( libusb/hid.c ):

Этот сервер использует libusb-1.0 для связи напрямую с USB-устройством. Этот сервер, конечно, не будет работать с устройствами Bluetooth.

Тестовый графический интерфейс

HIDAPI также поставляется с тестовым графическим интерфейсом. Тестовый графический интерфейс является кроссплатформенным и использует Fox Toolkit http://www.fox-toolkit.org. Он будет построен на каждой платформе, поддерживаемой HIDAPI. Поскольку он использует стороннюю библиотеку, его сборка необязательна, но полезна при отладке оборудования.

ПРИМЕЧАНИЕ. Тестовый графический интерфейс на основе Fox Toolkit активно не разрабатывается и не поддерживается командой HIDAPI. Он хранится как исторический артефакт. Возможно, когда-нибудь или на некоторых платформах он даже заработает, но никаких новых функций или исправлений в нем не будет.

Инструкции по установке Fox-Toolkit на каждую платформу не предусмотрены. Обязательно используйте Fox-Toolkit v1.6, если вы решите его использовать.

Консольное тестовое приложение

Если вы хотите поэкспериментировать со своим HID-устройством, прежде чем начинать разработку с помощью HIDAPI, и использование приложения с графическим интерфейсом для вас не вариант, вы можете попробовать hidapitester .

Это приложение имеет консольный интерфейс для большинства функций, поддерживаемых библиотекой HIDAPI.

Как выглядит API?

API предоставляет наиболее часто используемые функции HID, включая отправку и получение входных, выходных данных и отчетов о функциях. Пример программы, которая взаимодействует с сильно взломанной версией образца Microchip USB Generic HID, выглядит следующим образом (для простоты проверка ошибок удалена):

Предупреждение. Запускайте только тот код, который вам понятен, и только в том случае, если он соответствует спецификации устройства. Случайная запись данных ( hid_write ) на ваши HID-устройства может привести к их поломке.

 #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.

Установка ХИДАПИ

Если вы хотите создать собственное приложение, использующее устройства HID с HIDAPI, вам необходимо получить пакет разработки HIDAPI.

В зависимости от вашей среды разработки, HIDAPI, скорее всего, будет предоставлен вашим менеджером пакетов.

Например, в Ubuntu HIDAPI доступен через APT:

sudo apt install libhidapi-dev

Имя пакета HIDAPI для других систем/менеджеров пакетов может отличаться. Проверьте документацию/список пакетов вашего менеджера пакетов.

Сборка из исходного кода

Подробности на сайте BUILD.md.