### ESP32 USB Host Keyboard Example

Source: https://github.com/tanakamasayuki/espusbhost/blob/master/README.md

Demonstrates how to use the EspUsbHost library to detect keyboard input. Requires initializing the serial monitor and the USB host. The HID local setting can be configured.

```c++
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    if (' ' <= ascii && ascii <= '~') {
      Serial.printf("%c", ascii);
    } else if (ascii == '\r') {
      Serial.println();
    }
  };
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  delay(500);

  usbHost.begin();
  usbHost.setHIDLocal(HID_LOCAL_Japan_Katakana);
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### EspUsbHost Library Usage

Source: https://github.com/tanakamasayuki/espusbhost/blob/master/README.md

Example C++ code demonstrating how to initialize and use the EspUsbHost library to handle keyboard input.

```APIDOC
## EspUsbHost Library Usage Example

### Description
This example shows how to include the EspUsbHost library, create a custom class inheriting from `EspUsbHost`, and implement the `onKeyboardKey` callback to process keyboard input.

### Method
C++

### Endpoint
N/A

### Parameters
N/A

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    if (' ' <= ascii && ascii <= '~') {
      Serial.printf("%c", ascii);
    } else if (ascii == '\r') {
      Serial.println();
    }
  };
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  delay(500);

  usbHost.begin();
  usbHost.setHIDLocal(HID_LOCAL_Japan_Katakana);
}

void loop() {
  usbHost.task();
}
```

### Response
N/A
```

--------------------------------

### Initialize USB Host

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Initializes the USB host controller and registers the client event handler. Must be called once during setup before calling task().

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  // Override virtual functions here
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  delay(500);

  // Initialize USB host - must be called before task()
  usbHost.begin();
}
```

--------------------------------

### Complete Mouse Input Handler

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Tracks mouse cursor position and button states, including click detection and scrolling. Requires the EspUsbHost library. Call `mouse.begin()` in setup and `mouse.task()` in loop.

```cpp
#include "EspUsbHost.h"

class MouseHandler : public EspUsbHost {
private:
  int cursorX = 160;  // Start at center of 320px display
  int cursorY = 120;  // Start at center of 240px display
  int scrollPosition = 0;

public:
  void onMouseButtons(hid_mouse_report_t report, uint8_t last_buttons) {
    // Left click detection
    if (!(last_buttons & MOUSE_BUTTON_LEFT) && (report.buttons & MOUSE_BUTTON_LEFT)) {
      Serial.printf("LEFT CLICK at (%d, %d)\n", cursorX, cursorY);
      handleClick(cursorX, cursorY);
    }

    // Right click detection
    if (!(last_buttons & MOUSE_BUTTON_RIGHT) && (report.buttons & MOUSE_BUTTON_RIGHT)) {
      Serial.printf("RIGHT CLICK at (%d, %d)\n", cursorX, cursorY);
      handleRightClick(cursorX, cursorY);
    }

    // Middle click detection
    if (!(last_buttons & MOUSE_BUTTON_MIDDLE) && (report.buttons & MOUSE_BUTTON_MIDDLE)) {
      Serial.printf("MIDDLE CLICK at (%d, %d)\n", cursorX, cursorY);
    }
  }

  void onMouseMove(hid_mouse_report_t report) {
    // Update cursor position
    cursorX += (int8_t)report.x;
    cursorY += (int8_t)report.y;

    // Constrain to screen bounds
    cursorX = constrain(cursorX, 0, 319);
    cursorY = constrain(cursorY, 0, 239);

    // Handle scroll wheel
    if (report.wheel != 0) {
      scrollPosition += (int8_t)report.wheel;
      Serial.printf("Scroll position: %d\n", scrollPosition);
    }

    // Update display cursor (implement your display logic here)
    updateCursor(cursorX, cursorY);
  }

  void onGone(const usb_host_client_event_msg_t *eventMsg) {
    Serial.println("Mouse disconnected!");
  }

  void handleClick(int x, int y) {
    // Implement click handling for your application
    Serial.printf("Processing click at %d,%d\n", x, y);
  }

  void handleRightClick(int x, int y) {
    // Implement right-click context menu
    Serial.printf("Context menu at %d,%d\n", x, y);
  }

