usb

README

Yet another USB library for Go

The usb package is a cross platform, fully self-contained library for accessing and communicating with USB devices either via HID or low level interrupts. The goal of the library was to create a simple way to find-, attach to- and read/write form USB devices.

There are multiple already existing USB libraries:

• The original gousb package created by @kylelemons and nowadays maintained by @google is a CGO wrapper around libusb. It is the most advanced USB library for Go out there.
  • Unfortunately, gousb requires the libusb C library to be installed both during build as well as during runtime on the host operating system. This breaks binary portability and also adds unnecessary hurdles on Windows.
  • Furthermore, whilst HID devices are supported by libusb, the OS on Macos and Windows explicitly takes over these devices, so only native system calls can be used on recent versions (i.e. you cannot use libusb for HID).
• There is a fork of gousb created by @karalabe that statically linked libusb during build, but with the lack of HID access, that work was abandoned.
• For HID-only devices, a previous self-contained package was created at github.com/karalabe/hid, which worked well for hardware wallet uses cases in go-ethereum. It's a simple package that does its thing well.
  • Unfortunately, hid is not capable of talking to generic USB devices. When multiple different devices are needed, eventually some will not support the HID spec (e.g. WebUSB). Pulling in both hid and gousb will break down due to both depending internally on different versions of libusb on Linux.

This usb package is a proper integration of hidapi and libusb so that communication with HID devices is done via system calls, whereas communication with lower level USB devices is done via interrupts. All this detail is hidden away behind a tiny interface.

The package supports Linux, macOS, Windows and FreeBSD. 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 usb package is an implementation from scratch, HID support 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.

Wide character support in the HID support 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.

Error handling for the libusb integration originates from the gousb library.

License

This USB library is licensed under the GNU Lesser General Public License v3.0 (dictated by libusb).

If you are only interested in Human Interface devices, a less restrictive package can be found at github.com/karalabe/hid.

Documentation

Overview

Package usb provide interfaces for generic USB devices.

Index

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

Variables

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

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

var ErrUnsupportedPlatform = errors.New("usb: 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 USB library or not. The goal of this method is to allow programatically handling platforms that do not support USB 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)
}

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
	// contains filtered or unexported fields
}

DeviceInfo contains all the information we know about a USB device. In case of HID devices, that might be a lot more extensive (empty fields for raw USB).

func Enumerate

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

Enumerate returns a list of all the USB 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 devices are returned.

For any device that is HID capable, the enumeration will return an interface to the HID endpoints. For pure raw USB access, please use EnumerateRaw.

func EnumerateHid

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

EnumerateHid 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 devices are returned.

func EnumerateRaw

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

EnumerateRaw returns a list of all the USB 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 devices are returned.

func (DeviceInfo) Open

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

Open connects to a previsouly discovered USB device.