HID API для Linux, Mac OS X и Windows | pc

HIDAPI это многоплатформенная библиотека, которая позволяет писать приложения (ПО хоста USB) с доступом к интерфейсам устройств USB и Bluetooth HID-Class на операционных системах Windows, Linux и Mac OS X. В то время как эта библиотека может использоваться для обмена данными со стандартными устройствами HID наподобие клавиатур, мышей и джойстиков, особенно полезное применение библиотеки - работа с пользовательскими (определенными производителем, Vendor-Defined) устройствами HID. Множество устройств работают так, что не требуется писать специальный драйвер для каждой платформы. HIDAPI просто интегрируется с клиентским приложением (ПО хоста), потому что нужно всего лишь подключить в проект файл исходного кода. На платформе Windows, HIDAPI также можно опционально использовать как функции в DLL.

Программы, которые используют HIDAPI, не нуждаются в драйверах. Это означает, что не требуется применять пользовательский драйвер для каждого устройства на каждой платформе.

HIDAPI предоставляет ясный и непротиворечивый программный интерфейс для каждой платформы (операционной системы), что делает простым написание приложений, которые обмениваются данными с устройствами USB HID, при этом нет необходимости вдаваться в детали библиотек HID и интерфейсов операционной системы на каждой платформе.

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

Doxygen HTML документацию Вы можете просмотреть по ссылке [2].

API предоставляет простой метод для энумерации устройств HID, подключенных к системе, и простой доступ к наиболее часто используемым функциям HID, включая передачу данных Input Reports, Output Reports и Feature Reports. Ниже приведен пример программы, которая обменивается данными с модифицированной версией примера USB HID устройства (USB Generic HID sample), взятое из Microchip Application Library (находится в папке "Microchip Solutions\USB Device - HID - Custom Demos\Generic HID - Firmware", когда установлен Microchip Application Framework). Для упрощения из кода удалена проверка / обработка ошибок:

#include < stdio.h >

#include < stdlib.h >

#include "hidapi.h"

int main(int argc, char* argv[])
{
   int res;
   unsigned char buf[65];

   #define MAX_STR 255
   wchar_t wstr[MAX_STR];
   hid_device *handle;
   int i;
 
   // Энумерация и вывод информации всех устройств HID, подключенных к системе
   struct hid_device_info *devs, *cur_dev;   
 
   devs = hid_enumerate(0x0, 0x0);
   cur_dev = devs;
   while (cur_dev)
   {
      printf("Device Found\n  type: %04hx %04hx\n  path: %s\n  serial_number: %ls",
             cur_dev->vendor_id, cur_dev->product_id, cur_dev->path, cur_dev->serial_number);
      printf("\n");
      printf("  Manufacturer: %ls\n", cur_dev->manufacturer_string);
      printf("  Product:      %ls\n", cur_dev->product_string);
      printf("\n");
      cur_dev = cur_dev->next;
   }
   hid_free_enumeration(devs);
 
   // Открытие устройства, используя VID, PID,
   // и опционально серийный номер.
   handle = hid_open(0x4d8, 0x3f, NULL);
 
   // Чтение строки описания производителя (Manufacturer String)
   res = hid_get_manufacturer_string(handle, wstr, MAX_STR);
   printf("Manufacturer String: %ls\n", wstr);   
 
   // Чтение строки описания продукта (Product String)
   res = hid_get_product_string(handle, wstr, MAX_STR);
   printf("Product String: %ls\n", wstr);   
 
   // Чтение строки с серийным номером устройства (Serial Number String)
   res = hid_get_serial_number_string(handle, wstr, MAX_STR);
   printf("Serial Number String: %ls", wstr);
   printf("\n");   
 
   // Послать в устройство Feature Report
   buf[0] = 0x2; // В первом байте находится номер репорта
   buf[1] = 0xa0;
   buf[2] = 0x0a;
   res = hid_send_feature_report(handle, buf, 17);   
 
   // Чтение Feature Report из устройства
   buf[0] = 0x2;
   res = hid_get_feature_report(handle, buf, sizeof(buf));   
 
   // Вывод на экран прочитанных данных.
   printf("Feature Report\n   ");
   for (i = 0; i < res; i++)
      printf("%02hhx ", buf[i]);
   printf("\n");   
 
   // Установка функции hid_read() в неблокирующий режим.
   hid_set_nonblocking(handle, 1);   
 
   // Послать Output report, чтобы переключить светодиод LED (команда 0x80)
   buf[0] = 1; // В первом байте находится номер репорта
   buf[1] = 0x80;
   res = hid_write(handle, buf, 65);   
 
   // Послать Output report, чтобы запросить состояние (команда 0x81)
   buf[1] = 0x81;
   hid_write(handle, buf, 65);   
 
   // Прочитать запрошенное состояние
   res = hid_read(handle, buf, 65);
   if (res < 0)
      printf("Unable to read()\n");
 
   // Вывод на экран прочитанных данных.
   for (i = 0; i < res; i++)
      printf("buf[%d]: %d\n", i, buf[i]);   
 
   return 0;
}

HIDAPI может использоваться под управлением одной из трех лицензий, как это описано в общих чертах в файле LICENSE.txt. Вот эти лицензии: GPL v3 (см. LICENSE-gpl3.txt), BSD (см. LICENSE-bsd.txt), и более свободная оригинальная лицензия HIDAPI (см. LICENSE-orig.txt). Пользователь HIDAPI (разработчик, кто применяет HIDAPI в своем коде) может выбрать использование HIDAPI под любой из этих 3 лицензий по своему усмотрению. Например, автор программного обеспечения GPL может захотеть использовать HIDAPI по правилам GPL. Автор коммерческих продуктов с закрытым исходным кодом может использовать HIDAPI по правилам либо лицензии BSD-style, либо оригинальной лицензии HIDAPI.

При создании HIDAPI была идея сделать её доступной по возможности для максимального количества категорий пользователей, включая open-source и closed-source приложения, и предоставить гибкость для соединения с кодом так, как считает целесообразным разработчик.

HIDAPI можно загрузить с сайта GitHub. Пакет в виде zip-файла доступен на странице загрузки (Download Page). Чтобы получить последнюю ревизию транка (если у Вас установлена система управления версиями git) Вы можете выполнить следующую команду:

Windows. Выполните сборку под управлением Visual Studio, загрузив файл .sln. Он находится в каталоге windows/ архива.

Linux. Перейдите в директорию linux/ и запустите команду make.

Mac OS X. Перейдите в директорию mac/ и запустите команду make.

Windows. Выполните сборку под управлением Visual Studio, загрузив файл .sln. Он находится в каталоге hidtest/ архива. Убедитесь, что Вы предварительно настроили внешние зависимости (externals, Fox Toolkit), как это описано в файле README.txt.

Linux и Mac. Запустите команду make из каталога hidtest/. Убедитесь, что Вы перед этим установили fox-toolkit, как это описано в файле README.txt

В момент написания статьи список рассылки (mailing list) пока не был готов. В настоящее время обращайтесь с замечаниями и вопросами на email alan@signal11.us.