|
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.
[Как выглядит API библиотеки?]
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]
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) Вы можете выполнить следующую команду:
git clone git://github.com/signal11/hidapi.git
[Инструкции по сборке]
Windows. Выполните сборку под управлением Visual Studio, загрузив файл .sln. Он находится в каталоге windows/ архива.
Linux. Перейдите в директорию linux/ и запустите команду make.
Mac OS X. Перейдите в директорию mac/ и запустите команду make.
[Как собрать тестовое GUI-приложение]
Windows. Выполните сборку под управлением Visual Studio, загрузив файл .sln. Он находится в каталоге hidtest/ архива. Убедитесь, что Вы предварительно настроили внешние зависимости (externals, Fox Toolkit), как это описано в файле README.txt.
Linux и Mac. Запустите команду make из каталога hidtest/. Убедитесь, что Вы перед этим установили fox-toolkit, как это описано в файле README.txt
[Контактная информация]
В момент написания статьи список рассылки (mailing list) пока не был готов. В настоящее время обращайтесь с замечаниями и вопросами на email alan@signal11.us.
[Ссылки]
1. HID API for Linux, Mac OS X, and Windows site:signal11.us.
2. hidapi API site:signal11.us.
3. Библиотеки для управления устройствами USB HID. |