  void updateCursor(int x, int y) {
    // Update cursor position on display
    // Example: draw cursor sprite at x,y
  }

  int getCursorX() { return cursorX; }
  int getCursorY() { return cursorY; }
};

MouseHandler mouse;

void setup() {
  Serial.begin(115200);
  delay(500);

  mouse.begin();

  Serial.println("USB Mouse Ready");
  Serial.printf("Initial cursor position: (%d, %d)\n",
                mouse.getCursorX(), mouse.getCursorY());
}

void loop() {
  mouse.task();
}
```

--------------------------------

### Complete Keyboard Input Handler

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Handles keyboard input with text buffering and special key support (Enter, Backspace, Escape). Requires the EspUsbHost library. Call `keyboard.begin()` in setup and `keyboard.task()` in loop.

```cpp
#include "EspUsbHost.h"

class KeyboardHandler : public EspUsbHost {
private:
  char inputBuffer[256];
  int bufferPos = 0;

public:
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    // Handle printable characters
    if (' ' <= ascii && ascii <= '~') {
      if (bufferPos < sizeof(inputBuffer) - 1) {
        inputBuffer[bufferPos++] = ascii;
        inputBuffer[bufferPos] = '\0';
        Serial.printf("%c", ascii);
      }
    }
    // Handle Enter - process the input
    else if (ascii == '\r') {
      Serial.println();
      Serial.printf("Input received: %s\n", inputBuffer);
      processInput(inputBuffer);
      clearBuffer();
    }
    // Handle Backspace
    else if (ascii == '\b') {
      if (bufferPos > 0) {
        bufferPos--;
        inputBuffer[bufferPos] = '\0';
        Serial.print("\b \b");  // Erase character on terminal
      }
    }
    // Handle Escape - clear input
    else if (ascii == '\x1b') {
      clearBuffer();
      Serial.println("\n[Input cleared]");
    }
  }

  void clearBuffer() {
    bufferPos = 0;
    inputBuffer[0] = '\0';
  }

  void processInput(const char* input) {
    // Process the completed input line
    if (strcmp(input, "help") == 0) {
      Serial.println("Available commands: help, status, reset");
    } else if (strcmp(input, "status") == 0) {
      Serial.println("System running normally");
    } else if (strcmp(input, "reset") == 0) {
      Serial.println("Resetting...");
      ESP.restart();
    } else {
      Serial.printf("Unknown command: %s\n", input);
    }
  }

  void onGone(const usb_host_client_event_msg_t *eventMsg) {
    Serial.println("\nKeyboard disconnected!");
    clearBuffer();
  }
};

KeyboardHandler keyboard;

void setup() {
  Serial.begin(115200);
  delay(500);

  keyboard.begin();
  keyboard.setHIDLocal(HID_LOCAL_Japan_Katakana);

  Serial.println("USB Keyboard Ready");
  Serial.println("Type 'help' for available commands");
  Serial.print("> ");
}

void loop() {
  keyboard.task();
}
```

--------------------------------

### Core API - Initialization and Task Processing

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

This section covers the essential `begin()` and `task()` methods for initializing the USB host and processing events.

```APIDOC
## Core API - Initialization and Task Processing

### begin()

Initializes the USB host controller and registers the client event handler. This method must be called once during setup to configure the ESP32's USB host hardware and prepare for device connections.

### Method

`begin()`

### Endpoint

N/A (Library function)

### Parameters

None

### Request Example

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  // Override virtual functions here
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  delay(500);

  // Initialize USB host - must be called before task()
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

### Response

None (Initializes hardware)

### task()

Processes USB host events and triggers data transfers. This method must be called repeatedly in your main loop to handle USB device communication, process incoming data, and invoke the appropriate callback functions.

### Method

`task()`

### Endpoint

N/A (Library function)

### Parameters

None

### Request Example

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    Serial.printf("Key pressed: %c (code: 0x%02x)\n", ascii, keycode);
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  // Must be called continuously to process USB events
  usbHost.task();

  // Your other code here
  delay(1);
}
```

### Response

None (Processes events internally)
```

--------------------------------

