KKBox 可编程键鼠控制器

一、产品概述

KK Box 是一款基于 ESP32-S3 和两颗 CH9350L 的键盘鼠标桥接设备。它连接在键鼠设备与电脑之间，负责在两条 CH9350L 链路间透明转发键盘、鼠标数据，并在转发过程中解析 HID 输入事件。

产品可用于查看和记录键鼠操作、运行 Lua 脚本响应按键或鼠标事件，以及由脚本发送键盘和鼠标输入。用户正常按下的按键和脚本生成的按键会分别保存并安全合并，避免脚本释放用户仍在按住的按键。鼠标按钮同样采用独立状态管理，降低用户操作与脚本操作相互干扰的风险。

设备配有 OLED 屏幕，用于显示启动状态、网络地址、键鼠动作及运行信息。三个实体按键可用于菜单、左右切换和模式控制，按键采用低电平触发，并在固件中进行了稳定时间判断。

设备支持两种运行模式：

• 正常模式：启动 Wi‑Fi 和本地管理页面，可进行网络配置、脚本管理、日志查看和设备管理。
• 快速模式：默认不启动 Wi‑Fi，适合只进行键鼠透明转发和本地脚本运行，以减少无线网络带来的干扰。

Lua 是该产品的可编程入口。用户可以编写脚本监听键盘、鼠标和实体按键事件，也可以调用键盘、鼠标、屏幕、延时、日志和 TCP 通信接口实现自定义操作。脚本产生的键鼠数据会进入发送队列，在完整的 CH9350L 数据帧之间发送，避免破坏原有的透明转发数据。

简而言之，KK Box 当前是一台具备“透明键鼠转发 + HID 事件解析 + Lua 自动化 + OLED 状态显示 + Wi‑Fi 网页管理”的可编程键鼠桥接设备。

二、产品参数

控制方式：手机wifi联网控制

硬件接口：TypeC母头接口x1（连接电脑），USB-A母头接口x2（键鼠接口）

主控芯片：ESP32-S3双核

键鼠桥接芯片：2 × CH9350L两条 CH9350L 数据链路，用于键鼠数据转发与解析CH9350L

无线网络：2.4 GHz Wi‑Fi，802.11b/g/n

当前固件已实现： Wi‑Fi 配网和本地管理网页

功能显示屏：SSD1306 OLED128 × 64

供电：5V

典型功耗：约 1 W

峰值功耗：≤ 2 W（不含外接 USB 设备）

PCB尺寸：70x48mm

三、使用说明

1. 刷入固件
2. 将键盘和鼠标分别接入右侧两个 USB-A 接口。
3. 使用一根支持数据传输的 USB-C 线，将左侧 USB-C 接口连接到电脑。请勿使用仅充电线。
4. 设备通电后会自动启动。ESP32-S3 将初始化两颗 CH9350L，键盘和鼠标会自动与电脑建立连接；无需安装驱动，也无需设置通信波特率。
5. 默认情况下，设备进入正常模式，并启动 Wi‑Fi 管理功能。若尚未保存家庭或办公 Wi‑Fi 信息，设备会创建热点
6. 使用手机或电脑连接 KKBox 热点后，打开浏览器访问上述地址。进入管理页面后，可设置要连接的 Wi‑Fi 名称和密码。保存后设备会自动重启，并尝试连接该 Wi‑Fi。
7. 设备成功连接 Wi‑Fi 后，OLED 会显示当前 IP 地址。以后可让手机或电脑连接同一个局域网，并通过该 IP 地址打开管理页面。
8. 在管理页面中，用户可按需要编辑和运行 Lua 脚本、查看日志、切换正常/快速模式，以及进行固件管理。即使不创建任何脚本，设备也可以正常完成键盘和鼠标的透明转发。

四、备注

1、成本构成

元器件成本：¥178.92元 元；（不含PCB）

其他外设：¥0 元；

外壳、面板：¥40 元；（OLED屏幕）

总计：¥ 240元+

2、细节备注

1. 电脑端 USB-C 接口用于连接 PC，设备以标准 USB HID 键盘、鼠标方式工作，通常无需安装专用驱动；右侧两个 USB-A 接口用于连接键盘、鼠标等 USB HID 设备；
2. 本项目使用 ESP32-S3 主控，首次使用前需要烧录完整固件。固件采用 ESP-IDF 开发，可通过 U8 下载/测试接口连接 3.3V USB-UART 转换器，并使用 idf.py 或工程附带的刷机脚本完成烧录；
3. 附件包含设备固件、ESP-IDF 工程源代码、Lua API 及使用文档、构建与刷机脚本、原理图、硬件照片和接口配置位标注图等资料；
4. 本项目不提供 PCB 源文件、Gerber 文件及生产工程文件，随附硬件资料主要用于设备接线、功能说明、固件开发和故障排查；
5. 使用本产品时，请注意接口电压、供电方式和接线顺序。U8 下载接口采用 3.3V 电平，请勿向 ESP32-S3 GPIO 接入 5V，并避免短路、反接或多路电源同时供电。因操作不当造成的设备损坏或其他损失，由使用者自行承担。
6. 板载预留配置位可用于设置两颗 CH9350L 的工作模式和串口波特率，修改配置前请先断开设备电源；
7. 具体修改方式如下表：

• 波特率 需要焊接的 0Ω 电阻
• 115200 默认
• 57600 R116、R133
• 38400 R115、R132
• 300000 R115、R116、R132、R133
• 工作状态 需要焊接的 0Ω 电阻
• 状态 0/1 默认
• 状态 2 R117、R134
• 状态 3 R118、R135
• 状态 4 R117、R118、R134、R135

3. 固件如何烧录

本工程使用 ESP32-S3 的串口下载方式，不使用 Keil、ST-Link。首次烧录必须写入 Bootloader、分区表、OTA 数据、应用固件和 SPIFFS 存储镜像。

接线方法：

• USB-UART 的 TX 接 U8 的 RX。
• USB-UART 的 RX 接 U8 的 TX。
• USB-UART 的 GND 接 U8 的 GND。
• USB-UART 信号电平必须设置为 3.3V。
• 如果硬件板已经通过 USB-C 供电，不要再连接 USB-UART 的电源输出。
• 自动下载不可用时，将 BOOT0 拉低，按一下 RESET/EN，然后释放 RESET/EN，使 ESP32-S3 进入下载模式。

U8 定义：

| 引脚 | 定义 | 引脚 | 定义 |

| 1 | EN | 2 | +5V |

| 3 |  | 4 | +5V |

| 5 |  | 6 | GND |

| 7 |  | 8 | RX |

| 9 | GND | 10 | TX |

| 11 | BOOT0 | 12 |  |

| 13 |  | 14 | GND |

| 15 |  | 16 |  |

烧录指令：

esptool.py \ --chip esp32s3 \ --port "$ESP_PORT" \ --baud 115200 \ write_flash \ --flash-mode dio \ --flash-freq 80m \ --flash-size 8MB \ 0x0 bootloader/bootloader.bin \ 0x8000 partition_table/partition-table.bin \ 0xD000 ota_data_initial.bin \ 0x10000 esp32_basic.bin \ 0x410000 storage.bin 

空白硬件板首次必须进行上述完整烧录；

五、测试视频

视频中演示了Lua脚本控制功能， 脚本为 按下鼠标左键后，自动画一个圆形。

六、更新日志

V1.0 首次上传。