uhid

README

Go uhid API

This is an API for creating user space HID devices from Go (on linux).

This library is a fork of https://chromium.googlesource.com/chromiumos/platform/tast-tests.git, with modifications to make it usable as a stand alone library.

Documentation for the underlying kernel API can be found here: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/hid/uhid.rst?id=refs/tags/v5.11

Stability

The original API was primarily for testing. I intend to use this in non-testing scenarios, which means the API may evolve. We've already diverged from the upstream API and will not attempt to maintain compatibility with the chromiumos project.

Documentation

Overview

Package uhid supports creating, handling and destroying devices created via /dev/uhid.

Index

• Constants
• type Device
  • func NewDevice(name string, descriptor []byte) (*Device, error)
  • func NewDeviceFromRecording(ctx context.Context, file *os.File) (*Device, error)
  • func (d *Device) Bus() uint16
  • func (d *Device) Close() error
  • func (d *Device) EventNodes(ctx context.Context) ([]string, error)
  • func (d *Device) HidrawNodes(ctx context.Context) ([]string, error)
  • func (d *Device) InjectEvent(data []uint8) error
  • func (d *Device) Name() string
  • func (d *Device) Open(ctx context.Context) (chan Event, error)
  • func (d *Device) Phys() string
  • func (d *Device) ProductID() uint32
  • func (d *Device) Replay(ctx context.Context, file *os.File) error
  • func (d *Device) SetUniq(uniq string) error
  • func (d *Device) Uniq() string
  • func (d *Device) VendorID() uint32
  • func (d *Device) WriteEvent(i interface{}) error
• type DeviceData
• type Event
• type EventType
  • func (e EventType) String() string
• type GetReportReplyRequest
• type GetReportRequest
• type Input2Request
• type RNumType
• type ReadStatus

Constants

const (

	// Destroy destroys the device freeing up it's resources.
	Destroy EventType = 1
	// Start is written by the kernel to acknowledge the creation of
	// a device.
	Start = 2
	// Stop is written by the kernel to acknowledge the destruction
	// of a device.
	Stop = 3
	// Open is written by the kernel to signal that the data being
	// provided by the device is being read.
	Open = 4
	// Close is written by the kernel to signal that no more processes
	// are reading this device's data.
	Close = 5
	// Output is written by the kernel to signal that the HID device
	// driver wants to send raw data to the I/O device on the interrupt
	// channel.
	Output = 6
	// GetReport is written by the kernel to signal that the kernel
	// driver wants to perform a GET_REPORT request on the control
	// channeld as described in the HID specs.
	GetReport = 9
	// GetReportReply must be written by the user as a reply to a
	// UHIDGetReport request.
	GetReportReply = 10
	// Create2 is written by the user to create a device.
	Create2 = 11
	// Input2 is used to inject events to the device.
	Input2 = 12
	// SetReport is written by the kernel to signal that the kernel
	// driver wants to perform a SET_REPORT request on the control
	// channeld as described in the HID specs.
	SetReport = 13
	// SetReportReply must be written by the user as a reply to a
	// SetReport request.
	SetReportReply = 14
)

Types

type Device

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

Device is the main interface carrying all of the created (or soon to be created) kernel device's information.

func NewDevice

func NewDevice(name string, descriptor []byte) (*Device, error)

NewDevice returns a device with the given name and descriptor.

func NewDeviceFromRecording

func NewDeviceFromRecording(ctx context.Context, file *os.File) (*Device, error)

NewDeviceFromRecording receives a file containing a hid recording recorded using hid-tools (https://gitlab.freedesktop.org/libevdev/hid-tools) and creates a device based on the information contained in it.

func (*Device) Bus

func (d *Device) Bus() uint16

Bus returns the bus of this device.

func (*Device) Close

func (d *Device) Close() error

Close destroys the device specified in d by writing a destroy request to /dev/uhid. The file as well as the hidraw and event nodes are cleared.

func (*Device) EventNodes

func (d *Device) EventNodes(ctx context.Context) ([]string, error)

EventNodes returns the /dev/input/event* paths associated to this device.

func (*Device) HidrawNodes

func (d *Device) HidrawNodes(ctx context.Context) ([]string, error)

HidrawNodes returns the /dev/hidraw* paths associated to this device.

func (*Device) InjectEvent

func (d *Device) InjectEvent(data []uint8) error

InjectEvent Injects an event into an existing device. The data array will vary from device to device.

func (*Device) Name

func (d *Device) Name() string

Name returns the name of the device.

func (*Device) Open

func (d *Device) Open(ctx context.Context) (chan Event, error)

Open creates a device with the attributes specified in d. Only after calling this function will the device be ready for the other operations.

func (*Device) Phys

func (d *Device) Phys() string

Phys returns the phys of the device.

func (*Device) ProductID

func (d *Device) ProductID() uint32

ProductID returns the product id of this device.

func (*Device) Replay

func (d *Device) Replay(ctx context.Context, file *os.File) error

Replay receives a file containing a hid recording, parses it and injects the events into the given device. An error is returned if the recording file is invalid.

func (*Device) SetUniq

func (d *Device) SetUniq(uniq string) error

SetUniq sets the uniq of this device.

func (*Device) Uniq

func (d *Device) Uniq() string

Uniq returns the uniq of this device.

func (*Device) VendorID

func (d *Device) VendorID() uint32

VendorID returns the vendor id of this device.

func (*Device) WriteEvent

func (d *Device) WriteEvent(i interface{}) error

WriteEvent will write the struct given in i into /dev/uhid and return an error if unsuccessful.

type DeviceData

type DeviceData struct {
	Bus       uint16
	VendorID  uint32
	ProductID uint32
	// contains filtered or unexported fields
}

DeviceData encapsulates the non-trivial data that will then be copied over to a create request or be used to get information from the device. The fixed size byte arrays are meant to replicate those in struct uhid_create2_req in uhid.h.

type Event

type Event struct {
	Type EventType
	Err  error
	Data []byte
}

type EventType

type EventType uint32

EventType is the type used to encapsulate the different request types that can be written by the kernel or user to /dev/uhid.

func (EventType) String

func (e EventType) String() string

type GetReportReplyRequest

type GetReportReplyRequest struct {
	RequestType uint32
	ID          uint32
	Err         uint16
	DataSize    uint16
	Data        [hidMaxDescriptorSize]byte
}

GetReportReplyRequest replicates struct uhid_get_report_reply_req in uhid.h. It should be written to Device.File in response to a GetReportRequest by the kernel.

type GetReportRequest

type GetReportRequest struct {
	RequestType uint32
	ID          uint32
	RNum        RNumType
	RType       uint8
}

GetReportRequest replicates struct uhid_get_report_req in uhid.h. It is used to read GetReport requests written by the kernel and handling them afterwards if necessary.

type Input2Request

type Input2Request struct {
	RequestType uint32
	DataSize    uint16
	Data        [hidMaxDescriptorSize]uint8
}

Input2Request replicates struct uhid_input2_req in uhid.h. An input request is used to inject events into the created device.

type RNumType

type RNumType uint8

RNumType is the type used for the rnum field in get report requests.

type ReadStatus

type ReadStatus uint8

ReadStatus is returned by Dispatch to signal the multiple results of reading from /dev/uhid

const (
	// StatusOK signals that an event was read and no problem was
	// encountered.
	StatusOK ReadStatus = iota
	// StatusNoEvent signals that no event was read.
	StatusNoEvent
)