Skip to content
hidraw in detail

hidraw in detail

This page describes how to access the display without a HID library directly via the Linux hidraw interface – relevant for implementations in C, Rust, Go, Python, etc.

Finding the device

The number N in /dev/hidrawN is not stable. The device is found via sysfs (readable without root):

for d in /sys/class/hidraw/hidraw*; do
  grep -q '^HID_ID=0003:00005131:0000200E$' "$d/device/uevent" && echo "/dev/$(basename "$d")"
done
FileContent (example)
/sys/class/hidraw/hidraw5/device/ueventHID_ID=0003:00005131:0000200E (bus 3 = USB, VID, PID – hex, uppercase), HID_NAME=HID 5131:200e, HID_PHYS=usb-0000:02:00.0-10/input0
/sys/class/hidraw/hidraw5/device/report_descriptor34-byte report descriptor (binary)
/dev/input/by-id/usb-5131_200e-hidrawstable symlink (created by systemd-udev)

Alternatively with libudev: subsystem = "hidraw", parent device usb/usb_device with idVendor == "5131" and idProduct == "200e". For hotplug, subscribe a udev monitor to hidraw.

Opening

int fd = open("/dev/hidraw5", O_RDWR | O_NONBLOCK | O_CLOEXEC);

Multiple processes can open the node at the same time – the kernel serializes the writes, but the packets of both processes reach the display interleaved. A library should therefore use the device exclusively (e.g. via a lock file or a single service).

Writing

uint8_t buf[65] = {0};   // buf[0] = report ID 0 (device has no report IDs)
buf[1 + 1] = 0x01;       // packet offset 1: command
buf[1 + 2] = 0x02;       // packet offset 2: subcommand
buf[1 + 3] = 42;         // CPU temperature
ssize_t n = write(fd, buf, sizeof buf);   // n == 65 on success

What happens in the kernel (drivers/hid/hidraw.c → usbhid_output_report):

  1. hidraw passes the buffer as an output report to hid_hw_output_report().
  2. usbhid detects buf[0] == 0 and strips the report ID byte.
  3. The remaining 64 bytes go to endpoint 0x01 via interrupt transfer.
  4. write() blocks until the transfer completes (timeout in the kernel) and returns 65.
Error (errno)MeaningReaction
ENODEVdevice unpluggedclose, wait for hotplug
EPIPEendpoint stallclose, reopen
ETIMEDOUTdevice accepts nothingretry, reopen if needed
EACCES (on open)no permissionsudev rule
EINTRsignalretry
Always write exactly 65 bytes. Shorter writes produce short USB packets whose handling by the firmware is undefined.

Reading (input reports)

uint8_t in[64];
ssize_t n = read(fd, in, sizeof in);   // 64 bytes, WITHOUT report ID byte; EAGAIN if nothing available

Wait with poll() on POLLIN. The kernel buffers up to 64 reports per file descriptor.

Useful ioctls (<linux/hidraw.h>)

ioctlNumber (x86-64)Purpose
HIDIOCGRDESCSIZE0x80044801Length of the report descriptor (34)
HIDIOCGRDESC0x90044802Read the report descriptor (struct hidraw_report_descriptor)
HIDIOCGRAWINFO0x80084803bustype (3), vendor (0x5131), product (0x200e)
HIDIOCGRAWNAME(len)0x80004804 | len<<16Name: HID 5131:200e
HIDIOCGRAWPHYS(len)0x80004805 | len<<16Physical path: usb-0000:02:00.0-10/input0

HIDIOCSFEATURE/HIDIOCGFEATURE are pointless – the device has no feature reports.

Minimal example in the shell

For a quick test without any software (root or udev rule required). Sends “42 °C” for 20 s:

f=$(mktemp)
{ printf '\x00\x00\x01\x02\x2a'; head -c 60 /dev/zero; } > "$f"   # 65 bytes
for i in $(seq 80); do
  dd if="$f" of=/dev/hidraw5 bs=65 count=1 status=none
  sleep 0.25
done
rm "$f"

dd bs=65 ensures that the 65 bytes (00 report ID + 00 01 02 2a + 60 × 00) reach the kernel in a single write(). Redirecting several printf/head calls directly to the device would instead produce multiple short reports.