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를 사용하는 거의 모든 경우에는 문제가 되지 않습니다.

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을 사용하려면 반드시 Fox-Toolkit v1.6을 사용하세요.

콘솔 테스트 앱

HIDAPI로 개발을 시작하기 전에 HID 장치를 시험해보고 싶고 GUI 앱을 사용할 수 없는 경우 hidapitester 사용해 볼 수 있습니다.

이 앱에는 HIDAPI 라이브러리에서 지원하는 대부분의 기능에 대한 콘솔 인터페이스가 있습니다.

API는 어떤 모습인가요?

API는 입력, 출력 및 기능 보고서 전송 및 수신을 포함하여 가장 일반적으로 사용되는 HID 기능을 제공합니다. 심하게 해킹된 Microchip USB Generic HID 샘플 버전과 통신하는 샘플 프로그램은 다음과 같습니다(단순화를 위해 오류 검사가 제거됨).

경고: 이해하고 있는 코드만 실행하고 장치 사양을 준수하는 경우에만 실행하세요. 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에 설명된 세 가지 라이선스 중 하나에서 사용될 수 있습니다.

HIDAPI 설치

HIDAPI와 함께 HID 장치를 사용하는 자체 애플리케이션을 구축하려면 HIDAPI 개발 패키지를 받아야 합니다.

개발 환경에 따라 패키지 관리자가 HIDAPI를 제공할 수도 있습니다.

예를 들어 Ubuntu에서는 APT를 통해 HIDAPI를 사용할 수 있습니다.

sudo apt install libhidapi-dev

다른 시스템/패키지 관리자의 HIDAPI 패키지 이름은 다를 수 있습니다. 패키지 관리자의 문서/패키지 목록을 확인하세요.

소스에서 빌드

자세한 내용은 BUILD.md를 확인하세요.