hid

README

telesma-app/hid

telesma-app/hid is a cgo-free Go library for discovering and communicating with HID devices on Windows, macOS, and Linux. It uses native operating-system facilities and requires neither libhidapi nor a C toolchain.

The library was created primarily as the HID backend for telesma-app/ctap, but it is protocol-agnostic and can be used independently with other HID devices. The module is currently pre-v1, so its API may continue to evolve between minor releases.

Supported platforms

Capability	Windows	macOS	Linux
Enumeration and filtering	Yes	Yes	Yes
Connection events	Yes	Yes	Yes
Input/output reports	Yes	Yes	Yes
Feature reports	Yes	Yes	Yes
Context-aware reads and writes	Yes	Yes	Yes
Configurable read timeout	Yes	—	—
Native backend	HID, SetupAPI, Configuration Manager	IOKit and Core Foundation via purego	hidraw, sysfs, and kernel uevents

Installation

The module requires Go 1.27 or newer.

go get github.com/telesma-app/hid

Usage

Enumerate returns a Go iterator. Filters are exact matches and can be combined; this example selects the FIDO HID usage collection used by telesma-app:

for info, err := range hid.Enumerate(
	hid.WithUsagePage(0xf1d0),
	hid.WithUsage(0x01),
) {
	if err != nil {
		log.Printf("enumerate HID: %v", err)
	}
	if info == nil {
		continue
	}

	log.Printf("path=%q", info.Path)
	if info.ProductStr.Value != nil {
		log.Printf("product=%q", *info.ProductStr.Value)
	}
}

VendorID and ProductID are Descriptor[uint16]; MfrStr, ProductStr, and SerialNbr are Descriptor[string]. Each carries only Value *T and Err error:

• A non-nil Value is a successful read, including a zero ID or an empty string.
• A non-nil Err is a read or conversion failure; the original Go error is retained.
• Both nil means the platform did not provide a value; descriptor presence is unknown.

The caller owns serialization of descriptor errors; Err is omitted from JSON.

Descriptor failures do not hide a device from enumeration or events; filters match only successfully read values. Enumeration can return both a device and an error for incomplete discovery metadata; callers can still use the returned fields. The same error is retained as MetadataErr in watcher snapshots and events.

Pass DeviceInfo.Path to OpenPath to get a device with Read, Write, SendFeatureReport, GetFeatureReport, and Close. Output and feature-report buffers begin with the report ID; use 0 for an unnumbered report. Higher-level framing, such as CTAPHID, is intentionally left to packages such as telesma-app/ctap.

Reads and writes accept a context because they can block. Cancellation is best-effort:

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

if _, err := device.Write(ctx, request); err != nil {
	log.Fatal(err)
}
if _, err := device.Read(ctx, response); err != nil {
	log.Fatal(err)
}

After a canceled write, do not assume that the report was not sent and do not automatically retry it. The driver or device may finish an in-flight write after Write returns ctx.Err().

Connection events

Watch captures every HID device already present in an initial snapshot, then publishes live connected and disconnected events.

watcher, err := hid.Watch()
if err != nil {
	log.Fatal(err)
}
defer watcher.Close()

for _, device := range watcher.Snapshot().Devices {
	if device.DeviceInfo != nil {
		log.Printf("present: %s", device.DeviceInfo.Path)
	}
}

for event := range watcher.Listen() {
	if event.DeviceInfo != nil {
		log.Printf("%s: %s", event.Type, event.DeviceInfo.Path)
	}
	if event.MetadataErr != nil {
		log.Printf("HID event metadata: %v", event.MetadataErr)
	}
}

if err := watcher.Close(); err != nil {
	log.Printf("HID watcher stopped: %v", err)
}

Watch covers all HID devices and should be filtered by the caller. Delivery is ordered and queued, so the channel should be consumed continuously or the watcher closed when it is no longer needed. A non-nil DeviceEvent.MetadataErr means that the state change occurred but some metadata may be incomplete. When Listen closes unexpectedly, call Close to retrieve the terminal watcher error.

