☕ La Marzocco 旋钮控制器

固件版本 v2.4.1 | ESP32-S3 | LVGL 8.4 | 360×360 圆形触屏

一、概述

La Marzocco 旋钮控制器是一款专为 La Marzocco 咖啡机（MICRA / MINI / GS3等型号）设计的智能圆形触屏旋钮控制面板。它通过 BLE 蓝牙和 云端 WebSocket 双通道与咖啡机通信，实现萃取参数设定、实时状态监控、萃取计时、预设管理等功能。

控制器内置 Wi-Fi 模块、Web 配置门户、触屏手势交互和旋钮编码器，无需手机 App 即可独立完成所有操作。

设计理念：云端权威数据（brewingStartTime、extractionSeconds）+ BLE 近场直连 + 旋钮直觉操作 = 专业咖啡师的最简工作流。

二、硬件规格

项目	参数
主控芯片	ESP32-S3
屏幕	360×360 圆形 TFT（ST77916 驱动）
触控	CST816S 电容触控（手势识别）
输入旋钮	正交编码器 + 触觉反馈马达 + LED 光环
无线	Wi-Fi 802.11 b/g/n（2.4GHz）+ BLE 5.0
存储	16 MB Flash + 8 MB PSRAM
电源	USB-C 供电，内置电池监控

三、UI 操作

3.1 屏幕布局

顶部状态栏：Wi-Fi 图标、BLE 图标、加热图标、缺水警报、USB 图标、电池图标
主卡片（280×192）：显示当前字段的标题、设定值、提示文字、实时温度
底部页面点：指示当前所在页面（最多 8 页）
加热圆环：围绕屏幕的环形进度条，显示预热剩余时间

3.2 手势操作

屏幕	手势	操作
主屏幕	左滑/右滑	切换字段页面
主屏幕	上滑	打开 Web 设置门户
主屏幕	下滑	打开预设界面
预设界面	上滑	返回主屏幕
设置界面	下滑	返回主屏幕
设置界面	长按	进入隐藏恢复模式
计时器（STICKY）	任意滑动	退出计时器
计时器（CALCULATING）	下滑	强制退出计时器

3.3 旋钮操作

顺时针旋转：增加当前字段值 / 右切换 / 唤醒机器
逆时针旋转：减少当前字段值 / 左切换 / 待机
每次旋转触发触觉反馈振动 + LED 光环闪烁

3.4 颜色体系

颜色	用途
■ 琥珀金 #FFC685	当前焦点标题、加热圆环、Wi-Fi/BLE 活跃、主按钮
■ 米白 #F4EFE7	主数值文字
■ 暖灰 #B7A08B	提示文字、不可用值、非活跃标题
■ 绿色 #73D073	实时温度、萃取计时结果
■ 蓝色 #73C8FF	缺水警报图标

四、字段详解

页面	字段名	显示	范围	步长	通信
1	冲煮锅炉	92.0°C	80.0–103.0°C	0.1/0.5°C	BLE + Cloud
2	预浸泡开启	1.0 s / OFF	0.0–9.0 s	0.1/0.5 s	Cloud
3	预浸泡关闭	2.0 s / OFF	0.0–9.0 s	0.1/0.5 s	Cloud
4	蒸汽锅炉	OFF / 1 / 2 / 3	4 档位	—	BLE + Cloud
5	机器状态	开启 / 待机	2 状态	—	BLE + Cloud
6	称重萃取	剂量1/2/连续	3 模式	—	Cloud
7	BBW 剂量 1	32.0 g	5.0–100.0 g	0.1 g	Cloud
8	BBW 剂量 2	34.0 g	5.0–100.0 g	0.1 g	Cloud

* BBW 字段仅在云端报告机器支持称重萃取时显示

4.1 预浸泡 OFF 功能

当预浸泡开启和关闭均设为 0.0 s 时，逆时针旋到底即可触发 OFF 模式。UI 显示 "OFF"，云端下发 Disabled 指令关闭预浸泡。顺时针旋转可从 OFF 恢复到步长值。

4.2 实时温度显示

在冲煮锅炉页面，设定值下方以绿色显示当前锅炉实际温度（如「实时温度 93.5°C」）。数据来源于 BLE 通信，BLE 离线时隐藏。

4.3 延迟发送机制

连续旋转调节温度、预浸泡时间、BBW 剂量时，系统不会每次旋转都发送指令，而是等待 800ms 无操作后一次性发送最终值。蒸汽档位和待机状态则立即发送。

五、预设系统

预设数量：2–6 个（通过 Web 门户高级设置配置）
预设内容：温度、预浸泡时间、蒸汽档位、BBW 设置
加载预设：下滑进入预设界面 → 旋钮选择 → 点击「加载」
保存预设：调整好参数 → 进入预设界面 → 选择槽位 → 点击「保存」
预设名称：可在 Web 门户自定义（最长 32 字符）

六、萃取计时器

萃取计时器默认关闭，需在 Web 门户中手动启用。

工作原理

萃取开始：云端检测到萃取开始，计时器全屏显示「正在萃取...」
萃取结束：云端返回精确萃取时长，显示为「萃取耗费」+「27 S」
自动退出：15 秒后自动消失，或任意滑动立即退出
连续萃取：在 15 秒显示期间开始新萃取，计时器立即刷新

七、加热显示

默认开启。当机器预热时：

顶部状态栏显示闪电图标
屏幕外围环形进度条显示预热进度
蒸汽锅炉和机器状态页面显示「正在加热剩余 3:45」

可在 Web 门户中关闭此功能。

八、Wi-Fi 设置

首次启动：自动进入设置模式，作为 AP 热点广播
手动进入：主屏幕上滑即可启动设置门户
扫描网络：Web 门户中点击「扫描附近网络」
连接：选择或输入 SSID 和密码，保存后自动连接
验证：屏幕显示 QR 码，手机扫码即可访问设置页面

