init

src/hid/backend.rs

@@ -0,0 +1,130 @@
+//! HID backend trait definition
+
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+
+use super::types::{KeyboardEvent, MouseEvent};
+use crate::error::Result;
+
+/// Default CH9329 baud rate
+fn default_ch9329_baud_rate() -> u32 {
+    9600
+}
+
+/// HID backend type
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "lowercase")]
+pub enum HidBackendType {
+    /// USB OTG gadget mode
+    Otg,
+    /// CH9329 serial HID controller
+    Ch9329 {
+        /// Serial port path
+        port: String,
+        /// Baud rate (default: 9600)
+        #[serde(default = "default_ch9329_baud_rate")]
+        baud_rate: u32,
+    },
+    /// No HID backend (disabled)
+    None,
+}
+
+impl Default for HidBackendType {
+    fn default() -> Self {
+        Self::None
+    }
+}
+
+impl HidBackendType {
+    /// Check if OTG backend is available on this system
+    pub fn otg_available() -> bool {
+        // Check for USB gadget support
+        std::path::Path::new("/sys/class/udc").exists()
+    }
+
+    /// Detect the best available backend
+    pub fn detect() -> Self {
+        // Check for OTG gadget support
+        if Self::otg_available() {
+            return Self::Otg;
+        }
+
+        // Check for common CH9329 serial ports
+        let common_ports = [
+            "/dev/ttyUSB0",
+            "/dev/ttyUSB1",
+            "/dev/ttyAMA0",
+            "/dev/serial0",
+        ];
+
+        for port in &common_ports {
+            if std::path::Path::new(port).exists() {
+                return Self::Ch9329 {
+                    port: port.to_string(),
+                    baud_rate: 9600, // Use default baud rate for auto-detection
+                };
+            }
+        }
+
+        Self::None
+    }
+
+    /// Get backend name as string
+    pub fn name_str(&self) -> &str {
+        match self {
+            Self::Otg => "otg",
+            Self::Ch9329 { .. } => "ch9329",
+            Self::None => "none",
+        }
+    }
+}
+
+/// HID backend trait
+#[async_trait]
+pub trait HidBackend: Send + Sync {
+    /// Get backend name
+    fn name(&self) -> &'static str;
+
+    /// Initialize the backend
+    async fn init(&self) -> Result<()>;
+
+    /// Send a keyboard event
+    async fn send_keyboard(&self, event: KeyboardEvent) -> Result<()>;
+
+    /// Send a mouse event
+    async fn send_mouse(&self, event: MouseEvent) -> Result<()>;
+
+    /// Reset all inputs (release all keys/buttons)
+    async fn reset(&self) -> Result<()>;
+
+    /// Shutdown the backend
+    async fn shutdown(&self) -> Result<()>;
+
+    /// Check if backend supports absolute mouse positioning
+    fn supports_absolute_mouse(&self) -> bool {
+        false
+    }
+
+    /// Get screen resolution (for absolute mouse)
+    fn screen_resolution(&self) -> Option<(u32, u32)> {
+        None
+    }
+
+    /// Set screen resolution (for absolute mouse)
+    fn set_screen_resolution(&mut self, _width: u32, _height: u32) {}
+}
+
+/// HID backend information
+#[derive(Debug, Clone, Serialize)]
+pub struct HidBackendInfo {
+    /// Backend name
+    pub name: String,
+    /// Backend type
+    pub backend_type: String,
+    /// Is initialized
+    pub initialized: bool,
+    /// Supports absolute mouse
+    pub absolute_mouse: bool,
+    /// Screen resolution (if absolute mouse)
+    pub resolution: Option<(u32, u32)>,
+}

src/hid/datachannel.rs

@@ -0,0 +1,281 @@
+//! DataChannel HID message parsing and handling
+//!
+//! Binary message format:
+//! - Byte 0: Message type
+//!   - 0x01: Keyboard event
+//!   - 0x02: Mouse event
+//! - Remaining bytes: Event data
+//!
+//! Keyboard event (type 0x01):
+//! - Byte 1: Event type (0x00 = down, 0x01 = up)
+//! - Byte 2: Key code (USB HID usage code or JS keyCode)
+//! - Byte 3: Modifiers bitmask
+//!   - Bit 0: Left Ctrl
+//!   - Bit 1: Left Shift
+//!   - Bit 2: Left Alt
+//!   - Bit 3: Left Meta
+//!   - Bit 4: Right Ctrl
+//!   - Bit 5: Right Shift
+//!   - Bit 6: Right Alt
+//!   - Bit 7: Right Meta
+//!
+//! Mouse event (type 0x02):
+//! - Byte 1: Event type
+//!   - 0x00: Move (relative)
+//!   - 0x01: MoveAbs (absolute)
+//!   - 0x02: Down
+//!   - 0x03: Up
+//!   - 0x04: Scroll
+//! - Bytes 2-3: X coordinate (i16 LE for relative, u16 LE for absolute)
+//! - Bytes 4-5: Y coordinate (i16 LE for relative, u16 LE for absolute)
+//! - Byte 6: Button (0=left, 1=middle, 2=right) or Scroll delta (i8)
+
+use tracing::{debug, warn};
+
+use super::{
+    KeyEventType, KeyboardEvent, KeyboardModifiers, MouseButton, MouseEvent, MouseEventType,
+};
+
+/// Message types
+pub const MSG_KEYBOARD: u8 = 0x01;
+pub const MSG_MOUSE: u8 = 0x02;
+
+/// Keyboard event types
+pub const KB_EVENT_DOWN: u8 = 0x00;
+pub const KB_EVENT_UP: u8 = 0x01;
+
+/// Mouse event types
+pub const MS_EVENT_MOVE: u8 = 0x00;
+pub const MS_EVENT_MOVE_ABS: u8 = 0x01;
+pub const MS_EVENT_DOWN: u8 = 0x02;
+pub const MS_EVENT_UP: u8 = 0x03;
+pub const MS_EVENT_SCROLL: u8 = 0x04;
+
+/// Parsed HID event from DataChannel
+#[derive(Debug, Clone)]
+pub enum HidChannelEvent {
+    Keyboard(KeyboardEvent),
+    Mouse(MouseEvent),
+}
+
+/// Parse a binary HID message from DataChannel
+pub fn parse_hid_message(data: &[u8]) -> Option<HidChannelEvent> {
+    if data.is_empty() {
+        warn!("Empty HID message");
+        return None;
+    }
+
+    let msg_type = data[0];
+
+    match msg_type {
+        MSG_KEYBOARD => parse_keyboard_message(&data[1..]),
+        MSG_MOUSE => parse_mouse_message(&data[1..]),
+        _ => {
+            warn!("Unknown HID message type: 0x{:02X}", msg_type);
+            None
+        }
+    }
+}
+
+/// Parse keyboard message payload
+fn parse_keyboard_message(data: &[u8]) -> Option<HidChannelEvent> {
+    if data.len() < 3 {
+        warn!("Keyboard message too short: {} bytes", data.len());
+        return None;
+    }
+
+    let event_type = match data[0] {
+        KB_EVENT_DOWN => KeyEventType::Down,
+        KB_EVENT_UP => KeyEventType::Up,
+        _ => {
+            warn!("Unknown keyboard event type: 0x{:02X}", data[0]);
+            return None;
+        }
+    };
+
+    let key = data[1];
+    let modifiers_byte = data[2];
+
+    let modifiers = KeyboardModifiers {
+        left_ctrl: modifiers_byte & 0x01 != 0,
+        left_shift: modifiers_byte & 0x02 != 0,
+        left_alt: modifiers_byte & 0x04 != 0,
+        left_meta: modifiers_byte & 0x08 != 0,
+        right_ctrl: modifiers_byte & 0x10 != 0,
+        right_shift: modifiers_byte & 0x20 != 0,
+        right_alt: modifiers_byte & 0x40 != 0,
+        right_meta: modifiers_byte & 0x80 != 0,
+    };
+
+    debug!(
+        "Parsed keyboard: {:?} key=0x{:02X} modifiers=0x{:02X}",
+        event_type, key, modifiers_byte
+    );
+
+    Some(HidChannelEvent::Keyboard(KeyboardEvent {
+        event_type,
+        key,
+        modifiers,
+    }))
+}
+
+/// Parse mouse message payload
+fn parse_mouse_message(data: &[u8]) -> Option<HidChannelEvent> {
+    if data.len() < 6 {
+        warn!("Mouse message too short: {} bytes", data.len());
+        return None;
+    }
+
+    let event_type = match data[0] {
+        MS_EVENT_MOVE => MouseEventType::Move,
+        MS_EVENT_MOVE_ABS => MouseEventType::MoveAbs,
+        MS_EVENT_DOWN => MouseEventType::Down,
+        MS_EVENT_UP => MouseEventType::Up,
+        MS_EVENT_SCROLL => MouseEventType::Scroll,
+        _ => {
+            warn!("Unknown mouse event type: 0x{:02X}", data[0]);
+            return None;
+        }
+    };
+
+    // Parse coordinates as i16 LE (works for both relative and absolute)
+    let x = i16::from_le_bytes([data[1], data[2]]) as i32;
+    let y = i16::from_le_bytes([data[3], data[4]]) as i32;
+
+    // Button or scroll delta
+    let (button, scroll) = match event_type {
+        MouseEventType::Down | MouseEventType::Up => {
+            let btn = match data[5] {
+                0 => Some(MouseButton::Left),
+                1 => Some(MouseButton::Middle),
+                2 => Some(MouseButton::Right),
+                3 => Some(MouseButton::Back),
+                4 => Some(MouseButton::Forward),
+                _ => Some(MouseButton::Left),
+            };
+            (btn, 0i8)
+        }
+        MouseEventType::Scroll => (None, data[5] as i8),
+        _ => (None, 0i8),
+    };
+
+    debug!(
+        "Parsed mouse: {:?} x={} y={} button={:?} scroll={}",
+        event_type, x, y, button, scroll
+    );
+
+    Some(HidChannelEvent::Mouse(MouseEvent {
+        event_type,
+        x,
+        y,
+        button,
+        scroll,
+    }))
+}
+
+/// Encode a keyboard event to binary format (for sending to client if needed)
+pub fn encode_keyboard_event(event: &KeyboardEvent) -> Vec<u8> {
+    let event_type = match event.event_type {
+        KeyEventType::Down => KB_EVENT_DOWN,
+        KeyEventType::Up => KB_EVENT_UP,
+    };
+
+    let modifiers = event.modifiers.to_hid_byte();
+
+    vec![MSG_KEYBOARD, event_type, event.key, modifiers]
+}
+
+/// Encode a mouse event to binary format (for sending to client if needed)
+pub fn encode_mouse_event(event: &MouseEvent) -> Vec<u8> {
+    let event_type = match event.event_type {
+        MouseEventType::Move => MS_EVENT_MOVE,
+        MouseEventType::MoveAbs => MS_EVENT_MOVE_ABS,
+        MouseEventType::Down => MS_EVENT_DOWN,
+        MouseEventType::Up => MS_EVENT_UP,
+        MouseEventType::Scroll => MS_EVENT_SCROLL,
+    };
+
+    let x_bytes = (event.x as i16).to_le_bytes();
+    let y_bytes = (event.y as i16).to_le_bytes();
+
+    let extra = match event.event_type {
+        MouseEventType::Down | MouseEventType::Up => {
+            event.button.as_ref().map(|b| match b {
+                MouseButton::Left => 0u8,
+                MouseButton::Middle => 1u8,
+                MouseButton::Right => 2u8,
+                MouseButton::Back => 3u8,
+                MouseButton::Forward => 4u8,
+            }).unwrap_or(0)
+        }
+        MouseEventType::Scroll => event.scroll as u8,
+        _ => 0,
+    };
+
+    vec![
+        MSG_MOUSE,
+        event_type,
+        x_bytes[0],
+        x_bytes[1],
+        y_bytes[0],
+        y_bytes[1],
+        extra,
+    ]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_keyboard_down() {
+        let data = [MSG_KEYBOARD, KB_EVENT_DOWN, 0x04, 0x01]; // A key with left ctrl
+        let event = parse_hid_message(&data).unwrap();
+
+        match event {
+            HidChannelEvent::Keyboard(kb) => {
+                assert!(matches!(kb.event_type, KeyEventType::Down));
+                assert_eq!(kb.key, 0x04);
+                assert!(kb.modifiers.left_ctrl);
+                assert!(!kb.modifiers.left_shift);
+            }
+            _ => panic!("Expected keyboard event"),
+        }
+    }
+
+    #[test]
+    fn test_parse_mouse_move() {
+        let data = [MSG_MOUSE, MS_EVENT_MOVE, 0x0A, 0x00, 0xF6, 0xFF, 0x00]; // x=10, y=-10
+        let event = parse_hid_message(&data).unwrap();
+
+        match event {
+            HidChannelEvent::Mouse(ms) => {
+                assert!(matches!(ms.event_type, MouseEventType::Move));
+                assert_eq!(ms.x, 10);
+                assert_eq!(ms.y, -10);
+            }
+            _ => panic!("Expected mouse event"),
+        }
+    }
+
+    #[test]
+    fn test_encode_keyboard() {
+        let event = KeyboardEvent {
+            event_type: KeyEventType::Down,
+            key: 0x04,
+            modifiers: KeyboardModifiers {
+                left_ctrl: true,
+                left_shift: false,
+                left_alt: false,
+                left_meta: false,
+                right_ctrl: false,
+                right_shift: false,
+                right_alt: false,
+                right_meta: false,
+            },
+        };
+
+        let encoded = encode_keyboard_event(&event);
+        assert_eq!(encoded, vec![MSG_KEYBOARD, KB_EVENT_DOWN, 0x04, 0x01]);
+    }
+}

src/hid/keymap.rs

