立创开源智能家居键盘SmartKB32_v2：基于ESP32-S3的蓝牙/有线双模多功能控制器设计详解

最近在做一个智能家居控制的项目，发现市面上的键盘要么功能太单一，要么自定义程度不够。比如很多客制化键盘虽然有旋钮，但基本只能调音量，而且旋钮都在右边，用起来不太顺手。于是我就琢磨着，能不能自己做一把既能当键盘用，又能控制智能设备，还能根据不同的软件切换快捷键的'全能型'键盘？

这就是今天要跟大家分享的 SmartKB32_v2。它基于性能强劲的ESP32-S3芯片，不仅支持蓝牙和有线双模连接，还内置了Web服务器，可以通过网页随时修改按键功能。更酷的是，它左侧集成了一个带屏幕和力反馈的智能旋钮，配合SD卡存储的'映射表'，可以一键切换成设计师模式、游戏模式或者智能家居控制模式。

无论你是想复刻这个项目的创客，还是对ESP32-S3开发、HID设备（键盘鼠标这类人机交互设备）设计感兴趣的工程师，这篇文章都会带你从硬件到软件，把它的设计思路和实现方法讲清楚。

1. 项目核心功能与设计思路

1.1 为什么要做这样一把键盘？

很多朋友可能和我有一样的痛点：用不同的设计软件（比如PS、AI、CAD）时，快捷键各不相同，每次切换软件都要重新适应，效率很低。市面上的宏键盘层数有限，没法覆盖所有需求。同时，智能家居设备越来越多，开关灯、调节氛围还得掏手机，不够直接。

SmartKB32_v2就是为了解决这些问题而生的：

一机多用：它既是一把全功能键盘，也是一个智能家居控制中心。
高度自定义：通过SD卡存储'映射表'，可以为上百款软件或游戏预存专属快捷键配置。
智能旋钮：将旋钮放在左手边，配合屏幕显示，可以直观地控制软件参数（如画笔大小、图层透明度）或智能设备（如灯光亮度、色温）。
双模连接：既可以用USB线连接电脑（有线模式），稳定可靠；也可以用蓝牙连接（无线模式），桌面更整洁。

1.2 核心功能一览

这把键盘的功能相当丰富，咱们来快速过一遍：

功能类别	具体实现
智能家居控制	控制智能台灯的开关、亮度、色温；控制桌面充电站的电源输出。
设计师工作流	通过SD卡预存不同设计软件（如PS、AI）的快捷键映射表，快速切换。
游戏宏定义	预存游戏连招、技能组合的映射表，支持单键循环输出或多键同时触发。
网页配置界面	键盘内置Web服务器，用电脑或手机浏览器就能实时修改按键功能，无需刷固件。
指纹识别	（可选）接入指纹模块，实现指纹解锁电脑或一键登录系统。
媒体控制	控制电脑的音乐播放/暂停、切歌、音量调节。
'摸鱼'模式	可以自定义一个或多个按键为'摸鱼键'，一键快速切换窗口或隐藏游戏。

注意：项目完全开源（遵循GPL3协议），所有硬件设计文件、源代码、3D打印文件都可以在开源平台找到，仅供学习使用，禁止商用。

2. 硬件系统设计解析

整个键盘的硬件可以看作由'主控'和'副控'两大部分组成，核心是一颗ESP32-S3芯片。这颗芯片功能非常强大，它集成了Wi-Fi、蓝牙、充足的GPIO和计算资源，是项目的'大脑'。

2.1 主控部分：ESP32-S3及其关键外设

主控部分负责最核心的键盘HID（人机接口设备）功能、旋钮控制和音频处理。

ESP32-S3：作为主控MCU，它同时运行着几个重要任务：
1. 蓝牙HID：模拟蓝牙键盘，向电脑发送按键信号。
2. USB HID：模拟有线键盘，通过USB线直接通信。
3. Web服务器：建立一个Wi-Fi热点（或连接本地网络），提供网页配置界面。
4. 文件系统：管理SD卡，读写按键映射表配置文件。
MPU6050：这是一个集成了3轴陀螺仪和3轴加速度计的传感器。在这里，它被用来实现FOC（磁场定向控制）旋钮。通过检测旋钮上磁铁的磁场变化，MPU6050可以非常精确地感知旋钮的旋转角度和速度，从而实现像Surface Dial那样细腻的力反馈和精准控制。
WM8978：这是一颗音频编解码器芯片。它让键盘具备了音频输入/输出能力。未来规划中，它可以用于语音输入提示音或音频反馈，让交互更有趣。