Platform notes

• Device paths are opaque and platform-specific. Optional descriptor availability is recorded explicitly; other metadata remains best-effort.
• Windows reads descriptors through HidD_GetAttributes and the HID string APIs. macOS reads IOHID properties; a missing property is unknown, because IOHID does not expose its underlying read outcome.
• Linux reads USB descriptors from sysfs. HIDName and HIDUnique preserve kernel-provided names and identifiers separately; HIDUnique may be a transport address.
• Enumeration and event monitoring do not guarantee I/O access; OpenPath remains subject to operating-system, driver, and sandbox policy.
• Reads block by default. A context deadline is portable; WithReadTimeout remains available in Windows builds.
• Cancellation is best-effort. Windows requests cancellation of the specific overlapped read or write with CancelIoEx. On macOS, canceling a read stops waiting for the next callback report. Linux I/O and an in-flight macOS write may continue in the driver or device after the method returns; operations of the same kind remain serialized until the native call finishes.
• Feature-report methods do not accept a context because the synchronous HID APIs used here do not provide a practical, operation-specific cancellation mechanism.
• On macOS, enumeration and events do not open devices, but opening protected devices for I/O may still be denied by system or sandbox policy.
• On Linux, access to /dev/hidrawN depends on udev rules and permissions. A connection event may arrive before the device node and its final permissions are ready.

Testing

go test ./...
CGO_ENABLED=0 go test ./...
go vet ./...

Linting

With golangci-lint v2 installed:

golangci-lint run ./...

License

Licensed under the Apache License 2.0.

Documentation

Index

• func Enumerate(options ...EnumerateOption) iter.Seq2[*DeviceInfo, error]
• func WithContext(ctx context.Context, device ContextReadWriter) io.ReadWriter
• type ContextReadWriter
• type Descriptor
• type Device
  • func OpenPath(path string) (*Device, error)
  • func (d *Device) Close() error
  • func (d *Device) GetFeatureReport(report []byte) (int, error)
  • func (d *Device) Read(ctx context.Context, b []byte) (int, error)
  • func (d *Device) SendFeatureReport(report []byte) error
  • func (d *Device) Write(ctx context.Context, b []byte) (int, error)
• type DeviceEvent
• type DeviceEventType
• type DeviceInfo
• type DeviceSnapshot
• type EnumerateOption
  • func WithInstanceID(instanceID string) EnumerateOption
  • func WithInterfaceNumber(interfaceNbr int) EnumerateOption
  • func WithManufacturerString(mfrStr string) EnumerateOption
  • func WithParentDeviceID(parentDeviceID string) EnumerateOption
  • func WithPath(path string) EnumerateOption
  • func WithProductID(productID uint16) EnumerateOption
  • func WithProductString(productStr string) EnumerateOption
  • func WithReleaseNumber(releaseNbr uint16) EnumerateOption
  • func WithSerialNumber(serialNbr string) EnumerateOption
  • func WithUsage(usage uint16) EnumerateOption
  • func WithUsagePage(usagePage uint16) EnumerateOption
  • func WithVendorID(vendorID uint16) EnumerateOption
• type Snapshot
• type Watcher
  • func Watch() (Watcher, error)

Functions

func Enumerate

func Enumerate(options ...EnumerateOption) iter.Seq2[*DeviceInfo, error]

func WithContext

func WithContext(ctx context.Context, device ContextReadWriter) io.ReadWriter

WithContext binds ctx to device and adapts it to io.ReadWriter. Read and Write delegate directly to device without adding context checks.

Types

type ContextReadWriter

type ContextReadWriter interface {
	Read(context.Context, []byte) (int, error)
	Write(context.Context, []byte) (int, error)
}

ContextReadWriter reads and writes HID reports using a context.

type Descriptor

