1. Queuetue Digital Balance 库深度解析：面向嵌入式称重系统的高精度数据处理框架

1.1 库定位与工程价值

Queuetue Digital Balance Library 是一个专为 Arduino 平台设计的轻量级、高鲁棒性数字衡器软件框架，其核心目标并非简单读取传感器原始值，而是构建一套完整的 嵌入式称重数据处理流水线 。该库在 2015 年由 Scott Russell 发布，采用 MIT 许可证开源，其设计哲学深刻体现了嵌入式系统开发中“软硬协同、数据可信”的核心原则。

在实际工业与消费类衡器产品中，硬件传感器（如 HX711 驱动的应变片桥路）输出的原始数据存在三大固有缺陷： 高频噪声（jitter）、非线性响应（non-linearity）和零点漂移（zero drift） 。传统做法常将滤波、校准、去皮等逻辑散落在主循环中，导致代码耦合度高、调试困难、复用性差。Queuetue Balance 库通过清晰的职责分离（Separation of Concerns）和状态机驱动（State Machine Driven）的设计，将这些关键环节封装为可配置、可扩展、可调试的模块。它不依赖特定 ADC 芯片，仅需用户按周期调用 measure() 注入原始采样值，即可完成从“毛刺信号”到“可信重量读数”的全链路转换，这使其成为构建高可靠性嵌入式称重终端（如智能厨房秤、实验室微量天平、工业包装秤）的理想底层数据处理引擎。

1.2 核心架构与数据流模型

Q2Balance 类采用单例模式（Singleton Pattern）设计，内部维护一个完整且自洽的状态机。其核心数据流遵循严格的时序逻辑：

[原始ADC采样] 
    ↓ (调用 measure(long raw))
[原始值缓存] → [动态抖动检测] → [跳变抑制判断] → [滑动平均滤波]
    ↓ (tick() 触发)
[零点校准/去皮状态管理] → [多点线性映射校准] → [单位换算]
    ↓
[adjustedValue()] → [最终显示/控制]

整个流程的关键在于 tick() 函数——它并非一个被动的“获取值”接口，而是一个主动的“状态推进器”。开发者必须在主循环（或高优先级 FreeRTOS 任务）中以足够高的频率（建议 ≥ 100Hz）调用 tick() ，以确保：

• 滤波器能持续更新其滑动窗口；
• “settling”（稳定态）检测能及时响应物理变化；
• 所有异步操作（如校准、去皮）的状态机得以正确演进。

这种设计强制开发者关注实时性，避免了因轮询疏漏导致的读数滞后或状态僵死，是嵌入式衡器系统稳定性的基石。

2. 核心功能模块详解

2.1 多点分段线性校准（Multi-Point Piecewise Linear Calibration）

这是 Queuetue Balance 区别于普通滤波库的核心竞争力。它摒弃了单一斜率的粗暴线性拟合，转而支持最多 10 个校准锚点（Calibration Setpoints） ，形成一条由多段直线构成的校准曲线，精准补偿传感器在整个量程内的非线性误差。

校准机制原理

校准过程分为两个独立步骤：

1. 零点校准（ calibrateZero() ） ：在传感器完全空载（无任何负载）状态下执行。库会采集一段稳定期（由参数 msToSettle 指定）内的原始值，将其记录为 zeroOffset 。此值是所有后续计算的基准偏移。
2. 量程校准（ calibrate(uint8_t index, long massInMg, uint32_t msToSettle) ） ：在传感器加载已知标准质量（ massInMg ，单位为毫克）后执行。库同样采集稳定期数据，并将该原始值与 zeroOffset 的差值（即净信号）与标准质量建立映射关系，存储于指定索引 index （0-9）。

分段映射策略

校准点必须按质量 从小到大顺序设置 。例如，若需覆盖 0-5000g 量程并提升中段精度，可设置：

• calibrate(0, 100000, 2000); // 100g 锚点
• calibrate(1, 1000000, 2000); // 1000g 锚点
• calibrate(2, 5000000, 2000); // 5000g 锚点

当读取一个原始测量值 raw 时，库首先计算其净信号 net = raw - zeroOffset ，然后根据 net 的大小，自动选择最邻近的两个锚点进行线性插值：

• 若 net 小于 index=0 的净信号，则直接使用 index=0 的斜率；
• 若 net 介于 index=i 和 index=i+1 的净信号之间，则使用这两点确定的斜率进行插值；
• 若 net 大于 index=9 的净信号，则使用 index=9 的斜率外推。

