commit a6f800da6a083e74605275cb2acca4d2326c7cd0
parent 80f913ba55836c6e79c32b8ccc474d327a864bd1
Author: Robert Russell <robertrussell.72001@gmail.com>
Date: Wed, 17 Jul 2024 15:29:15 -0700
Add README and a Makefile target to generate it
Diffstat:
3 files changed, 49 insertions(+), 2 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -1 +1 @@
-vhidkb
-\ No newline at end of file
+vhidkb
diff --git a/Makefile b/Makefile
@@ -5,6 +5,9 @@ include config.mk
vhidkb: vhidkb.c config.mk
$(CC) $(CFLAGS) -o $@ vhidkb.c
+README: vhidkb.1
+ man ./vhidkb.1 | col -b | sed 's/\t/ /g' > README
+
install: vhidkb
mkdir -p $(DESTDIR)$(PREFIX)/bin
cp -f vhidkb $(DESTDIR)$(PREFIX)/bin/
diff --git a/README b/README
@@ -0,0 +1,45 @@
+VHIDKB(1) User Commands VHIDKB(1)
+
+NAME
+ vhidkb - virtual HID keyboard
+
+SYNOPSIS
+ vhidkb [-h] [-d DEVICE] [-t DELAY]
+
+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 reaching EOF.
+
+OPTIONS
+ -h Display a help message.
+
+ -d DEVICE
+ Use DEVICE as the /dev/uhid interface instead of "/dev/uhid".
+
+ -t DELAY
+ Wait DELAY milliseconds after the first process opens the HID
+ device before sending key events. If DELAY 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.
+
+NOTES
+ The -t 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 DELAY, 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.
+
+ 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.)
+
+SEE ALSO
+ HID Usage Tables <https://usb.org/sites/default/files/hut1_3_0.pdf>
+
+vhidkb 2022-08-29 VHIDKB(1)
