README
¶
gid - Gopher Interface Devices
Yet another Go package tailored for interacting with USB Human Interface Devices (HID).
This package facilitates cross-platform communications with HID devices on macOS, Linux, and Windows. Behind the scenes, it employs boombuler/hid as its foundation and broadens its functionalities by reading feature reports from USB HID devices, and its Linux implementation is a derivative of dolmen-go/hid, which wraps hidapi.
Divergent from comprehensive USB HID packages, gid chiefly focuses on offering support limited to HID devices with feature reports across major platforms. Our primary spotlight is the ThingM blink(1) devices.
Compatible Operating Systems
gid is designed to work seamlessly with the following systems:
- macOS: Through its native IOKit framework
- Linux: Leverages libusb 1.0+
- Windows: Utilizes native Windows HID library
We've tested the package on different platforms to ensure its compatibility:
- macOS Venture 13.5.2 (on Apple M1 Chip)
- Windows 10 x64 - Build 19045
- Windows 11 x64 - Build 22621
- Raspberry Pi OS 64-bit Bullseye (on Raspberry Pi 3 Model B)
The package has been verified to work with the following devices:
- ThingM blink(1) mk2
Limitations
This package is designed to support minimum USB HID functionality needed for ThingM blink(1) on major platforms only. Therefore, not all HID features have been implemented.
Credits and License
The gid package owes its genesis to the following repositories:
The included dependencies carry the following licenses:
hidapi: 3-clause BSDlibusb: GNU LGPL 2.1gowchar: 3-clause BSD
Being open-source, the gid package is licensed under the widely-accepted MIT license.
Documentation
¶
Overview ¶
Package gid provides a platform independent interface to access Human Interface Devices. The platform specific parts of this package are heavily based on Signal 11 - HIDAPI (https://github.com/signal11/hidapi).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Devices ¶
func Devices() <-chan *DeviceInfo
Devices returns a channel that will receive a DeviceInfo struct for each HID device.
func FindDevices ¶
func FindDevices(vendor uint16, product uint16) <-chan *DeviceInfo
FindDevices creates a channel to emit all devices with a given vendor and product id. It returns a channel which is closed when all devices have been enumerated.
func FindDevicesByProduct ¶
func FindDevicesByProduct(product string) <-chan *DeviceInfo
FindDevicesByProduct creates a channel to emit device information where the device's product name contains the given string. The channel is closed after all devices have been processed.
Types ¶
type Device ¶
type Device interface {
// Close closes the device and release all kept resources.
Close()
// Write to the device (technically a HID report with type 'output' is sent to the device)
Write([]byte) error
// WriteFeature to the device (technically a HID report with type 'feature' is sent to the device)
WriteFeature([]byte) error
// Read from the device
Read([]byte) (int, error)
// ReadFeature from the device
ReadFeature([]byte) (int, error)
}
Device interface for an opened HID USB device
type DeviceInfo ¶
type DeviceInfo struct {
// Path contains a Platform-specific device path which is used to identify the device
Path string
// VendorID contains the USB Vendor ID of the device
VendorID uint16
// ProductID contains the USB Product ID of the device
ProductID uint16
// VersionNumber contains the Version / Release Number of the device
VersionNumber uint16
// Manufacturer of the USB device
Manufacturer string
// Product contains the product name of the device
Product string
// SerialNumber contains the serial number of the device
SerialNumber string
InputReportLength uint16
OutputReportLength uint16
FeatureReportLength uint16
}
DeviceInfo provides general information about a device
func ListAllDevices ¶
func ListAllDevices(cond func(*DeviceInfo) bool) []*DeviceInfo
ListAllDevices returns all devices of which the cond function returns true.
func ListFirstDevice ¶
func ListFirstDevice(cond func(*DeviceInfo) bool) *DeviceInfo
ListFirstDevice returns the first device of which the cond function returns true. If no device is found, nil is returned.
func (*DeviceInfo) Open ¶
func (di *DeviceInfo) Open() (Device, error)
Open connects to an HID device by its path name.
Source Files