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 および Bluetooth HID クラス デバイスとインターフェイスできるようにするマルチプラットフォーム ライブラリです。 HIDAPI は、共有ライブラリ ( .so 、 .dllまたは.dylib ) として構築することも、単一のソースファイル (プラットフォームごと) と単一のヘッダーを追加することでターゲット アプリケーションに直接埋め込むこともできます。
ビルド システムに直接埋め込む場合の注意事項を参照してください。

HIDAPI ライブラリはもともと Alan Ott (signal11) によって開発されました。

重要なバグ修正をマージし、ライブラリの開発を継続するために、2019 年 6 月 4 日に libusb/hidapi に移動されました。

目次

• について
  • GUIのテスト
  • コンソールテストアプリ
• API はどのようなものですか?
• ライセンス
• HIDAPI のインストール
• ソースからビルドする

について

HIDAPI には 4 つのバックエンドがあります。

• Windows ( hid.dll使用)
• Linux/hidraw (カーネルの hidraw ドライバーを使用)
• libusb (libusb-1.0 - Linux/BSD/その他の UNIX 系システムを使用)
• macOS (IOHidManager を使用)

Linux では、hidraw または libusb バックエンドのいずれかを使用できます。トレードオフがあり、サポートされる機能が若干異なります。どちらもデフォルトでビルドされます。 libhidapi-libusbまたはlibhidapi-hidrawのいずれかにリンクすることにより、リンク時にバックエンドを選択するかどうかは、hidapi にリンクするアプリケーション次第です。

特権のないユーザーが hidapi を使用して HID デバイスにアクセスできるようにするには、アプリケーションに udev ルール ファイルをインストールする必要があることに注意してください。例については、 udevディレクトリ内の 69-hid.rules ファイルを参照してください。

Linux/hidraw ( linux/hid.c ):

このバックエンドは、Linux カーネルの hidraw インターフェイスを使用し、USB と Bluetooth HID デバイスの両方をサポートします。ビルドするにはカーネル バージョン 2.6.39 以上が必要です。さらに、hidraw ノードが関連付けられているデバイスとのみ通信します。 hidraw ノードを持つためにブラックリストに登録されているキーボード、マウス、その他の一部のデバイスは動作しません。幸いなことに、hidraw のほぼすべての使用において、これは問題になりません。

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

このバックエンドは libusb-1.0 を使用して USB デバイスと直接通信します。もちろん、このバックエンドは Bluetooth デバイスでは動作しません。

GUIのテスト

HIDAPI にはテスト GUI も付属しています。テスト GUI はクロスプラットフォームであり、Fox Toolkit http://www.fox-toolkit.org を使用します。 HIDAPI がサポートするすべてのプラットフォーム上に構築されます。サードパーティのライブラリに依存しているため、ビルドはオプションですが、ハードウェアをデバッグするときに役立ちます。

注: Fox Toolkit に基づくテスト GUI は、HIDAPI チームによって積極的に開発またはサポートされていません。歴史的遺物として保管されています。いつか、または一部のプラットフォームで動作する可能性もありますが、新しい機能やバグ修正は行われません。

各プラットフォームに 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 に概要が記載されている 3 つのライセンスのいずれかで使用できます。

HIDAPI のインストール

HIDAPI で HID デバイスを使用する独自のアプリケーションを構築する場合は、HIDAPI 開発パッケージを入手する必要があります。

開発環境に応じて、HIDAPI はパッケージ マネージャーによって提供される可能性があります。

たとえば、Ubuntu では、APT 経由で HIDAPI を利用できます。

sudo apt install libhidapi-dev

他のシステム/パッケージ マネージャーの HIDAPI パッケージ名は異なる場合があります。パッケージ マネージャーのドキュメント/パッケージ リストを確認してください。

ソースからビルドする

詳細については、BUILD.md を確認してください。