commit 584d756dfc1392450ca6606fa79a2333d8b323e3
parent 443631d6755b8f0381954c2e3c0de98b5c57031d
Author: Robert Russell <robertrussell.72001@gmail.com>
Date: Mon, 29 Aug 2022 23:09:35 -0700
Add man page
Diffstat:
| A | vhidkb.1 | | | 38 | ++++++++++++++++++++++++++++++++++++++ |
1 file changed, 38 insertions(+), 0 deletions(-)
diff --git a/vhidkb.1 b/vhidkb.1
@@ -0,0 +1,38 @@
+.TH "VHIDKB" "1" "2022-08-29" "vhidkb" "User Commands"
+.SH NAME
+vhidkb \- virtual HID keyboard
+.SH SYNOPSIS
+\fBvhidkb\fR [\-h] [\-d \fIDEVICE\fR] [\-t \fIDELAY\fR]
+.SH DESCRIPTION
+vhidkb creates a virtual 256-key HID keyboard with N-key rollover using the
+Linux /dev/uhid interface. Each key starts in the released state, and each
+byte received over stdin toggles the key of that number. Keys are numbered
+in accordance with the HID usage page 0x07. vhidkb destroys the virtual
+keyboard and exits after receiving EOF.
+.SH OPTIONS
+.TP
+\fB\-h\fR
+Display a help message.
+.TP
+\fB\-d\fR \fIDEVICE\fR
+Use \fIDEVICE\fR as the /dev/uhid interface instead of "/dev/uhid".
+.TP
+\fB\-t\fR \fIDELAY\fR
+Wait \fIDELAY\fR milliseconds after the first process opens the HID device
+before sending key events. If \fIDELAY\fR is negative, then key events are sent
+even if no process has the HID device open. By default, vhidkb acts as if
+"\-t 100" is passed as an option.
+.SH NOTES
+The \fB\-t\fR option exists as a hack to solve timing issues where an X server
+opens the HID device, closes it, and then opens it again, all within a few tens
+of milliseconds. (Why does Xorg do this? I don't know.) With 0ms \fIDELAY\fR,
+the first opening causes vhidkb to start sending key events (assuming some data
+is available on stdin), but these events will most likely end up being
+discarded.
+.P
+By default, accessing /dev/uhid requires root privilages. For easy and secure
+use, the author recommends creating a "uhid" group for the /dev/uhid device and
+the vhidkb executable, with the latter having its SGID bit set. (Changing the
+group of /dev/uhid can be automated in init scripts.)
+.SH "SEE ALSO"
+HID Usage Tables <https://usb.org/sites/default/files/hut1_3_0.pdf>