这种策略完美模拟了高端商用衡器的“分段校准”特性，显著提升了全量程内的绝对精度，尤其适用于对中低量程精度要求苛刻的应用（如珠宝秤、药剂称量）。

校准数据持久化

校准数据以结构体形式暴露，便于保存至 EEPROM 或 Flash：

typedef struct {
    long zeroOffset;           // 零点偏移（原始ADC值）
    uint8_t count;             // 已设置的有效校准点数量
    long netValues[10];        // 各点对应的净信号值（原始ADC差值）
    long masses[10];           // 各点对应的标准质量（毫克）
} Q2BalanceCalibration;

调用 getCalibration() 可获取当前全部数据； setCalibration(const Q2BalanceCalibration* cal) 则用于从非易失存储器中恢复。此设计为产品量产中的“出厂校准”流程提供了标准化接口。

2.2 自适应滤波与动态稳定性管理

衡器读数的“晃动”（jitter）是影响用户体验的关键因素。Queuetue Balance 提供了一套融合多种策略的智能滤波方案。

滑动平均滤波（Moving Average）

基础滤波器采用固定长度的滑动平均（ SAMPLE_COUNT 默认为 10）。每次调用 measure(long raw) 即向环形缓冲区注入一个新样本， smoothValue() 返回当前窗口的平均值。此方法有效抑制白噪声，但对阶跃变化响应迟钝。

动态跳变检测（Jump Detection）

为解决上述迟滞问题，库引入了 JUMPLIMIT （默认 200）阈值。当新注入的 raw 值与上一次 smoothValue() 的差值绝对值超过此阈值时，滤波器被强制“重置”， smoothValue() 立即跳变为新值，而非缓慢收敛。这确保了当用户快速放置或取下重物时，读数能迅速响应，避免了令人困惑的“拖尾”现象。

抖动量化与稳定态判定（Settling）

jitter 成员变量记录了最近一次 settle() 过程中，原始采样值在其均值附近的波动幅度（标准差的近似）。 settling 布尔标志则指示当前是否处于“等待稳定”状态。 settle(uint32_t ms) 函数会启动一个定时器，在 ms 毫秒内持续采集并计算 jitter ，当 jitter 低于某个内部阈值（通常与 JUMPLIMIT 相关）时， settling 置为 false ，表示读数已稳定。这一机制是实现“自动归零”、“自动去皮”等高级功能的物理基础。

2.3 去皮（Taring）与零点管理

去皮是衡器最常用的功能，但其实现极易出错。Queuetue Balance 将“硬件零点”（ calibrateZero ）与“软件零点”（ tare ）严格分离，避免了概念混淆。

• 硬件零点（ zeroOffset ） ：反映传感器自身的物理偏移，一经校准，除非环境温度/应力发生剧变，否则长期有效。
• 软件零点（ tareOffset ） ：用户在任意时刻设定的临时偏移，用于扣除容器重量。其有效性受 TARELIMIT （默认 110）约束。

tare(uint32_t msToSettle) 函数在 msToSettle 毫秒的稳定期后，将当前的 adjustedValue() （已校准、已滤波的克重）作为新的 tareOffset 。此后，所有 adjustedValue() 输出均减去此值。 tared 标志位为 true 表示去皮已生效； taring 为 true 表示正在执行去皮操作。一旦当前读数与 tareOffset 的绝对差值超过 TARELIMIT ， tared 自动置为 false ，即“破皮”，防止因超载导致的错误归零。

3. API 接口详述与工程化使用指南

3.1 核心类与构造

class Q2Balance {
public:
    Q2Balance(); // 无参构造，所有状态初始化为默认值
};

工程提示 ：由于其状态机特性，全局声明一个 Q2Balance balance; 实例即可，切勿在函数内频繁创建销毁。

3.2 关键成员函数与参数解析