type Descriptor[T any] struct {
	Value *T    `json:"value"`
	Err   error `json:"-"`
}

Descriptor holds a platform observation. A non-nil Value is a successful read, including zero IDs and empty strings. Err holds a read failure. When neither is set, the platform did not provide a value.

type Device

type Device struct {
	// contains filtered or unexported fields
}

func OpenPath

func OpenPath(path string) (*Device, error)

func (*Device) Close

func (d *Device) Close() error

func (*Device) GetFeatureReport

func (d *Device) GetFeatureReport(report []byte) (int, error)

func (*Device) Read

func (d *Device) Read(ctx context.Context, b []byte) (int, error)

func (*Device) SendFeatureReport

func (d *Device) SendFeatureReport(report []byte) error

func (*Device) Write

func (d *Device) Write(ctx context.Context, b []byte) (int, error)

type DeviceEvent

type DeviceEvent struct {
	Type       DeviceEventType
	DeviceInfo *DeviceInfo
	// MetadataErr covers discovery failures outside individual descriptors.
	MetadataErr error `json:"-"`
}

type DeviceEventType

type DeviceEventType string

const (
	DeviceEventConnected    DeviceEventType = "connected"
	DeviceEventDisconnected DeviceEventType = "disconnected"
)

type DeviceInfo

type DeviceInfo struct {
	Path string // Platform-Specific Device Path
	// VendorID and ProductID may be unavailable on macOS.
	VendorID       Descriptor[uint16]
	ProductID      Descriptor[uint16]
	SerialNbr      Descriptor[string] // Reported serial; not a verified identity
	ReleaseNbr     uint16             // Device Version Number
	MfrStr         Descriptor[string]
	ProductStr     Descriptor[string]
	UsagePage      uint16 // Usage Page for Device/Interface
	Usage          uint16 // Usage for Device/Interface
	InterfaceNbr   int    // USB Interface Number
	InstanceID     string
	ParentDeviceID string
	// HIDName and HIDUnique retain Linux HID_NAME and HID_UNIQ separately from
	// USB descriptors. HIDUnique may be a transport address.
	HIDName   Descriptor[string]
	HIDUnique Descriptor[string]
}

type DeviceSnapshot

type DeviceSnapshot struct {
	DeviceInfo  *DeviceInfo
	MetadataErr error `json:"-"`
}

DeviceSnapshot describes one device in a Watcher's initial snapshot. MetadataErr means that the device is present but some metadata is incomplete.

type EnumerateOption

type EnumerateOption func(*enumerateOptions)

func WithInstanceID

func WithInstanceID(instanceID string) EnumerateOption

func WithInterfaceNumber

func WithInterfaceNumber(interfaceNbr int) EnumerateOption

func WithManufacturerString

func WithManufacturerString(mfrStr string) EnumerateOption

func WithParentDeviceID

func WithParentDeviceID(parentDeviceID string) EnumerateOption

func WithPath

func WithPath(path string) EnumerateOption

func WithProductID

func WithProductID(productID uint16) EnumerateOption

func WithProductString

func WithProductString(productStr string) EnumerateOption

func WithReleaseNumber

func WithReleaseNumber(releaseNbr uint16) EnumerateOption

func WithSerialNumber

func WithSerialNumber(serialNbr string) EnumerateOption

func WithUsage

func WithUsage(usage uint16) EnumerateOption

func WithUsagePage

func WithUsagePage(usagePage uint16) EnumerateOption

func WithVendorID

func WithVendorID(vendorID uint16) EnumerateOption

type Snapshot

type Snapshot struct {
	Devices []DeviceSnapshot
}

Snapshot is the initial device state captured by Watch.

type Watcher

type Watcher interface {
	Snapshot() Snapshot
	Listen() <-chan DeviceEvent
	Close() error
}

Watcher publishes changes which happen after Snapshot.

func Watch

func Watch() (Watcher, error)

Watch captures the current HID snapshot and then publishes later connection and removal events.