Skip to content
Self contained USB and HID library for Go
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
hidapi Fix Windows gcc compiler warning. Jun 6, 2019
libusb Fix device refcounts for Windows, add interface claiming. Jun 3, 2019
.travis.yml Fix musl (Alpine/Docker) builds and test via Travis. Jun 7, 2019
AUTHORS Add Martin to the list of authors. Jun 6, 2019
Dockerfile.alpine Fix musl (Alpine/Docker) builds and test via Travis. Jun 7, 2019
Dockerfile.ubuntu Fix musl (Alpine/Docker) builds and test via Travis. Jun 7, 2019
LICENSE Clean up license from fork to full LGPL 3.0 May 30, 2019
README.md Fixup package docs, hide internal types. Jun 4, 2019
appveyor.yml appveyor: bump to Go 1.12.6 Jun 13, 2019
demo.go Disallow HID via RAW, add a demo lister for debugging. Jun 4, 2019
go.mod Swap out the import path from hid to usb May 30, 2019
hid_disabled.go Refactor entire library to cleanly handle RAW + HID devices May 31, 2019
hid_enabled.go Fixup package docs, hide internal types. Jun 4, 2019
libs.go Fix musl (Alpine/Docker) builds and test via Travis. Jun 7, 2019
raw_disabled.go Refactor entire library to cleanly handle RAW + HID devices May 31, 2019
raw_enabled.go Fixup package docs, hide internal types. Jun 4, 2019
raw_errors.go Refactor entire library to cleanly handle RAW + HID devices May 31, 2019
usb.go Fixup package docs, hide internal types. Jun 4, 2019
usb_disabled.go Add disabled version of Open (#4) Jul 3, 2019
usb_enabled.go Disallow HID via RAW, add a demo lister for debugging. Jun 4, 2019
usb_test.go Skip usbfs dependent tests on Travis Linux. Jun 6, 2019
wchar.go Swap out the import path from hid to usb May 30, 2019
wchar_test.go Fix nocgo interface, fix nocgo tests, run nocgo on CI. Jun 6, 2019

README.md

Travis AppVeyor GoDoc

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 it's 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.

You can’t perform that action at this time.