2.2 副控与扩展功能模块

这部分硬件扩展了键盘的输入、输出和控制能力。

按键扫描（74HC165）：一把全尺寸键盘有上百个按键，如果每个键都单独接一个GPIO，ESP32-S3的引脚肯定不够用。这里使用了74HC165这款'并转串'芯片。简单来说，它可以把多路并行输入（很多个按键的状态）转换成一路串行数据输出给ESP32-S3，极大地节省了主控的引脚。
- 工作原理：ESP32-S3周期性地给74HC165一个脉冲信号，74HC165就会把当前所有按键的通断状态（0或1）一位一位地发送出来。主控读取这些数据，就知道哪个键被按下了。
指示灯控制（74HC595）：同理，为了控制多个状态指示灯（如大小写锁定、映射表编号等），使用了74HC595这款'串转并'芯片。ESP32-S3把要点亮哪些灯的数据串行发送给74HC595，74HC595再并行输出到各个LED上。
实时时钟（DS1302）：为键盘提供精确的计时功能，可用于实现定时任务，比如定时开关智能台灯。
声音采样（Max4466）：这是一个麦克风放大器模块，可用于声音触发或未来的语音交互功能。

2.3 结构设计与复刻要点

从爆炸图可以看出，整个键盘是模块化设计的，包括主PCB、定位板、轴体、键帽、旋钮模块和外壳。

如果你也想动手复刻一个，有几个硬件上的细节需要特别注意：

PCB厚度：
- 键盘主PCB：1.6mm
- 屏幕和电机驱动板PCB：1.0mm（如果使用3205B电机版本，则为1.6mm）
- 定位板（固定轴体的金属/塑料板）：1.5mm
旋钮电机二选一：
- 方案A：2804云台电机 + 径向磁铁（外径10mm，内径6.3mm，厚度2mm）。电机通过一颗 M2.5*27mm的铜柱焊接固定。
- 方案B：3205B去限位版云台电机。这个版本不需要额外的径向磁铁，固定铜柱为 M2.5*2mm。
- 两种电机性能有差异，原作者提供了两种设计文件，任选一种即可。
物料获取：所有电路板设计文件（.pcb）、3D打印外壳文件（.stl）、以及需要采购的元器件清单（BOM表），都可以在项目开源页面找到。

3. 软件架构与关键实现

软件是让这套硬件'活'起来的关键。项目的软件系统主要围绕'事件触发'和'配置管理'两个核心概念构建。

3.1 核心：按键映射表与触发事件

这是本项目最精髓的部分。键盘的每个按键都不是固定功能的，它的行为由一个叫做'映射表'的配置文件来决定。

什么是映射表？ 你可以把它想象成一个巨大的Excel表格。每一行对应键盘上的一个物理按键，每一列定义了在不同条件下（比如单击、长按、配合旋钮时）这个按键应该执行什么'动作'。
动作是什么？ 动作就是'触发事件'。项目的固件里预定义了超过230种触发事件。这些事件五花八门：
- 键盘事件：发送单个字母（如'A'）、组合键（如Ctrl+C）、多媒体键（音量加）。
- 系统事件：打开计算器、锁定电脑、切换输入法。
- 智能家居事件：通过Wi-Fi或ESPNOW协议，向智能台灯发送'开灯'、'调至暖光'的命令。
- 内部控制事件：切换当前使用的映射表（比如从'Photoshop模式'切换到'游戏模式'）。

// 这是一个简化的映射表数据结构示例 typedef struct { uint16_t key_id; // 物理按键的编号 action_t tap_action; // 单击时触发的动作 action_t hold_action; // 长按时触发的动作 action_t knob_action; // 配合旋钮时触发的动作 uint8_t target_layer; // 该按键所属的映射表（层） } key_mapping_t; // 动作（action_t）可能包含的类型 typedef enum { ACTION_NONE, ACTION_KEYPRESS, // 发送键盘按键 ACTION_CONSUMER, // 发送多媒体键 ACTION_SWITCH_LAYER, // 切换映射表 ACTION_HOMEASSISTANT, // 控制智能家居 // ... 其他230多种事件类型 } action_type_t;

创新点：键盘左侧有一列特殊的按键。长按它们时，功能就和普通按键一样（比如是Ctrl键）。但单击它们时，功能就变成了切换映射表。这个设计非常巧妙，既节省了按键，又让模式切换变得极其快捷。

3.2 双模连接与Web服务器

蓝牙/有线双模：ESP32-S3原生支持蓝牙和USB。固件中实现了标准的HID协议。插入USB线时，自动以有线模式工作；拔掉线，则自动切换到蓝牙模式并等待配对，实现了无缝切换。
内置Web服务器：这是实现'免刷机'配置的关键。
1. 键盘启动后，ESP32-S3会创建一个Wi-Fi热点（比如叫'SmartKB32'）。
2. 用电脑或手机连接这个热点。
3. 在浏览器输入管理地址（通常是 192.168.4.1），就能看到一个配置网页。
4. 在网页上，你可以像搭积木一样，为每个按键选择单击、长按等操作对应的'触发事件'，然后点击保存。新的映射表会直接写入键盘的SD卡中，立即生效。

网页配置界面示意图

网页映射表生成器界面，可以通过拖拽或选择的方式配置按键功能

3.3 智能旋钮（FOC控制）的实现

旋钮的体验之所以流畅，离不开FOC算法和MPU6050的配合。

角度感知：旋钮底部安装了一个环形磁铁。MPU6050紧贴在下方，可以精确测量磁场矢量。当旋钮转动时，磁场方向改变，通过算法就能计算出精确的旋转角度。
力反馈（FOC）：ESP32-S3根据计算出的角度，通过电机驱动电路控制2804或3205B电机产生一个反向扭矩。当你快速转动旋钮时，电机会产生阻力，模拟机械旋钮的'刻度感'；当你慢慢微调时，阻力变小，实现平滑控制。这种带力反馈的交互，比普通编码器旋钮体验好太多。
屏幕交互：旋钮上方的OLED屏幕会显示当前模式下的参数，比如亮度百分比、色温值、或是Photoshop里的画笔大小，实现视觉反馈。

4. 如何开始你的复刻与开发之旅

如果你对这个项目心动，想自己做一个或者基于它进行二次开发，可以按以下步骤开始：

4.1 获取资源

所有的开发资源都在开源平台（Gitee）上：

源代码：包含完整的ESP32-S3固件，使用PlatformIO或Arduino IDE均可编译。
- 地址：https://gitee.com/jiawenling/smart-kb32_v2
硬件资料：在工程页面的'附件'或相关仓库中，可以找到：
- 电路原理图（.sch）和PCB文件（.pcb）
- 3D打印外壳文件（.stl）
- 元器件清单（BOM表）
- 最新版本的固件烧录文件（.bin）
- 详细的烧录教程

4.2 烧录与配置步骤

硬件焊接与组装：按照BOM表采购元件，焊接PCB，并按照爆炸图组装所有结构件。特别注意电机和磁铁的安装。
烧录固件：
- 使用USB线连接键盘的Type-C接口到电脑。
- 按住键盘上的'Boot'按钮（或短接PCB上的进入下载模式的触点），再按一下'Reset'按钮，使ESP32-S3进入下载模式。
- 使用乐鑫官方的flash_download_tool或esptool.py工具，将下载好的.bin固件文件烧录到芯片的0x0地址。
首次使用与配置：
- 烧录完成后，键盘重启。用USB线连接电脑，它应该会被识别为一个USB键盘。
- 同时，键盘会开启一个Wi-Fi热点。用手机或另一台电脑连接这个热点。
- 浏览器访问 192.168.4.1，进入Web配置页面。
- 在'映射表管理'中，你可以导入预设的映射表（如设计师配置），或者从头开始创建你自己的配置。

4.3 二次开发建议

这个项目的代码架构已经比较清晰，如果你想增加功能：

添加新的触发事件：在固件的 action_definitions.h 或类似文件中，找到事件枚举和事件处理函数，仿照着添加你自己的事件类型和处理逻辑。
修改Web界面：网页文件通常存放在固件的 data 目录下（作为SPIFFS或LittleFS文件系统镜像）。你可以修改HTML/CSS/JS文件来改变配置页面的外观和逻辑。
接入其他智能家居平台：目前项目通过ESPNOW和点灯科技控制设备。你可以修改网络通信部分的代码，接入Home Assistant、MQTT等更通用的物联网协议。

这个项目从构思到实现，花了作者近一年的时间，期间打样测试了无数个版本。最大的坑可能是在FOC旋钮的调校上，电机力矩、磁铁位置、PID参数都需要反复调试才能达到'跟手'的效果。另一个经验是，按键扫描的防抖算法和Web服务器的响应速度需要平衡好，否则在快速打字时配置页面可能会卡顿。

希望这篇详细的解析，能帮你打开思路，看到用ESP32-S3这样的物联网芯片，结合巧妙的硬件和软件设计，能做出多么有趣和实用的设备。