# esp32ble_keyboard

**Repository Path**: panzi/esp32ble_keyboard

## Basic Information

- **Project Name**: esp32ble_keyboard
- **Description**: ESP-IDF框架开发的蓝牙键盘
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-13
- **Last Updated**: 2026-02-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BLE Keyboard over Wi-Fi UDP + BLE HID

中文 | [English](#english)

## 中文

一个基于 **ESP-IDF** 的 BLE HID 键盘项目，配套一个 iOS 遥控键盘应用。

- iOS App 通过 Wi-Fi UDP 发送按键数据到 ESP32。
- ESP32 将 UDP 按键事件转换为 BLE HID 键盘报告并发送给电脑/平板/手机。
- 适合做远程输入、定制快捷键、软键盘控制等场景。

## 功能特性

- BLE HID 键盘（ESP32 作为外设）
- iOS 横屏软键盘（类 Magic Keyboard 布局）
- UDP 键盘协议（支持 `key tap / key down / key up`）
- 修饰键组合（Shift / Ctrl / Option / Command）
- 可配置目标芯片（如 `esp32c6`）

## 项目结构

- `main/`：ESP-IDF 固件代码
- `main/esp_hid_device_main.c`：主逻辑、HID report map、UDP 接收与按键上报
- `main/esp_hid_gap.c` / `main/esp_hid_gap.h`：BLE GAP、配对、广播
- `ios/BLEKeyboardRemote/`：iOS 遥控键盘工程（SwiftUI）
- `ios/BLEKeyboardRemote/Sources/UDPClient.swift`：UDP 发包
- `ios/BLEKeyboardRemote/Sources/KeyboardViewModel.swift`：键位映射与状态

## 快速开始（固件）

在仓库根目录执行：

```bash
idf.py set-target esp32c6
idf.py menuconfig
idf.py build
idf.py -p <PORT> flash monitor
```

> 切换芯片或构建异常时可执行：`idf.py clean`

## 快速开始（iOS）

```bash
cd ios/BLEKeyboardRemote
xcodegen generate
open BLEKeyboardRemote.xcodeproj
```

默认连接参数：

- Host: `192.168.4.1`
- Port: `9999`

如果只做命令行构建：

```bash
cd ios/BLEKeyboardRemote
xcodebuild -project BLEKeyboardRemote.xcodeproj \
  -scheme BLEKeyboardRemote \
  -configuration Debug \
  -sdk iphonesimulator build
```

## UDP 键盘协议（KB v1）

单包 8 字节：

`magic(0x4B,0x42) + version + type + modifier + keycode + repeat + reserved`

- `type=0x01`：Key Tap
- `type=0x02`：Key Down
- `type=0x03`：Key Up

## 验证建议

最少验证：

1. `idf.py build` 编译通过。
2. iOS App 可发送 UDP。
3. ESP32 成功连接 BLE 主机并可输入字符。
4. 修饰键与组合键行为符合预期。

## 注意事项

- 不要提交私钥、凭据等敏感信息。
- `sdkconfig` 变更请在提交说明中写清原因。
- 发布前确认 BLE 配对/安全配置。

---

## English

This is an **ESP-IDF** BLE HID keyboard project with a companion iOS remote keyboard app.

- The iOS app sends key events to ESP32 over Wi-Fi UDP.
- ESP32 translates UDP key events into BLE HID keyboard reports.
- Useful for remote typing, custom shortcuts, and software keyboard control.

## Features

- BLE HID keyboard peripheral on ESP32
- Landscape iOS keyboard UI (Magic Keyboard style)
- UDP keyboard protocol with `key tap / key down / key up`
- Modifier key handling (Shift / Ctrl / Option / Command)
- Configurable ESP target (for example `esp32c6`)

## Repository Layout

- `main/`: ESP-IDF firmware source
- `main/esp_hid_device_main.c`: app entry, HID report map, UDP input path
- `main/esp_hid_gap.c` / `main/esp_hid_gap.h`: GAP, pairing, advertising helpers
- `ios/BLEKeyboardRemote/`: iOS SwiftUI app
- `ios/BLEKeyboardRemote/Sources/UDPClient.swift`: UDP client
- `ios/BLEKeyboardRemote/Sources/KeyboardViewModel.swift`: key mapping and state

## Quick Start (Firmware)

Run from repository root:

```bash
idf.py set-target esp32c6
idf.py menuconfig
idf.py build
idf.py -p <PORT> flash monitor
```

> Use `idf.py clean` when switching targets or troubleshooting stale build artifacts.

## Quick Start (iOS)

```bash
cd ios/BLEKeyboardRemote
xcodegen generate
open BLEKeyboardRemote.xcodeproj
```

Default endpoint:

- Host: `192.168.4.1`
- Port: `9999`

CLI build example:

```bash
cd ios/BLEKeyboardRemote
xcodebuild -project BLEKeyboardRemote.xcodeproj \
  -scheme BLEKeyboardRemote \
  -configuration Debug \
  -sdk iphonesimulator build
```

## UDP Keyboard Packet (KB v1)

8-byte packet format:

`magic(0x4B,0x42) + version + type + modifier + keycode + repeat + reserved`

- `type=0x01`: Key Tap
- `type=0x02`: Key Down
- `type=0x03`: Key Up

## Validation Checklist

1. `idf.py build` passes.
2. iOS app sends UDP packets.
3. ESP32 pairs/connects as BLE keyboard.
4. Key and modifier behavior is correct on host device.

## Security Notes

- Do not commit secrets or private keys.
- Explain `sdkconfig` changes in commits/PRs.
- Verify Bluetooth pairing/security settings before release.