hid

README

Gopher Interface Devices (USB HID)

The hid package is a cross platform library for accessing and communicating with USB Human Interface Devices (HID). It is an alternative package to gousb for use cases where devices support this ligher mode of operation (e.g. input devices, hardware crypto wallets).

The package wraps hidapi for accessing OS specific USB HID APIs directly instead of using low level USB constructs, which might have permission issues on some platforms. The hidapi dependency is vendored directly into the repository and wrapped using CGO (or ccgo/purego for targets that support CGO less operation), making the hid package self-contained and go-gettable.

Supported platforms at the moment are Linux, macOS, Windows, majority of BSD platforms and Android (exclude constraints are also specified for iOS to allow smoother vendoring into cross platform projects).

The hidapi on linux unfortunately requires libuddev (libudev-dev on ubuntu, systemd-devel on fedora). Therefore, this library includes libusb which we use as a backend on linux, and thus avoid runtime dependencies.

API differences from github.com/karalabe/hid

This fork is intended to stay close to upstream but fixes a few sharp edges for embedders:

• Enumerate(vid, pid) returns ([]DeviceInfo, error) — propagation of enumeration failures (e.g. transient USB errors) instead of only []DeviceInfo.
• Device is an interface — store opened handles as hid.Device, not *hid.Device. A pointer to an interface is almost never what you want and will not implement Device.

When CGO_ENABLED=0 (or unsupported OS), the stub implementation in hid_disabled.go is used: Supported() is false and Enumerate returns empty results with a nil error unless extended later for a CGO-less backend.

Cross-compiling

Using go get the embedded C library is compiled into the binary format of your host OS. Cross compiling to a different platform or architecture entails disabling CGO by default in Go. This library supports CGO less operation by using a transpiled libusb driver via ccgo.

To cross compile a functional version of this library simply disable CGO and you should be ready, on targets/architectures not supported by ccgo you'll need to enable CGO during cross compilation via CGO_ENABLED=1 and you'll need to install and set a cross compilation enabled C toolkit via CC=your-cross-gcc.

Acknowledgements

Although the hid package is an implementation from scratch, it was heavily inspired by the existing hid library, which seems abandoned since 2022 and the go.hid library, which seems abandoned since 2015; is incompatible with Go 1.6+; and has various external dependencies. Given its inspirational roots, I thought it important to give credit to the author of said package too.

Wide character support in the hid package is done via the gowchar library, unmaintained since 2013; non buildable with a modern Go release and failing go vet checks. As such, gowchar was also vendored in inline (copyright headers and origins preserved).

License

The components of hid are licensed as such:

• hidapi is released under the three licenses: GPL-V3, 3-clause BSD and original HIDAPI license.
• libusb is released under GPLv2.1
• go.hid was released under the 2-clause BSD license.
• gowchar is released under the 3-clause BSD license.

Given the above, hid is licensed under GNU LGPL 2.1 or later on Linux and 3-clause BSD on other platforms.

Documentation

Overview

Package hid provides an interface for USB HID devices.

Package hid provides an interface for USB HID devices.

Index

• Variables
• func Supported() bool
• type Device
• type DeviceInfo
  • func Enumerate(vendorID uint16, productID uint16) ([]DeviceInfo, error)
  • func (info DeviceInfo) Open() (Device, error)

Variables

var ErrDeviceClosed = errors.New("hid: device closed")

ErrDeviceClosed is returned for operations where the device closed before or during the execution.

var ErrUnsupportedPlatform = errors.New("hid: unsupported platform")

ErrUnsupportedPlatform is returned for all operations where the underlying operating system is not supported by the library.

Functions

func Supported

func Supported() bool

Supported returns whether this platform is supported by the HID library or not. The goal of this method is to allow programatically handling platforms that do not support HID and not having to fall back to build constraints.

Types

type Device

type Device interface {
	// Close releases the USB device handle.
	Close() error

	// Write sends a binary blob to a USB device. For HID devices write uses reports,
	// for low level USB write uses interrupt transfers.
	Write(b []byte) (int, error)

	// Read retrieves a binary blob from a USB device. For HID devices read uses
	// reports, for low level USB read uses interrupt transfers.
	Read(b []byte) (int, error)

	// Read retrieves a binary blob from a USB device, using a timeout. A timeout
	// of 0 means blocking.
	ReadTimeout(b []byte, timeout int) (int, error)

	// GetFeatureReport retreives a feature report from a HID device
	//
	// Set the first byte of []b to the Report ID of the report to be read. Make
	// sure to allow space for this extra byte in []b. Upon return, the first byte
	// will still contain the Report ID, and the report data will start in b[1].
	GetFeatureReport(b []byte) (int, error)

	// SendFeatureReport sends a feature report to a HID device
	//
	// Feature reports are sent over the Control endpoint as a Set_Report transfer.
	// The first byte of b must contain the Report ID. For devices which only
	// support a single report, this must be set to 0x0. The remaining bytes
	// contain the report data. Since the Report ID is mandatory, calls to
	// SendFeatureReport() will always contain one more byte than the report
	// contains. For example, if a hid report is 16 bytes long, 17 bytes must be
	// passed to SendFeatureReport(): the Report ID (or 0x0, for devices
	// which do not use numbered reports), followed by the report data (16 bytes).
	// In this example, the length passed in would be 17.
	SendFeatureReport(b []byte) (int, error)
}

Device is a generic USB device interface. It may either be backed by a USB HID device or a low level raw (libusb) device.

type DeviceInfo

type DeviceInfo struct {
	Path         string // Platform-specific device path
	VendorID     uint16 // Device Vendor ID
	ProductID    uint16 // Device Product ID
	Release      uint16 // Device Release Number in binary-coded decimal, also known as Device Version Number
	Serial       string // Serial Number
	Manufacturer string // Manufacturer String
	Product      string // Product string
	UsagePage    uint16 // Usage Page for this Device/Interface (Windows/Mac only)
	Usage        uint16 // Usage for this Device/Interface (Windows/Mac only)

	// The USB interface which this logical device
	// represents. Valid on both Linux implementations
	// in all cases, and valid on the Windows implementation
	// only if the device contains more than one interface.
	Interface int
}

DeviceInfo contains all the information we know about a USB device.

func Enumerate

func Enumerate(vendorID uint16, productID uint16) ([]DeviceInfo, error)

Enumerate returns a list of all the HID devices attached to the system which match the vendor and product id:

• If the vendor id is set to 0 then any vendor matches.
• If the product id is set to 0 then any product matches.
• If the vendor and product id are both 0, all HID devices are returned.

func (DeviceInfo) Open

func (info DeviceInfo) Open() (Device, error)

Open connects to a previsouly discovered HID device.