# ble-keyboard-usb-adapter

**Repository Path**: jinguangyang/ble-keyboard-usb-adapter

## Basic Information

- **Project Name**: ble-keyboard-usb-adapter
- **Description**: No description available
- **Primary Language**: C
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32-S3 BLE to USB HID Bridge (Keyboard Optimized)
# ESP32-S3 蓝牙转 USB HID 键盘适配器

[English](#english) | [中文](#chinese)

---

<a name="english"></a>
## English Description

### Project Overview
This project transforms an ESP32-S3 development board into a **BLE to USB HID Bridge**. It connects to Bluetooth Low Energy (BLE) keyboards (specifically optimized for **Lofree ES112s** and **EH211s**) and forwards their input to a computer via USB. This allows wireless keyboards to work on devices that lack Bluetooth or require a wired USB connection (e.g., BIOS, KVM switches, or strict security environments).

### Core Functionality

1.  **High-Performance Bridge**:
    *   Utilizes ESP32-S3 (N8R8) with 8MB Flash and 8MB Octal PSRAM.
    *   Removes all display/GUI overhead to prioritize input latency and stability.

2.  **Adaptive Retry Strategy (Anti-Ghosting)**:
    *   Implements an intelligent algorithm to handle USB congestion.
    *   **Priority Release**: Even if the system is busy, "Key Release" events are prioritized and retried up to 20 times to ensure keys never get "stuck" (ghosting).
    *   **Dynamic Backoff**: Automatically reduces retry attempts for non-critical "Key Press" events during congestion to clear the queue faster.

3.  **Composite HID Support**:
    *   Simulates a composite USB device supporting both **Standard Keyboard** (Report ID 1) and **Consumer Control** (Report ID 2).
    *   Supports standard typing keys + Media keys (Volume, Brightness, Play/Pause) + Fn combinations.

4.  **Auto-Connection & Security**:
    *   **Bonding Support**: Automatically pairs and bonds with the target keyboard.
    *   **Auto-Reconnect**: Automatically scans and reconnects to the bonded device on startup or disconnection.
    *   **Device Filtering**: Filters devices by MAC address and Name (configurable via NVS).

5.  **Status Indication**:
    *   **Blue LED**: Bluetooth Connected.
    *   **Red LED**: Bluetooth Disconnected / Scanning.

### Secondary Development Notes

#### 1. Development Environment
*   **Framework**: ESP-IDF v5.x (Tested with v5.3).
*   **Target**: ESP32-S3.
*   **Recommended Hardware**: QtPy ESP32-S3 or generic ESP32-S3-N8R8 boards.

#### 2. Key Code Structure
*   **`main/main.cpp`**: Core logic. Contains the `KeyboardPipeline` class which handles the input processing pipeline:
    *   Receives BLE HID reports.
    *   Performs software deduplication (based on Report ID).
    *   Executes the Adaptive Retry Strategy.
    *   Sends reports to USB via TinyUSB.
*   **`main/ble.cpp`**: BLE Client logic using NimBLE. Handles scanning, connecting, bonding, and receiving notifications.
*   **`components/keyboard/src/keyboard.cpp`**: Defines the USB HID Report Descriptor. Modify this if you need to add Mouse, Gamepad, or other HID device support.

#### 3. Dynamic Configuration (NVS)
To adapt to different keyboards without recompiling:
1.  Use `nvs_partition_gen.py` to create a `config.bin` containing:
    *   `target_mac`: Target BLE Address.
    *   `filter_name_1` / `filter_name_2`: Device name substrings to filter.
2.  Flash to the NVS partition (default offset `0x9000`).
3.  The firmware reads these values in `app_main()`.

#### 4. Debugging
*   Use `idf.py monitor` to view logs.
*   Log Tags:
    *   `BLE_HID`: Bluetooth connection/scanning events.
    *   `USB_HID`: USB report sending status.
    *   `PIPELINE`: Input processing and retry logic stats.

---

<a name="chinese"></a>
## 中文说明 (Chinese)

### 项目简介
本项目将 ESP32-S3 开发板模拟为一个 **蓝牙转 USB HID 桥接器**。它连接蓝牙低功耗 (BLE) 键盘（特别针对 **洛斐 Lofree ES112s** 和 **EH211s** 进行了优化），并通过 USB 将输入转发给电脑。这使得无线键盘可以在没有蓝牙功能或必须使用有线连接的设备（如 BIOS、KVM 切换器或高安全环境）上使用。

### 核心功能

1.  **高性能桥接**:
    *   基于 ESP32-S3 (N8R8)，配备 8MB Flash 和 8MB Octal PSRAM。
    *   移除所有屏幕/GUI 代码，专注于极低延迟和高稳定性。

2.  **自适应重试策略 (Adaptive Retry - 防卡死)**:
    *   内置智能算法处理 USB 通信拥堵。
    *   **优先松开 (Priority Release)**: 即使系统繁忙，“按键松开”事件也会被优先处理并重试高达 20 次，确保绝对不会出现“按键卡死/无限输出”的情况。
    *   **动态退避**: 在拥堵时自动减少普通“按键按下”事件的重试次数，以快速清空队列。

3.  **复合 HID 支持**:
    *   模拟复合 USB 设备，同时支持 **标准键盘** (Report ID 1) 和 **消费类控制/多媒体键** (Report ID 2)。
    *   完美支持标准打字键 + 多媒体键（音量、亮度、播放/暂停）+ Fn 组合键功能。

4.  **自动连接与安全**:
    *   **配对绑定**: 支持 BLE 配对和绑定，确保连接安全。
    *   **自动回连**: 启动或断开后自动扫描并重连已绑定的设备。
    *   **设备过滤**: 支持通过 MAC 地址和名称过滤目标设备（可通过 NVS 配置）。

5.  **状态指示**:
    *   **蓝色 LED**: 蓝牙已连接。
    *   **红色 LED**: 蓝牙断开 / 正在扫描。

### 二次开发注意事项

#### 1. 开发环境
*   **框架**: ESP-IDF v5.x (测试版本 v5.3)。
*   **目标芯片**: ESP32-S3。
*   **推荐硬件**: QtPy ESP32-S3 或通用的 ESP32-S3-N8R8 开发板。

#### 2. 关键代码结构
*   **`main/main.cpp`**: 核心逻辑。包含 `KeyboardPipeline` 类，负责输入处理流水线：
    *   接收 BLE HID 报告。
    *   执行软件去重 (基于 Report ID)。
    *   执行自适应重试策略。
    *   通过 TinyUSB 发送到 USB 主机。
*   **`main/ble.cpp`**: 基于 NimBLE 的 BLE 客户端逻辑。负责扫描、连接、绑定以及接收通知数据。
*   **`components/keyboard/src/keyboard.cpp`**: 定义 USB HID 报告描述符。如果您需要添加鼠标、手柄或其他 HID 设备支持，请修改此文件。

#### 3. 动态配置 (NVS)
为了适配不同的键盘而无需重新编译代码：
1.  使用 `nvs_partition_gen.py` 生成包含以下键值的 `config.bin`:
    *   `target_mac`: 目标蓝牙 MAC 地址。
    *   `filter_name_1` / `filter_name_2`: 设备名称过滤关键词。
2.  烧录到 NVS 分区（默认偏移量 `0x9000`）。
3.  固件会在 `app_main()` 中读取这些配置。

#### 4. 调试指南
*   使用 `idf.py monitor` 查看串口日志。
*   主要日志标签:
    *   `BLE_HID`: 蓝牙连接和扫描事件。
    *   `USB_HID`: USB 报告发送状态。
    *   `PIPELINE`: 输入处理流水线和重试逻辑统计。

### Build and Flash / 编译与烧录

```bash
# Clone the repository / 克隆仓库
git clone --recurse-submodules https://github.com/jinguangyang/ble-keyboard-usb-adapter.git

# Set target / 设置目标
idf.py set-target esp32s3

# Build / 编译
idf.py build

# Flash & Monitor / 烧录并监控
idf.py -p COMx flash monitor
```