hidapi

HIDAPI-Bibliothek für Windows, Linux, FreeBSD und macOS

CI-Instanz	Status
Linux/macOS/Windows (master)
Windows (master)
BSD, last build (branch/PR)
Coverity Scan (last)

HIDAPI ist eine plattformübergreifende Bibliothek, die es einer Anwendung ermöglicht, mit USB- und Bluetooth-Geräten der HID-Klasse unter Windows, Linux, FreeBSD und macOS zu kommunizieren. HIDAPI kann entweder als gemeinsam genutzte Bibliothek ( .so , .dll oder .dylib ) erstellt oder direkt in eine Zielanwendung eingebettet werden, indem eine einzelne Quelldatei (pro Plattform) und ein einzelner Header hinzugefügt werden.
Siehe Hinweise zur direkten Einbettung in Ihr Build-System.

Die HIDAPI-Bibliothek wurde ursprünglich von Alan Ott (signal11) entwickelt.

Sie wurde am 4. Juni 2019 nach libusb/hidapi verschoben, um wichtige Bugfixes zusammenzuführen und die Entwicklung der Bibliothek fortzusetzen.

Inhaltsverzeichnis

• Um
  • Test-GUI
  • Konsolentest-App
• Wie sieht die API aus?
• Lizenz
• HIDAPI installieren
• Aus der Quelle erstellen

Um

HIDAPI verfügt über vier Back-Ends:

• Windows (mit hid.dll )
• Linux/hidraw (unter Verwendung des Hidraw-Treibers des Kernels)
• libusb (unter Verwendung von libusb-1.0 – Linux/BSD/andere UNIX-ähnliche Systeme)
• macOS (mit IOHidManager)

Unter Linux kann entweder das Hidraw- oder das Libusb-Backend verwendet werden. Es gibt Kompromisse und die unterstützte Funktionalität unterscheidet sich geringfügig. Beide werden standardmäßig erstellt. Es liegt an der Anwendung, die eine Verknüpfung zu hidapi herstellt, das Backend zum Zeitpunkt der Verknüpfung auszuwählen, indem sie entweder eine Verknüpfung zu libhidapi-libusb oder libhidapi-hidraw herstellt.

Beachten Sie, dass Sie eine udev-Regeldatei mit Ihrer Anwendung installieren müssen, damit nichtprivilegierte Benutzer mit Hidapi auf HID-Geräte zugreifen können. Ein Beispiel finden Sie in der Datei 69-hid.rules im udev -Verzeichnis.

Linux/hidraw ( linux/hid.c ):

Dieses Back-End nutzt die Hidraw-Schnittstelle im Linux-Kernel und unterstützt sowohl USB- als auch Bluetooth-HID-Geräte. Zum Erstellen ist mindestens die Kernel-Version 2.6.39 erforderlich. Darüber hinaus kommuniziert es nur mit Geräten, denen Hidraw-Knoten zugeordnet sind. Tastaturen, Mäuse und einige andere Geräte, die wegen Hidraw-Knoten auf der schwarzen Liste stehen, funktionieren nicht. Glücklicherweise ist dies bei fast allen Anwendungen von Hidraw kein Problem.

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

Dieses Back-End verwendet libusb-1.0, um direkt mit einem USB-Gerät zu kommunizieren. Dieses Backend funktioniert natürlich nicht mit Bluetooth-Geräten.

Test-GUI

HIDAPI verfügt außerdem über eine Test-GUI. Die Test-GUI ist plattformübergreifend und verwendet Fox Toolkit http://www.fox-toolkit.org. Es wird auf jeder Plattform aufbauen, die HIDAPI unterstützt. Da es auf einer Bibliothek eines Drittanbieters basiert, ist die Erstellung optional, aber beim Debuggen von Hardware nützlich.

HINWEIS: Die auf Fox Toolkit basierende Test-GUI wird vom HIDAPI-Team weder aktiv entwickelt noch unterstützt. Es wird als historisches Artefakt aufbewahrt. Es könnte sogar irgendwann oder auf einigen Plattformen funktionieren, aber es wird keine neuen Funktionen oder Bugfixes geben.

Anweisungen zur Installation von Fox-Toolkit auf jeder Plattform werden nicht bereitgestellt. Stellen Sie sicher, dass Sie Fox-Toolkit v1.6 verwenden, wenn Sie es verwenden möchten.

Konsolentest-App

Wenn Sie mit Ihrem HID-Gerät herumspielen möchten, bevor Sie mit der Entwicklung mit HIDAPI beginnen, und die Verwendung einer GUI-App für Sie keine Option ist, können Sie hidapitester ausprobieren.

Diese App verfügt über eine Konsolenschnittstelle für die meisten von der HIDAPI-Bibliothek unterstützten Funktionen.

Wie sieht die API aus?

Die API stellt die am häufigsten verwendeten HID-Funktionen bereit, einschließlich des Sendens und Empfangens von Eingabe-, Ausgabe- und Funktionsberichten. Das Beispielprogramm, das mit einer stark gehackten Version des Microchip USB Generic HID-Beispiels kommuniziert, sieht folgendermaßen aus (der Einfachheit halber wurde die Fehlerprüfung entfernt):

Warnung: Führen Sie nur den Code aus, den Sie verstehen, und nur, wenn er der Gerätespezifikation entspricht. Das wahllose Schreiben von Daten ( hid_write ) auf Ihre HID-Geräte kann diese beschädigen.

 #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 ;
}

Sie können hidtest/test.c auch als Ausgangspunkt für Ihre Anwendungen verwenden.

Lizenz

HIDAPI kann mit einer von drei Lizenzen verwendet werden, wie in LICENSE.txt beschrieben.

HIDAPI installieren

Wenn Sie Ihre eigene Anwendung erstellen möchten, die HID-Geräte mit HIDAPI verwendet, benötigen Sie das HIDAPI-Entwicklungspaket.

Abhängig von Ihrer Entwicklungsumgebung wird HIDAPI wahrscheinlich von Ihrem Paketmanager bereitgestellt.

Unter Ubuntu ist HIDAPI beispielsweise über APT verfügbar:

sudo apt install libhidapi-dev

Der HIDAPI-Paketname für andere Systeme/Paketmanager kann abweichen. Überprüfen Sie die Dokumentation/Paketliste Ihres Paketmanagers.

Aus der Quelle erstellen

Weitere Informationen finden Sie in BUILD.md.