@@ -0,0 +1,430 @@
+//! USB HID keyboard key codes mapping
+//!
+//! This module provides mapping between JavaScript key codes and USB HID usage codes.
+//! Reference: USB HID Usage Tables 1.12, Section 10 (Keyboard/Keypad Page)
+
+/// USB HID key codes (Usage Page 0x07)
+#[allow(dead_code)]
+pub mod usb {
+    // Letters A-Z (0x04 - 0x1D)
+    pub const KEY_A: u8 = 0x04;
+    pub const KEY_B: u8 = 0x05;
+    pub const KEY_C: u8 = 0x06;
+    pub const KEY_D: u8 = 0x07;
+    pub const KEY_E: u8 = 0x08;
+    pub const KEY_F: u8 = 0x09;
+    pub const KEY_G: u8 = 0x0A;
+    pub const KEY_H: u8 = 0x0B;
+    pub const KEY_I: u8 = 0x0C;
+    pub const KEY_J: u8 = 0x0D;
+    pub const KEY_K: u8 = 0x0E;
+    pub const KEY_L: u8 = 0x0F;
+    pub const KEY_M: u8 = 0x10;
+    pub const KEY_N: u8 = 0x11;
+    pub const KEY_O: u8 = 0x12;
+    pub const KEY_P: u8 = 0x13;
+    pub const KEY_Q: u8 = 0x14;
+    pub const KEY_R: u8 = 0x15;
+    pub const KEY_S: u8 = 0x16;
+    pub const KEY_T: u8 = 0x17;
+    pub const KEY_U: u8 = 0x18;
+    pub const KEY_V: u8 = 0x19;
+    pub const KEY_W: u8 = 0x1A;
+    pub const KEY_X: u8 = 0x1B;
+    pub const KEY_Y: u8 = 0x1C;
+    pub const KEY_Z: u8 = 0x1D;
+
+    // Numbers 1-9, 0 (0x1E - 0x27)
+    pub const KEY_1: u8 = 0x1E;
+    pub const KEY_2: u8 = 0x1F;
+    pub const KEY_3: u8 = 0x20;
+    pub const KEY_4: u8 = 0x21;
+    pub const KEY_5: u8 = 0x22;
+    pub const KEY_6: u8 = 0x23;
+    pub const KEY_7: u8 = 0x24;
+    pub const KEY_8: u8 = 0x25;
+    pub const KEY_9: u8 = 0x26;
+    pub const KEY_0: u8 = 0x27;
+
+    // Control keys
+    pub const KEY_ENTER: u8 = 0x28;
+    pub const KEY_ESCAPE: u8 = 0x29;
+    pub const KEY_BACKSPACE: u8 = 0x2A;
+    pub const KEY_TAB: u8 = 0x2B;
+    pub const KEY_SPACE: u8 = 0x2C;
+    pub const KEY_MINUS: u8 = 0x2D;
+    pub const KEY_EQUAL: u8 = 0x2E;
+    pub const KEY_LEFT_BRACKET: u8 = 0x2F;
+    pub const KEY_RIGHT_BRACKET: u8 = 0x30;
+    pub const KEY_BACKSLASH: u8 = 0x31;
+    pub const KEY_HASH: u8 = 0x32; // Non-US # and ~
+    pub const KEY_SEMICOLON: u8 = 0x33;
+    pub const KEY_APOSTROPHE: u8 = 0x34;
+    pub const KEY_GRAVE: u8 = 0x35;
+    pub const KEY_COMMA: u8 = 0x36;
+    pub const KEY_PERIOD: u8 = 0x37;
+    pub const KEY_SLASH: u8 = 0x38;
+    pub const KEY_CAPS_LOCK: u8 = 0x39;
+
+    // Function keys F1-F12
+    pub const KEY_F1: u8 = 0x3A;
+    pub const KEY_F2: u8 = 0x3B;
+    pub const KEY_F3: u8 = 0x3C;
+    pub const KEY_F4: u8 = 0x3D;
+    pub const KEY_F5: u8 = 0x3E;
+    pub const KEY_F6: u8 = 0x3F;
+    pub const KEY_F7: u8 = 0x40;
+    pub const KEY_F8: u8 = 0x41;
+    pub const KEY_F9: u8 = 0x42;
+    pub const KEY_F10: u8 = 0x43;
+    pub const KEY_F11: u8 = 0x44;
+    pub const KEY_F12: u8 = 0x45;
+
+    // Special keys
+    pub const KEY_PRINT_SCREEN: u8 = 0x46;
+    pub const KEY_SCROLL_LOCK: u8 = 0x47;
+    pub const KEY_PAUSE: u8 = 0x48;
+    pub const KEY_INSERT: u8 = 0x49;
+    pub const KEY_HOME: u8 = 0x4A;
+    pub const KEY_PAGE_UP: u8 = 0x4B;
+    pub const KEY_DELETE: u8 = 0x4C;
+    pub const KEY_END: u8 = 0x4D;
+    pub const KEY_PAGE_DOWN: u8 = 0x4E;
+    pub const KEY_RIGHT_ARROW: u8 = 0x4F;
+    pub const KEY_LEFT_ARROW: u8 = 0x50;
+    pub const KEY_DOWN_ARROW: u8 = 0x51;
+    pub const KEY_UP_ARROW: u8 = 0x52;
+
+    // Numpad
+    pub const KEY_NUM_LOCK: u8 = 0x53;
+    pub const KEY_NUMPAD_DIVIDE: u8 = 0x54;
+    pub const KEY_NUMPAD_MULTIPLY: u8 = 0x55;
+    pub const KEY_NUMPAD_MINUS: u8 = 0x56;
+    pub const KEY_NUMPAD_PLUS: u8 = 0x57;
+    pub const KEY_NUMPAD_ENTER: u8 = 0x58;
+    pub const KEY_NUMPAD_1: u8 = 0x59;
+    pub const KEY_NUMPAD_2: u8 = 0x5A;
+    pub const KEY_NUMPAD_3: u8 = 0x5B;
+    pub const KEY_NUMPAD_4: u8 = 0x5C;
+    pub const KEY_NUMPAD_5: u8 = 0x5D;
+    pub const KEY_NUMPAD_6: u8 = 0x5E;
+    pub const KEY_NUMPAD_7: u8 = 0x5F;
+    pub const KEY_NUMPAD_8: u8 = 0x60;
+    pub const KEY_NUMPAD_9: u8 = 0x61;
+    pub const KEY_NUMPAD_0: u8 = 0x62;
+    pub const KEY_NUMPAD_DECIMAL: u8 = 0x63;
+
+    // Additional keys
+    pub const KEY_NON_US_BACKSLASH: u8 = 0x64;
+    pub const KEY_APPLICATION: u8 = 0x65; // Context menu
+    pub const KEY_POWER: u8 = 0x66;
+    pub const KEY_NUMPAD_EQUAL: u8 = 0x67;
+
+    // F13-F24
+    pub const KEY_F13: u8 = 0x68;
+    pub const KEY_F14: u8 = 0x69;
+    pub const KEY_F15: u8 = 0x6A;
+    pub const KEY_F16: u8 = 0x6B;
+    pub const KEY_F17: u8 = 0x6C;
+    pub const KEY_F18: u8 = 0x6D;
+    pub const KEY_F19: u8 = 0x6E;
+    pub const KEY_F20: u8 = 0x6F;
+    pub const KEY_F21: u8 = 0x70;
+    pub const KEY_F22: u8 = 0x71;
+    pub const KEY_F23: u8 = 0x72;
+    pub const KEY_F24: u8 = 0x73;
+
+    // Modifier keys (these are handled separately in the modifier byte)
+    pub const KEY_LEFT_CTRL: u8 = 0xE0;
+    pub const KEY_LEFT_SHIFT: u8 = 0xE1;
+    pub const KEY_LEFT_ALT: u8 = 0xE2;
+    pub const KEY_LEFT_META: u8 = 0xE3;
+    pub const KEY_RIGHT_CTRL: u8 = 0xE4;
+    pub const KEY_RIGHT_SHIFT: u8 = 0xE5;
+    pub const KEY_RIGHT_ALT: u8 = 0xE6;
+    pub const KEY_RIGHT_META: u8 = 0xE7;
+}
+
+/// JavaScript key codes (event.keyCode / event.code)
+#[allow(dead_code)]
+pub mod js {
+    // Letters
+    pub const KEY_A: u8 = 65;
+    pub const KEY_B: u8 = 66;
+    pub const KEY_C: u8 = 67;
+    pub const KEY_D: u8 = 68;
+    pub const KEY_E: u8 = 69;
+    pub const KEY_F: u8 = 70;
+    pub const KEY_G: u8 = 71;
+    pub const KEY_H: u8 = 72;
+    pub const KEY_I: u8 = 73;
+    pub const KEY_J: u8 = 74;
+    pub const KEY_K: u8 = 75;
+    pub const KEY_L: u8 = 76;
+    pub const KEY_M: u8 = 77;
+    pub const KEY_N: u8 = 78;
+    pub const KEY_O: u8 = 79;
+    pub const KEY_P: u8 = 80;
+    pub const KEY_Q: u8 = 81;
+    pub const KEY_R: u8 = 82;
+    pub const KEY_S: u8 = 83;
+    pub const KEY_T: u8 = 84;
+    pub const KEY_U: u8 = 85;
+    pub const KEY_V: u8 = 86;
+    pub const KEY_W: u8 = 87;
+    pub const KEY_X: u8 = 88;
+    pub const KEY_Y: u8 = 89;
+    pub const KEY_Z: u8 = 90;
+
+    // Numbers (top row)
+    pub const KEY_0: u8 = 48;
+    pub const KEY_1: u8 = 49;
+    pub const KEY_2: u8 = 50;
+    pub const KEY_3: u8 = 51;
+    pub const KEY_4: u8 = 52;
+    pub const KEY_5: u8 = 53;
+    pub const KEY_6: u8 = 54;
+    pub const KEY_7: u8 = 55;
+    pub const KEY_8: u8 = 56;
+    pub const KEY_9: u8 = 57;
+
+    // Function keys
+    pub const KEY_F1: u8 = 112;
+    pub const KEY_F2: u8 = 113;
+    pub const KEY_F3: u8 = 114;
+    pub const KEY_F4: u8 = 115;
+    pub const KEY_F5: u8 = 116;
+    pub const KEY_F6: u8 = 117;
+    pub const KEY_F7: u8 = 118;
+    pub const KEY_F8: u8 = 119;
+    pub const KEY_F9: u8 = 120;
+    pub const KEY_F10: u8 = 121;
+    pub const KEY_F11: u8 = 122;
+    pub const KEY_F12: u8 = 123;
+
+    // Control keys
+    pub const KEY_BACKSPACE: u8 = 8;
+    pub const KEY_TAB: u8 = 9;
+    pub const KEY_ENTER: u8 = 13;
+    pub const KEY_SHIFT: u8 = 16;
+    pub const KEY_CTRL: u8 = 17;
+    pub const KEY_ALT: u8 = 18;
+    pub const KEY_PAUSE: u8 = 19;
+    pub const KEY_CAPS_LOCK: u8 = 20;
+    pub const KEY_ESCAPE: u8 = 27;
+    pub const KEY_SPACE: u8 = 32;
+    pub const KEY_PAGE_UP: u8 = 33;
+    pub const KEY_PAGE_DOWN: u8 = 34;
+    pub const KEY_END: u8 = 35;
+    pub const KEY_HOME: u8 = 36;
+    pub const KEY_LEFT: u8 = 37;
+    pub const KEY_UP: u8 = 38;
+    pub const KEY_RIGHT: u8 = 39;
+    pub const KEY_DOWN: u8 = 40;
+    pub const KEY_INSERT: u8 = 45;
+    pub const KEY_DELETE: u8 = 46;
+
+    // Punctuation
+    pub const KEY_SEMICOLON: u8 = 186;
+    pub const KEY_EQUAL: u8 = 187;
+    pub const KEY_COMMA: u8 = 188;
+    pub const KEY_MINUS: u8 = 189;
+    pub const KEY_PERIOD: u8 = 190;
+    pub const KEY_SLASH: u8 = 191;
+    pub const KEY_GRAVE: u8 = 192;
+    pub const KEY_LEFT_BRACKET: u8 = 219;
+    pub const KEY_BACKSLASH: u8 = 220;
+    pub const KEY_RIGHT_BRACKET: u8 = 221;
+    pub const KEY_APOSTROPHE: u8 = 222;
+
+    // Numpad
+    pub const KEY_NUMPAD_0: u8 = 96;
+    pub const KEY_NUMPAD_1: u8 = 97;
+    pub const KEY_NUMPAD_2: u8 = 98;
+    pub const KEY_NUMPAD_3: u8 = 99;
+    pub const KEY_NUMPAD_4: u8 = 100;
+    pub const KEY_NUMPAD_5: u8 = 101;
+    pub const KEY_NUMPAD_6: u8 = 102;
+    pub const KEY_NUMPAD_7: u8 = 103;
+    pub const KEY_NUMPAD_8: u8 = 104;
+    pub const KEY_NUMPAD_9: u8 = 105;
+    pub const KEY_NUMPAD_MULTIPLY: u8 = 106;
+    pub const KEY_NUMPAD_ADD: u8 = 107;
+    pub const KEY_NUMPAD_SUBTRACT: u8 = 109;
+    pub const KEY_NUMPAD_DECIMAL: u8 = 110;
+    pub const KEY_NUMPAD_DIVIDE: u8 = 111;
+
+    // Lock keys
+    pub const KEY_NUM_LOCK: u8 = 144;
+    pub const KEY_SCROLL_LOCK: u8 = 145;
+
+    // Windows keys
+    pub const KEY_META_LEFT: u8 = 91;
+    pub const KEY_META_RIGHT: u8 = 92;
+    pub const KEY_CONTEXT_MENU: u8 = 93;
+}
+
+/// JavaScript keyCode to USB HID keyCode mapping table
+/// Using a fixed-size array for O(1) lookup instead of HashMap
+/// Index = JavaScript keyCode, Value = USB HID keyCode (0 means unmapped)
+static JS_TO_USB_TABLE: [u8; 256] = {
+    let mut table = [0u8; 256];
+
+    // Letters A-Z (JS 65-90 -> USB 0x04-0x1D)
+    let mut i = 0u8;
+    while i < 26 {
+        table[(65 + i) as usize] = usb::KEY_A + i;
+        i += 1;
+    }
+
+    // Numbers 1-9, 0 (JS 49-57, 48 -> USB 0x1E-0x27)
+    table[49] = usb::KEY_1;  // 1
+    table[50] = usb::KEY_2;  // 2
+    table[51] = usb::KEY_3;  // 3
+    table[52] = usb::KEY_4;  // 4
+    table[53] = usb::KEY_5;  // 5
+    table[54] = usb::KEY_6;  // 6
+    table[55] = usb::KEY_7;  // 7
+    table[56] = usb::KEY_8;  // 8
+    table[57] = usb::KEY_9;  // 9
+    table[48] = usb::KEY_0;  // 0
+
+    // Function keys F1-F12 (JS 112-123 -> USB 0x3A-0x45)
+    table[112] = usb::KEY_F1;
+    table[113] = usb::KEY_F2;
+    table[114] = usb::KEY_F3;
+    table[115] = usb::KEY_F4;
+    table[116] = usb::KEY_F5;
+    table[117] = usb::KEY_F6;
+    table[118] = usb::KEY_F7;
+    table[119] = usb::KEY_F8;
+    table[120] = usb::KEY_F9;
+    table[121] = usb::KEY_F10;
+    table[122] = usb::KEY_F11;
+    table[123] = usb::KEY_F12;
+
+    // Control keys
+    table[13] = usb::KEY_ENTER;      // Enter
+    table[27] = usb::KEY_ESCAPE;     // Escape
+    table[8] = usb::KEY_BACKSPACE;   // Backspace
+    table[9] = usb::KEY_TAB;         // Tab
+    table[32] = usb::KEY_SPACE;      // Space
+    table[20] = usb::KEY_CAPS_LOCK;  // Caps Lock
+
+    // Punctuation (JS codes vary by browser/layout)
+    table[189] = usb::KEY_MINUS;         // -
+    table[187] = usb::KEY_EQUAL;         // =
+    table[219] = usb::KEY_LEFT_BRACKET;  // [
+    table[221] = usb::KEY_RIGHT_BRACKET; // ]
+    table[220] = usb::KEY_BACKSLASH;     // \
+    table[186] = usb::KEY_SEMICOLON;     // ;
+    table[222] = usb::KEY_APOSTROPHE;    // '
+    table[192] = usb::KEY_GRAVE;         // `
+    table[188] = usb::KEY_COMMA;         // ,
+    table[190] = usb::KEY_PERIOD;        // .
+    table[191] = usb::KEY_SLASH;         // /
+
+    // Navigation keys
+    table[45] = usb::KEY_INSERT;
+    table[46] = usb::KEY_DELETE;
+    table[36] = usb::KEY_HOME;
+    table[35] = usb::KEY_END;
+    table[33] = usb::KEY_PAGE_UP;
+    table[34] = usb::KEY_PAGE_DOWN;
+
+    // Arrow keys
+    table[39] = usb::KEY_RIGHT_ARROW;
+    table[37] = usb::KEY_LEFT_ARROW;
+    table[40] = usb::KEY_DOWN_ARROW;
+    table[38] = usb::KEY_UP_ARROW;
+
+    // Numpad
+    table[144] = usb::KEY_NUM_LOCK;
+    table[111] = usb::KEY_NUMPAD_DIVIDE;
+    table[106] = usb::KEY_NUMPAD_MULTIPLY;
+    table[109] = usb::KEY_NUMPAD_MINUS;
+    table[107] = usb::KEY_NUMPAD_PLUS;
+    table[96] = usb::KEY_NUMPAD_0;
+    table[97] = usb::KEY_NUMPAD_1;
+    table[98] = usb::KEY_NUMPAD_2;
+    table[99] = usb::KEY_NUMPAD_3;
+    table[100] = usb::KEY_NUMPAD_4;
+    table[101] = usb::KEY_NUMPAD_5;
+    table[102] = usb::KEY_NUMPAD_6;
+    table[103] = usb::KEY_NUMPAD_7;
+    table[104] = usb::KEY_NUMPAD_8;
+    table[105] = usb::KEY_NUMPAD_9;
+    table[110] = usb::KEY_NUMPAD_DECIMAL;
+
+    // Special keys
+    table[19] = usb::KEY_PAUSE;
+    table[145] = usb::KEY_SCROLL_LOCK;
+    table[93] = usb::KEY_APPLICATION;  // Context menu
+
+    // Modifier keys
+    table[17] = usb::KEY_LEFT_CTRL;
+    table[16] = usb::KEY_LEFT_SHIFT;
+    table[18] = usb::KEY_LEFT_ALT;
+    table[91] = usb::KEY_LEFT_META;   // Left Windows/Command
+    table[92] = usb::KEY_RIGHT_META;  // Right Windows/Command
+
+    table
+};
+
+/// Convert JavaScript keyCode to USB HID keyCode
+///
+/// Uses a fixed-size lookup table for O(1) performance.
+/// Returns None if the key code is not mapped.
+#[inline]
+pub fn js_to_usb(js_code: u8) -> Option<u8> {
+    let usb_code = JS_TO_USB_TABLE[js_code as usize];
+    if usb_code != 0 {
+        Some(usb_code)
+    } else {
+        None
+    }
+}
+
+/// Check if a key code is a modifier key
+pub fn is_modifier_key(usb_code: u8) -> bool {
+    (0xE0..=0xE7).contains(&usb_code)
+}
+
+/// Get modifier bit for a modifier key
+pub fn modifier_bit(usb_code: u8) -> Option<u8> {
+    match usb_code {
+        usb::KEY_LEFT_CTRL => Some(0x01),
+        usb::KEY_LEFT_SHIFT => Some(0x02),
+        usb::KEY_LEFT_ALT => Some(0x04),
+        usb::KEY_LEFT_META => Some(0x08),
+        usb::KEY_RIGHT_CTRL => Some(0x10),
+        usb::KEY_RIGHT_SHIFT => Some(0x20),
+        usb::KEY_RIGHT_ALT => Some(0x40),
+        usb::KEY_RIGHT_META => Some(0x80),
+        _ => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_letter_mapping() {
+        assert_eq!(js_to_usb(65), Some(usb::KEY_A)); // A
+        assert_eq!(js_to_usb(90), Some(usb::KEY_Z)); // Z
+    }
+
+    #[test]
+    fn test_number_mapping() {
+        assert_eq!(js_to_usb(48), Some(usb::KEY_0));
+        assert_eq!(js_to_usb(49), Some(usb::KEY_1));
+    }
+
+    #[test]
+    fn test_modifier_key() {
+        assert!(is_modifier_key(usb::KEY_LEFT_CTRL));
+        assert!(is_modifier_key(usb::KEY_RIGHT_SHIFT));
+        assert!(!is_modifier_key(usb::KEY_A));
+    }
+}

src/hid/mod.rs

@@ -0,0 +1,417 @@
+//! HID (Human Interface Device) control module
+//!
+//! This module provides keyboard and mouse control for remote KVM:
+//! - USB OTG gadget mode (native Linux USB gadget)
+//! - CH9329 serial HID controller
+//!
+//! Architecture:
+//! ```text
+//! Web Client --> WebSocket/DataChannel --> HID Events --> Backend --> Target PC
+//!                                              |
+//!                                      [OTG | CH9329]
+//! ```
+
+pub mod backend;
+pub mod ch9329;
+pub mod datachannel;
+pub mod keymap;
+pub mod monitor;
+pub mod otg;
+pub mod types;
+pub mod websocket;
+
+pub use backend::{HidBackend, HidBackendType};
+pub use monitor::{HidHealthMonitor, HidHealthStatus, HidMonitorConfig};
+pub use otg::LedState;
+pub use types::{
+    KeyEventType, KeyboardEvent, KeyboardModifiers, MouseButton, MouseEvent, MouseEventType,
+};
+
+/// HID backend information
+#[derive(Debug, Clone)]
+pub struct HidInfo {
+    /// Backend name
+    pub name: &'static str,
+    /// Whether backend is initialized
+    pub initialized: bool,
+    /// Whether absolute mouse positioning is supported
+    pub supports_absolute_mouse: bool,
+    /// Screen resolution for absolute mouse
+    pub screen_resolution: Option<(u32, u32)>,
+}
+
+use std::sync::Arc;
+use tokio::sync::RwLock;
+use tracing::{info, warn};
+
+use crate::error::{AppError, Result};
+use crate::otg::OtgService;
+
+/// HID controller managing keyboard and mouse input
+pub struct HidController {
+    /// OTG Service reference (only used when backend is OTG)
+    otg_service: Option<Arc<OtgService>>,
+    /// Active backend
+    backend: Arc<RwLock<Option<Box<dyn HidBackend>>>>,
+    /// Backend type (mutable for reload)
+    backend_type: RwLock<HidBackendType>,
+    /// Event bus for broadcasting state changes (optional)
+    events: tokio::sync::RwLock<Option<Arc<crate::events::EventBus>>>,
+    /// Health monitor for error tracking and recovery
+    monitor: Arc<HidHealthMonitor>,
+}
+
+impl HidController {
+    /// Create a new HID controller with specified backend
+    ///
+    /// For OTG backend, otg_service should be provided to support hot-reload
+    pub fn new(backend_type: HidBackendType, otg_service: Option<Arc<OtgService>>) -> Self {
+        Self {
+            otg_service,
+            backend: Arc::new(RwLock::new(None)),
+            backend_type: RwLock::new(backend_type),
+            events: tokio::sync::RwLock::new(None),
+            monitor: Arc::new(HidHealthMonitor::with_defaults()),
+        }
+    }
+
+    /// Set event bus for broadcasting state changes
+    pub async fn set_event_bus(&self, events: Arc<crate::events::EventBus>) {
+        *self.events.write().await = Some(events.clone());
+        // Also set event bus on the monitor for health notifications
+        self.monitor.set_event_bus(events).await;
+    }
+
+    /// Initialize the HID backend
+    pub async fn init(&self) -> Result<()> {
+        let backend_type = self.backend_type.read().await.clone();
+        let backend: Box<dyn HidBackend> = match backend_type {
+            HidBackendType::Otg => {
+                // Request HID functions from OtgService
+                let otg_service = self
+                    .otg_service
+                    .as_ref()
+                    .ok_or_else(|| AppError::Internal("OtgService not available".into()))?;
+
+                info!("Requesting HID functions from OtgService");
+                let handles = otg_service.enable_hid().await?;
+
+                // Create OtgBackend from handles (no longer manages gadget itself)
+                info!("Creating OTG HID backend from device paths");
+                Box::new(otg::OtgBackend::from_handles(handles)?)
+            }
+            HidBackendType::Ch9329 { ref port, baud_rate } => {
+                info!("Initializing CH9329 HID backend on {} @ {} baud", port, baud_rate);
+                Box::new(ch9329::Ch9329Backend::with_baud_rate(port, baud_rate)?)
+            }
+            HidBackendType::None => {
+                warn!("HID backend disabled");
+                return Ok(());
+            }
+        };
+
+        backend.init().await?;
+        *self.backend.write().await = Some(backend);
+
+        info!("HID backend initialized: {:?}", backend_type);
+        Ok(())
+    }
+
+    /// Shutdown the HID backend and release resources
+    pub async fn shutdown(&self) -> Result<()> {
+        info!("Shutting down HID controller");
+
+        // Close the backend
+        *self.backend.write().await = None;
+
+        // If OTG backend, notify OtgService to disable HID
+        let backend_type = self.backend_type.read().await.clone();
+        if matches!(backend_type, HidBackendType::Otg) {
+            if let Some(ref otg_service) = self.otg_service {
+                info!("Disabling HID functions in OtgService");
+                otg_service.disable_hid().await?;
+            }
+        }
+
+        info!("HID controller shutdown complete");
+        Ok(())
+    }
+
+    /// Send keyboard event
+    pub async fn send_keyboard(&self, event: KeyboardEvent) -> Result<()> {
+        let backend = self.backend.read().await;
+        match backend.as_ref() {
+            Some(b) => {
+                match b.send_keyboard(event).await {
+                    Ok(_) => {
+                        // Check if we were in an error state and now recovered
+                        if self.monitor.is_error().await {
+                            let backend_type = self.backend_type.read().await;
+                            self.monitor.report_recovered(backend_type.name_str()).await;
+                        }
+                        Ok(())
+                    }
+                    Err(e) => {
+                        // Report error to monitor, but skip temporary EAGAIN retries
+                        // - "eagain_retry": within threshold, just temporary busy
+                        // - "eagain": exceeded threshold, report as error
+                        if let AppError::HidError { ref backend, ref reason, ref error_code } = e {
+                            if error_code != "eagain_retry" {
+                                self.monitor.report_error(backend, None, reason, error_code).await;
+                            }
+                        }
+                        Err(e)
+                    }
+                }
+            }
+            None => Err(AppError::BadRequest("HID backend not available".to_string())),
+        }
+    }
+
+    /// Send mouse event
+    pub async fn send_mouse(&self, event: MouseEvent) -> Result<()> {
+        let backend = self.backend.read().await;
+        match backend.as_ref() {
+            Some(b) => {
+                match b.send_mouse(event).await {
+                    Ok(_) => {
+                        // Check if we were in an error state and now recovered
+                        if self.monitor.is_error().await {
+                            let backend_type = self.backend_type.read().await;
+                            self.monitor.report_recovered(backend_type.name_str()).await;
+                        }
+                        Ok(())
+                    }
+                    Err(e) => {
+                        // Report error to monitor, but skip temporary EAGAIN retries
+                        // - "eagain_retry": within threshold, just temporary busy
+                        // - "eagain": exceeded threshold, report as error
+                        if let AppError::HidError { ref backend, ref reason, ref error_code } = e {
+                            if error_code != "eagain_retry" {
+                                self.monitor.report_error(backend, None, reason, error_code).await;
+                            }
+                        }
+                        Err(e)
+                    }
+                }
+            }
+            None => Err(AppError::BadRequest("HID backend not available".to_string())),
+        }
+    }
+
+    /// Reset all keys (release all pressed keys)
+    pub async fn reset(&self) -> Result<()> {
+        let backend = self.backend.read().await;
+        match backend.as_ref() {
+            Some(b) => b.reset().await,
+            None => Ok(()),
+        }
+    }
+
+    /// Check if backend is available
+    pub async fn is_available(&self) -> bool {
+        self.backend.read().await.is_some()
+    }
+
+    /// Get backend type
+    pub async fn backend_type(&self) -> HidBackendType {
+        self.backend_type.read().await.clone()
+    }
+
+    /// Get backend info
+    pub async fn info(&self) -> Option<HidInfo> {
+        let backend = self.backend.read().await;
+        backend.as_ref().map(|b| HidInfo {
+            name: b.name(),
+            initialized: true,
+            supports_absolute_mouse: b.supports_absolute_mouse(),
+            screen_resolution: b.screen_resolution(),
+        })
+    }
+
+    /// Get current state as SystemEvent
+    pub async fn current_state_event(&self) -> crate::events::SystemEvent {
+        let backend = self.backend.read().await;
+        let backend_type = self.backend_type().await;
+        let (backend_name, initialized) = match backend.as_ref() {
+            Some(b) => (b.name(), true),
+            None => (backend_type.name_str(), false),
+        };
+
+        // Include error information from monitor
+        let (error, error_code) = match self.monitor.status().await {
+            HidHealthStatus::Error { reason, error_code, .. } => {
+                (Some(reason), Some(error_code))
+            }
+            _ => (None, None),
+        };
+
+        crate::events::SystemEvent::HidStateChanged {
+            backend: backend_name.to_string(),
+            initialized,
+            error,
+            error_code,
+        }
+    }
+
+    /// Get the health monitor reference
+    pub fn monitor(&self) -> &Arc<HidHealthMonitor> {
+        &self.monitor
+    }
+
+    /// Get current health status
+    pub async fn health_status(&self) -> HidHealthStatus {
+        self.monitor.status().await
+    }
+
+    /// Check if the HID backend is healthy
+    pub async fn is_healthy(&self) -> bool {
+        self.monitor.is_healthy().await
+    }
+
+    /// Reload the HID backend with new type
+    pub async fn reload(&self, new_backend_type: HidBackendType) -> Result<()> {
+        info!("Reloading HID backend: {:?}", new_backend_type);
+
+        // Shutdown existing backend first
+        if let Some(backend) = self.backend.write().await.take() {
+            if let Err(e) = backend.shutdown().await {
+                warn!("Error shutting down old HID backend: {}", e);
+            }
+        }
+
+        // Create and initialize new backend
+        let new_backend: Option<Box<dyn HidBackend>> = match new_backend_type {
+            HidBackendType::Otg => {
+                info!("Initializing OTG HID backend");
+
+                // Get OtgService reference
+                let otg_service = match self.otg_service.as_ref() {
+                    Some(svc) => svc,
+                    None => {
+                        warn!("OTG backend requires OtgService, but it's not available");
+                        return Err(AppError::Config(
+                            "OTG backend not available (OtgService missing)".to_string()
+                        ));
+                    }
+                };
+
+                // Request HID functions from OtgService
+                match otg_service.enable_hid().await {
+                    Ok(handles) => {
+                        // Create OtgBackend from handles
+                        match otg::OtgBackend::from_handles(handles) {
+                            Ok(backend) => {
+                                let boxed: Box<dyn HidBackend> = Box::new(backend);
+                                match boxed.init().await {
+                                    Ok(_) => {
+                                        info!("OTG backend initialized successfully");
+                                        Some(boxed)
+                                    }
+                                    Err(e) => {
+                                        warn!("Failed to initialize OTG backend: {}", e);
+                                        // Cleanup: disable HID in OtgService
+                                        if let Err(e2) = otg_service.disable_hid().await {
+                                            warn!("Failed to cleanup HID after init failure: {}", e2);
+                                        }
+                                        None
+                                    }
+                                }
+                            }
+                            Err(e) => {
+                                warn!("Failed to create OTG backend: {}", e);
+                                // Cleanup: disable HID in OtgService
+                                if let Err(e2) = otg_service.disable_hid().await {
+                                    warn!("Failed to cleanup HID after creation failure: {}", e2);
+                                }
+                                None
+                            }
+                        }
+                    }
+                    Err(e) => {
+                        warn!("Failed to enable HID in OtgService: {}", e);
+                        None
+                    }
+                }
+            }
+            HidBackendType::Ch9329 { ref port, baud_rate } => {
+                info!("Initializing CH9329 HID backend on {} @ {} baud", port, baud_rate);
+                match ch9329::Ch9329Backend::with_baud_rate(port, baud_rate) {
+                    Ok(b) => {
+                        let boxed = Box::new(b);
+                        match boxed.init().await {
+                            Ok(_) => Some(boxed),
+                            Err(e) => {
+                                warn!("Failed to initialize CH9329 backend: {}", e);
+                                None
+                            }
+                        }
+                    }
+                    Err(e) => {
+                        warn!("Failed to create CH9329 backend: {}", e);
+                        None
+                    }
+                }
+            }
+            HidBackendType::None => {
+                warn!("HID backend disabled");
+                None
+            }
+        };
+
+        *self.backend.write().await = new_backend;
+
+        if self.backend.read().await.is_some() {
+            info!("HID backend reloaded successfully: {:?}", new_backend_type);
+
+            // Update backend_type on success
+            *self.backend_type.write().await = new_backend_type.clone();
+
+            // Reset monitor state on successful reload
+            self.monitor.reset().await;
+
+            // Publish HID state changed event
+            let backend_name = new_backend_type.name_str().to_string();
+            self.publish_event(crate::events::SystemEvent::HidStateChanged {
+                backend: backend_name,
+                initialized: true,
+                error: None,
+                error_code: None,
+            })
+            .await;
+
+            Ok(())
+        } else {
+            warn!("HID backend reload resulted in no active backend");
+
+            // Update backend_type even on failure (to reflect the attempted change)
+            *self.backend_type.write().await = new_backend_type.clone();
+
+            // Publish event with initialized=false
+            self.publish_event(crate::events::SystemEvent::HidStateChanged {
+                backend: new_backend_type.name_str().to_string(),
+                initialized: false,
+                error: Some("Failed to initialize HID backend".to_string()),
+                error_code: Some("init_failed".to_string()),
+            })
+            .await;
+
+            Err(AppError::Internal(
+                "Failed to reload HID backend".to_string(),
+            ))
+        }
+    }
+
+    /// Publish event to event bus if available
+    async fn publish_event(&self, event: crate::events::SystemEvent) {
+        if let Some(events) = self.events.read().await.as_ref() {
+            events.publish(event);
+        }
+    }
+}
+
+impl Default for HidController {
+    fn default() -> Self {
+        Self::new(HidBackendType::None, None)
+    }
+}

src/hid/monitor.rs

@@ -0,0 +1,429 @@
+//! HID device health monitoring
+//!
+//! This module provides health monitoring for HID devices, including:
+//! - Device connectivity checks
+//! - Automatic reconnection on failure
+//! - Error tracking and notification
+//! - Log throttling to prevent log flooding
+
+use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+use tokio::sync::RwLock;
+use tracing::{debug, warn};
+
+use crate::events::{EventBus, SystemEvent};
+use crate::utils::LogThrottler;
+
+/// HID health status
+#[derive(Debug, Clone, PartialEq)]
+pub enum HidHealthStatus {
+    /// Device is healthy and operational
+    Healthy,
+    /// Device has an error, attempting recovery
+    Error {
+        /// Human-readable error reason
+        reason: String,
+        /// Error code for programmatic handling
+        error_code: String,
+        /// Number of recovery attempts made
+        retry_count: u32,
+    },
+    /// Device is disconnected
+    Disconnected,
+}
+
+impl Default for HidHealthStatus {
+    fn default() -> Self {
+        Self::Healthy
+    }
+}
+
+/// HID health monitor configuration
+#[derive(Debug, Clone)]
+pub struct HidMonitorConfig {
+    /// Health check interval in milliseconds
+    pub check_interval_ms: u64,
+    /// Retry interval when device is lost (milliseconds)
+    pub retry_interval_ms: u64,
+    /// Maximum retry attempts before giving up (0 = infinite)
+    pub max_retries: u32,
+    /// Log throttle interval in seconds
+    pub log_throttle_secs: u64,
+    /// Recovery cooldown in milliseconds (suppress logs after recovery)
+    pub recovery_cooldown_ms: u64,
+}
+
+impl Default for HidMonitorConfig {
+    fn default() -> Self {
+        Self {
+            check_interval_ms: 1000,
+            retry_interval_ms: 1000,
+            max_retries: 0, // infinite retry
+            log_throttle_secs: 5,
+            recovery_cooldown_ms: 1000, // 1 second cooldown after recovery
+        }
+    }
+}
+
+/// HID health monitor
+///
+/// Monitors HID device health and manages error recovery.
+/// Publishes WebSocket events when device status changes.
+pub struct HidHealthMonitor {
+    /// Current health status
+    status: RwLock<HidHealthStatus>,
+    /// Event bus for notifications
+    events: RwLock<Option<Arc<EventBus>>>,
+    /// Log throttler to prevent log flooding
+    throttler: LogThrottler,
+    /// Configuration
+    config: HidMonitorConfig,
+    /// Whether monitoring is active (reserved for future use)
+    #[allow(dead_code)]
+    running: AtomicBool,
+    /// Current retry count
+    retry_count: AtomicU32,
+    /// Last error code (for change detection)
+    last_error_code: RwLock<Option<String>>,
+    /// Last recovery timestamp (milliseconds since start, for cooldown)
+    last_recovery_ms: AtomicU64,
+    /// Start instant for timing
+    start_instant: Instant,
+}
+
+impl HidHealthMonitor {
+    /// Create a new HID health monitor with the specified configuration
+    pub fn new(config: HidMonitorConfig) -> Self {
+        let throttle_secs = config.log_throttle_secs;
+        Self {
+            status: RwLock::new(HidHealthStatus::Healthy),
+            events: RwLock::new(None),
+            throttler: LogThrottler::with_secs(throttle_secs),
+            config,
+            running: AtomicBool::new(false),
+            retry_count: AtomicU32::new(0),
+            last_error_code: RwLock::new(None),
+            last_recovery_ms: AtomicU64::new(0),
+            start_instant: Instant::now(),
+        }
+    }
+
+    /// Create a new HID health monitor with default configuration
+    pub fn with_defaults() -> Self {
+        Self::new(HidMonitorConfig::default())
+    }
+
+    /// Set the event bus for broadcasting state changes
+    pub async fn set_event_bus(&self, events: Arc<EventBus>) {
+        *self.events.write().await = Some(events);
+    }
+
+    /// Report an error from HID operations
+    ///
+    /// This method is called when an HID operation fails. It:
+    /// 1. Updates the health status
+    /// 2. Logs the error (with throttling and cooldown respect)
+    /// 3. Publishes a WebSocket event if the error is new or changed
+    ///
+    /// # Arguments
+    ///
+    /// * `backend` - The HID backend type ("otg" or "ch9329")
+    /// * `device` - The device path (if known)
+    /// * `reason` - Human-readable error description
+    /// * `error_code` - Error code for programmatic handling
+    pub async fn report_error(
+        &self,
+        backend: &str,
+        device: Option<&str>,
+        reason: &str,
+        error_code: &str,
+    ) {
+        let count = self.retry_count.fetch_add(1, Ordering::Relaxed) + 1;
+
+        // Check if we're in cooldown period after recent recovery
+        let current_ms = self.start_instant.elapsed().as_millis() as u64;
+        let last_recovery = self.last_recovery_ms.load(Ordering::Relaxed);
+        let in_cooldown = last_recovery > 0 && current_ms < last_recovery + self.config.recovery_cooldown_ms;
+
+        // Check if error code changed
+        let error_changed = {
+            let last = self.last_error_code.read().await;
+            last.as_ref().map(|s| s.as_str()) != Some(error_code)
+        };
+
+        // Log with throttling (skip if in cooldown period unless error type changed)
+        let throttle_key = format!("hid_{}_{}", backend, error_code);
+        if !in_cooldown && (error_changed || self.throttler.should_log(&throttle_key)) {
+            warn!(
+                "HID {} error: {} (code: {}, attempt: {})",
+                backend, reason, error_code, count
+            );
+        }
+
+        // Update last error code
+        *self.last_error_code.write().await = Some(error_code.to_string());
+
+        // Update status
+        *self.status.write().await = HidHealthStatus::Error {
+            reason: reason.to_string(),
+            error_code: error_code.to_string(),
+            retry_count: count,
+        };
+
+        // Publish event (only if error changed or first occurrence, and not in cooldown)
+        if !in_cooldown && (error_changed || count == 1) {
+            if let Some(ref events) = *self.events.read().await {
+                events.publish(SystemEvent::HidDeviceLost {
+                    backend: backend.to_string(),
+                    device: device.map(|s| s.to_string()),
+                    reason: reason.to_string(),
+                    error_code: error_code.to_string(),
+                });
+            }
+        }
+    }
+
+    /// Report that a reconnection attempt is starting
+    ///
+    /// Publishes a reconnecting event to notify clients.
+    ///
+    /// # Arguments
+    ///
+    /// * `backend` - The HID backend type
+    pub async fn report_reconnecting(&self, backend: &str) {
+        let attempt = self.retry_count.load(Ordering::Relaxed);
+
+        // Only publish every 5 attempts to avoid event spam
+        if attempt == 1 || attempt % 5 == 0 {
+            debug!("HID {} reconnecting, attempt {}", backend, attempt);
+
+            if let Some(ref events) = *self.events.read().await {
+                events.publish(SystemEvent::HidReconnecting {
+                    backend: backend.to_string(),
+                    attempt,
+                });
+            }
+        }
+    }
+
+    /// Report that the device has recovered
+    ///
+    /// This method is called when the HID device successfully reconnects.
+    /// It resets the error state and publishes a recovery event.
+    ///
+    /// # Arguments
+    ///
+    /// * `backend` - The HID backend type
+    pub async fn report_recovered(&self, backend: &str) {
+        let prev_status = self.status.read().await.clone();
+
+        // Only report recovery if we were in an error state
+        if prev_status != HidHealthStatus::Healthy {
+            let retry_count = self.retry_count.load(Ordering::Relaxed);
+
+            // Set cooldown timestamp
+            let current_ms = self.start_instant.elapsed().as_millis() as u64;
+            self.last_recovery_ms.store(current_ms, Ordering::Relaxed);
+
+            // Only log and publish events if there were multiple retries
+            // (avoid log spam for transient single-retry recoveries)
+            if retry_count > 1 {
+                debug!(
+                    "HID {} recovered after {} retries",
+                    backend, retry_count
+                );
+
+                // Publish recovery event
+                if let Some(ref events) = *self.events.read().await {
+                    events.publish(SystemEvent::HidRecovered {
+                        backend: backend.to_string(),
+                    });
+
+                    // Also publish state changed to indicate healthy state
+                    events.publish(SystemEvent::HidStateChanged {
+                        backend: backend.to_string(),
+                        initialized: true,
+                        error: None,
+                        error_code: None,
+                    });
+                }
+            }
+
+            // Reset state (always reset, even for single-retry recoveries)
+            self.retry_count.store(0, Ordering::Relaxed);
+            *self.last_error_code.write().await = None;
+            *self.status.write().await = HidHealthStatus::Healthy;
+        }
+    }
+
+    /// Get the current health status
+    pub async fn status(&self) -> HidHealthStatus {
+        self.status.read().await.clone()
+    }
+
+    /// Get the current retry count
+    pub fn retry_count(&self) -> u32 {
+        self.retry_count.load(Ordering::Relaxed)
+    }
+
+    /// Check if the monitor is in an error state
+    pub async fn is_error(&self) -> bool {
+        matches!(*self.status.read().await, HidHealthStatus::Error { .. })
+    }
+
+    /// Check if the monitor is healthy
+    pub async fn is_healthy(&self) -> bool {
+        matches!(*self.status.read().await, HidHealthStatus::Healthy)
+    }
+
+    /// Reset the monitor to healthy state without publishing events
+    ///
+    /// This is useful during initialization.
+    pub async fn reset(&self) {
+        self.retry_count.store(0, Ordering::Relaxed);
+        *self.last_error_code.write().await = None;
+        *self.status.write().await = HidHealthStatus::Healthy;
+        self.throttler.clear_all();
+    }
+
+    /// Get the configuration
+    pub fn config(&self) -> &HidMonitorConfig {
+        &self.config
+    }
+
+    /// Check if we should continue retrying
+    ///
+    /// Returns `false` if max_retries is set and we've exceeded it.
+    pub fn should_retry(&self) -> bool {
+        if self.config.max_retries == 0 {
+            return true; // Infinite retry
+        }
+        self.retry_count.load(Ordering::Relaxed) < self.config.max_retries
+    }
+
+    /// Get the retry interval
+    pub fn retry_interval(&self) -> Duration {
+        Duration::from_millis(self.config.retry_interval_ms)
+    }
+}
+
+impl Default for HidHealthMonitor {
+    fn default() -> Self {
+        Self::with_defaults()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_initial_status() {
+        let monitor = HidHealthMonitor::with_defaults();
+        assert!(monitor.is_healthy().await);
+        assert!(!monitor.is_error().await);
+        assert_eq!(monitor.retry_count(), 0);
+    }
+
+    #[tokio::test]
+    async fn test_report_error() {
+        let monitor = HidHealthMonitor::with_defaults();
+
+        monitor
+            .report_error("otg", Some("/dev/hidg0"), "Device not found", "enoent")
+            .await;
+
+        assert!(monitor.is_error().await);
+        assert_eq!(monitor.retry_count(), 1);
+
+        if let HidHealthStatus::Error {
+            reason,
+            error_code,
+            retry_count,
+        } = monitor.status().await
+        {
+            assert_eq!(reason, "Device not found");
+            assert_eq!(error_code, "enoent");
+            assert_eq!(retry_count, 1);
+        } else {
+            panic!("Expected Error status");
+        }
+    }
+
+    #[tokio::test]
+    async fn test_report_recovered() {
+        let monitor = HidHealthMonitor::with_defaults();
+
+        // First report an error
+        monitor
+            .report_error("ch9329", None, "Port not found", "port_not_found")
+            .await;
+        assert!(monitor.is_error().await);
+
+        // Then report recovery
+        monitor.report_recovered("ch9329").await;
+        assert!(monitor.is_healthy().await);
+        assert_eq!(monitor.retry_count(), 0);
+    }
+
+    #[tokio::test]
+    async fn test_retry_count_increments() {
+        let monitor = HidHealthMonitor::with_defaults();
+
+        for i in 1..=5 {
+            monitor
+                .report_error("otg", None, "Error", "io_error")
+                .await;
+            assert_eq!(monitor.retry_count(), i);
+        }
+    }
+
+    #[tokio::test]
+    async fn test_should_retry_infinite() {
+        let monitor = HidHealthMonitor::new(HidMonitorConfig {
+            max_retries: 0, // infinite
+            ..Default::default()
+        });
+
+        for _ in 0..100 {
+            monitor
+                .report_error("otg", None, "Error", "io_error")
+                .await;
+            assert!(monitor.should_retry());
+        }
+    }
+
+    #[tokio::test]
+    async fn test_should_retry_limited() {
+        let monitor = HidHealthMonitor::new(HidMonitorConfig {
+            max_retries: 3,
+            ..Default::default()
+        });
+
+        assert!(monitor.should_retry());
+
+        monitor.report_error("otg", None, "Error", "io_error").await;
+        assert!(monitor.should_retry()); // 1 < 3
+
+        monitor.report_error("otg", None, "Error", "io_error").await;
+        assert!(monitor.should_retry()); // 2 < 3
+
+        monitor.report_error("otg", None, "Error", "io_error").await;
+        assert!(!monitor.should_retry()); // 3 >= 3
+    }
+
+    #[tokio::test]
+    async fn test_reset() {
+        let monitor = HidHealthMonitor::with_defaults();
+
+        monitor
+            .report_error("otg", None, "Error", "io_error")
+            .await;
+        assert!(monitor.is_error().await);
+
+        monitor.reset().await;
+        assert!(monitor.is_healthy().await);
+        assert_eq!(monitor.retry_count(), 0);
+    }
+}

src/hid/otg.rs

@@ -0,0 +1,848 @@
+//! OTG USB Gadget HID backend
+//!
+//! This backend uses Linux USB Gadget API to emulate USB HID devices.
+//! It creates and manages three HID devices:
+//! - hidg0: Keyboard (8-byte reports, with LED feedback)
+//! - hidg1: Relative Mouse (4-byte reports)
+//! - hidg2: Absolute Mouse (6-byte reports)
+//!
+//! Requirements:
+//! - USB OTG/Device controller (UDC)
+//! - ConfigFS with USB gadget support
+//! - Root privileges for gadget setup
+//!
+//! Error Recovery:
+//! This module implements automatic device reconnection based on PiKVM's approach.
+//! When ESHUTDOWN or EAGAIN errors occur (common during MSD operations), the device
+//! file handles are closed and reopened on the next operation.
+//! See: https://github.com/raspberrypi/linux/issues/4373
+
+use async_trait::async_trait;
+use parking_lot::Mutex;
+use std::fs::{self, File, OpenOptions};
+use std::io::{Read, Write};
+use std::os::unix::fs::OpenOptionsExt;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, AtomicU8, Ordering};
+use tracing::{debug, info, trace, warn};
+
+use super::backend::HidBackend;
+use super::keymap;
+use super::types::{KeyEventType, KeyboardEvent, KeyboardReport, MouseEvent, MouseEventType};
+use crate::error::{AppError, Result};
+use crate::otg::{HidDevicePaths, wait_for_hid_devices};
+
+/// Device type for ensure_device operations
+#[derive(Debug, Clone, Copy)]
+enum DeviceType {
+    Keyboard,
+    MouseRelative,
+    MouseAbsolute,
+}
+
+/// Keyboard LED state
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct LedState {
+    /// Num Lock LED
+    pub num_lock: bool,
+    /// Caps Lock LED
+    pub caps_lock: bool,
+    /// Scroll Lock LED
+    pub scroll_lock: bool,
+    /// Compose LED
+    pub compose: bool,
+    /// Kana LED
+    pub kana: bool,
+}
+
+impl LedState {
+    /// Create from raw byte
+    pub fn from_byte(b: u8) -> Self {
+        Self {
+            num_lock: b & 0x01 != 0,
+            caps_lock: b & 0x02 != 0,
+            scroll_lock: b & 0x04 != 0,
+            compose: b & 0x08 != 0,
+            kana: b & 0x10 != 0,
+        }
+    }
+
+    /// Convert to raw byte
+    pub fn to_byte(&self) -> u8 {
+        let mut b = 0u8;
+        if self.num_lock { b |= 0x01; }
+        if self.caps_lock { b |= 0x02; }
+        if self.scroll_lock { b |= 0x04; }
+        if self.compose { b |= 0x08; }
+        if self.kana { b |= 0x10; }
+        b
+    }
+}
+
+/// OTG HID backend with 3 devices
+///
+/// This backend opens HID device files created by OtgService.
+/// It does NOT manage the USB gadget itself - that's handled by OtgService.
+///
+/// ## Error Recovery
+///
+/// Based on PiKVM's implementation, this backend automatically handles:
+/// - EAGAIN (errno 11): Resource temporarily unavailable - just retry later, don't close device
+/// - ESHUTDOWN (errno 108): Transport endpoint shutdown - close and reopen device
+///
+/// When ESHUTDOWN occurs, the device file handle is closed and will be
+/// reopened on the next operation attempt.
+pub struct OtgBackend {
+    /// Keyboard device path (/dev/hidg0)
+    keyboard_path: PathBuf,
+    /// Relative mouse device path (/dev/hidg1)
+    mouse_rel_path: PathBuf,
+    /// Absolute mouse device path (/dev/hidg2)
+    mouse_abs_path: PathBuf,
+    /// Keyboard device file
+    keyboard_dev: Mutex<Option<File>>,
+    /// Relative mouse device file
+    mouse_rel_dev: Mutex<Option<File>>,
+    /// Absolute mouse device file
+    mouse_abs_dev: Mutex<Option<File>>,
+    /// Current keyboard state
+    keyboard_state: Mutex<KeyboardReport>,
+    /// Current mouse button state
+    mouse_buttons: AtomicU8,
+    /// Last known LED state (using parking_lot::RwLock for sync access)
+    led_state: parking_lot::RwLock<LedState>,
+    /// Screen resolution for absolute mouse (using parking_lot::RwLock for sync access)
+    screen_resolution: parking_lot::RwLock<Option<(u32, u32)>>,
+    /// UDC name for state checking (e.g., "fcc00000.usb")
+    udc_name: parking_lot::RwLock<Option<String>>,
+    /// Whether the device is currently online (UDC configured and devices accessible)
+    online: AtomicBool,
+    /// Last error log time for throttling (using parking_lot for sync)
+    last_error_log: parking_lot::Mutex<std::time::Instant>,
+    /// Error count since last successful operation (for log throttling)
+    error_count: AtomicU8,
+    /// Consecutive EAGAIN count (for offline threshold detection)
+    eagain_count: AtomicU8,
+}
+
+/// Threshold for consecutive EAGAIN errors before reporting offline
+const EAGAIN_OFFLINE_THRESHOLD: u8 = 3;
+
+impl OtgBackend {
+    /// Create OTG backend from device paths provided by OtgService
+    ///
+    /// This is the ONLY way to create an OtgBackend - it no longer manages
+    /// the USB gadget itself. The gadget must already be set up by OtgService.
+    pub fn from_handles(paths: HidDevicePaths) -> Result<Self> {
+        Ok(Self {
+            keyboard_path: paths.keyboard,
+            mouse_rel_path: paths.mouse_relative,
+            mouse_abs_path: paths.mouse_absolute,
+            keyboard_dev: Mutex::new(None),
+            mouse_rel_dev: Mutex::new(None),
+            mouse_abs_dev: Mutex::new(None),
+            keyboard_state: Mutex::new(KeyboardReport::default()),
+            mouse_buttons: AtomicU8::new(0),
+            led_state: parking_lot::RwLock::new(LedState::default()),
+            screen_resolution: parking_lot::RwLock::new(Some((1920, 1080))),
+            udc_name: parking_lot::RwLock::new(None),
+            online: AtomicBool::new(false),
+            last_error_log: parking_lot::Mutex::new(std::time::Instant::now()),
+            error_count: AtomicU8::new(0),
+            eagain_count: AtomicU8::new(0),
+        })
+    }
+
+    /// Log throttled error message (max once per second)
+    fn log_throttled_error(&self, msg: &str) {
+        let mut last_log = self.last_error_log.lock();
+        let now = std::time::Instant::now();
+        if now.duration_since(*last_log).as_secs() >= 1 {
+            let count = self.error_count.swap(0, Ordering::Relaxed);
+            if count > 1 {
+                warn!("{} (repeated {} times)", msg, count);
+            } else {
+                warn!("{}", msg);
+            }
+            *last_log = now;
+        } else {
+            self.error_count.fetch_add(1, Ordering::Relaxed);
+        }
+    }
+
+    /// Reset error count on successful operation
+    fn reset_error_count(&self) {
+        self.error_count.store(0, Ordering::Relaxed);
+        // Also reset EAGAIN count - successful operation means device is working
+        self.eagain_count.store(0, Ordering::Relaxed);
+    }
+
+    /// Set the UDC name for state checking
+    pub fn set_udc_name(&self, udc: &str) {
+        *self.udc_name.write() = Some(udc.to_string());
+    }
+
+    /// Check if the UDC is in "configured" state
+    ///
+    /// This is based on PiKVM's `__is_udc_configured()` method.
+    /// The UDC state file indicates whether the USB host has enumerated and configured the gadget.
+    pub fn is_udc_configured(&self) -> bool {
+        let udc_name = self.udc_name.read();
+        if let Some(ref udc) = *udc_name {
+            let state_path = format!("/sys/class/udc/{}/state", udc);
+            match fs::read_to_string(&state_path) {
+                Ok(content) => {
+                    let state = content.trim().to_lowercase();
+                    trace!("UDC {} state: {}", udc, state);
+                    state == "configured"
+                }
+                Err(e) => {
+                    debug!("Failed to read UDC state from {}: {}", state_path, e);
+                    // If we can't read the state, assume it might be configured
+                    // to avoid blocking operations unnecessarily
+                    true
+                }
+            }
+        } else {
+            // No UDC name set, try to auto-detect
+            if let Some(udc) = Self::find_udc() {
+                drop(udc_name);
+                *self.udc_name.write() = Some(udc.clone());
+                let state_path = format!("/sys/class/udc/{}/state", udc);
+                fs::read_to_string(&state_path)
+                    .map(|s| s.trim().to_lowercase() == "configured")
+                    .unwrap_or(true)
+            } else {
+                true
+            }
+        }
+    }
+
+    /// Find the first available UDC
+    fn find_udc() -> Option<String> {
+        let udc_path = PathBuf::from("/sys/class/udc");
+        if let Ok(entries) = fs::read_dir(&udc_path) {
+            for entry in entries.flatten() {
+                if let Some(name) = entry.file_name().to_str() {
+                    return Some(name.to_string());
+                }
+            }
+        }
+        None
+    }
+
+    /// Check if device is online
+    pub fn is_online(&self) -> bool {
+        self.online.load(Ordering::Relaxed)
+    }
+
+    /// Ensure a device is open and ready for I/O
+    ///
+    /// This method is based on PiKVM's `__ensure_device()` pattern:
+    /// 1. Check if device path exists, close handle if not
+    /// 2. If handle is None but path exists, reopen the device
+    /// 3. Return whether the device is ready for I/O
+    fn ensure_device(&self, device_type: DeviceType) -> Result<()> {
+        let (path, dev_mutex) = match device_type {
+            DeviceType::Keyboard => (&self.keyboard_path, &self.keyboard_dev),
+            DeviceType::MouseRelative => (&self.mouse_rel_path, &self.mouse_rel_dev),
+            DeviceType::MouseAbsolute => (&self.mouse_abs_path, &self.mouse_abs_dev),
+        };
+
+        // Check if device path exists
+        if !path.exists() {
+            // Close the device if open (device was removed)
+            let mut dev = dev_mutex.lock();
+            if dev.is_some() {
+                debug!("Device path {} no longer exists, closing handle", path.display());
+                *dev = None;
+            }
+            self.online.store(false, Ordering::Relaxed);
+            return Err(AppError::HidError {
+                backend: "otg".to_string(),
+                reason: format!("Device not found: {}", path.display()),
+                error_code: "enoent".to_string(),
+            });
+        }
+
+        // If device is not open, try to open it
+        let mut dev = dev_mutex.lock();
+        if dev.is_none() {
+            match Self::open_device(path) {
+                Ok(file) => {
+                    info!("Reopened HID device: {}", path.display());
+                    *dev = Some(file);
+                }
+                Err(e) => {
+                    warn!("Failed to reopen HID device {}: {}", path.display(), e);
+                    return Err(e);
+                }
+            }
+        }
+
+        self.online.store(true, Ordering::Relaxed);
+        Ok(())
+    }
+
+    /// Close a device (used when ESHUTDOWN is received)
+    #[allow(dead_code)]
+    fn close_device(&self, device_type: DeviceType) {
+        let dev_mutex = match device_type {
+            DeviceType::Keyboard => &self.keyboard_dev,
+            DeviceType::MouseRelative => &self.mouse_rel_dev,
+            DeviceType::MouseAbsolute => &self.mouse_abs_dev,
+        };
+
+        let mut dev = dev_mutex.lock();
+        if dev.is_some() {
+            debug!("Closing {:?} device handle for recovery", device_type);
+            *dev = None;
+        }
+    }
+
+    /// Close all device handles (for recovery)
+    #[allow(dead_code)]
+    fn close_all_devices(&self) {
+        self.close_device(DeviceType::Keyboard);
+        self.close_device(DeviceType::MouseRelative);
+        self.close_device(DeviceType::MouseAbsolute);
+        self.online.store(false, Ordering::Relaxed);
+    }
+
+    /// Open a HID device file with read/write access
+    fn open_device(path: &PathBuf) -> Result<File> {
+        OpenOptions::new()
+            .read(true)
+            .write(true)
+            .custom_flags(libc::O_NONBLOCK)
+            .open(path)
+            .map_err(|e| {
+                AppError::Internal(format!("Failed to open HID device {}: {}", path.display(), e))
+            })
+    }
+
+    /// Convert I/O error to HidError with appropriate error code
+    fn io_error_to_hid_error(e: std::io::Error, operation: &str) -> AppError {
+        let error_code = match e.raw_os_error() {
+            Some(32) => "epipe",       // EPIPE - broken pipe
+            Some(108) => "eshutdown",  // ESHUTDOWN - transport endpoint shutdown
+            Some(11) => "eagain",      // EAGAIN - resource temporarily unavailable
+            Some(6) => "enxio",        // ENXIO - no such device or address
+            Some(19) => "enodev",      // ENODEV - no such device
+            Some(5) => "eio",          // EIO - I/O error
+            Some(2) => "enoent",       // ENOENT - no such file or directory
+            _ => "io_error",
+        };
+
+        AppError::HidError {
+            backend: "otg".to_string(),
+            reason: format!("{}: {}", operation, e),
+            error_code: error_code.to_string(),
+        }
+    }
+
+    /// Check if all HID device files exist
+    pub fn check_devices_exist(&self) -> bool {
+        self.keyboard_path.exists()
+            && self.mouse_rel_path.exists()
+            && self.mouse_abs_path.exists()
+    }
+
+    /// Get list of missing device paths
+    pub fn get_missing_devices(&self) -> Vec<String> {
+        let mut missing = Vec::new();
+        if !self.keyboard_path.exists() {
+            missing.push(self.keyboard_path.display().to_string());
+        }
+        if !self.mouse_rel_path.exists() {
+            missing.push(self.mouse_rel_path.display().to_string());
+        }
+        if !self.mouse_abs_path.exists() {
+            missing.push(self.mouse_abs_path.display().to_string());
+        }
+        missing
+    }
+
+    /// Send keyboard report (8 bytes)
+    ///
+    /// This method ensures the device is open before writing, and handles
+    /// ESHUTDOWN errors by closing the device handle for later reconnection.
+    /// EAGAIN errors are treated as temporary - device stays open.
+    fn send_keyboard_report(&self, report: &KeyboardReport) -> Result<()> {
+        // Ensure device is ready
+        self.ensure_device(DeviceType::Keyboard)?;
+
+        let mut dev = self.keyboard_dev.lock();
+        if let Some(ref mut file) = *dev {
+            let data = report.to_bytes();
+            match file.write_all(&data) {
+                Ok(_) => {
+                    self.online.store(true, Ordering::Relaxed);
+                    self.reset_error_count();
+                    trace!("Sent keyboard report: {:02X?}", data);
+                    Ok(())
+                }
+                Err(e) => {
+                    let error_code = e.raw_os_error();
+
+                    match error_code {
+                        Some(108) => {
+                            // ESHUTDOWN - endpoint closed, need to reopen device
+                            self.online.store(false, Ordering::Relaxed);
+                            self.eagain_count.store(0, Ordering::Relaxed);
+                            debug!("Keyboard ESHUTDOWN, closing for recovery");
+                            *dev = None;
+                            Err(Self::io_error_to_hid_error(e, "Failed to write keyboard report"))
+                        }
+                        Some(11) => {
+                            // EAGAIN - temporary busy, track consecutive count
+                            self.log_throttled_error("HID keyboard busy (EAGAIN)");
+                            let count = self.eagain_count.fetch_add(1, Ordering::Relaxed) + 1;
+
+                            if count >= EAGAIN_OFFLINE_THRESHOLD {
+                                // Exceeded threshold, report as offline
+                                self.online.store(false, Ordering::Relaxed);
+                                Err(AppError::HidError {
+                                    backend: "otg".to_string(),
+                                    reason: format!("Device busy ({} consecutive EAGAIN)", count),
+                                    error_code: "eagain".to_string(),
+                                })
+                            } else {
+                                // Within threshold, return retry error (won't trigger offline event)
+                                Err(AppError::HidError {
+                                    backend: "otg".to_string(),
+                                    reason: "Device temporarily busy".to_string(),
+                                    error_code: "eagain_retry".to_string(),
+                                })
+                            }
+                        }
+                        _ => {
+                            self.online.store(false, Ordering::Relaxed);
+                            self.eagain_count.store(0, Ordering::Relaxed);
+                            warn!("Keyboard write error: {}", e);
+                            Err(Self::io_error_to_hid_error(e, "Failed to write keyboard report"))
+                        }
+                    }
+                }
+            }
+        } else {
+            Err(AppError::HidError {
+                backend: "otg".to_string(),
+                reason: "Keyboard device not opened".to_string(),
+                error_code: "not_opened".to_string(),
+            })
+        }
+    }
+
+    /// Send relative mouse report (4 bytes: buttons, dx, dy, wheel)
+    ///
+    /// This method ensures the device is open before writing, and handles
+    /// ESHUTDOWN errors by closing the device handle for later reconnection.
+    /// EAGAIN errors are treated as temporary - device stays open.
+    fn send_mouse_report_relative(&self, buttons: u8, dx: i8, dy: i8, wheel: i8) -> Result<()> {
+        // Ensure device is ready
+        self.ensure_device(DeviceType::MouseRelative)?;
+
+        let mut dev = self.mouse_rel_dev.lock();
+        if let Some(ref mut file) = *dev {
+            let data = [buttons, dx as u8, dy as u8, wheel as u8];
+            match file.write_all(&data) {
+                Ok(_) => {
+                    self.online.store(true, Ordering::Relaxed);
+                    self.reset_error_count();
+                    trace!("Sent relative mouse report: {:02X?}", data);
+                    Ok(())
+                }
+                Err(e) => {
+                    let error_code = e.raw_os_error();
+
+                    match error_code {
+                        Some(108) => {
+                            self.online.store(false, Ordering::Relaxed);
+                            self.eagain_count.store(0, Ordering::Relaxed);
+                            debug!("Relative mouse ESHUTDOWN, closing for recovery");
+                            *dev = None;
+                            Err(Self::io_error_to_hid_error(e, "Failed to write mouse report"))
+                        }
+                        Some(11) => {
+                            // EAGAIN - temporary busy, track consecutive count
+                            self.log_throttled_error("HID relative mouse busy (EAGAIN)");
+                            let count = self.eagain_count.fetch_add(1, Ordering::Relaxed) + 1;
+
+                            if count >= EAGAIN_OFFLINE_THRESHOLD {
+                                // Exceeded threshold, report as offline
+                                self.online.store(false, Ordering::Relaxed);
+                                Err(AppError::HidError {
+                                    backend: "otg".to_string(),
+                                    reason: format!("Device busy ({} consecutive EAGAIN)", count),
+                                    error_code: "eagain".to_string(),
+                                })
+                            } else {
+                                // Within threshold, return retry error (won't trigger offline event)
+                                Err(AppError::HidError {
+                                    backend: "otg".to_string(),
+                                    reason: "Device temporarily busy".to_string(),
+                                    error_code: "eagain_retry".to_string(),
+                                })
+                            }
+                        }
+                        _ => {
+                            self.online.store(false, Ordering::Relaxed);
+                            self.eagain_count.store(0, Ordering::Relaxed);
+                            warn!("Relative mouse write error: {}", e);
+                            Err(Self::io_error_to_hid_error(e, "Failed to write mouse report"))
+                        }
+                    }
+                }
+            }
+        } else {
+            Err(AppError::HidError {
+                backend: "otg".to_string(),
+                reason: "Relative mouse device not opened".to_string(),
+                error_code: "not_opened".to_string(),
+            })
+        }
+    }
+
+    /// Send absolute mouse report (6 bytes: buttons, x_lo, x_hi, y_lo, y_hi, wheel)
+    ///
+    /// This method ensures the device is open before writing, and handles
+    /// ESHUTDOWN errors by closing the device handle for later reconnection.
+    /// EAGAIN errors are treated as temporary - device stays open.
+    fn send_mouse_report_absolute(&self, buttons: u8, x: u16, y: u16, wheel: i8) -> Result<()> {
+        // Ensure device is ready
+        self.ensure_device(DeviceType::MouseAbsolute)?;
+
+        let mut dev = self.mouse_abs_dev.lock();
+        if let Some(ref mut file) = *dev {
+            let data = [
+                buttons,
+                (x & 0xFF) as u8,
+                (x >> 8) as u8,
+                (y & 0xFF) as u8,
+                (y >> 8) as u8,
+                wheel as u8,
+            ];
+            match file.write_all(&data) {
+                Ok(_) => {
+                    self.online.store(true, Ordering::Relaxed);
+                    self.reset_error_count();
+                    trace!("Sent absolute mouse report: {:02X?}", data);
+                    Ok(())
+                }
+                Err(e) => {
+                    let error_code = e.raw_os_error();
+
+                    match error_code {
+                        Some(108) => {
+                            self.online.store(false, Ordering::Relaxed);
+                            self.eagain_count.store(0, Ordering::Relaxed);
+                            debug!("Absolute mouse ESHUTDOWN, closing for recovery");
+                            *dev = None;
+                            Err(Self::io_error_to_hid_error(e, "Failed to write mouse report"))
+                        }
+                        Some(11) => {
+                            // EAGAIN - temporary busy, track consecutive count
+                            self.log_throttled_error("HID absolute mouse busy (EAGAIN)");
+                            let count = self.eagain_count.fetch_add(1, Ordering::Relaxed) + 1;
+
+                            if count >= EAGAIN_OFFLINE_THRESHOLD {
+                                // Exceeded threshold, report as offline
+                                self.online.store(false, Ordering::Relaxed);
+                                Err(AppError::HidError {
+                                    backend: "otg".to_string(),
+                                    reason: format!("Device busy ({} consecutive EAGAIN)", count),
+                                    error_code: "eagain".to_string(),
+                                })
+                            } else {
+                                // Within threshold, return retry error (won't trigger offline event)
+                                Err(AppError::HidError {
+                                    backend: "otg".to_string(),
+                                    reason: "Device temporarily busy".to_string(),
+                                    error_code: "eagain_retry".to_string(),
+                                })
+                            }
+                        }
+                        _ => {
+                            self.online.store(false, Ordering::Relaxed);
+                            self.eagain_count.store(0, Ordering::Relaxed);
+                            warn!("Absolute mouse write error: {}", e);
+                            Err(Self::io_error_to_hid_error(e, "Failed to write mouse report"))
+                        }
+                    }
+                }
+            }
+        } else {
+            Err(AppError::HidError {
+                backend: "otg".to_string(),
+                reason: "Absolute mouse device not opened".to_string(),
+                error_code: "not_opened".to_string(),
+            })
+        }
+    }
+
+    /// Read keyboard LED state (non-blocking)
+    pub fn read_led_state(&self) -> Result<Option<LedState>> {
+        let mut dev = self.keyboard_dev.lock();
+        if let Some(ref mut file) = *dev {
+            let mut buf = [0u8; 1];
+            match file.read(&mut buf) {
+                Ok(1) => {
+                    let state = LedState::from_byte(buf[0]);
+                    // Update LED state (using parking_lot RwLock)
+                    *self.led_state.write() = state;
+                    Ok(Some(state))
+                }
+                Ok(_) => Ok(None), // No data available
+                Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => Ok(None),
+                Err(e) => Err(AppError::Internal(format!("Failed to read LED state: {}", e))),
+            }
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Get last known LED state
+    pub fn led_state(&self) -> LedState {
+        *self.led_state.read()
+    }
+}
+
+#[async_trait]
+impl HidBackend for OtgBackend {
+    fn name(&self) -> &'static str {
+        "OTG USB Gadget"
+    }
+
+    async fn init(&self) -> Result<()> {
+        info!("Initializing OTG HID backend");
+
+        // Auto-detect UDC name for state checking
+        if let Some(udc) = Self::find_udc() {
+            info!("Auto-detected UDC: {}", udc);
+            self.set_udc_name(&udc);
+        }
+
+        // Wait for devices to appear (they should already exist from OtgService)
+        let device_paths = vec![
+            self.keyboard_path.clone(),
+            self.mouse_rel_path.clone(),
+            self.mouse_abs_path.clone(),
+        ];
+
+        if !wait_for_hid_devices(&device_paths, 2000).await {
+            return Err(AppError::Internal("HID devices did not appear".into()));
+        }
+
+        // Open keyboard device
+        if self.keyboard_path.exists() {
+            let file = Self::open_device(&self.keyboard_path)?;
+            *self.keyboard_dev.lock() = Some(file);
+            info!("Keyboard device opened: {}", self.keyboard_path.display());
+        } else {
+            warn!("Keyboard device not found: {}", self.keyboard_path.display());
+        }
+
+        // Open relative mouse device
+        if self.mouse_rel_path.exists() {
+            let file = Self::open_device(&self.mouse_rel_path)?;
+            *self.mouse_rel_dev.lock() = Some(file);
+            info!("Relative mouse device opened: {}", self.mouse_rel_path.display());
+        } else {
+            warn!("Relative mouse device not found: {}", self.mouse_rel_path.display());
+        }
+
+        // Open absolute mouse device
+        if self.mouse_abs_path.exists() {
+            let file = Self::open_device(&self.mouse_abs_path)?;
+            *self.mouse_abs_dev.lock() = Some(file);
+            info!("Absolute mouse device opened: {}", self.mouse_abs_path.display());
+        } else {
+            warn!("Absolute mouse device not found: {}", self.mouse_abs_path.display());
+        }
+
+        // Mark as online if all devices opened successfully
+        self.online.store(true, Ordering::Relaxed);
+
+        Ok(())
+    }
+
+    async fn send_keyboard(&self, event: KeyboardEvent) -> Result<()> {
+        // Convert JS keycode to USB HID if needed
+        let usb_key = keymap::js_to_usb(event.key).unwrap_or(event.key);
+
+        // Handle modifier keys separately
+        if keymap::is_modifier_key(usb_key) {
+            let mut state = self.keyboard_state.lock();
+
+            if let Some(bit) = keymap::modifier_bit(usb_key) {
+                match event.event_type {
+                    KeyEventType::Down => state.modifiers |= bit,
+                    KeyEventType::Up => state.modifiers &= !bit,
+                }
+            }
+
+            let report = state.clone();
+            drop(state);
+
+            self.send_keyboard_report(&report)?;
+        } else {
+            let mut state = self.keyboard_state.lock();
+
+            // Update modifiers from event
+            state.modifiers = event.modifiers.to_hid_byte();
+
+            match event.event_type {
+                KeyEventType::Down => {
+                    state.add_key(usb_key);
+                }
+                KeyEventType::Up => {
+                    state.remove_key(usb_key);
+                }
+            }
+
+            let report = state.clone();
+            drop(state);
+
+            self.send_keyboard_report(&report)?;
+        }
+
+        Ok(())
+    }
+
+    async fn send_mouse(&self, event: MouseEvent) -> Result<()> {
+        let buttons = self.mouse_buttons.load(Ordering::Relaxed);
+
+        match event.event_type {
+            MouseEventType::Move => {
+                // Relative movement - use hidg1
+                let dx = event.x.clamp(-127, 127) as i8;
+                let dy = event.y.clamp(-127, 127) as i8;
+                self.send_mouse_report_relative(buttons, dx, dy, 0)?;
+            }
+            MouseEventType::MoveAbs => {
+                // Absolute movement - use hidg2
+                // Frontend sends 0-32767 range directly (standard HID absolute mouse range)
+                let x = event.x.clamp(0, 32767) as u16;
+                let y = event.y.clamp(0, 32767) as u16;
+                self.send_mouse_report_absolute(buttons, x, y, 0)?;
+            }
+            MouseEventType::Down => {
+                if let Some(button) = event.button {
+                    let bit = button.to_hid_bit();
+                    let new_buttons = self.mouse_buttons.fetch_or(bit, Ordering::Relaxed) | bit;
+                    // Send on relative device for button clicks
+                    self.send_mouse_report_relative(new_buttons, 0, 0, 0)?;
+                }
+            }
+            MouseEventType::Up => {
+                if let Some(button) = event.button {
+                    let bit = button.to_hid_bit();
+                    let new_buttons = self.mouse_buttons.fetch_and(!bit, Ordering::Relaxed) & !bit;
+                    self.send_mouse_report_relative(new_buttons, 0, 0, 0)?;
+                }
+            }
+            MouseEventType::Scroll => {
+                self.send_mouse_report_relative(buttons, 0, 0, event.scroll)?;
+            }
+        }
+
+        Ok(())
+    }
+
+    async fn reset(&self) -> Result<()> {
+        // Reset keyboard
+        {
+            let mut state = self.keyboard_state.lock();
+            state.clear();
+            let report = state.clone();
+            drop(state);
+            self.send_keyboard_report(&report)?;
+        }
+
+        // Reset mouse
+        self.mouse_buttons.store(0, Ordering::Relaxed);
+        self.send_mouse_report_relative(0, 0, 0, 0)?;
+        self.send_mouse_report_absolute(0, 0, 0, 0)?;
+
+        info!("HID state reset");
+        Ok(())
+    }
+
+    async fn shutdown(&self) -> Result<()> {
+        // Reset before closing
+        self.reset().await?;
+
+        // Close devices
+        *self.keyboard_dev.lock() = None;
+        *self.mouse_rel_dev.lock() = None;
+        *self.mouse_abs_dev.lock() = None;
+
+        // Gadget cleanup is handled by OtgService, not here
+
+        info!("OTG backend shutdown");
+        Ok(())
+    }
+
+    fn supports_absolute_mouse(&self) -> bool {
+        self.mouse_abs_path.exists()
+    }
+
+    fn screen_resolution(&self) -> Option<(u32, u32)> {
+        *self.screen_resolution.read()
+    }
+
+    fn set_screen_resolution(&mut self, width: u32, height: u32) {
+        *self.screen_resolution.write() = Some((width, height));
+    }
+}
+
+/// Check if OTG HID gadget is available
+pub fn is_otg_available() -> bool {
+    // Check for existing HID devices (they should be created by OtgService)
+    let kb = PathBuf::from("/dev/hidg0");
+    let mouse_rel = PathBuf::from("/dev/hidg1");
+    let mouse_abs = PathBuf::from("/dev/hidg2");
+
+    kb.exists() && mouse_rel.exists() && mouse_abs.exists()
+}
+
+/// Implement Drop for OtgBackend to close device files
+impl Drop for OtgBackend {
+    fn drop(&mut self) {
+        // Close device files
+        // Note: Gadget cleanup is handled by OtgService, not here
+        *self.keyboard_dev.lock() = None;
+        *self.mouse_rel_dev.lock() = None;
+        *self.mouse_abs_dev.lock() = None;
+        debug!("OtgBackend dropped, device files closed");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_otg_availability_check() {
+        // This just tests the function runs without panicking
+        let _available = is_otg_available();
+    }
+
+    #[test]
+    fn test_led_state() {
+        let state = LedState::from_byte(0b00000011);
+        assert!(state.num_lock);
+        assert!(state.caps_lock);
+        assert!(!state.scroll_lock);
+
+        assert_eq!(state.to_byte(), 0b00000011);
+    }
+
+    #[test]
+    fn test_report_sizes() {
+        // Keyboard report is 8 bytes
+        let kb_report = KeyboardReport::default();
+        assert_eq!(kb_report.to_bytes().len(), 8);
+    }
+}

src/hid/types.rs

@@ -0,0 +1,382 @@
+//! HID event types for keyboard and mouse
+
+use serde::{Deserialize, Serialize};
+
+/// Keyboard event type
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum KeyEventType {
+    /// Key pressed down
+    Down,
+    /// Key released
+    Up,
+}
+
+/// Keyboard modifier flags
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+pub struct KeyboardModifiers {
+    /// Left Control
+    #[serde(default)]
+    pub left_ctrl: bool,
+    /// Left Shift
+    #[serde(default)]
+    pub left_shift: bool,
+    /// Left Alt
+    #[serde(default)]
+    pub left_alt: bool,
+    /// Left Meta (Windows/Super key)
+    #[serde(default)]
+    pub left_meta: bool,
+    /// Right Control
+    #[serde(default)]
+    pub right_ctrl: bool,
+    /// Right Shift
+    #[serde(default)]
+    pub right_shift: bool,
+    /// Right Alt (AltGr)
+    #[serde(default)]
+    pub right_alt: bool,
+    /// Right Meta
+    #[serde(default)]
+    pub right_meta: bool,
+}
+
+impl KeyboardModifiers {
+    /// Convert to USB HID modifier byte
+    pub fn to_hid_byte(&self) -> u8 {
+        let mut byte = 0u8;
+        if self.left_ctrl {
+            byte |= 0x01;
+        }
+        if self.left_shift {
+            byte |= 0x02;
+        }
+        if self.left_alt {
+            byte |= 0x04;
+        }
+        if self.left_meta {
+            byte |= 0x08;
+        }
+        if self.right_ctrl {
+            byte |= 0x10;
+        }
+        if self.right_shift {
+            byte |= 0x20;
+        }
+        if self.right_alt {
+            byte |= 0x40;
+        }
+        if self.right_meta {
+            byte |= 0x80;
+        }
+        byte
+    }
+
+    /// Create from USB HID modifier byte
+    pub fn from_hid_byte(byte: u8) -> Self {
+        Self {
+            left_ctrl: byte & 0x01 != 0,
+            left_shift: byte & 0x02 != 0,
+            left_alt: byte & 0x04 != 0,
+            left_meta: byte & 0x08 != 0,
+            right_ctrl: byte & 0x10 != 0,
+            right_shift: byte & 0x20 != 0,
+            right_alt: byte & 0x40 != 0,
+            right_meta: byte & 0x80 != 0,
+        }
+    }
+
+    /// Check if any modifier is active
+    pub fn any(&self) -> bool {
+        self.left_ctrl
+            || self.left_shift
+            || self.left_alt
+            || self.left_meta
+            || self.right_ctrl
+            || self.right_shift
+            || self.right_alt
+            || self.right_meta
+    }
+}
+
+/// Keyboard event
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct KeyboardEvent {
+    /// Event type (down/up)
+    #[serde(rename = "type")]
+    pub event_type: KeyEventType,
+    /// Key code (USB HID usage code or JavaScript key code)
+    pub key: u8,
+    /// Modifier keys state
+    #[serde(default)]
+    pub modifiers: KeyboardModifiers,
+}
+
+impl KeyboardEvent {
+    /// Create a key down event
+    pub fn key_down(key: u8, modifiers: KeyboardModifiers) -> Self {
+        Self {
+            event_type: KeyEventType::Down,
+            key,
+            modifiers,
+        }
+    }
+
+    /// Create a key up event
+    pub fn key_up(key: u8, modifiers: KeyboardModifiers) -> Self {
+        Self {
+            event_type: KeyEventType::Up,
+            key,
+            modifiers,
+        }
+    }
+}
+
+/// Mouse button
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum MouseButton {
+    Left,
+    Right,
+    Middle,
+    Back,
+    Forward,
+}
+
+impl MouseButton {
+    /// Convert to USB HID button bit
+    pub fn to_hid_bit(&self) -> u8 {
+        match self {
+            MouseButton::Left => 0x01,
+            MouseButton::Right => 0x02,
+            MouseButton::Middle => 0x04,
+            MouseButton::Back => 0x08,
+            MouseButton::Forward => 0x10,
+        }
+    }
+}
+
+/// Mouse event type
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum MouseEventType {
+    /// Mouse moved (relative movement)
+    Move,
+    /// Mouse moved (absolute position)
+    MoveAbs,
+    /// Button pressed
+    Down,
+    /// Button released
+    Up,
+    /// Mouse wheel scroll
+    Scroll,
+}
+
+/// Mouse event
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct MouseEvent {
+    /// Event type
+    #[serde(rename = "type")]
+    pub event_type: MouseEventType,
+    /// X coordinate or delta
+    #[serde(default)]
+    pub x: i32,
+    /// Y coordinate or delta
+    #[serde(default)]
+    pub y: i32,
+    /// Button (for down/up events)
+    #[serde(default)]
+    pub button: Option<MouseButton>,
+    /// Scroll delta (for scroll events)
+    #[serde(default)]
+    pub scroll: i8,
+}
+
+impl MouseEvent {
+    /// Create a relative move event
+    pub fn move_rel(dx: i32, dy: i32) -> Self {
+        Self {
+            event_type: MouseEventType::Move,
+            x: dx,
+            y: dy,
+            button: None,
+            scroll: 0,
+        }
+    }
+
+    /// Create an absolute move event
+    pub fn move_abs(x: i32, y: i32) -> Self {
+        Self {
+            event_type: MouseEventType::MoveAbs,
+            x,
+            y,
+            button: None,
+            scroll: 0,
+        }
+    }
+
+    /// Create a button down event
+    pub fn button_down(button: MouseButton) -> Self {
+        Self {
+            event_type: MouseEventType::Down,
+            x: 0,
+            y: 0,
+            button: Some(button),
+            scroll: 0,
+        }
+    }
+
+    /// Create a button up event
+    pub fn button_up(button: MouseButton) -> Self {
+        Self {
+            event_type: MouseEventType::Up,
+            x: 0,
+            y: 0,
+            button: Some(button),
+            scroll: 0,
+        }
+    }
+
+    /// Create a scroll event
+    pub fn scroll(delta: i8) -> Self {
+        Self {
+            event_type: MouseEventType::Scroll,
+            x: 0,
+            y: 0,
+            button: None,
+            scroll: delta,
+        }
+    }
+}
+
+/// Combined HID event (keyboard or mouse)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "device", rename_all = "lowercase")]
+pub enum HidEvent {
+    Keyboard(KeyboardEvent),
+    Mouse(MouseEvent),
+}
+
+/// USB HID keyboard report (8 bytes)
+#[derive(Debug, Clone, Default)]
+pub struct KeyboardReport {
+    /// Modifier byte
+    pub modifiers: u8,
+    /// Reserved byte
+    pub reserved: u8,
+    /// Key codes (up to 6 simultaneous keys)
+    pub keys: [u8; 6],
+}
+
+impl KeyboardReport {
+    /// Convert to bytes for USB HID
+    pub fn to_bytes(&self) -> [u8; 8] {
+        [
+            self.modifiers,
+            self.reserved,
+            self.keys[0],
+            self.keys[1],
+            self.keys[2],
+            self.keys[3],
+            self.keys[4],
+            self.keys[5],
+        ]
+    }
+
+    /// Add a key to the report
+    pub fn add_key(&mut self, key: u8) -> bool {
+        for slot in &mut self.keys {
+            if *slot == 0 {
+                *slot = key;
+                return true;
+            }
+        }
+        false // All slots full
+    }
+
+    /// Remove a key from the report
+    pub fn remove_key(&mut self, key: u8) {
+        for slot in &mut self.keys {
+            if *slot == key {
+                *slot = 0;
+            }
+        }
+        // Compact the array
+        self.keys.sort_by(|a, b| b.cmp(a));
+    }
+
+    /// Clear all keys
+    pub fn clear(&mut self) {
+        self.modifiers = 0;
+        self.keys = [0; 6];
+    }
+}
+
+/// USB HID mouse report
+#[derive(Debug, Clone, Default)]
+pub struct MouseReport {
+    /// Button state
+    pub buttons: u8,
+    /// X movement (-127 to 127)
+    pub x: i8,
+    /// Y movement (-127 to 127)
+    pub y: i8,
+    /// Wheel movement (-127 to 127)
+    pub wheel: i8,
+}
+
+impl MouseReport {
+    /// Convert to bytes for USB HID (relative mouse)
+    pub fn to_bytes_relative(&self) -> [u8; 4] {
+        [
+            self.buttons,
+            self.x as u8,
+            self.y as u8,
+            self.wheel as u8,
+        ]
+    }
+
+    /// Convert to bytes for USB HID (absolute mouse)
+    pub fn to_bytes_absolute(&self, x: u16, y: u16) -> [u8; 6] {
+        [
+            self.buttons,
+            (x & 0xFF) as u8,
+            (x >> 8) as u8,
+            (y & 0xFF) as u8,
+            (y >> 8) as u8,
+            self.wheel as u8,
+        ]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_modifier_conversion() {
+        let mods = KeyboardModifiers {
+            left_ctrl: true,
+            left_shift: true,
+            ..Default::default()
+        };
+        assert_eq!(mods.to_hid_byte(), 0x03);
+
+        let mods2 = KeyboardModifiers::from_hid_byte(0x03);
+        assert!(mods2.left_ctrl);
+        assert!(mods2.left_shift);
+        assert!(!mods2.left_alt);
+    }
+
+    #[test]
+    fn test_keyboard_report() {
+        let mut report = KeyboardReport::default();
+        assert!(report.add_key(0x04)); // 'A'
+        assert!(report.add_key(0x05)); // 'B'
+        assert_eq!(report.keys[0], 0x04);
+        assert_eq!(report.keys[1], 0x05);
+
+        report.remove_key(0x04);
+        assert_eq!(report.keys[0], 0x05);
+    }
+}

src/hid/websocket.rs

@@ -0,0 +1,160 @@
+//! WebSocket HID channel for HTTP/MJPEG mode
+//!
+//! This provides an alternative to WebRTC DataChannel for HID input
+//! when using MJPEG streaming mode.
+//!
+//! Uses binary protocol only (same format as DataChannel):
+//! - Keyboard: [0x01, event_type, key, modifiers] (4 bytes)
+//! - Mouse: [0x02, event_type, x_lo, x_hi, y_lo, y_hi, button/scroll] (7 bytes)
+//!
+//! See datachannel.rs for detailed protocol specification.
+
+use axum::{
+    extract::{
+        ws::{Message, WebSocket, WebSocketUpgrade},
+        State,
+    },
+    response::Response,
+};
+use futures::{SinkExt, StreamExt};
+use std::sync::Arc;
+use tracing::{debug, error, info, warn};
+
+use super::datachannel::{parse_hid_message, HidChannelEvent};
+use crate::state::AppState;
+use crate::utils::LogThrottler;
+
+/// Binary response codes
+const RESP_OK: u8 = 0x00;
+const RESP_ERR_HID_UNAVAILABLE: u8 = 0x01;
+const RESP_ERR_INVALID_MESSAGE: u8 = 0x02;
+#[allow(dead_code)]
+const RESP_ERR_SEND_FAILED: u8 = 0x03;
+
+/// WebSocket HID upgrade handler
+pub async fn ws_hid_handler(ws: WebSocketUpgrade, State(state): State<Arc<AppState>>) -> Response {
+    ws.on_upgrade(move |socket| handle_hid_socket(socket, state))
+}
+
+/// Handle HID WebSocket connection
+async fn handle_hid_socket(socket: WebSocket, state: Arc<AppState>) {
+    let (mut sender, mut receiver) = socket.split();
+    // Log throttler for error messages (5 second interval)
+    let log_throttler = LogThrottler::with_secs(5);
+
+    info!("WebSocket HID connection established (binary protocol)");
+
+    // Check if HID controller is available and send initial status
+    let hid_available = state.hid.is_available().await;
+    let initial_response = if hid_available {
+        vec![RESP_OK]
+    } else {
+        vec![RESP_ERR_HID_UNAVAILABLE]
+    };
+
+    if sender.send(Message::Binary(initial_response)).await.is_err() {
+        error!("Failed to send initial HID status");
+        return;
+    }
+
+    // Process incoming messages (binary only)
+    while let Some(msg) = receiver.next().await {
+        match msg {
+            Ok(Message::Binary(data)) => {
+                // Check HID availability before processing each message
+                let hid_available = state.hid.is_available().await;
+                if !hid_available {
+                    if log_throttler.should_log("hid_unavailable") {
+                        warn!("HID controller not available, ignoring message");
+                    }
+                    // Send error response (optional, for client awareness)
+                    let _ = sender.send(Message::Binary(vec![RESP_ERR_HID_UNAVAILABLE])).await;
+                    continue;
+                }
+
+                if let Err(e) = handle_binary_message(&data, &state).await {
+                    // Log with throttling to avoid spam
+                    if log_throttler.should_log("binary_hid_error") {
+                        warn!("Binary HID message error: {}", e);
+                    }
+                    // Don't send error response for every failed message to reduce overhead
+                }
+            }
+            Ok(Message::Text(text)) => {
+                // Text messages are no longer supported
+                if log_throttler.should_log("text_message_rejected") {
+                    debug!("Received text message (not supported): {} bytes", text.len());
+                }
+                let _ = sender.send(Message::Binary(vec![RESP_ERR_INVALID_MESSAGE])).await;
+            }
+            Ok(Message::Ping(data)) => {
+                let _ = sender.send(Message::Pong(data)).await;
+            }
+            Ok(Message::Close(_)) => {
+                info!("WebSocket HID connection closed by client");
+                break;
+            }
+            Err(e) => {
+                error!("WebSocket error: {}", e);
+                break;
+            }
+            _ => {}
+        }
+    }
+
+    info!("WebSocket HID connection ended");
+}
+
+/// Handle binary HID message (same format as DataChannel)
+async fn handle_binary_message(data: &[u8], state: &AppState) -> Result<(), String> {
+    let event = parse_hid_message(data).ok_or("Invalid binary HID message")?;
+
+    match event {
+        HidChannelEvent::Keyboard(kb_event) => {
+            state
+                .hid
+                .send_keyboard(kb_event)
+                .await
+                .map_err(|e| e.to_string())?;
+        }
+        HidChannelEvent::Mouse(ms_event) => {
+            state
+                .hid
+                .send_mouse(ms_event)
+                .await
+                .map_err(|e| e.to_string())?;
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::hid::datachannel::{MSG_KEYBOARD, MSG_MOUSE, KB_EVENT_DOWN, MS_EVENT_MOVE};
+
+    #[test]
+    fn test_response_codes() {
+        assert_eq!(RESP_OK, 0x00);
+        assert_eq!(RESP_ERR_HID_UNAVAILABLE, 0x01);
+        assert_eq!(RESP_ERR_INVALID_MESSAGE, 0x02);
+        assert_eq!(RESP_ERR_SEND_FAILED, 0x03);
+    }
+
+    #[test]
+    fn test_keyboard_message_format() {
+        // Keyboard message: [0x01, event_type, key, modifiers]
+        let data = [MSG_KEYBOARD, KB_EVENT_DOWN, 0x04, 0x01]; // 'A' key with left ctrl
+        let event = parse_hid_message(&data);
+        assert!(event.is_some());
+    }
+
+    #[test]
+    fn test_mouse_message_format() {
+        // Mouse message: [0x02, event_type, x_lo, x_hi, y_lo, y_hi, extra]
+        let data = [MSG_MOUSE, MS_EVENT_MOVE, 0x0A, 0x00, 0xF6, 0xFF, 0x00]; // x=10, y=-10
+        let event = parse_hid_message(&data);
+        assert!(event.is_some());
+    }
+}