X-Knob 开源项目教程

2026-01-17 08:53:50作者：谭伦延

项目介绍

X-Knob 是一个基于 LVGL UI 框架的力反馈智能旋钮，支持智能家居控制（通过 MQTT）和 Surface Dial（通过蓝牙）。该项目结合了 Smart Knob 和 X-TRACK UI 框架，提供了丰富的旋钮操作模式和用户界面。

主要特性

X-TRACK UI 框架：提供流畅的用户界面体验。
7 种旋钮模式：包括边界限制、棘轮、回弹等模式的组合。
Surface Dial：支持蓝牙连接的 Surface Dial 功能。
按键按压振动反馈：提供物理反馈增强用户体验。
电源管理：包括电池管理和系统深度休眠功能。
MQTT 接入 Home Assistant：实现智能家居设备的控制。

项目快速启动

硬件准备

主控板：ESP32-S3 WROOM-1U-N16R8
屏幕：240x240 圆形 LCD GC9A01
磁编码器：MT6701CT3205
无刷直流电机：602535
锂电池：600mAh

软件环境

开发环境：Arduino IDE 或 PlatformIO
依赖库：LVGL、MQTT 客户端库

代码示例

以下是一个简单的代码示例，展示如何初始化 X-Knob 并连接到 MQTT 服务器：

#include <WiFi.h>
#include <PubSubClient.h>
#include <lvgl.h>

// WiFi 和 MQTT 配置
const char* ssid = "your_SSID";
const char* password = "your_PASSWORD";
const char* mqtt_server = "your_MQTT_SERVER";

WiFiClient espClient;
PubSubClient client(espClient);

void setup() {
  Serial.begin(115200);
  setup_wifi();
  client.setServer(mqtt_server, 1883);
  setup_lvgl();
}

void setup_wifi() {
  delay(10);
  Serial.println();
  Serial.print("Connecting to ");
  Serial.println(ssid);

  WiFi.begin(ssid, password);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }

  Serial.println("");
  Serial.println("WiFi connected");
  Serial.println("IP address: ");
  Serial.println(WiFi.localIP());
}

void setup_lvgl() {
  lv_init();
  // 初始化 LVGL 显示和输入设备
  // ...
}

void loop() {
  if (!client.connected()) {
    reconnect();
  }
  client.loop();
  lv_task_handler();
  delay(5);
}

void reconnect() {
  while (!client.connected()) {
    Serial.print("Attempting MQTT connection...");
    if (client.connect("ESP32Client")) {
      Serial.println("connected");
      // 订阅主题
      client.subscribe("home/xknob");
    } else {
      Serial.print("failed, rc=");
      Serial.print(client.state());
      Serial.println(" try again in 5 seconds");
      delay(5000);
    }
  }
}