Raw HID devices from /dev/hidraw*. It lists the nodes and who they
belong to, opens one, reads its reports, and sends its output and feature
reports. It never decides what a report's bytes mean.
A device without a kernel driver of its own reaches a program only here. A controller is the usual case: its state arrives as a report, and its settings go out as feature reports.
open_raw(path) is the C open that open wraps. READ_CAP is how many
reports one read drains at most.
| Name | Signature |
|---|---|
| list | list(root) -> nodes |
| open | open(path) -> dev, err, errno |
list(
root) ->nodes
List the hidraw nodes and their devices
Reads each node's uevent under root, /sys/class/hidraw by default,
and opens nothing. So a node this process may not open is still listed,
with the device it belongs to. Nodes come in number order. A node whose
uevent does not read or carries no HID_ID is left out.
| field | description |
|---|---|
path | the node, /dev/hidrawN |
bustype | the bus, 3 for USB and 5 for Bluetooth |
vendor | the vendor id |
product | the product id |
interface | the USB interface number; nil off USB |
name | the device's name |
phys | the device's physical path |
uniq | the serial number, empty when the device has none |
open(
path) ->dev,err,errno
Open one hidraw node
Opens path for reading and writing, non-blocking, and reads the device's
identity once. Returns nil, an error and the errno when the node does not
open, and when it is not a hidraw node: a regular file refuses with
ENOTTY.
| field | description |
|---|---|
dev.path | the node's path |
dev.info | { bustype, vendor, product, name, phys } |
| method | description |
|---|---|
dev:read() | the pending reports, one string each, oldest first; an empty table when none wait; nil, an error and the errno when the device is gone |
dev:write(report) | send an output report; the byte count, or nil, an error and the errno |
dev:set_feature(report) | send a feature report; the byte count, or nil, an error and the errno |
dev:get_feature(id, len) | fetch feature report id, len bytes counting the id; the report, or nil, an error and the errno |
dev:fileno() | the descriptor, for lev.core.wait_readable |
dev:close() | close the node; safe to call twice |
A numbered report carries its id in the first byte, both ways. An
unnumbered device's reports carry no id, and its feature reports go out
with a zero first byte. One read drains at most READ_CAP reports, the
kernel's own queue for one reader.
A device stalls a fetch it has no reply for, and the fetch fails with
EPIPE. A wireless receiver stalls one until the reply has crossed the
air, so a caller that expects a reply retries.