Add ability to track modifier state on the device (#725)

Remove LED sync source option and add keypress reporting while still working with devices that haven't been upgraded
We return the modifiers as the valid bitmask so that the VirtualKeyboard and InfoBar can represent the correct keys as down. This is important when we have strokes like Left-Control + Right-Control + Keypad-1 (used in switching KVMs and such).
Fix handling of modifier keys in client and also removed the extraneous resetKeyboardState.
Manage state to eliminate rerenders by judicious use of useMemo.
Centralized keyboard layout and localized display maps
Move keyboardOptions to useKeyboardLayouts
Added translations for display maps.
Add documentation on the legacy support.

Return the KeysDownState from keyboardReport
Clear out the hidErrorRollOver once sent to reset the keyboard to nothing down.
Handles the returned KeysDownState from keyboardReport
Now passes all logic through handleKeyPress.
If we get a state back from a keyboardReport, use it and also enable keypressReport because we now know it's an upgraded device.
Added exposition on isoCode management

Fix de-DE chars to reflect German E2 keyboard.
https://kbdlayout.info/kbdgre2/overview+virtualkeys

Ran go modernize
Morphs Interface{} to any
Ranges over SplitSeq and FieldSeq for iterating splits
Used min for end calculation remote_mount.Read
Used range 16 in wol.createMagicPacket
DID NOT apply the Omitempty cleanup.

Strong typed in the typescript realm.
Cleanup react state management to enable upgrading Zustand

internal/usbgadget/hid_keyboard.go

@@ -1,10 +1,10 @@
 package usbgadget
 
 import (
+	"bytes"
 	"context"
 	"fmt"
 	"os"
-	"reflect"
 	"time"
 )
 
@@ -61,6 +61,8 @@ var keyboardReportDesc = []byte{
 
 const (
 	hidReadBufferSize = 8
+	hidKeyBufferSize  = 6
+	hidErrorRollOver  = 0x01
 	// https://www.usb.org/sites/default/files/documents/hid1_11.pdf
 	// https://www.usb.org/sites/default/files/hut1_2.pdf
 	KeyboardLedMaskNumLock    = 1 << 0
@@ -68,7 +70,9 @@ const (
 	KeyboardLedMaskScrollLock = 1 << 2
 	KeyboardLedMaskCompose    = 1 << 3
 	KeyboardLedMaskKana       = 1 << 4
-	ValidKeyboardLedMasks     = KeyboardLedMaskNumLock | KeyboardLedMaskCapsLock | KeyboardLedMaskScrollLock | KeyboardLedMaskCompose | KeyboardLedMaskKana
+	// power on/off LED is 5
+	KeyboardLedMaskShift  = 1 << 6
+	ValidKeyboardLedMasks = KeyboardLedMaskNumLock | KeyboardLedMaskCapsLock | KeyboardLedMaskScrollLock | KeyboardLedMaskCompose | KeyboardLedMaskKana | KeyboardLedMaskShift
 )
 
 // Synchronization between LED states and CAPS LOCK, NUM LOCK, SCROLL LOCK,
@@ -81,6 +85,7 @@ type KeyboardState struct {
 	ScrollLock bool `json:"scroll_lock"`
 	Compose    bool `json:"compose"`
 	Kana       bool `json:"kana"`
+	Shift      bool `json:"shift"` // This is not part of the main USB HID spec
 }
 
 func getKeyboardState(b byte) KeyboardState {
@@ -91,27 +96,27 @@ func getKeyboardState(b byte) KeyboardState {
 		ScrollLock: b&KeyboardLedMaskScrollLock != 0,
 		Compose:    b&KeyboardLedMaskCompose != 0,
 		Kana:       b&KeyboardLedMaskKana != 0,
+		Shift:      b&KeyboardLedMaskShift != 0,
 	}
 }
 
-func (u *UsbGadget) updateKeyboardState(b byte) {
+func (u *UsbGadget) updateKeyboardState(state byte) {
 	u.keyboardStateLock.Lock()
 	defer u.keyboardStateLock.Unlock()
 
-	if b&^ValidKeyboardLedMasks != 0 {
-		u.log.Trace().Uint8("b", b).Msg("contains invalid bits, ignoring")
+	if state&^ValidKeyboardLedMasks != 0 {
+		u.log.Warn().Uint8("state", state).Msg("ignoring invalid bits")
 		return
 	}
 
-	newState := getKeyboardState(b)
-	if reflect.DeepEqual(u.keyboardState, newState) {
+	if u.keyboardState == state {
 		return
 	}
-	u.log.Info().Interface("old", u.keyboardState).Interface("new", newState).Msg("keyboardState updated")
-	u.keyboardState = newState
+	u.log.Trace().Uint8("old", u.keyboardState).Uint8("new", state).Msg("keyboardState updated")
+	u.keyboardState = state
 
 	if u.onKeyboardStateChange != nil {
-		(*u.onKeyboardStateChange)(newState)
+		(*u.onKeyboardStateChange)(getKeyboardState(state))
 	}
 }
 
@@ -123,7 +128,35 @@ func (u *UsbGadget) GetKeyboardState() KeyboardState {
 	u.keyboardStateLock.Lock()
 	defer u.keyboardStateLock.Unlock()
 
-	return u.keyboardState
+	return getKeyboardState(u.keyboardState)
+}
+
+func (u *UsbGadget) GetKeysDownState() KeysDownState {
+	u.keyboardStateLock.Lock()
+	defer u.keyboardStateLock.Unlock()
+
+	return u.keysDownState
+}
+
+func (u *UsbGadget) updateKeyDownState(state KeysDownState) {
+	u.keyboardStateLock.Lock()
+	defer u.keyboardStateLock.Unlock()
+
+	if u.keysDownState.Modifier == state.Modifier &&
+		bytes.Equal(u.keysDownState.Keys, state.Keys) {
+		return // No change in key down state
+	}
+
+	u.log.Trace().Interface("old", u.keysDownState).Interface("new", state).Msg("keysDownState updated")
+	u.keysDownState = state
+
+	if u.onKeysDownChange != nil {
+		(*u.onKeysDownChange)(state)
+	}
+}
+
+func (u *UsbGadget) SetOnKeysDownChange(f func(state KeysDownState)) {
+	u.onKeysDownChange = &f
 }
 
 func (u *UsbGadget) listenKeyboardEvents() {
@@ -142,7 +175,7 @@ func (u *UsbGadget) listenKeyboardEvents() {
 				l.Info().Msg("context done")
 				return
 			default:
-				l.Trace().Msg("reading from keyboard")
+				l.Trace().Msg("reading from keyboard for LED state changes")
 				if u.keyboardHidFile == nil {
 					u.logWithSuppression("keyboardHidFileNil", 100, &l, nil, "keyboardHidFile is nil")
 					// show the error every 100 times to avoid spamming the logs
@@ -159,7 +192,7 @@ func (u *UsbGadget) listenKeyboardEvents() {
 				}
 				u.resetLogSuppressionCounter("keyboardHidFileRead")
 
-				l.Trace().Int("n", n).Bytes("buf", buf).Msg("got data from keyboard")
+				l.Trace().Int("n", n).Uints8("buf", buf).Msg("got data from keyboard")
 				if n != 1 {
 					l.Trace().Int("n", n).Msg("expected 1 byte, got")
 					continue
@@ -195,12 +228,12 @@ func (u *UsbGadget) OpenKeyboardHidFile() error {
 	return u.openKeyboardHidFile()
 }
 
-func (u *UsbGadget) keyboardWriteHidFile(data []byte) error {
+func (u *UsbGadget) keyboardWriteHidFile(modifier byte, keys []byte) error {
 	if err := u.openKeyboardHidFile(); err != nil {
 		return err
 	}
 
-	_, err := u.keyboardHidFile.Write(data)
+	_, err := u.keyboardHidFile.Write(append([]byte{modifier, 0x00}, keys[:hidKeyBufferSize]...))
 	if err != nil {
 		u.logWithSuppression("keyboardWriteHidFile", 100, u.log, err, "failed to write to hidg0")
 		u.keyboardHidFile.Close()
@@ -211,22 +244,145 @@ func (u *UsbGadget) keyboardWriteHidFile(data []byte) error {
 	return nil
 }
 
-func (u *UsbGadget) KeyboardReport(modifier uint8, keys []uint8) error {
+func (u *UsbGadget) UpdateKeysDown(modifier byte, keys []byte) KeysDownState {
+	// if we just reported an error roll over, we should clear the keys
+	if keys[0] == hidErrorRollOver {
+		for i := range keys {
+			keys[i] = 0
+		}
+	}
+
+	downState := KeysDownState{
+		Modifier: modifier,
+		Keys:     []byte(keys[:]),
+	}
+	u.updateKeyDownState(downState)
+	return downState
+}
+
+func (u *UsbGadget) KeyboardReport(modifier byte, keys []byte) (KeysDownState, error) {
 	u.keyboardLock.Lock()
 	defer u.keyboardLock.Unlock()
+	defer u.resetUserInputTime()
 
-	if len(keys) > 6 {
-		keys = keys[:6]
+	if len(keys) > hidKeyBufferSize {
+		keys = keys[:hidKeyBufferSize]
 	}
-	if len(keys) < 6 {
-		keys = append(keys, make([]uint8, 6-len(keys))...)
+	if len(keys) < hidKeyBufferSize {
+		keys = append(keys, make([]byte, hidKeyBufferSize-len(keys))...)
 	}
 
-	err := u.keyboardWriteHidFile([]byte{modifier, 0, keys[0], keys[1], keys[2], keys[3], keys[4], keys[5]})
+	err := u.keyboardWriteHidFile(modifier, keys)
 	if err != nil {
-		return err
+		u.log.Warn().Uint8("modifier", modifier).Uints8("keys", keys).Msg("Could not write keyboard report to hidg0")
 	}
 
-	u.resetUserInputTime()
-	return nil
+	return u.UpdateKeysDown(modifier, keys), err
+}
+
+const (
+	// https://www.usb.org/sites/default/files/documents/hut1_2.pdf
+	// Dynamic Flags (DV)
+	LeftControl  = 0xE0
+	LeftShift    = 0xE1
+	LeftAlt      = 0xE2
+	LeftSuper    = 0xE3 // Left GUI (e.g. Windows key, Apple Command key)
+	RightControl = 0xE4
+	RightShift   = 0xE5
+	RightAlt     = 0xE6
+	RightSuper   = 0xE7 // Right GUI (e.g. Windows key, Apple Command key)
+)
+
+const (
+	// https://www.usb.org/sites/default/files/documents/hid1_11.pdf Appendix C
+	ModifierMaskLeftControl  = 0x01
+	ModifierMaskRightControl = 0x10
+	ModifierMaskLeftShift    = 0x02
+	ModifierMaskRightShift   = 0x20
+	ModifierMaskLeftAlt      = 0x04
+	ModifierMaskRightAlt     = 0x40
+	ModifierMaskLeftSuper    = 0x08
+	ModifierMaskRightSuper   = 0x80
+)
+
+// KeyCodeToMaskMap is a slice of KeyCodeMask for quick lookup
+var KeyCodeToMaskMap = map[byte]byte{
+	LeftControl:  ModifierMaskLeftControl,
+	LeftShift:    ModifierMaskLeftShift,
+	LeftAlt:      ModifierMaskLeftAlt,
+	LeftSuper:    ModifierMaskLeftSuper,
+	RightControl: ModifierMaskRightControl,
+	RightShift:   ModifierMaskRightShift,
+	RightAlt:     ModifierMaskRightAlt,
+	RightSuper:   ModifierMaskRightSuper,
+}
+
+func (u *UsbGadget) KeypressReport(key byte, press bool) (KeysDownState, error) {
+	u.keyboardLock.Lock()
+	defer u.keyboardLock.Unlock()
+	defer u.resetUserInputTime()
+
+	// IMPORTANT: This code parallels the logic in the kernel's hid-gadget driver
+	// for handling key presses and releases. It ensures that the USB gadget
+	// behaves similarly to a real USB HID keyboard. This logic is paralleled
+	// in the client/browser-side code in useKeyboard.ts so make sure to keep
+	// them in sync.
+	var state = u.keysDownState
+	modifier := state.Modifier
+	keys := append([]byte(nil), state.Keys...)
+
+	if mask, exists := KeyCodeToMaskMap[key]; exists {
+		// If the key is a modifier key, we update the keyboardModifier state
+		// by setting or clearing the corresponding bit in the modifier byte.
+		// This allows us to track the state of dynamic modifier keys like
+		// Shift, Control, Alt, and Super.
+		if press {
+			modifier |= mask
+		} else {
+			modifier &^= mask
+		}
+	} else {
+		// handle other keys that are not modifier keys by placing or removing them
+		// from the key buffer since the buffer tracks currently pressed keys
+		overrun := true
+		for i := range hidKeyBufferSize {
+			// If we find the key in the buffer the buffer, we either remove it (if press is false)
+			// or do nothing (if down is true) because the buffer tracks currently pressed keys
+			// and if we find a zero byte, we can place the key there (if press is true)
+			if keys[i] == key || keys[i] == 0 {
+				if press {
+					keys[i] = key // overwrites the zero byte or the same key if already pressed
+				} else {
+					// we are releasing the key, remove it from the buffer
+					if keys[i] != 0 {
+						copy(keys[i:], keys[i+1:])
+						keys[hidKeyBufferSize-1] = 0 // Clear the last byte
+					}
+				}
+				overrun = false // We found a slot for the key
+				break
+			}
+		}
+
+		// If we reach here it means we didn't find an empty slot or the key in the buffer
+		if overrun {
+			if press {
+				u.log.Error().Uint8("key", key).Msg("keyboard buffer overflow, key not added")
+				// Fill all key slots with ErrorRollOver (0x01) to indicate overflow
+				for i := range keys {
+					keys[i] = hidErrorRollOver
+				}
+			} else {
+				// If we are releasing a key, and we didn't find it in a slot, who cares?
+				u.log.Warn().Uint8("key", key).Msg("key not found in buffer, nothing to release")
+			}
+		}
+	}
+
+	err := u.keyboardWriteHidFile(modifier, keys)
+	if err != nil {
+		u.log.Warn().Uint8("modifier", modifier).Uints8("keys", keys).Msg("Could not write keypress report to hidg0")
+	}
+
+	return u.UpdateKeysDown(modifier, keys), err
 }

internal/usbgadget/hid_mouse_absolute.go

@@ -85,17 +85,17 @@ func (u *UsbGadget) absMouseWriteHidFile(data []byte) error {
 	return nil
 }
 
-func (u *UsbGadget) AbsMouseReport(x, y int, buttons uint8) error {
+func (u *UsbGadget) AbsMouseReport(x int, y int, buttons uint8) error {
 	u.absMouseLock.Lock()
 	defer u.absMouseLock.Unlock()
 
 	err := u.absMouseWriteHidFile([]byte{
-		1,             // Report ID 1
-		buttons,       // Buttons
-		uint8(x),      // X Low Byte
-		uint8(x >> 8), // X High Byte
-		uint8(y),      // Y Low Byte
-		uint8(y >> 8), // Y High Byte
+		1,            // Report ID 1
+		buttons,      // Buttons
+		byte(x),      // X Low Byte
+		byte(x >> 8), // X High Byte
+		byte(y),      // Y Low Byte
+		byte(y >> 8), // Y High Byte
 	})
 	if err != nil {
 		return err

internal/usbgadget/hid_mouse_relative.go

@@ -75,15 +75,15 @@ func (u *UsbGadget) relMouseWriteHidFile(data []byte) error {
 	return nil
 }
 
-func (u *UsbGadget) RelMouseReport(mx, my int8, buttons uint8) error {
+func (u *UsbGadget) RelMouseReport(mx int8, my int8, buttons uint8) error {
 	u.relMouseLock.Lock()
 	defer u.relMouseLock.Unlock()
 
 	err := u.relMouseWriteHidFile([]byte{
-		buttons,   // Buttons
-		uint8(mx), // X
-		uint8(my), // Y
-		0,         // Wheel
+		buttons,  // Buttons
+		byte(mx), // X
+		byte(my), // Y
+		0,        // Wheel
 	})
 	if err != nil {
 		return err

internal/usbgadget/usbgadget.go

@@ -41,6 +41,11 @@ var defaultUsbGadgetDevices = Devices{
 	MassStorage:   true,
 }
 
+type KeysDownState struct {
+	Modifier byte      `json:"modifier"`
+	Keys     ByteSlice `json:"keys"`
+}
+
 // UsbGadget is a struct that represents a USB gadget.
 type UsbGadget struct {
 	name          string
@@ -60,7 +65,9 @@ type UsbGadget struct {
 	relMouseHidFile *os.File
 	relMouseLock    sync.Mutex
 
-	keyboardState       KeyboardState
+	keyboardState byte          // keyboard latched state (NumLock, CapsLock, ScrollLock, Compose, Kana)
+	keysDownState KeysDownState // keyboard dynamic state (modifier keys and pressed keys)
+
 	keyboardStateLock   sync.Mutex
 	keyboardStateCtx    context.Context
 	keyboardStateCancel context.CancelFunc
@@ -77,6 +84,7 @@ type UsbGadget struct {
 	txLock sync.Mutex
 
 	onKeyboardStateChange *func(state KeyboardState)
+	onKeysDownChange      *func(state KeysDownState)
 
 	log *zerolog.Logger
 
@@ -122,7 +130,8 @@ func newUsbGadget(name string, configMap map[string]gadgetConfigItem, enabledDev
 		txLock:              sync.Mutex{},
 		keyboardStateCtx:    keyboardCtx,
 		keyboardStateCancel: keyboardCancel,
-		keyboardState:       KeyboardState{},
+		keyboardState:       0,
+		keysDownState:       KeysDownState{Modifier: 0, Keys: []byte{0, 0, 0, 0, 0, 0}}, // must be initialized to hidKeyBufferSize (6) zero bytes
 		enabledDevices:      *enabledDevices,
 		lastUserInput:       time.Now(),
 		log:                 logger,

internal/usbgadget/utils.go

@@ -2,6 +2,7 @@ package usbgadget
 
 import (
 	"bytes"
+	"encoding/json"
 	"fmt"
 	"path/filepath"
 	"strconv"
@@ -10,6 +11,31 @@ import (
 	"github.com/rs/zerolog"
 )
 
+type ByteSlice []byte
+
+func (s ByteSlice) MarshalJSON() ([]byte, error) {
+	vals := make([]int, len(s))
+	for i, v := range s {
+		vals[i] = int(v)
+	}
+	return json.Marshal(vals)
+}
+
+func (s *ByteSlice) UnmarshalJSON(data []byte) error {
+	var vals []int
+	if err := json.Unmarshal(data, &vals); err != nil {
+		return err
+	}
+	*s = make([]byte, len(vals))
+	for i, v := range vals {
+		if v < 0 || v > 255 {
+			return fmt.Errorf("value %d out of byte range", v)
+		}
+		(*s)[i] = byte(v)
+	}
+	return nil
+}
+
 func joinPath(basePath string, paths []string) string {
 	pathArr := append([]string{basePath}, paths...)
 	return filepath.Join(pathArr...)
@@ -81,7 +107,7 @@ func compareFileContent(oldContent []byte, newContent []byte, looserMatch bool)
 	return false
 }
 
-func (u *UsbGadget) logWithSuppression(counterName string, every int, logger *zerolog.Logger, err error, msg string, args ...interface{}) {
+func (u *UsbGadget) logWithSuppression(counterName string, every int, logger *zerolog.Logger, err error, msg string, args ...any) {
 	u.logSuppressionLock.Lock()
 	defer u.logSuppressionLock.Unlock()