工程笔记，按时间留下可追溯的现场记录。
围绕真实项目里遇到的问题写成短文：STM32、RT-Thread、Flutter、部署链路和联调细节都按项目归档。
项目索引
最近更新
从 RT-Thread 迁移到 Zephyr：API 对照与实战
Mill 控制器固件从 RT-Thread 迁移到 Zephyr 的完整记录：线程/互斥锁/消息队列/信号量/看门狗 API 对照表、K_THREAD_DEFINE 静态线程、HAL 到 Zephyr 驱动迁移、业务模块命名统一、初始化顺序调整。
Zephyr NVS：配置持久化与 HMAC 鉴权
Mill 项目用 Zephyr NVS 子系统持久化配置镜像和诊断快照：storage_partition 4KB 分区、配置 CRC16 校验、V1/V2 诊断快照兼容加载、HMAC-SHA256 鉴权（PSA Crypto + cJSON）、设备密钥从 WSL 私有配置注入。
Zephyr LittleFS VFS：从裸 lfs API 到 VFS 集成
Mill 项目 Zephyr 侧的 LittleFS 集成：SPI NOR DTS 节点、FS_LITTLEFS_DECLARE_DEFAULT_CONFIG、VFS API 替代裸 lfs API、K_MSGQ_DEFINE 异步日志队列、K_THREAD_DEFINE 静态线程、K_SEM_DEFINE 初始化同步、按天日志轮转与云端上报。
Zephyr 原生 Modbus：主站与 RAW 模式从站
Mill 项目用 Zephyr 原生 Modbus 库替代 nanomodbus：DTS modbus-serial 节点配置主站（USART2 + de-gpios=PD7）、RAW ADU 模式从站（USART3 三协议复用）、user_callbacks 桥接 DR154 寄存器、BusService 互斥锁串行化多线程总线访问。
SMP-over-MQTT：Zephyr 自定义 smp_transport 传输
在 Zephyr 中注册自定义 smp_transport，通过 USART3 + RS485 + DR154 DTU 传输 SMP CBOR 帧。包含 COBS 编解码、USART3 三协议时分复用状态机路由器、RS485 DE 控制时序、JSON 帧工作队列延迟解析、MCUmgr OTA 状态钩子。
MCUboot 集成：A/B 槽位与镜像确认
Zephyr sysbuild 双镜像构建、imgtool 自动签名、Flash 分区布局（mcuboot 64KB + slot0/slot1 各 220KB）、boot_write_img_confirmed 确认机制、防降级、MCUmgr 镜像管理配置、OTA 状态钩子。
Zephyr WSL 跨系统构建：Windows 写码、WSL 构建、Windows 烧录
Mill 项目的 Zephyr 构建工作流：Windows 侧 git push → WSL 侧 git pull + west sysbuild → 构建产物复制回 Windows → J-Link Commander 烧录。包含 build-config.psd1 配置、私有密钥注入、生产构建分离、日志记录。
Zephyr 自定义 Board：STM32F103ZE 的 DTS 配置
在 Zephyr 中为 STM32F103ZE 自定义 Board：文件结构、DTS 时钟树（HSE 8MHz × PLL9 = 72MHz）、USART1/2/3 三串口分工、RS485 DE 引脚、TIM2/3/4/8 流量计、SPI2 外接 NM25Q128 16MB NOR Flash，以及 Flash 分区布局（mcuboot/slot0/slot1/scratch/storage）。
Inno Setup 安装包：.NET Desktop Runtime 检测与静默安装
OTA 桌面工具的 Inno Setup 安装包工程：.NET Desktop Runtime 10 注册表+文件系统双重检测、静默安装+修复回退双策略、20秒轮询等待、退出码 0/3010/1641 处理、[Code] 段 Pascal Script 实践。
Docker 小内存 VPS 部署：三服务编排与 MySQL 调优
Mill 系统的 Docker Compose 部署：MySQL 8.4 小内存调优（64M buffer pool）、Mosquitto 2 TLS 8883、Node.js API 内网通信，使用 Docker profiles 分离部署组合，环境变量强制校验敏感配置。
Nginx 反向代理：API + SCADA + WebSocket + 登录限速
Mill 系统 Nginx 配置解析：SCADA 静态服务 auth_basic 保护与 SPA 回退、静态资源 immutable 缓存、API 反向代理、登录限速 5r/m 防暴力破解、WebSocket /ws/live 长连接代理、Certbot SSL 证书。
micro-ecc 椭圆曲线固件签名：STM32F1 上的 ECDSA-P256 实现
在 STM32F1 上集成 micro-ecc 库实现 ECDSA-P256 固件签名验证：签名清单 50 字节结构设计、设备端公钥嵌入、SHA256+uECC_verify 验证流程、.NET 侧签名工具的三子命令、与 imgtool 工具链的配合。
Flutter 依赖注入与路由架构：Provider DI 树 + GoRouter 状态保持
Mill 客户端的 Flutter 架构：MultiProvider 装配完整DI树、.value vs create 生命周期区分、Mock模式切换、远程配置引导启动、GoRouter StatefulShellRoute 五Tab状态保持、登录态路由重评估、生命周期管理。
MySQL 数据库设计：10张表的工业物联网 Schema
STM32 Mill 控制系统的数据库设计：程序化建表、JSON列+索引列混合策略、组态布局draft/published双份设计、版本快照回滚、操作审计三索引，覆盖遥测、告警、配置、组态、审计五大领域。
GitHub Actions CI/CD：VPS 部署的完整流水线
两个GitHub Actions workflow覆盖后端API和前端SCADA的部署：pnpm检查、SSH密钥注入、VPS运行时备份、rsync上传、Nginx配置热重载、docker compose重建、容器健康轮询、HTTPS端到端验证。
W25Q128 + LittleFS + 异步日志：Flash 持久化全栈实现
STM32F1 外接 W25Q128 SPI Flash 的日志持久化全栈：SPI 驱动、LittleFS 块设备适配层（544B RAM）、磨损均衡、空白分区检测保护、DataLogger 按天日志轮转、LogService 异步消息队列，以及 Flash 长操作期间喂狗策略。
SMP 升级协议：从零实现 Zephyr mcumgr 串口/MQTT 升级
在.NET侧从零实现Zephyr mcumgr的SMP协议：8字节Header、CBOR payload、COBS帧分隔、状态机帧读取器、串口与MQTT双传输路径，以及升级流程编排和踩坑记录。
RT-Thread 多线程任务架构：三线程协作的工业控制器内核
STM32F1 + RT-Thread 的三线程架构设计：维护线程、采集线程、日志线程的职责拆分，互斥锁保护配置快照、邮箱上报健康标志、消息队列异步持久化日志，以及继电器规则引擎、DI去抖、现场设备故障冷却、A/B槽位升级确认等关键业务逻辑。
Flutter 工程杂项与项目回顾：主题、日志、Result 类型与开发历程
PipeMonitor 系列收尾篇，合并 Material 3 主题、Logger 配置、Result 类型三个薄主题，并回顾 Archive/Plans 下的开发历程与多版本备份组织方式。
跨端时间戳处理：设备 uptime 与服务端墙钟时间的对齐
梳理 PipeMonitor 中 STM32 uptime、Node.js 服务端 received_at 与 Flutter 本地时区三套时间戳的语义差异、转换链路与工程取舍。
用户登录与设备控制 UI：两态切换、表单校验与命令下发反馈
拆解 PipeMonitor Flutter 端用户页两态切换、Form 校验、BottomSheet 周期选择、二次确认对话框与控制页 post-frame SnackBar 反馈的实现细节。
报警列表 UI：FilterChip 筛选 + SliverList 分隔 + 未读徽章
拆解 PipeMonitor Flutter 端报警页：Consumer 响应式绑定、CustomScrollView + SliverList.separated 滚动列表、FilterChip 严重等级筛选、_AlarmTile 展开收起与空态处理。
分阶段部署方法论：三阶段切分让小项目安全上线
PipeMonitor 用 manual-first-stage、private-mqtt-stage、mysql-stage 三阶段切分上线，借助 Docker Compose profiles 按需启用服务，每阶段都有明确 Out Of Scope、验收清单和回退路径。
PT100 温度编码解析：从 16 位原始值到 0.1℃ 有符号整数
详解 PT100 模块 16 位原始值的符号位编码、故障哨兵检测与多通道批量解析的完整数据流。
GitHub Actions 部署 Flutter Web：从触发到 rsync 上线
PipeMonitor 的 Flutter Web 通过 GitHub Actions 自动构建并以 rsync 部署到 VPS 子路径，覆盖 paths 过滤、并发控制、SSH 注入、远程目录校验等关键细节。
Flutter 单元测试实践：从刻度算法到 HTTP/WS 两态命令
结合 PipeMonitor 的四个真实测试文件，讲清单测的组织方式、命名规范、setUp/tearDown 用法，以及刻度边界、旧 payload 兼容、Timer.run 模拟 WS 延迟 ack 等技巧。
Flutter 依赖注入树与 GoRouter 路由设计：从 MultiProvider 到 StatefulShellRoute
拆解 PipeMonitor Flutter 端的依赖注入装配、.value 与 create 的生命周期取舍、StatefulShellRoute 四 Tab 栈保留与登录态驱动的路由重建。
Nginx 反向代理实战：缓存、限流、WebSocket 与 HTTPS
管道监控系统公网入口的 Nginx 配置实录：Flutter Web 缓存策略、登录限流、WebSocket 反代、Basic Auth 与 Certbot HTTPS。
从 H562 到 F103VC：一次降级背后的工程取舍
讲述管道监控系统从 STM32H562 迁移到 STM32F103VC 的引脚、显示、存储与线程模型重构。
RS485 串口驱动细节：DE 控制、TC 等待与错误标志清除
梳理 PipeMonitor 上行链路 USART3 + MAX485 驱动的关键实现：方向脚保护延时、TC 等待、RXNE 屏蔽、F1 错误标志清除顺序与 JSON 完整性检测。
MySQL 存储层：自动建表、历史幂等性与游标分页
详解 PipeMonitor API 的 MySQL 存储层设计：连接池有限次重试、启动自动建表、三元唯一索引去重、uptime 时间戳语义与 before_id 游标分页。
Flutter 跨平台文件保存：Web/Mobile/Desktop 三端实现
详解 PipeMonitor 的跨平台文件保存方案：条件导入、Web Blob 下载、Android Downloads 目录推导、三级回退、UTF-8 BOM 与 CSV 多字段合并导出。
fl_chart 历史曲线绘制：分度值预设与可拖动视口
基于 fl_chart 实现 PipeMonitor 历史曲线页，覆盖 X 轴分度值预设、1/2/5 × 10ⁿ Y 轴刻度算法、可拖动视口与多通道共用时间轴。
远程命令处理与延时复位：ack 先落线再执行
详解 PipeMonitor 的远程命令处理机制：reboot 和 set_upload_period 的执行流程、延时复位保证 ack 先到达云端、以及命令序号回显的请求-响应匹配。
Mosquitto MQTT 私有 Broker 与 ACL：设备到云端的消息通道
详解 PipeMonitor 的 Mosquitto MQTT Broker 配置：Topic 命名规范、ACL 权限控制、设备认证，以及 JSON 行分隔的上行消息格式。
KiCad 硬件设计：双 RS485 传感器板的原理图与物料清单
详解 PipeMonitor 的 KiCad 硬件设计：STM32F103VCT6 主控、双 RS485 通道（传感器 + 上行）、USB-C + CH340C 串口、电源保护，以及设计决策备忘。
LVGL 嵌入式 UI 设计：320x480 屏幕上的管道监控仪表盘
详解 PipeMonitor 基于 LVGL v9 的 LCD 界面设计：卡片式布局、流量主视觉进度条、告警状态栏、心跳脉冲动画，以及 flush 回调与局部刷新策略。
Windows C# Modbus 桌面调试工具：WPF 串口管理与 NModbus 封装
详解 PipeMonitor 配套的 Windows WPF 桌面调试工具：COM 口自动识别、Modbus RTU 主站轮询、压力/流量传感器寄存器解析，以及 NModbus 超时重试机制。
Docker 容器化部署与 Node.js 后端：从 MQTT 到 REST API
详解 PipeMonitor 的 Docker Compose 三容器部署架构、Node.js API 服务的 JWT 鉴权、WebSocket 实时推送，以及 MQTT 与 REST 的双向数据通道。
Flutter 应用数据模型与 API 设计：从 JSON 到 UI 的数据流
详解 PipeMonitor Flutter 端的数据模型设计、Measurement 帧解析与缺值补齐、API 服务抽象层，以及 CSV 导出与文件保存的跨平台实现。
上行 JSON 协议与手写解析器：从传感器到云端的帧格式
详解 PipeMonitor 的 JSON 上行帧格式设计、newlib-nano 浮点格式化兼容方案、valid 位图机制，以及下行命令的手写极简 JSON 解析器。
项目改造历程：从「有人云」到自建 MQTT 平台
STM32 磨坊系统从商业物联网平台迁到自建 MQTT + API 服务器的完整历程：G780s 边缘 JSON 组包、服务端字段映射、Flutter 客户端适配，以及 18 项任务清单的推进记录。
OTA Bug 分析：Bootloader 模式下 A/B 槽位选择的陷阱
深入分析一个隐蔽的 OTA 升级 Bug：为何 Bootloader 模式下刷 App_A.bin 会"假成功"？根因在于 Bootloader 自行决定目标槽位，上位机的镜像选择并未约束写入目标。
软件发布与代码签名：Inno Setup + Authenticode
.NET WPF 桌面应用的发布流程：dotnet publish 生成自包含程序、Inno Setup 打包安装器、静默安装 .NET Runtime、Authenticode 代码签名，以及 PowerShell 一键发布脚本。
FUXA 本地 SCADA 适配器：Node.js 桥接后端 API
在 Windows 本机运行 FUXA Electron 组态平台，通过 Node.js 适配器桥接 mill-api 后端，实现实时遥测标签、继电器双模控制、本地告警评估，以及一键启动脚本。
Flutter 跨平台 CSV 导出：条件导入与三级回退
Flutter 历史传感器数据导出功能：11 字段秒级去重 CSV 生成、dart:html / dart:io 条件导入实现跨平台文件保存、Android FileProvider 授权，以及三级回退策略。
网页 SCADA：Vue3 + Konva 实时监控前端
基于 Vue 3 + TypeScript + Konva 的工业 SCADA 前端：11 种可编辑组态元件、WebSocket 实时数据驱动、大屏模式、告警面板、继电器控制，以及完整的工艺流程图布局。
OTA 工具架构重构：从单体 WPF 到五层架构
.NET/WPF 桌面应用的架构演进：从单项目承载全部职责，到 Models/Protocols/Core/ViewModels/UI 五层拆分，引入 CommunityToolkit.Mvvm 和 DI 容器。
KiCad 硬件设计：STM32F103ZE 控制板
使用 Python 脚本生成 KiCad PCB：STM32F103ZETx 主控、CH340C USB 转串口、双路 MAX485E RS485、AMS1117 供电，以及 100mm×100mm 双层板布局。
Bootloader 多层校验链：从 YMODEM 到向量表的 7 层防护
STM32 Bootloader 的完整校验链路：YMODEM 单包 CRC16、状态页 CRC16、Flash 逐字节回读、整包 CRC32、整包 SHA-256、向量表合法性校验，以及 DONE 状态下的上电复核机制。
嵌入式诊断体系：96 个寄存器的远程排障设计
STM32 设备端的远程诊断寄存器布局：固件版本与编译时间、运行时长与上电次数、重启原因追踪、Modbus CRC 错误与 UART 异常分类统计、非法读写记录，以及升级快照。
远程维护与参数配置体系
STM32 的远程参数维护框架：解锁口令与30秒维护窗口、配置暂存/提交/回滚机制、参数范围校验与组合约束、Flash 持久化，以及完整的 Modbus 维护指令集。
本地升级链路：YMODEM 协议适配与 Bootloader 状态机
STM32 本地固件升级的完整链路：Modbus 维护命令触发、YMODEM-C 协议适配、Bootloader 状态机设计，以及 14 种错误码的排障指南。
继电器控制与 DI 去抖：手动/自动模式
STM32 的继电器输出控制、DI 输入去抖处理、手动/自动模式切换，以及本地按键与远程控制的优先级设计。
服务端架构：Mosquitto + Node API + WebSocket
智能磨坊的服务端设计：MQTT broker 订阅设备数据、Node.js API 持久化与鉴权、WebSocket 实时广播。
Modbus 寄存器映射：现场主站与维护从站
STM32 双角色 Modbus 设计：USART2 主站轮询传感器，USART3 从站暴露 91 个寄存器供 G780s 和远程维护使用。
Flutter 智能磨坊客户端：实时监控与历史回溯
com.varka.mill 的 Flutter 客户端设计，覆盖实时 WebSocket 数据、历史趋势图、告警管理和继电器远程控制。
G780s 边缘 JSON 与 MQTT 上云
G780s 通信模块的 AT 配置、边缘 JSON 组包、MQTT over TLS 上云，以及服务端字段映射的实现。
OTA 桌面工具：从本地升级到远程维护
.NET / WPF 架构的 OTA 工具设计，覆盖本地 YMODEM 升级、虚拟串口远程升级和 Modbus 维护帧生成。
A/B 双槽位固件升级：Bootloader 设计与回退机制
STM32 的 Flash 分区策略、Bootloader 升级流程、CRC32 + SHA-256 + 向量表三重校验，以及连续失败自动回退的实现细节。
智能磨坊综述：STM32F103 工业控制与远程维护
围绕 STM32F103 + G780s 构建的智能磨坊控制与维护系统，覆盖 Modbus 现场采集、A/B 双槽位固件升级、远程 MQTT 通信和 Flutter 移动端监控。
FAL 分区与 LittleFS：SPI NOR Flash 的可靠存储
从 Flash 分区表到 LittleFS 文件系统挂载，详解管道监控系统如何在 SPI NOR Flash 上构建断电安全的存储层。
字节序问题：流量计 REAL4 解析与联调踩坑
Modbus RTU 的 32 位数据传输涉及字节序和字序的组合，不同厂商的习惯不同。详解管道监控系统如何用可配置的解析策略解决联调时的字节序问题。
嵌入式浮点处理：避免 %f 的定点格式化技巧
在 newlib-nano 不支持 %f 的环境下，如何用纯整数运算实现浮点数的定点格式化，保证 LCD 和 JSON 输出的精度与对齐。
报警系统：阈值判定、边沿触发与多级严重性
管道监控系统的报警设计：如何避免同一条规则每 2 秒刷一次报警，如何区分警告和严重故障，如何让上行线程即时上报。
Modbus 服务层：邮箱队列与总线串行化
通过邮箱 + 信号量实现 Modbus 总线的串行化访问，让多个业务线程安全地共享同一条 RS485 总线，避免时序冲突。
传感器驱动抽象：流量计、温压、PT100 的统一设计模式
详解管道监控系统三类传感器驱动的分层设计：设备层屏蔽硬件差异，服务层提供统一接口，业务层只关心测量值。
离线缓存与断点补传：LittleFS 上的可靠存储
管道监控系统的双层存储设计：CSV 落盘供离线分析，pending.jsonl 缓存未送达的上行帧，网络恢复后自动补传，保证数据不丢。
按键输入与 LCD 电源管理：PA15 复用与防残影策略
从硬件引脚复用到软件消抖，从 LCD 背光控制到周期性 IC 重初始化，详解管道监控系统的人机交互与显示维护设计。
看门狗与多任务健康监控：不止是喂狗
管道监控系统的看门狗设计：不止是简单的 IWDG 喂狗，而是对采集、显示、心跳、上行四个关键线程分别做健康检查，任一线程卡死都能自动复位恢复。
上行通信：JSON 编码、云端 ACK 与断点补传
详解管道监控系统的上行服务设计：手写 JSON 编码器、DR154 透传链路、云端确认机制，以及网络中断时的离线缓存与自动补传策略。
云端确认与历史去重：cloud_ack 下行链路 + UNIQUE(device_id, seq)
tele / alarm 先落库再回 cloud_ack，历史表用 (device_id, seq) 唯一键 + ON DUPLICATE KEY 兜底重放，配合 heart_count 心跳计数把上行链路的可靠性闭环。
管道监控系统多线程架构：RT-Thread 事件驱动设计
围绕 STM32H562 + RT-Thread 的多线程分离架构，详解采集、显示、存储、上行四大线程如何通过事件位与消息队列解耦协作。
Flutter Web 子路径部署与页面组态
管道监控系统的 Flutter Web 端通过 base-href 编排部署到 /scada/，与 API 和 WebSocket 共用同一服务域名，Nginx 子路径单独做 SPA 回退。
LCD 防闪烁与 LittleFS CSV 存储
UI 线程通过脏数据局部重绘消除闪烁；LittleFS 上的 measurements.csv 按时间批量刷盘并自动 Rotate，保证现场无网络也能离线溯源。
Modbus RTU 主站与 nanomodbus 封装
Modbus_Master / Modbus_Service / nanomodbus 三层划分，统一管理采集间隔、超时容错和异常节点过滤，支撑 PXW、超声波、PT100 三类传感器接入。
管道监控系统综述：STM32H562 + RT-Thread 边缘管道监控
围绕 STM32H562 与 RT-Thread 完整版搭建的 Modbus RTU 主站，统一接入压力、温度、流量传感器，本地 LCD 实时显示并落盘 CSV。