函数签名	参数说明	返回值	工程用途与注意事项
void measure(long raw)	raw : 从 ADC 或 HX711 获取的原始整型采样值（通常为 24 位有符号数）	void	数据注入入口 。必须在 tick() 之前调用。 raw 值应为“去噪后”的相对稳定值，而非原始高频噪声。
void tick()	无	void	状态机驱动核心 。必须在 loop() 中高频调用（推荐 delay(10) 或 FreeRTOS vTaskDelay(10) ）。缺失此调用，所有功能将停滞。
float adjustedValue()	无	当前校准、滤波、去皮后的重量值（单位：克）	主读数接口 。返回 float 便于单位换算。若未完成零点校准，返回 0.0f 。
float adjustedRawValue(Q2BalanceUnit unit)	unit : 枚举值（见下表）	指定单位下的重量值	单位转换接口 。内部查表换算，无浮点运算开销。 Q2BALANCE_UNIT_POUND 返回十进制磅（如 2.34 ），非 2 lb 5 oz 。
void calibrateZero(uint32_t msToSettle, void (*afterCalibrated)(void) = nullptr)	msToSettle : 稳定期（毫秒） afterCalibrated : 成功回调	void	零点校准 。执行前务必清空秤盘。回调在稳定且校准成功后触发。失败（如未稳定）则不触发。
void calibrate(uint8_t index, long massInMg, uint32_t msToSettle, void (*afterCalibrated)(void) = nullptr)	index : 0-9 massInMg : 标准质量（毫克） msToSettle : 稳定期 afterCalibrated : 回调	void	量程校准 。 massInMg 是关键！1kg = 1,000,000 mg。回调同上。
void tare(uint32_t msToSettle, void (*afterTared)(void) = nullptr)	msToSettle : 稳定期 afterTared : 回调	void	去皮操作 。执行前秤盘上应放置需扣除的容器。回调在稳定且去皮成功后触发。

3.3 单位枚举与换算表

typedef enum {
    Q2BALANCE_UNIT_GRAM,     // 克 (g) - 基准单位
    Q2BALANCE_UNIT_POUND,    // 磅 (lb) - 1 lb = 453.59237 g
    Q2BALANCE_UNIT_OUNCE,    // 盎司 (oz) - 1 oz = 28.349523125 g
    Q2BALANCE_UNIT_GRAIN,    // 格令 (gr) - 1 gr = 0.06479891 g
    Q2BALANCE_UNIT_TROY,     // 金衡盎司 (oz t) - 1 oz t = 31.1034768 g
    Q2BALANCE_UNIT_PWT,      // 英钱 (pwt) - 1 pwt = 1.55517384 g
    Q2BALANCE_UNIT_CARAT,    // 克拉 (ct) - 1 ct = 0.2 g
    Q2BALANCE_UNIT_NEWTON    // 牛顿 (N) - 1 N ≈ 101.971621 g (g=9.80665 m/s²)
} Q2BalanceUnit;

工程提示 ：所有单位换算均基于 adjustedValue() （克）进行静态乘法，无运行时浮点除法，保证了在资源受限 MCU 上的高效性。

3.4 状态查询与调试接口

接口	用途	典型应用场景
bool calibrating , bool taring , bool settling , bool tared	查询当前操作状态	在 UI 中显示“CALIBRATING...”、“TARING...”、“STABILIZING...”等提示；禁止在 calibrating 时再次触发校准。
long jitter , long rawValue , long smoothValue	获取底层数据	调试滤波效果；绘制实时波形；评估传感器噪声水平。
void printCalibration(uint8_t index) , void printCalibrations()	串口打印校准信息	出厂校准日志；现场故障诊断；验证 EEPROM 加载是否成功。

4. 与主流硬件及 RTOS 的集成实践

4.1 与 HX711 ADC 的典型集成

HX711 是最常用的称重专用 ADC，其 read() 方法返回 24 位有符号整数。集成代码高度简洁：

#include <Q2Balance.h>
#include <HX711.h>

HX711 scale;
Q2Balance balance;

void setup() {
    Serial.begin(115200);
    scale.begin(DOUT, CLK); // DOUT: 数据引脚, CLK: 时钟引脚
    scale.set_gain(128);    // 设置增益
}

void loop() {
    if (scale.is_ready()) { // 确保 HX711 数据就绪
        long raw = scale.read(); // 获取原始值
        balance.measure(raw);    // 注入平衡库
    }
    balance.tick();            // 推进状态机
    delay(10);                 // 保持 ~100Hz 更新率
}

关键点 ： scale.read() 必须在 balance.measure() 之前调用，且 balance.tick() 的调用频率必须与 scale.read() 的可用频率匹配，避免数据注入过快或过慢。

4.2 在 FreeRTOS 环境下的安全使用

在多任务系统中， Q2Balance 的状态变量需线程安全访问。推荐方案是将其封装在一个专用任务中：

Q2Balance balance;
QueueHandle_t xBalanceQueue; // 用于向主任务发送读数的队列