### Set HID Keyboard Locale

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Sets the HID keyboard locale for proper keycode-to-ASCII conversion. Use HID_LOCAL_Japan_Katakana for Japanese layout; US layout is the default.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    if (' ' <= ascii && ascii <= '~') {
      Serial.printf("%c", ascii);
    } else if (ascii == '\r') {
      Serial.println();
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  delay(500);

  usbHost.begin();

  // Set Japanese keyboard layout for proper character mapping
  usbHost.setHIDLocal(HID_LOCAL_Japan_Katakana);

  // For US layout, use default (no call needed) or:
  // usbHost.setHIDLocal(HID_LOCAL_US);
}
```

--------------------------------

### Handle Keyboard Events with EspUsbHost

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Implement the onKeyboard callback to process keyboard state changes, including modifier and key press events. This is useful for advanced keyboard handling.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboard(hid_keyboard_report_t report, hid_keyboard_report_t last_report) {
    // Log modifier changes
    if (report.modifier != last_report.modifier) {
      Serial.printf("Modifier changed: 0x%02x -> 0x%02x\n",
                    last_report.modifier, report.modifier);
    }

    // Log all currently pressed keys (up to 6 simultaneous)
    Serial.print("Keys pressed: ");
    for (int i = 0; i < 6; i++) {
      if (report.keycode[i] != 0) {
        Serial.printf("0x%02x ", report.keycode[i]);
      }
    }
    Serial.println();
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### Handle Mouse Button Events with EspUsbHost

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Implement the onMouseButtons callback to detect clicks and releases for various mouse buttons, including left, right, middle, backward, and forward. This allows for custom interaction logic based on mouse input.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onMouseButtons(hid_mouse_report_t report, uint8_t last_buttons) {
    // Detect LEFT button click
    if (!(last_buttons & MOUSE_BUTTON_LEFT) && (report.buttons & MOUSE_BUTTON_LEFT)) {
      Serial.println("LEFT Click");
    }
    if ((last_buttons & MOUSE_BUTTON_LEFT) && !(report.buttons & MOUSE_BUTTON_LEFT)) {
      Serial.println("LEFT Release");
    }

    // Detect RIGHT button click
    if (!(last_buttons & MOUSE_BUTTON_RIGHT) && (report.buttons & MOUSE_BUTTON_RIGHT)) {
      Serial.println("RIGHT Click");
    }
    if ((last_buttons & MOUSE_BUTTON_RIGHT) && !(report.buttons & MOUSE_BUTTON_RIGHT)) {
      Serial.println("RIGHT Release");
    }

    // Detect MIDDLE button click
    if (!(last_buttons & MOUSE_BUTTON_MIDDLE) && (report.buttons & MOUSE_BUTTON_MIDDLE)) {
      Serial.println("MIDDLE Click");
    }
    if ((last_buttons & MOUSE_BUTTON_MIDDLE) && !(report.buttons & MOUSE_BUTTON_MIDDLE)) {
      Serial.println("MIDDLE Release");
    }

    // Detect BACKWARD button (side button)
    if (!(last_buttons & MOUSE_BUTTON_BACKWARD) && (report.buttons & MOUSE_BUTTON_BACKWARD)) {
      Serial.println("BACKWARD Click");
    }

    // Detect FORWARD button (side button)
    if (!(last_buttons & MOUSE_BUTTON_FORWARD) && (report.buttons & MOUSE_BUTTON_FORWARD)) {
      Serial.println("FORWARD Click");
    }

    // Show current button state
    Serial.printf("Buttons: %c%c%c%c%c\n",
                  (report.buttons & MOUSE_BUTTON_LEFT) ? 'L' : '-',
                  (report.buttons & MOUSE_BUTTON_RIGHT) ? 'R' : '-',
                  (report.buttons & MOUSE_BUTTON_MIDDLE) ? 'M' : '-',
                  (report.buttons & MOUSE_BUTTON_BACKWARD) ? 'B' : '-',
                  (report.buttons & MOUSE_BUTTON_FORWARD) ? 'F' : '-');
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### Core API - HID Locale Setting

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Configure the HID keyboard locale for accurate character mapping.

```APIDOC
## Core API - HID Locale Setting

### setHIDLocal(hid_local_enum_t code)

Sets the HID keyboard locale for proper keycode-to-ASCII conversion. Supports different keyboard layouts including US (default) and Japanese Katakana layouts.

### Method

`setHIDLocal(hid_local_enum_t code)`

### Endpoint

N/A (Library function)

