FaderBuddy 完全指南:电机推子、固件原理、ESPHome 集成与 I2C 协议一站式深度解析

原创2026-10-24 15:28:341,836 阅读

FaderBuddy 完全指南:电机推子、固件原理、ESPHome 集成与 I2C 协议一站式深度解析

FaderBuddy 是一款即插即用的电机化推子(motorized fader)控制板,只需 2 根 I2C 线加电源,就能让 Behringer MF60T 60mm 电机推子变成双向智能控件:读取推子位置、驱动推子移动到指定位置、提供触觉反馈(线性档位感),并原生支持 ESPHome / Home Assistant 集成与 I2C 远程固件升级。本文带你一站式看懂它的硬件设计、固件状态机、8 层(Layers)架构和 I2C 协议,最后给出完整的接入教程。

一、FaderBuddy 是什么?为什么值得入手 🎛️

FaderBuddy 解决的是一个很实际的问题:想在家装或合成器里加一个"会自己动的推子",传统做法要自己画电机驱动(H 桥)、自己写 PID 闭环控制,接线繁琐且极易翻车。FaderBuddy 把这些全部塞进一块小 PCB 里:

  • 双向控制:人推 → 主机读到位置;主机下发 → 电机推子跑到目标位置
  • 即插即用:多块板可以直接用排针"首尾串接",所有推子只共享 2 根 I2C 信号线
  • 零控制算法负担:闭环电机控制、摩擦前馈、自校准全部由板载 MCU 完成
  • 触觉反馈:顺滑模式、磁性端点(吸附 0%/100%)、1–15 个可配置档位(detents),相当于"线性版旋钮"
  • I2C 升级固件:不用 UPDI 烧录器,Home Assistant 里点一下"安装"即可完成升级

💡 核心思路:让 ESP32(主机)只负责"说目标位置",实时的电机闭环控制交给板载 ATtiny1616 独立完成——这也是整个项目最聪明的架构决策。

二、硬件设计解析:一块小 PCB 里有什么

2.1 关键元器件

部件 作用
ATtiny1616(20MHz) 板载 MCU,负责闭环电机控制、电容触摸检测、I2C 从机
DRV8837 电机驱动 H 桥驱动 MF60T 推子电机,PWM 控制
电位器位置反馈 ADC 采样推子实际位置,实现闭环
STEMMA QT / QWIIC 接口 兼容 Adafruit 生态,方便接入其他设备
0.1" 排针 支持相邻 FaderBuddy 板直接链式堆叠(18/19mm 间距)
地址跳线 A0–A2 3 个焊盘跳线,把 I2C 地址从 0x20 改到 0x20–0x27
电源 / 调试 LED 状态指示

完整的 KiCad 设计文件在 electronics/ 目录,原理图与 PCB 主文件为 fader_buddy_main.kicad_sch 和 fader_buddy_main.kicad_pcb。想自己打板的话,ABOUT_PCB_FABRICATION.md 给出了在 JLCPCB 下单、拼板(kikit 拼板脚本见 kikit_faderbuddy_tabs.py)和装配的完整流程。

2.2 接线:5 根线搞定

最常见的 3.3V MCU(如 ESP32)接法是 5 根线:

主机 FaderBuddy 说明
5V Vmot 电机电源,建议 5V
3.3V Vio 逻辑电源,必须与 I2C 总线电平一致
GND GND 地
SDA SDA I2C 数据(板载上拉)
SCL SCL I2C 时钟(板载上拉)

⚠️ 避坑提示:板上有一个 Vmot ↔ Vio 焊接桥(solder bridge)。如果你桥接了它让 5V 同时供电给逻辑和电机,之后千万别再把它用于 3.3V IO 环境——桥接状态会把 5V 灌进 3.3V IO,可能烧毁主机。

2.3 I2C 地址怎么设

默认地址是 0x20。多块板并联时,用板上的 A2/A1/A0 三个跳线焊盘改地址(跳线 = 置 1):

地址 A2 A1 A0 地址 A2 A1 A0
0x20 ✗ ✗ ✗ 0x24 ✓ ✗ ✗
0x21 ✗ ✗ ✓ 0x25 ✓ ✗ ✓
0x22 ✗ ✓ ✗ 0x26 ✓ ✓ ✗
0x23 ✗ ✓ ✓ 0x27 ✓ ✓ ✓

2.4 触摸按键帽(可选但加分)

FaderBuddy 用电容触摸检测"用户在不在推推子",这带来两个好处:电机移动途中用户一触摸就立即让位(不会"跟人抢推子")、还能识别双击手势。触摸需要导电的推子帽,官方建议用导电 PLA 3D 打印(高电阻反而更适合做触摸面),或购买现成的双色导电推子帽。没有触摸帽也能正常工作,只是失去"让位"和双击功能。

三、固件原理:状态机 + 闭环电机控制

ATtiny1616 固件是整个系统的"大脑",源码在 firmware/src/,核心文件:

  • main.cpp — 模式状态机、控制律、触觉、触摸、I2C 从机
  • motor_control.h — 电机驱动原语与所有调参常量
  • motor_cal.cpp — 自校准与电机特性测量