void vBalanceTask(void *pvParameters) {
    (void) pvParameters;
    for(;;) {
        if (hx711_is_data_ready()) { // 替换为你的 HX711 就绪检查
            long raw = hx711_read();
            balance.measure(raw);
        }
        balance.tick();
        // 每 100ms 发送一次最新读数
        if (xSemaphoreTake(xReadSemaphore, portMAX_DELAY) == pdTRUE) {
            float weight = balance.adjustedValue();
            xQueueSend(xBalanceQueue, &weight, 0);
        }
        vTaskDelay(10 / portTICK_PERIOD_MS);
    }
}

注意 ： measure() 和 tick() 是纯内存操作，无需互斥锁；但 adjustedValue() 等读取接口，若在多个任务中并发调用，应确保其原子性，或通过队列传递结果，这是更优的嵌入式设计范式。

5. 高级配置与性能调优

5.1 关键宏定义及其工程意义

所有可调参数均以 #define 形式提供，位于库头文件中，便于编译时定制：

宏名	默认值	调优建议	工程影响
TARELIMIT	110	高精度场景（如 mg 级）可设为 50 ；工业大秤可设为 500	控制“破皮”灵敏度。过小易误破，过大则超载风险。
JUMPLIMIT	200	噪声大的传感器（如长导线）可增大至 500 ；高响应需求场景可减小至 100	平衡“抗干扰”与“响应速度”。直接影响用户体验。
SAMPLE_COUNT	10	对稳定性要求极高（如实验室）可增至 20 ；对响应速度要求极高（如高速分拣）可减至 5	滤波强度。 N 越大，噪声抑制越强，但阶跃响应时间越长（约 N * 10ms ）。

5.2 内存占用与实时性分析

Q2Balance 实例的 RAM 占用极小：

• 固定开销：约 120 字节（含 10 个 long 的校准数组、状态标志、滤波缓冲区等）。
• ROM 开销：约 1.2KB （纯 C++ 代码，无浮点库依赖）。

在 STM32F103C8T6（72MHz）上，一次 tick() 调用耗时约 8-12μs ， adjustedValue() 耗时约 3μs 。这意味着即使在 10kHz 的极端采样率下，其 CPU 占用率也低于 0.1% ，为其他任务（如 LCD 刷新、通信协议栈）留出了充足余量。

6. 故障排查与最佳实践

6.1 常见问题诊断树

现象	可能原因	排查步骤
adjustedValue() 始终返回 0.0	未执行 calibrateZero() ；或 calibrateZero() 期间秤盘未清空	调用 printCalibrations() ，确认 zeroOffset 是否为非零有效值。
读数剧烈跳变，无法稳定	JUMPLIMIT 过小； SAMPLE_COUNT 过小；传感器供电不稳	增大 JUMPLIMIT ；检查电源纹波；用 jitter 值评估噪声水平。
去皮后读数缓慢漂移	TARELIMIT 过大；环境温度变化导致传感器零点漂移	减小 TARELIMIT ；考虑在 tare() 后重新执行 calibrateZero() 。
校准后线性度差	校准点未按质量升序设置；标准砝码精度不足；传感器已损坏	用 printCalibrations() 确认索引顺序；使用更高精度砝码复测。

6.2 生产级部署 checklist

• ✅ 出厂校准 ：在洁净、恒温环境中，使用 NIST 可溯源砝码，依次执行 calibrateZero() 和 calibrate(0, ...) 至 calibrate(n, ...) ，并将 getCalibration() 结构体写入 EEPROM。
• ✅ 上电自检 ： setup() 中调用 setCalibration(&eeprom_cal) 加载校准数据，并用 printCalibrations() 验证完整性。
• ✅ 用户交互 ：为 calibrateZero() 和 tare() 设计明确的 UI 流程（如长按按键 3 秒），并在操作期间禁用其他功能。
• ✅ 异常保护 ：在 loop() 中监控 balance.settling() 和 balance.calibrating() ，若超时（如 > 5000ms），强制复位状态机并报错。

Queuetue Balance 库的价值，不仅在于其提供的现成算法，更在于它为嵌入式衡器开发者建立了一套严谨的数据处理思维范式： 以物理世界的真实约束（噪声、非线性、漂移）为起点，以状态机为骨架，以可配置参数为血肉，最终交付一个行为可预测、结果可信赖的“数字秤” 。在物联网与边缘智能加速渗透消费电子与工业现场的今天，这样一份历经十年考验、代码简洁、文档清晰、理念先进的开源库，依然是构建高价值称重应用不可多得的坚实基石。