### Parameters

- **code** (hid_local_enum_t) - Required - The locale to set. Use `HID_LOCAL_US` for US layout or `HID_LOCAL_Japan_Katakana` for Japanese Katakana.

### Request Example

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    if (' ' <= ascii && ascii <= '~') {
      Serial.printf("%c", ascii);
    } else if (ascii == '\r') {
      Serial.println();
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  delay(500);

  usbHost.begin();

  // Set Japanese keyboard layout for proper character mapping
  usbHost.setHIDLocal(HID_LOCAL_Japan_Katakana);

  // For US layout, use default (no call needed) or:
  // usbHost.setHIDLocal(HID_LOCAL_US);
}

void loop() {
  usbHost.task();
}
```

### Response

None (Configures internal settings)
```

--------------------------------

### Handle Mouse Movement and Scroll Events

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Implement this callback to process relative mouse movement deltas and scroll wheel activity. Ensure cursor coordinates are clamped to display boundaries if necessary.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  int cursorX = 0;
  int cursorY = 0;

  void onMouseMove(hid_mouse_report_t report) {
    // Update cursor position with movement deltas
    cursorX += (int8_t)report.x;
    cursorY += (int8_t)report.y;

    // Clamp cursor to screen bounds (example: 320x240 display)
    cursorX = constrain(cursorX, 0, 319);
    cursorY = constrain(cursorY, 0, 239);

    Serial.printf("Mouse: X=%d, Y=%d (cursor: %d,%d)\n",
                  (int8_t)report.x, (int8_t)report.y, cursorX, cursorY);

    // Handle scroll wheel
    if (report.wheel != 0) {
      Serial.printf("Scroll: %d\n", (int8_t)report.wheel);
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### Handle Raw USB Data Reception

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Implement this callback to receive and process raw USB transfer data. It provides access to endpoint information and the data buffer for custom protocol analysis or debugging.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onReceive(const usb_transfer_t *transfer) {
    // Log raw USB transfer data
    Serial.printf("USB Transfer - Endpoint: 0x%02x, Bytes: %d\n",
                  transfer->bEndpointAddress,
                  transfer->actual_num_bytes);

    // Print raw data bytes
    Serial.print("Data: ");
    for (int i = 0; i < transfer->actual_num_bytes; i++) {
      Serial.printf("%02x ", transfer->data_buffer[i]);
    }
    Serial.println();
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### Keyboard Event Handling

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

The onKeyboard callback is invoked on every keyboard state change, providing the full HID keyboard report. This allows for advanced handling of simultaneous key presses and modifier states.

```APIDOC
## onKeyboard

### Description
Called on every keyboard state change with the full HID keyboard report. Provides access to all 6 simultaneous keypresses and modifier state for advanced keyboard handling.

### Method
`void onKeyboard(hid_keyboard_report_t report, hid_keyboard_report_t last_report)`

### Parameters
- **report** (hid_keyboard_report_t) - The current HID keyboard report.
- **last_report** (hid_keyboard_report_t) - The previous HID keyboard report.

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboard(hid_keyboard_report_t report, hid_keyboard_report_t last_report) {
    // Log modifier changes
    if (report.modifier != last_report.modifier) {
      Serial.printf("Modifier changed: 0x%02x -> 0x%02x\n",
                    last_report.modifier, report.modifier);
    }

    // Log all currently pressed keys (up to 6 simultaneous)
    Serial.print("Keys pressed: ");
    for (int i = 0; i < 6; i++) {
      if (report.keycode[i] != 0) {
        Serial.printf("0x%02x ", report.keycode[i]);
      }
    }
    Serial.println();
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```
```

--------------------------------

### onReceive Callback

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

This callback is invoked for every USB data transfer received. It provides raw access to the USB transfer data, which is useful for custom protocol handling or detailed debugging.

```APIDOC
## onReceive(const usb_transfer_t *transfer)

### Description
Called for every USB data transfer received. Provides raw access to USB transfer data for custom protocol handling or debugging.

### Method
Callback function within the EspUsbHost class.

### Parameters
#### Request Body
- **transfer** (const usb_transfer_t *) - A pointer to the usb_transfer_t structure containing received data.
  - **transfer.bEndpointAddress** (uint8_t) - The endpoint address of the transfer.
  - **transfer.actual_num_bytes** (int) - The number of bytes actually received in the transfer.
  - **transfer.data_buffer** (uint8_t *) - A pointer to the buffer containing the received data.

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onReceive(const usb_transfer_t *transfer) {
    // Log raw USB transfer data
    Serial.printf("USB Transfer - Endpoint: 0x%02x, Bytes: %d\n",
                  transfer->bEndpointAddress,
                  transfer->actual_num_bytes);

    // Print raw data bytes
    Serial.print("Data: ");
    for (int i = 0; i < transfer->actual_num_bytes; i++) {
      Serial.printf("%02x ", transfer->data_buffer[i]);
    }
    Serial.println();
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

### Response
This is a callback function and does not return a value. It processes incoming USB data transfers.
```

--------------------------------

### EspUsbHost Virtual Functions

Source: https://github.com/tanakamasayuki/espusbhost/blob/master/README.md

Overview of the virtual functions available in the EspUsbHost class for handling common, keyboard, and mouse events.

```APIDOC
## EspUsbHost Virtual Functions

### Description
These virtual functions can be overridden in a derived class to handle specific USB host events and data.

### Method
C++ Virtual Functions

### Endpoint
N/A

### Parameters
N/A

### Common Events

#### `onData`
- `virtual void onData(const usb_transfer_t *transfer)`: Called when data is transferred over USB.

#### `onGone`
- `virtual void onGone(const usb_host_client_event_msg_t *eventMsg)`: Called when a USB device is disconnected or an event occurs.

### Keyboard Events

#### `getKeycodeToAscii`
- `virtual uint8_t getKeycodeToAscii(uint8_t keycode, uint8_t shift)`: Converts a keycode to its ASCII representation based on shift state.

#### `onKeyboard`
- `virtual void onKeyboard(hid_keyboard_report_t report, hid_keyboard_report_t last_report)`: Called when a keyboard report is received.

#### `onKeyboardKey`
- `virtual void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier)`: Called for each key press event, providing ASCII value, keycode, and modifier keys.

### Mouse Events

#### `onMouse`
- `virtual void onMouse(hid_mouse_report_t report, uint8_t last_buttons)`: Called when a general mouse report is received.

#### `onMouseButtons`
- `virtual void onMouseButtons(hid_mouse_report_t report, uint8_t last_buttons)`: Called specifically for mouse button events.

#### `onMouseMove`
- `virtual void onMouseMove(hid_mouse_report_t report)`: Called when the mouse is moved.
```

--------------------------------

### Handle Complete Mouse Events

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Use this callback for comprehensive mouse event handling, including button states, movement, and scroll wheel. It's suitable for detecting combined actions like dragging.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onMouse(hid_mouse_report_t report, uint8_t last_buttons) {
    // Log complete mouse state
    Serial.printf("Mouse Report - Buttons: 0x%02x, X: %d, Y: %d, Wheel: %d\n",
                  report.buttons,
                  (int8_t)report.x,
                  (int8_t)report.y,
                  (int8_t)report.wheel);

    // Detect drag operation (movement while button held)
    if ((report.buttons & MOUSE_BUTTON_LEFT) && (report.x != 0 || report.y != 0)) {
      Serial.println("Dragging with left button");
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### Custom Keycode to ASCII Conversion

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Override the getKeycodeToAscii method to implement custom key mappings, such as remapping special keys. The onKeyboardKey callback can then be used to process the converted ASCII values.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  // Custom keycode conversion with special handling
  uint8_t getKeycodeToAscii(uint8_t keycode, uint8_t shift) {
    // Call parent implementation for standard keys
    uint8_t ascii = EspUsbHost::getKeycodeToAscii(keycode, shift);

    // Custom mapping: remap F1 key (0x3A) to send '!'
    if (keycode == 0x3A) {
      return '!';
    }

    return ascii;
  }

  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    if (ascii != 0) {
      Serial.printf("Converted: %c\n", ascii);
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### Handle Keyboard Key Press Events

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Callback function called when a keyboard key is pressed. Logs the ASCII character, raw keycode, modifier state, and specific key events like Enter or Backspace.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    // Check for printable ASCII characters
    if (' ' <= ascii && ascii <= '~') {
      Serial.printf("Character: %c\n", ascii);
    }
    // Handle Enter key
    else if (ascii == '\r') {
      Serial.println("Enter pressed");
    }
    // Handle Backspace
    else if (ascii == '\b') {
      Serial.println("Backspace pressed");
    }
    // Handle Tab
    else if (ascii == '\t') {
      Serial.println("Tab pressed");
    }
    // Handle Escape
    else if (ascii == '\x1b') {
      Serial.println("Escape pressed");
    }

    // Check modifier keys
    if (modifier & KEYBOARD_MODIFIER_LEFTSHIFT) {
      Serial.println("Left Shift held");
    }
    if (modifier & KEYBOARD_MODIFIER_RIGHTSHIFT) {
      Serial.println("Right Shift held");
    }

    // Log raw keycode for debugging
    Serial.printf("Keycode: 0x%02x, Modifier: 0x%02x\n", keycode, modifier);
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### Keyboard Callback Functions

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Callback function triggered upon keyboard key press events.

```APIDOC
## Keyboard Callback Functions

### onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier)

Called when a keyboard key is pressed. Receives the ASCII character, raw HID keycode, and modifier state (shift, ctrl, etc.). This is the primary callback for handling keyboard input.

### Method

`onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier)`

### Endpoint

N/A (Callback function)

### Parameters

- **ascii** (uint8_t) - The ASCII representation of the key pressed.
- **keycode** (uint8_t) - The raw HID keycode of the key pressed.
- **modifier** (uint8_t) - A bitmask representing modifier keys (e.g., Shift, Ctrl, Alt).

### Request Example

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    // Check for printable ASCII characters
    if (' ' <= ascii && ascii <= '~') {
      Serial.printf("Character: %c\n", ascii);
    }
    // Handle Enter key
    else if (ascii == '\r') {
      Serial.println("Enter pressed");
    }
    // Handle Backspace
    else if (ascii == '\b') {
      Serial.println("Backspace pressed");
    }
    // Handle Tab
    else if (ascii == '\t') {
      Serial.println("Tab pressed");
    }
    // Handle Escape
    else if (ascii == '\x1b') {
      Serial.println("Escape pressed");
    }

    // Check modifier keys
    if (modifier & KEYBOARD_MODIFIER_LEFTSHIFT) {
      Serial.println("Left Shift held");
    }
    if (modifier & KEYBOARD_MODIFIER_RIGHTSHIFT) {
      Serial.println("Right Shift held");
    }

    // Log raw keycode for debugging
    Serial.printf("Keycode: 0x%02x, Modifier: 0x%02x\n", keycode, modifier);
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

### Response

None (Callback function, no direct response)
```

--------------------------------

### Process USB Host Events

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

Processes USB host events and triggers data transfers. Must be called continuously in the main loop to handle USB device communication and invoke callbacks.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    Serial.printf("Key pressed: %c (code: 0x%02x)\n", ascii, keycode);
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  // Must be called continuously to process USB events
  usbHost.task();

  // Your other code here
  delay(1);
}
```

--------------------------------

### Keycode to ASCII Conversion

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

The getKeycodeToAscii function converts a HID keycode to its ASCII representation. It can be overridden to implement custom key mappings.

```APIDOC
## getKeycodeToAscii

### Description
Converts a HID keycode to its ASCII representation based on the current locale and shift state. Override this method to implement custom key mappings.

### Method
`uint8_t getKeycodeToAscii(uint8_t keycode, uint8_t shift)`

### Parameters
- **keycode** (uint8_t) - The HID keycode to convert.
- **shift** (uint8_t) - The current shift state (e.g., 0 for no shift, 1 for shift pressed).

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  // Custom keycode conversion with special handling
  uint8_t getKeycodeToAscii(uint8_t keycode, uint8_t shift) {
    // Call parent implementation for standard keys
    uint8_t ascii = EspUsbHost::getKeycodeToAscii(keycode, shift);

    // Custom mapping: remap F1 key (0x3A) to send '!'
    if (keycode == 0x3A) {
      return '!';
    }

    return ascii;
  }

  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    if (ascii != 0) {
      Serial.printf("Converted: %c\n", ascii);
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```
```

--------------------------------

### Handle USB Device Disconnection

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

This callback is invoked when a USB device is disconnected. Use it to clean up any device-specific state and reset connection flags. It provides the device handle for reference.

```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  bool deviceConnected = false;

  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    deviceConnected = true;
    Serial.printf("Key: %c\n", ascii);
  }

  void onGone(const usb_host_client_event_msg_t *eventMsg) {
    deviceConnected = false;
    Serial.println("USB device disconnected!");
    Serial.printf("Device handle: 0x%x\n", eventMsg->dev_gone.dev_hdl);

    // Reset any device-specific state here
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
  Serial.println("Waiting for USB device...");
}

void loop() {
  usbHost.task();
}
```

--------------------------------

### onMouse Callback

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

This callback is triggered on every mouse event, providing the complete mouse report. It's useful for handling combined button states and movement, such as detecting drag operations.

```APIDOC
## onMouse(hid_mouse_report_t report, uint8_t last_buttons)

### Description
Called on every mouse event with the complete mouse report. Use this for combined button and movement handling.

### Method
Callback function within the EspUsbHost class.

### Parameters
#### Request Body
- **report** (hid_mouse_report_t) - An object containing the current state of the mouse.
  - **report.buttons** (uint8_t) - Bitmask representing the current state of mouse buttons (e.g., MOUSE_BUTTON_LEFT).
  - **report.x** (int8_t) - Relative movement delta on the X-axis.
  - **report.y** (int8_t) - Relative movement delta on the Y-axis.
  - **report.wheel** (int8_t) - Scroll wheel movement amount.
- **last_buttons** (uint8_t) - The state of the mouse buttons from the previous event.

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onMouse(hid_mouse_report_t report, uint8_t last_buttons) {
    // Log complete mouse state
    Serial.printf("Mouse Report - Buttons: 0x%02x, X: %d, Y: %d, Wheel: %d\n",
                  report.buttons,
                  (int8_t)report.x,
                  (int8_t)report.y,
                  (int8_t)report.wheel);

    // Detect drag operation (movement while button held)
    if ((report.buttons & MOUSE_BUTTON_LEFT) && (report.x != 0 || report.y != 0)) {
      Serial.println("Dragging with left button");
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

### Response
This is a callback function and does not return a value. It processes incoming mouse events.
```

--------------------------------

### onGone Callback

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

This callback is triggered when a USB device is disconnected. It allows for handling device removal and cleaning up any associated state or resources.

```APIDOC
## onGone(const usb_host_client_event_msg_t *eventMsg)

### Description
Called when a USB device is disconnected. Use this callback to handle device removal and clean up any state.

### Method
Callback function within the EspUsbHost class.

### Parameters
#### Request Body
- **eventMsg** (const usb_host_client_event_msg_t *) - A pointer to the event message structure containing details about the device gone event.
  - **eventMsg.dev_gone.dev_hdl** (uint32_t) - The handle of the disconnected device.

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  bool deviceConnected = false;

  void onKeyboardKey(uint8_t ascii, uint8_t keycode, uint8_t modifier) {
    deviceConnected = true;
    Serial.printf("Key: %c\n", ascii);
  }

  void onGone(const usb_host_client_event_msg_t *eventMsg) {
    deviceConnected = false;
    Serial.println("USB device disconnected!");
    Serial.printf("Device handle: 0x%x\n", eventMsg->dev_gone.dev_hdl);

    // Reset any device-specific state here
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
  Serial.println("Waiting for USB device...");
}

void loop() {
  usbHost.task();
}
```

### Response
This is a callback function and does not return a value. It handles the event of a USB device disconnection.
```

--------------------------------

### Mouse Button Event Handling

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

The onMouseButtons callback is triggered when mouse button states change, allowing detection of clicks and releases for various mouse buttons.

```APIDOC
## onMouseButtons

### Description
Called when mouse button state changes. Detects clicks and releases for left, right, middle, backward, and forward buttons.

### Method
`void onMouseButtons(hid_mouse_report_t report, uint8_t last_buttons)`

### Parameters
- **report** (hid_mouse_report_t) - The current HID mouse report, including button states.
- **last_buttons** (uint8_t) - The button states from the previous report.

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  void onMouseButtons(hid_mouse_report_t report, uint8_t last_buttons) {
    // Detect LEFT button click
    if (!(last_buttons & MOUSE_BUTTON_LEFT) && (report.buttons & MOUSE_BUTTON_LEFT)) {
      Serial.println("LEFT Click");
    }
    if ((last_buttons & MOUSE_BUTTON_LEFT) && !(report.buttons & MOUSE_BUTTON_LEFT)) {
      Serial.println("LEFT Release");
    }

    // Detect RIGHT button click
    if (!(last_buttons & MOUSE_BUTTON_RIGHT) && (report.buttons & MOUSE_BUTTON_RIGHT)) {
      Serial.println("RIGHT Click");
    }
    if ((last_buttons & MOUSE_BUTTON_RIGHT) && !(report.buttons & MOUSE_BUTTON_RIGHT)) {
      Serial.println("RIGHT Release");
    }

    // Detect MIDDLE button click
    if (!(last_buttons & MOUSE_BUTTON_MIDDLE) && (report.buttons & MOUSE_BUTTON_MIDDLE)) {
      Serial.println("MIDDLE Click");
    }
    if ((last_buttons & MOUSE_BUTTON_MIDDLE) && !(report.buttons & MOUSE_BUTTON_MIDDLE)) {
      Serial.println("MIDDLE Release");
    }

    // Detect BACKWARD button (side button)
    if (!(last_buttons & MOUSE_BUTTON_BACKWARD) && (report.buttons & MOUSE_BUTTON_BACKWARD)) {
      Serial.println("BACKWARD Click");
    }

    // Detect FORWARD button (side button)
    if (!(last_buttons & MOUSE_BUTTON_FORWARD) && (report.buttons & MOUSE_BUTTON_FORWARD)) {
      Serial.println("FORWARD Click");
    }

    // Show current button state
    Serial.printf("Buttons: %c%c%c%c%c\n",
                  (report.buttons & MOUSE_BUTTON_LEFT) ? 'L' : '-',
                  (report.buttons & MOUSE_BUTTON_RIGHT) ? 'R' : '-',
                  (report.buttons & MOUSE_BUTTON_MIDDLE) ? 'M' : '-',
                  (report.buttons & MOUSE_BUTTON_BACKWARD) ? 'B' : '-',
                  (report.buttons & MOUSE_BUTTON_FORWARD) ? 'F' : '-');
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```
```

--------------------------------

### onMouseMove Callback

Source: https://context7.com/tanakamasayuki/espusbhost/llms.txt

This callback is invoked when mouse movement or scroll wheel activity is detected. It provides relative X/Y movement deltas and the scroll wheel amount, allowing for real-time cursor updates and scroll handling.

```APIDOC
## onMouseMove(hid_mouse_report_t report)

### Description
Called when mouse movement or scroll wheel activity is detected. Provides relative X/Y movement deltas and wheel scroll amount.

### Method
Callback function within the EspUsbHost class.

### Parameters
#### Request Body
- **report** (hid_mouse_report_t) - An object containing mouse movement and scroll data.
  - **report.x** (int8_t) - Relative movement delta on the X-axis.
  - **report.y** (int8_t) - Relative movement delta on the Y-axis.
  - **report.wheel** (int8_t) - Scroll wheel movement amount.
  - **report.buttons** (uint8_t) - Current state of mouse buttons.

### Request Example
```cpp
#include "EspUsbHost.h"

class MyEspUsbHost : public EspUsbHost {
  int cursorX = 0;
  int cursorY = 0;

  void onMouseMove(hid_mouse_report_t report) {
    // Update cursor position with movement deltas
    cursorX += (int8_t)report.x;
    cursorY += (int8_t)report.y;

    // Clamp cursor to screen bounds (example: 320x240 display)
    cursorX = constrain(cursorX, 0, 319);
    cursorY = constrain(cursorY, 0, 239);

    Serial.printf("Mouse: X=%d, Y=%d (cursor: %d,%d)
",
                  (int8_t)report.x, (int8_t)report.y, cursorX, cursorY);

    // Handle scroll wheel
    if (report.wheel != 0) {
      Serial.printf("Scroll: %d\n", (int8_t)report.wheel);
    }
  }
};

MyEspUsbHost usbHost;

void setup() {
  Serial.begin(115200);
  usbHost.begin();
}

void loop() {
  usbHost.task();
}
```

### Response
This is a callback function and does not return a value. It processes incoming mouse events.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.