README
¶
gokbd
About
gokbd is a package that uses libevdev to talk to a keyboard on Linux. It allows snooping the keys pressed as well as typing out keys.
Usage
import gokbd "github.com/joshuar/gokbd"
Examples for reading what keys are being typed (snooping) and writing to a
virtual keyboard are available under the examples/ directory. To run them:
cd examples/snoop
go build
sudo setcap cap_setgid,cap_setuid=p ./snoop
./snoop
cd examples/type
go build
sudo setcap cap_setgid,cap_setuid=p ./type
./type
Permissions
You may need to grant additional permissions to the user running any program
using gokbd.
- To read (snoop) from keyboards, the user will need to be part of the
inputgroup. Typically, the user can be added with the following command:
sudo gpasswd -a $USER input
- To create a virtual keyboard and write to it, the user will need access to the kernel uinput device. Typically, this can be granted with a udev rule like the following:
echo KERNEL==\"uinput\", GROUP=\"$USER\", MODE:=\"0660\" | sudo tee /etc/udev/rules.d/99-$USER.rules
sudo udevadm trigger
You will also need to grant your compiled binary the CAP_SETUID and
CAP_SETGID Linux capabilities. You can do this with:
sudo setcap cap_setgid,cap_setuid=p /path/to/binary
Documentation
¶
Index ¶
- func CodeAndCase(r rune) (int, bool)
- func OpenAllKeyboardDevices() <-chan *KeyboardDevice
- func SnoopAllKeyboards(ctx context.Context, kbds <-chan *KeyboardDevice) <-chan KeyEvent
- func SnoopKeyboard(ctx context.Context, kbd *KeyboardDevice) <-chan KeyEvent
- type CharVariants
- type KeyEvent
- type KeyModifiers
- type KeyboardDevice
- type VirtualKeyboardDevice
- func (u *VirtualKeyboardDevice) Close()
- func (u *VirtualKeyboardDevice) Grab() (func() error, error)
- func (u *VirtualKeyboardDevice) TypeBackspace() error
- func (u *VirtualKeyboardDevice) TypeKey(c int, holdShift bool) error
- func (u *VirtualKeyboardDevice) TypeRune(r rune) error
- func (u *VirtualKeyboardDevice) TypeSpace() error
- func (u *VirtualKeyboardDevice) TypeString(str string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CodeAndCase ¶
CodeAndCase returns the keycode and whether the key was an upper or lowercase rune for the typed key
func OpenAllKeyboardDevices ¶
func OpenAllKeyboardDevices() <-chan *KeyboardDevice
OpenAllKeyboardDevices will open all currently connected keyboards passing them out through a channel for further processing
func SnoopAllKeyboards ¶
func SnoopAllKeyboards(ctx context.Context, kbds <-chan *KeyboardDevice) <-chan KeyEvent
SnoopAllKeyboards will snoop or listen for all key events on all currently connected keyboards. Keyboards are passed in through a channel, see OpenKeyboardDevices for an example of opening all connected keyboards
func SnoopKeyboard ¶
func SnoopKeyboard(ctx context.Context, kbd *KeyboardDevice) <-chan KeyEvent
SnoopKeyboard will snoop or listen for all key events on the given keyboard device.
Types ¶
type CharVariants ¶
type CharVariants struct {
// contains filtered or unexported fields
}
CharVariants represents the upper and lower case variants for a charactor
type KeyEvent ¶
type KeyEvent struct {
Value int
TypeName string
EventName string
AsRune rune
// contains filtered or unexported fields
}
KeyEvent represents an event received from the keyboard eventRaw is the libevdev input event, see https://www.kernel.org/doc/html/v4.17/input/input.html#event-interface Value is the event value, for example 1 for key press, 0 for key release TypeName is the event type as a string, for example EV_KEY or EV_SYN EventName is the event name as a string, for example KEY_A AsRune is the key as a Go rune, for example 'a'
func NewKeyEvent ¶
func NewKeyEvent(ev C.struct_input_event) *KeyEvent
NewKeyEvent will create a new key event for whatever just happened on the keyboard
func (*KeyEvent) IsBackspace ¶
IsBackspace will return true when the event represents a key involved is the backspace key
func (*KeyEvent) IsKeyPress ¶
IsKeyPress will return true when the event represents a key being pressed
func (*KeyEvent) IsKeyRelease ¶
IsKeyRelease will return true when the event represents a key being released
func (*KeyEvent) IsModifier ¶
IsModifier will return true when the event represents any of the "modifier" keys: Ctrl, Alt, Meta or Shift
type KeyModifiers ¶
KeyModifiers represents the state of any "modifier" keys on the keyboard
func NewKeyModifers ¶
func NewKeyModifers() *KeyModifiers
NewKeyModifiers sets up a struct for tracking whether any of the modifier keys have been pressed
func (*KeyModifiers) ToggleAlt ¶
func (km *KeyModifiers) ToggleAlt()
ToggleAlt keeps track of whether an Alt key has been pressed
func (*KeyModifiers) ToggleCapsLock ¶
func (km *KeyModifiers) ToggleCapsLock()
ToggleCapsLock keeps track of whether the Caps Lock key has been pressed
func (*KeyModifiers) ToggleCtrl ¶
func (km *KeyModifiers) ToggleCtrl()
ToggleCtrl keeps track of whether an Ctrl key has been pressed
func (*KeyModifiers) ToggleMeta ¶
func (km *KeyModifiers) ToggleMeta()
ToggleMeta keeps track of whether an Meta key has been pressed
func (*KeyModifiers) ToggleShift ¶
func (km *KeyModifiers) ToggleShift()
ToggleShift keeps track of whether an Shift key has been pressed
type KeyboardDevice ¶
type KeyboardDevice struct {
// contains filtered or unexported fields
}
KeyboardDevice represents a physical keyboard, it contains the dev struct, file descriptor and state of any "modifier" keys
func OpenKeyboardDevice ¶
func OpenKeyboardDevice(devPath string) (*KeyboardDevice, error)
OpenKeyboardDevice will open a specific keyboard device (from the device path passed as a string)
func (*KeyboardDevice) Close ¶
func (k *KeyboardDevice) Close()
Close will gracefully handle closing a keyboard device, freeing memory and file descriptors
func (*KeyboardDevice) Grab ¶ added in v0.1.1
func (k *KeyboardDevice) Grab() (func() error, error)
type VirtualKeyboardDevice ¶
type VirtualKeyboardDevice struct {
Name string
DevNode string
SysPath string
// contains filtered or unexported fields
}
VirtualKeyboardDevice represents a "virtual" (uinput) keyboard device
func NewVirtualKeyboard ¶
func NewVirtualKeyboard(name string) (*VirtualKeyboardDevice, error)
NewVirtualKeyboard will create a new virtual keyboard device (with the name passed in)
func (*VirtualKeyboardDevice) Close ¶
func (u *VirtualKeyboardDevice) Close()
Close will gracefully remove a virtual keyboard, freeing memory and file descriptors
func (*VirtualKeyboardDevice) Grab ¶ added in v0.1.1
func (u *VirtualKeyboardDevice) Grab() (func() error, error)
Grab will grab the virtual keyboard which prevents any other clients and the kernel from recieving events from it. The returned func can be used to ungrab the keyboard, allowing other clients and the kernel to see its events again.
func (*VirtualKeyboardDevice) TypeBackspace ¶
func (u *VirtualKeyboardDevice) TypeBackspace() error
TypeBackspace allows you to "type" a backspace key and remove a single character
func (*VirtualKeyboardDevice) TypeKey ¶
func (u *VirtualKeyboardDevice) TypeKey(c int, holdShift bool) error
func (*VirtualKeyboardDevice) TypeRune ¶
func (u *VirtualKeyboardDevice) TypeRune(r rune) error
func (*VirtualKeyboardDevice) TypeSpace ¶
func (u *VirtualKeyboardDevice) TypeSpace() error
TypeSpace is a high level way to "type" a space character (effectively, press/release the spacebar)
func (*VirtualKeyboardDevice) TypeString ¶
func (u *VirtualKeyboardDevice) TypeString(str string) error
TypeString is a high level function that makes it easy to "type" out a string to the virtual keyboard
Source Files
Directories