九、云账户

登录 La Marzocco 云账户后，可在机器列表中选择目标机器
选择机器后，所有云端字段（预浸泡、BBW）变为可编辑
云端 WebSocket 实时推送机器状态和萃取事件
系统时钟通过云端服务器自动校准

十、Web 配置门户

分区	功能
概览	连接状态、局域网地址
控制器	主机名、设备语言（中文/English/Deutsch）
网络	Wi-Fi SSID/密码、扫描、连接
云	账户登录、机器列表、选择机器、BBW 配置
配方	预设编辑、自定义名称
高级	预设数量、温度步长、时间步长、加热显示、远程截图、萃取计时、管理员密码、系统操作
诊断	只读连接状态和调试信息

十一、高级设置

设置项	默认值	说明
预设数量	4	2–6 个，减少时需确认删除
温度步长	0.1°C	旋钮每格调节精度
时间步长	0.1 s	预浸泡时间调节精度
加热显示	开启	控制预热图标/圆环/ETA
远程截图	关闭	开启后可通过 /debug/screenshot.bmp 获取屏幕截图
萃取计时	关闭	开启萃取计时器功能
管理员密码	无	设置局域网访问密码

十二、隐藏恢复模式

进入方式：主屏幕 → 上滑进入设置 → 长按设置卡片

清除网页密码：重置设置门户密码
重置网络：清除 Wi-Fi、云账户、机器选择（保留云端配给和 Logo）
恢复出厂设置：通过 Web 门户执行，清除全部数据并重启

十三、BLE 蓝牙连接

开机自动扫描附近的 La Marzocco 咖啡机（以机器序列号识别）
连接后通过 GATT 特征值读写机器参数（温度、蒸汽、待机状态）
BLE 离线时，温度/蒸汽/待机字段切换为云端通信
实时温度数据仅通过蓝牙采集，如咖啡机处于蓝牙静默状态，需重启激活

十四、多语言支持

设备界面：支持中文、英文、德文（通过 Web 门户切换）
Web 门户：右上角独立的中/英文切换按钮
字体：阿里巴巴普惠体 + Noto Sans SC，3000 常用 CJK 字形

十五、设计架构思维导图

La Marzocco 旋钮控制器 v2.4.1
├── 输入层
│   ├── 旋钮编码器（正交相位 + 触觉反馈 + LED 光环）
│   └── 触屏手势（滑动切换 / 长按恢复）
├── UI 层（LVGL 8.4）
│   ├── 主屏幕 × 8 页（温度 / 预浸泡×2 / 蒸汽 / 待机 / BBW×3）
│   ├── 预设浏览器（加载 / 保存）
│   ├── 设置界面（QR 码 / 恢复入口）
│   ├── 萃取计时器（CALCULATING → STICKY → HIDDEN）
│   ├── 加热显示（图标 + 环形进度条 + ETA 倒计时）
│   ├── 实时温度（绿色）
│   └── 连接状态图标栏（Wi-Fi / BLE / 加热 / 缺水 / USB / 电池）
├── 通信层
│   ├── BLE 直连（NimBLE 协议栈）
│   │   ├── 读：machineMode / boilers / tankStatus / smartStandBy
│   │   └── 写：温度 / 蒸汽 / 待机
│   ├── 云端 REST API
│   │   ├── 认证 / 机器列表 / Dashboard 快照
│   │   └── 预浸泡 / BBW 指令下发
│   └── 云端 WebSocket（STOMP 协议）
│       ├── Dashboard 实时推送
│       ├── 萃取事件（brewingStartTime / extractionSeconds）
│       └── 加热 ETA 更新
├── 业务逻辑层
│   ├── 本地值保护（旋转后 20s 内覆盖云端旧值）
│   ├── 延迟发送（连续旋转 800ms 停歇后一次性提交）
│   ├── 字段可编辑性判断（BLE 认证 / Cloud 在线）
│   └── 预浸泡 OFF 状态机（0.0+0.0 → OFF → CW 恢复）
├── 持久层（NVS）
│   ├── Wi-Fi 凭据 / 云账户 / 机器绑定
│   ├── 预设 × 6 槽位（名称 + 全部配方值）
│   └── 高级设置 / 自定义 Logo / 功能开关
└── Web 配置门户
    ├── 强制门户（Captive Portal 自动跳转）
    ├── 11 个功能分区（Wi-Fi / 云 / 配方 / 高级 / 诊断）
    └── 20+ 个 POST 路由处理器

十六、常见问题

Q: 屏幕中文显示不全或有方框？

当前固件使用原厂字体，部分生僻字回退至 16px 渲染。不影响常用文字显示。

Q: 萃取计时器不出现？

默认关闭。在 Web 门户 → 高级 → 萃取计时中启用。需要 Wi-Fi 连接且已选择云端机器。

Q: 计时器显示 0s？

云端需收到萃取结束消息（lastFlush/lastCoffee）后才能显示结果。如果萃取过程中 WebSocket 断连，计时器会停留在「正在萃取...」直到连接恢复。

Q: 如何关闭预浸泡功能？

将预浸泡开启和关闭界面逆时针旋至 0.0 s，再逆时针一步即进入OFF/关闭状态。

Q: 如何恢复出厂设置？

Web 门户 → 高级 → 恢复出厂设置。或在设置界面长按进入隐藏恢复模式 → 重置网络。

Q: 如何获取控制器 Logo SVG 文件？

在线下载地址：https://mrvautin.com/content/images/2021/01/La-Marzocco-red-logo.svg

下载后通过 Web 门户上传至控制器即可替换屏幕顶部文字标志。