当前位置：首页 > news >正文

2025最新SmartKnob开发指南:从固件烧录到Web Serial交互全流程

news 2026/5/31 14:50:02

你还在为复杂的旋钮控制器开发而烦恼吗？SmartKnob作为一款开源的触觉输入旋钮（Haptic input knob），通过软件定义的终端止动（endstops）和动态定位点（dynamic detents），为开发者提供了高度可定制的交互体验。本文将带你完成从固件烧录到Web Serial交互的全流程，让你快速掌握SmartKnob的开发精髓。

读完本文，你将能够：

了解SmartKnob的核心功能与硬件组成
搭建开发环境并成功烧录固件
通过Web Serial实现与SmartKnob的交互
掌握基本的参数配置与调试技巧

SmartKnob简介

SmartKnob是一个开源输入设备，其核心在于将无刷云台电机与磁性编码器配对，提供闭环扭矩反馈控制，从而动态创建和调整定位点和终端止动的触感。

核心功能

软件定义终端止动：可通过软件配置旋钮的旋转范围限制
动态定位点：模拟物理旋钮的卡点手感，支持动态调整
触觉反馈：通过电机提供精确的触觉反馈
按压检测：使用PCB挠曲和SMD电阻作为应变计实现按压检测
RGB LED环：8个侧发光RGB LED（SK6812-SIDE-A）环绕旋钮
环境光感应：VEML7700环境光传感器实现自动背光调节

硬件组成

SmartKnob的主要硬件组件包括：

240x240圆形LCD（GC9A01），由39.5mm表镜保护
无刷云台电机，带空心轴用于机械和电气连接LCD
ESP32-PICO-V3-02（Lilygo TMicro32 Plus模块）供电
USB-C（2.0）连接器，用于5V电源和串行数据/编程（CH340）
多功能背板，支持4个螺丝或2个3M中号Command条安装

开发环境搭建

准备工作

在开始之前，请确保你已准备好以下工具和材料：

SmartKnob硬件套件
计算机（Windows/macOS/Linux）
USB-C数据线
Git
PlatformIO IDE

克隆代码仓库

首先，克隆SmartKnob的代码仓库：

git clone https://gitcode.com/gh_mirrors/smar/smartknob
cd smartknob

安装依赖

SmartKnob的固件开发基于PlatformIO，因此需要安装相关依赖：

# 安装Python依赖
cd software/python
pipenv install# 安装JavaScript依赖
cd ../js
npm install

固件烧录

固件结构

SmartKnob的固件代码位于firmware/目录下，主要结构如下：

firmware/
├── include/           # 头文件
├── lib/               # 第三方库
│   └── tlv/           # TLV493D传感器库
├── src/               # 源代码
│   ├── main.cpp       # 主程序入口
│   ├── motor_task.cpp # 电机控制任务
│   ├── display_task.cpp # 显示任务
│   └── interface_task.cpp # 接口任务
└── platformio.ini     # PlatformIO配置文件

配置PlatformIO

打开platformio.ini文件，根据你的硬件版本选择合适的环境配置。对于标准的SmartKnob View，使用以下配置：

[env:view]
platform = espressif32
board = esp32-pico-kit
framework = arduino
monitor_speed = 115200
upload_speed = 460800

烧录固件

连接SmartKnob到计算机，执行以下命令烧录固件：

cd firmware
pio run --target upload

烧录成功后，你可以通过串口监视器查看调试信息：

pio device monitor

硬件校准

固件烧录完成后，首次启动需要进行硬件校准。校准过程包括：

电机零位校准
编码器校准
应变计校准

校准过程中，请确保旋钮处于自由状态，不要触摸。校准数据将保存在configuration.cpp和configuration.h文件中，你可以根据需要手动调整参数。

Web Serial交互

SmartKnob支持通过Web Serial协议与计算机进行通信。下面我们将使用官方提供的Web示例来演示如何与SmartKnob进行交互。

运行Web示例

cd software/js/packages/example-webserial-basic
npm start

打开浏览器，访问http://localhost:3000，你将看到一个简单的控制界面。

Web Serial连接步骤

点击界面上的"连接设备"按钮
在弹出的设备选择对话框中，选择SmartKnob设备
点击"连接"按钮建立通信

成功连接后，你可以通过界面控制SmartKnob的各种功能，如调整动态定位点、设置LED颜色等。

核心代码解析

Web Serial交互的核心代码位于software/js/packages/smartknobjs-webserial/src/index.ts中。以下是一个简单的示例，展示如何发送命令到SmartKnob：

import { WebSerialTransport } from 'smartknobjs-webserial';async function connect() {const transport = new WebSerialTransport();await transport.connect();// 设置动态定位点await transport.send({type: 'SET_DETENTS',detents: [0, 90, 180, 270],strength: 50});// 监听旋钮位置变化transport.on('position', (position) => {console.log('旋钮位置:', position);});
}

高级配置

参数配置

SmartKnob的配置参数主要在firmware/src/configuration.cpp和firmware/src/configuration.h文件中定义。你可以修改这些参数来自定义SmartKnob的行为：

DEFAULT_DETENT_STRENGTH：默认定位点强度
DEFAULT_ENDSTOP_STRENGTH：默认终端止动强度
MAX_ROTATION_DEGREES：最大旋转角度
ENCODER_RESOLUTION：编码器分辨率

自定义触觉反馈

通过修改firmware/src/motor_task.cpp文件中的motor_task函数，你可以自定义触觉反馈效果。例如，以下代码片段展示了如何实现一个简单的触觉反馈模式：

void motor_task(void *pvParameters) {// 初始化代码...while (1) {// 读取旋钮位置float position = encoder_get_position();// 根据位置提供触觉反馈if (should_provide_feedback(position)) {motor_set_torque(feedback_strength);vTaskDelay(pdMS_TO_TICKS(50));motor_set_torque(0);}vTaskDelay(pdMS_TO_TICKS(10));}
}