3.1 五种工作模式

固件用一个状态机仲裁"远程控制"和"本地用户输入":

模式 含义 关键行为
REMOTE_MOVEMENT(0) 电机正在去目标位置 触觉关闭;触摸 >50ms 立即让位;到点后稳定 >300ms 转 IDLE;8 秒超时且误差大才报错
INPUT_ACTIVE(1) 用户正在推 触觉引擎工作;忽略所有远程位置指令;1 秒无操作转 IDLE
INPUT_IDLE(2) 静止待命 电机断电;等新指令或新触摸
ERROR(3) 移动超时失败 清除错误后才能恢复
SELF_CALIBRATION(4) 自校准 电机驱动到两端,测量电位器范围并测量电机特性

3.2 闭环控制律:为什么推子又稳又安静

MF60T 电机被实测为一个"带摩擦死区的速度源":低于起步(breakaway)占空比完全不动,越过之后速度突然跳升(Stribeck 效应)。针对这个特性,ABOUT_MOTOR_CONTROL.md 详细解释了固件的级联控制设计:

  • 外环位置环:误差 → 目标速度(误差越小目标速度越低,提前"收油"滑行到位,杜绝过冲)
  • 内环速度环:实际跟踪目标速度,抑制振荡
  • 摩擦前馈:起步占空比 + v_ref/k,直接给出"刚好能走"的驱动力
  • 静摩擦爬坡:卡住时缓慢加力脱困,有上限防止堵转过载
  • 背隙补偿天花板:换向起步时限力,慢慢放开,消除皮带松动的"咔哒"冲击
  • 自校准电机建模:每次自校准会实测本台推子的起步占空比、速度/占空比斜率 k、Stribeck 跳变速度,并据此推导前馈、速度环增益、死区——不同摩擦/扭矩的推子都能稳定收敛,而不是对着某一台调参

想深入这块的"控制律为什么长这样",强烈建议读 firmware/ABOUT_MOTOR_CONTROL.md。

3.3 自校准

首次使用或感觉位置不准时,触发一次自校准:推子自动跑到两端标定电位器 ADC 范围,并顺带完成上面说的电机特性测量。结果存入 EEPROM,以后每次上电直接用。校准内容还能通过 REG_MOTOR_CAL(0x12)寄存器读出,只用一个 I2C 主机就能诊断单台推子的电机参数。

四、I2C 协议解析:主机视角的寄存器地图

协议定义在 firmware/src/shared/i2c_data.h(当前 v5),同一份头文件被固件、ESPHome 组件、产线测试工具、WebHID 演示工具四处共享,改协议时要保持同步。关键概念:

  • 层寻址寄存器:REG_LAYER_TARGET(0x0E,目标位置)、REG_LAYER_HAPTIC_CONFIG(0x0F,触觉配置)需要"寄存器 + 层索引"两步访问
  • STATE 寄存器(0x01):32 位打包寄存器,包含模式、当前层索引、触摸状态和若干 nonce
  • Nonce(2 位计数器):区分"用户本地输入"和"远程指令的echo",解决双向控制下的延迟歧义
  • 可选速度字节:LAYER_TARGET 支持第 4 字节(0–255,255=全速)限制移动速度,三字节写入完全向后兼容
  • REG_FW_VERSION(0x11):打包的 (major<<8)|minor,主机靠它做特性检测
  • REG_ENTER_BOOTLOADER(0x10):带魔数 payload,命令应用进入 I2C 引导加载程序
  • 调试寄存器(0xF0–0xF2):仅在编译 DEBUG_DRIVE 时存在,生产固件中不存在

五、8 层(Layers)架构:一个推子,八个身份 🎭

这是 FaderBuddy 最有特色的功能:每个推子有 8 个虚拟层(0–7),每层独立保存位置与触觉配置。

典型场景——一个推子同时管"客厅灯光亮度"和"风扇档位":

  • 层 0 = 亮度,触觉设为 smooth(顺滑)
  • 层 1 = 风速,触觉设为 4 档位(关/低/中/高)

切到层 1 时,推子自动滑回上次的风速位置,用户能感受到 4 个"咔哒"档位。还有两个贴心的细节:

  1. 延迟切换:用户正在推推子时收到切层请求,固件会等用户松手后再切换,绝不打断操作
  2. 非活动层写入:即使当前在层 0,也可以远程改写层 1 的位置——下次切回来时自动恢复

完整原理与两灯控制示例见 ABOUT_LAYERS.md。

六、ESPHome 集成实战:几行 YAML 接入 Home Assistant 🏠

官方 ESPHome 组件源码在 esphome/components/fader_buddy/,包含完整示例 esphome/examples/multi-fader-display.yaml(ESP32-S3 + LVGL 显示屏、三个推子)。

6.1 最小配置

external_components:
  - source:
      type: git
      url: https://gitcode.com/gh_mirrors/fa/FaderBuddy.git
      ref: master
    components: [fader_buddy]

i2c:
  sda: GPIO8
  scl: GPIO9
  scan: true   # 启动时扫描,确认 0x20 被识别

fader_buddy:
  - id: my_fader
    address: 0x20
    update_interval: 10ms
    layer_haptics:
      - layer: 0
        mode: smooth
        default_speed: 120
    on_manual_move:
      then:
        - lambda: |-
            // x = 位置 (0-255),layer = 当前层
            id(living_room_light).turn_on(
              brightness=static_cast<float>(x) / 255.0);

6.2 四个触发器 + 常用动作

触发器 何时触发 回调参数
on_manual_move 用户手动推动(推荐) x=位置, layer=当前层
on_touch_change 触摸/释放 x=触摸状态
on_double_tap 双击推子 layer
on_raw_position_update 任何位置变化(含电机移动中) x=位置, layer

常用动作:fader_buddy.remote_move_to(含可选 speed: 0-255)、fader_buddy.set_active_layer(切层,推子自动回位)、fader_buddy.set_layer_haptic_config(动态改触觉)、fader_buddy.run_self_calibration(触发自校准)。

6.3 双向同步小技巧

"灯光亮度变化 → 推子跟着动"只需再加一个 homeassistant 传感器监听亮度并调用 remote_move_to,完整示例在 ABOUT_ESPHOME_INTEGRATION.md 的"Light Brightness Control"一节。

七、I2C 远程固件升级:免烧录器的 Bootloader

这是 FaderBuddy 的一个隐藏杀手锏:固件里内嵌了一个 I2C 引导加载程序(bootloader),住在 ATtiny1616 的硬件 boot 区——CPU 在硬件层面永远无法改写 boot 区,所以坏应用也变不刷坏板子,恢复路径永远保留。

工作原理(详见 ABOUT_I2C_BOOTLOADER.md):

  1. 主机写 REG_ENTER_BOOTLOADER + 魔数 → 应用复位进 bootloader
  2. 擦除 → 分帧流式写入新镜像(每帧带 CRC16)→ 全镜像 CRC 校验 → RUN_APP
  3. bootloader 与应用使用同一 I2C 地址,读 0x00 寄存器返回 0xB0 标记时说明正停留在 bootloader

ESPHome 侧的体验:每台推子自动出现在 Home Assistant 里成为一个 Firmware 更新实体,带进度条,点"Install"即可——组件在编译时把官方固件镜像嵌入 ESP32,更新在 loop() 里切片执行,不阻塞 WiFi。注意:更新永远不自动执行,且固件 1.3 之前的老板需要一次性 UPDI 刷写才能解锁 I2C 升级。

万一刷了个坏应用连 I2C 都不应答,还有一条硬件逃生门:复位瞬间把测试点 TP5 短接到地,bootloader 会强制驻留等你重新刷写。

八、项目结构与上手路线 📦

目录 内容
electronics/ KiCad 原理图、PCB、拼板脚本、JLCPCB 导出
firmware/ ATtiny1616 固件(PlatformIO),含 bootloader 与自校准
esphome/ ESPHome 自定义组件 + 完整示例配置
software/mcp2221-webhid/ 浏览器 WebHID 调试工具(配合 MCP2221 USB-I2C 桥)
production_tools/programAndTest/ ESP32 产线测试工装
ci/ PCB 导出 / 固件打包自动化脚本

新手推荐路径:

  1. 读 README.md 了解全貌 → 按 ABOUT_UPDATING_FIRMWARE.md 用 UPDI Friend 首刷固件
  2. 按 ABOUT_ESPHOME_INTEGRATION.md 接上 ESP32,先跑通单推子亮度控制
  3. 学 ABOUT_LAYERS.md 配置多场景层
  4. 有兴趣再深挖 firmware/ABOUT_MOTOR_CONTROL.md(控制律)和 ABOUT_I2C_BOOTLOADER.md(升级机制)

没有烧录器想先玩玩协议?software/mcp2221-webhid/ 提供了一个纯浏览器调试界面:实时位置监控、触摸诊断、层切换、直接读写 I2C 寄存器,是学习协议的好帮手。

九、常见问题速查(Troubleshooting)

症状 处理
I2C 扫描找不到推子 查 5 根线接线;确认地址跳线设置;链路上两块板地址相同会"一乱一哑",数地址而不是数板子
推子方向反了 配置里加 invert: true
指令位置不到位 触发 fader_buddy.run_self_calibration 重新校准
双向控制时推子"回放"你的操作 Zigbee 等慢设备会排队下发旧亮度,用 value_change_min_interval: 100ms 限流
状态显示 Bootloader - no application 直接安装 Firmware 更新即可恢复
老固件报 Incompatible I2C protocol version 1.3 之前的固件需一次性 UPDI 刷写,无法走 I2C 升级

更多排查细节见 ABOUT_ESPHOME_INTEGRATION.md 的 Troubleshooting 章节。


FaderBuddy 用"板载实时闭环 + 极简 I2C 寄存器 + 固件托管层"三层架构,把电机推子从"DIY 重灾区"变成了真正即插即用的智能家居控件。配合 ESPHome 组件,从接线到 Home Assistant 里看到推子实体,只需要一个下午。祝你玩得开心,推得顺手!

登录后查看全文
FaderBuddy