hid

package module
Version: v0.9.1-0...-e1ffd6f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 7, 2019 License: BSD-3-Clause, LGPL-2.1 Imports: 1 Imported by: 0

README

Travis AppVeyor GoDoc

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. On Linux the package also wraps libusb. Both of these dependencies are vendored directly into the repository and wrapped using CGO, making the hid package self-contained and go-gettable.

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

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, causing device enumeration hid.Enumerate() to yield no results.

To cross compile a functional version of this library, 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 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:

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.

Index

Constants

This section is empty.

Variables

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

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

View Source
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 USB HID and not having to fall back to build constraints.

Types

type Device

type Device struct {
	DeviceInfo // Embed the infos for easier access
}

Device is a live HID USB connected device handle. On platforms that this file implements the type lacks the actual HID device and all methods are noop.

func (*Device) Close

func (dev *Device) Close() error

Close releases the HID USB device handle. On platforms that this file implements the method is just a noop.

func (*Device) Read

func (dev *Device) Read(b []byte) (int, error)

Read retrieves an input report from a HID device. On platforms that this file implements the method just returns an error.

func (*Device) Write

func (dev *Device) Write(b []byte) (int, error)

Write sends an output report to a HID device. On platforms that this file implements the method just returns an error.

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 is a hidapi info structure.

func Enumerate

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

Enumerate returns a list of all the HID devices attached to the system which match the vendor and product id. On platforms that this file implements the function is a noop and returns an empty list always.

func (DeviceInfo) Open

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

Open connects to an HID device by its path name. On platforms that this file implements the method just returns an error.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL