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

优质文章学习记录

— 14 min read

立创开源智能家居键盘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、定位板、轴体、键帽、旋钮模块和外壳。

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

  1. PCB厚度：
    • 键盘主PCB：1.6mm
    • 屏幕和电机驱动板PCB：1.0mm（如果使用3205B电机版本，则为1.6mm）
    • 定位板（固定轴体的金属/塑料板）：1.5mm
  2. 旋钮电机二选一：
    • 方案A：2804云台电机 + 径向磁铁（外径10mm，内径6.3mm，厚度2mm）。电机通过一颗 M2.5*27mm的铜柱焊接固定。
    • 方案B：3205B去限位版云台电机。这个版本不需要额外的径向磁铁，固定铜柱为 M2.5*2mm。
    • 两种电机性能有差异，原作者提供了两种设计文件，任选一种即可。
  3. 物料获取：所有电路板设计文件（.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的配合。

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

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

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

4.1 获取资源

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

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

4.2 烧录与配置步骤

  1. 硬件焊接与组装：按照BOM表采购元件，焊接PCB，并按照爆炸图组装所有结构件。特别注意电机和磁铁的安装。
  2. 烧录固件：
    • 使用USB线连接键盘的Type-C接口到电脑。
    • 按住键盘上的“Boot”按钮（或短接PCB上的进入下载模式的触点），再按一下“Reset”按钮，使ESP32-S3进入下载模式。
    • 使用乐鑫官方的flash_download_tool或esptool.py工具，将下载好的.bin固件文件烧录到芯片的0x0地址。
  3. 首次使用与配置：
    • 烧录完成后，键盘重启。用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这样的物联网芯片，结合巧妙的硬件和软件设计，能做出多么有趣和实用的设备。

Read more

用 Python 搭建本地 AI 问答系统：避开 90% 新手都会踩的环境坑

用 Python 搭建本地 AI 问答系统：避开 90% 新手都会踩的环境坑

欢迎文末添加好友交流，共同进步！ “ 俺はモンキー・D・ルフィ。海贼王になる男だ！” * 前言 * 一、整体架构概览 * 二、新手踩坑分布图 * 三、环境搭建：最容易翻车的第一步 * 3.1 用虚拟环境隔离，别污染全局 * 3.2 PyTorch 安装：版本对齐是关键 * 3.3 依赖管理：用 requirements.txt 锁定版本 * 四、模型下载：别让网络毁了你的心情 * 4.1 使用 Ollama 管理本地模型（强烈推荐） * 4.2 用 Python 调用 Ollama * 五、搭建 RAG 问答系统 * 5.
小白也能玩 OpenClaw？ToDesk AI桌面助手ToClaw 把门槛打到了零

小白也能玩 OpenClaw？ToDesk AI桌面助手ToClaw 把门槛打到了零

一、开篇 最近"小龙虾"彻底火出圈了。打开抖音、刷刷小红书，满屏都是 OpenClaw 的教程、测评和安装实录。更夸张的是，有人专门上门帮人部署，甚至有公司门口排起了长队——就为了装一只"龙虾"。 这波热度不亚于当年 ChatGPT 刚出来的时候。但热闹背后，有一个问题没人说清楚：这么多人在排队，到底在排什么？排的是环境配置、是服务器、是 API Key、是一堆看不懂的命令行。原生 OpenClaw 能力确实强，但它本质上是一个开源框架，想真正跑起来，你得先过技术这关。对普通用户来说，光是部署这一步，就足够劝退了。 所以问题来了——龙虾这么香，普通人就真的没办法吃到吗？ 还真不一定。ToDesk 悄悄做了一件事，把这只龙虾"

Stable Diffusion AIGC 视觉设计实战教程之 09-ControlNet 插件

ControlNet 插件 ControlNet 概述 ControlNet（控制网）是由 lllyasviel 团队于 2023 年提出的神经网络架构，核心是为了解决在 Stable Diffusion 中如何让图像生成变得更加可控的问题，是 Stable Diffusion 迈向工业化的非常重要的一步。 ControlNet 通过预处理器提取参考图中的姿态、深度、边缘等结构信息，再由 ControlNet 模型转换为检查点模型能够理解的生成条件，让生成图像精准遵循参考图的布局与结构，彻底解决生图结构失控的痛点，是 Stable Diffusion 中实现精准控图的核心插件。 ControlNet 插件的应用场景： * 插画创作：基于线稿生成高精度彩色插画，保留线条构图。 * 角色设计：基于姿势参考图生成指定动作的角色形象，如游戏角色战斗姿势等。 * 建筑可视化：根据图纸生成写实风格的建筑效果图。 * 3D 模型辅助生成：根据深度图、法线图控制生成图像的空间立体感，辅助 3D 建模纹理绘制。 * 摄影修图：
从 OpenClaw 到 ToClaw：AI 代理网关的产品化之路

从 OpenClaw 到 ToClaw：AI 代理网关的产品化之路

定位说明：这是一篇偏“体验与选型思路”的横测笔记，不是参数党跑分，也不是安装教程。内容基于我对产品定位与常见使用路径的理解，公测策略与功能细节可能会随版本变化。 01｜OpenClaw 是什么？能做什么？ OpenClaw 可以理解为一种“AI 代理（Agent）网关/中枢”：你在聊天界面下指令，它会调用模型能力并配合工具，去做更接近“完成任务”的事情，而不是只聊天。它强调可扩展（技能/插件）、可接入多渠道、可在你自己的设备上运行等方向。 你能用 OpenClaw 做什么（偏通用能力） * 在聊天软件里接收任务、输出结果，并尽量保持持续记忆与上下文（取决于你的配置与使用方式） * 通过工具/技能扩展能力：文件读写、浏览器自动化、系统命令、定时任务、接入第三方服务等（不同发行与生态会有差异） 但现实门槛也很明显 * 自部署往往需要 Node.js