1. 项目概述
AdaptiveTXWSN 是一款专为无线传感器网络（Wireless Sensor Network, WSN）节点设计的轻量级 Arduino 库，其核心目标是实现基于电池电压状态的自适应传输周期调控。在典型的 WSN 部署场景中，节点往往由不可更换的纽扣电池或小型锂聚合物电池供电，部署于野外、建筑结构内部或工业设备边缘等难以维护的位置。此时，能量效率直接决定网络寿命——一个节点提前失效可能导致局部监测盲区，甚至引发整个多跳路由拓扑的重构开销。
该库不依赖任何外部驱动或复杂中间件，仅需标准 Arduino Core（<Arduino.h>），即可在 ATmega328P（如 Nano、Pro Mini）、ATmega2560（Mega 2560）及兼容平台（如 ESP32 的 Arduino 框架模式）上稳定运行。其设计哲学是“用最小的资源开销换取最大的续航增益”：通过硬件 ADC 直接采样分压后的电池电压，结合带滞回（Hysteresis）的三级状态机判定当前电量等级（HIGH / MID / LOW），并据此动态切换下一次数据上报的时间间隔。当电压跌至临界阈值以下时，库主动进入CUTOFF状态，彻底禁止传输行为，避免因欠压导致 MCU 复位异常、Flash 写入损坏或射频模块（如 nRF24L01+、SX127x）发射失真等可靠性风险。
与通用低功耗框架（如 LowPower 或 SleepyPi）不同，AdaptiveTXWSN 并非单纯延长休眠时间，而是将能量状态感知与通信调度决策深度耦合。它不干预 MCU 的睡眠控制逻辑，而是向应用层提供一个高语义的布尔接口tick()—— 仅当系统判定“此刻既满足能量约束又达到调度窗口”时才返回true。开发者可据此自由选择：调用sleep()进入深度休眠、执行传感器读取与本地滤波、触发 LoRaWAN join request，或启动 BLE 广播。这种解耦设计使其能无缝集成于 FreeRTOS 任务调度、Arduino Event System 或裸机状态机架构中。
2. 核心机制解析
2.1 电池电压测量与校准模型
AdaptiveTXWSN 的电压感知能力建立在 AVR/ARM 微控制器的片上 ADC 基础之上。由于绝大多数 MCU 的 ADC 输入范围有限（典型为 0–Vref），而单节锂电池标称电压为 3.7 V，满电可达 4.2 V，因此必须采用电阻分压网络将电池电压衰减至安全采样区间。库内建的电压计算模型严格遵循欧姆定律与 ADC 量化原理：
$$ V_{bat} = \left( \frac{V_{adc}}{2^{n}} \times V_{ref} \right) \times \left(1 + \frac{R_{top}}{R_{bottom}}\right) $$
其中：
- $V_{adc}$ 为 ADC 原始读数（0–1023 对应 10-bit）
- $n$ 为 ADC 分辨率位数（默认 10）
- $V_{ref}$ 为参考电压（
config.voltajeReferenciaAdc，UNO/Nano 通常为 5.0 V，3.3 V MCU 需设为 3.3） - $R_{top}$ 与 $R_{bottom}$ 为分压电阻阻值（单位 kΩ，
config.divisorRArriba_k与config.divisorRAbajo_k）
该公式在AdaptiveTXWSN::readBatteryVolts()中实现，其关键在于消除系统性偏差。例如，若使用 100kΩ + 33kΩ 分压（分压比 ≈ 4.03），且 Vref 实际为 4.92 V（受 USB 电源波动影响），则未校准的读数将系统性偏低约 1.6%。库要求用户显式配置voltajeReferenciaAdc，正是为了将此误差纳入计算闭环。
工程实践建议：首次部署前，务必用万用表实测电池端电压 $V_{bat_meas}$ 与串口输出的
lastVolts()值。若存在偏差，优先检查voltajeReferenciaAdc设置是否匹配 MCU 当前供电模式（USB 供电 vs 外部稳压供电），其次微调divisorRArriba_k（因贴片电阻公差常达 ±5%）。切勿通过软件偏移量“打补丁”，这会破坏滞回逻辑的物理意义。
2.2 滞回比较器与三级电量状态机
电池电压在负载瞬变（如射频发射、传感器加热）下存在显著纹波，若采用简单阈值比较（如if (v > 3.6) level=HIGH），MCU 可能在 3.59 V ↔ 3.61 V 区间反复抖动，导致传输周期在 5s 与 15s 间无意义切换，徒增射频模块开关损耗。AdaptiveTXWSN 通过引入双阈值滞回（Hysteresis）彻底解决此问题。
其状态转换逻辑如下表所示（以默认配置为例）：
| 当前状态 | 电压上升条件 | 电压下降条件 | 转换后状态 |
|---|---|---|---|
BATT_LOW | $V_{bat} > 3.60\text{V}$ | — | BATT_MID |
BATT_MID | $V_{bat} > 3.90\text{V}$ | $V_{bat} < 3.40\text{V}$ | BATT_HIGH/CUTOFF |
BATT_HIGH | — | $V_{bat} < 3.60\text{V}$ | BATT_MID |
注意：CUTOFF是独立终态，一旦进入，level()返回BATT_LOW但isCutoff()恒为true，且tick()永远返回false。滞回宽度（umbralAlto_V - umbralMedio_V = 0.3V，umbralMedio_V - corteVoltaje_V = 0.2V）需根据电池放电曲线陡峭度设定。对于 LiPo，3.6 V 至 3.4 V 区间容量衰减极快，故将corteVoltaje_V设为 3.40 V 可预留安全余量；而 NiMH 电池平台区宽，滞回宽度宜设为 0.1–0.15 V。
2.3 自适应定时器引擎
tick()函数是库的调度中枢，其内部维护一个unsigned long类型的nextTxTime时间戳。每次调用时，它执行以下原子操作：
- 读取当前毫秒计时器值
millis() - 若
millis() >= nextTxTime，则：- 执行
readBatteryVolts()更新lastVolts_ - 调用
updateLevel()判定新电量等级 - 根据新等级查表获取对应周期
currentPeriod_ - 将
nextTxTime更新为millis() + currentPeriod_ - 返回
true
- 执行
- 否则返回
false
此设计确保：
- 严格单调性：
nextTxTime永远递增，杜绝因millis()溢出（约 49.7 天）导致的负数回绕。 - 无锁安全：所有状态变量均为
volatile修饰，tick()无静态局部变量，可在中断服务程序（ISR）中安全调用（需确保 ISR 不调用Serial等阻塞函数）。 - 零延迟唤醒：若
loop()执行过慢（如传感器读取耗时 200ms），tick()仍能精确捕获首个满足条件的时刻，不会累积误差。
// AdaptiveTXWSN.cpp 关键片段（简化） bool AdaptiveTXWSN::tick() { const unsigned long now = millis(); if (now >= nextTxTime) { lastVolts_ = readBatteryVolts(); // ADC 采样 updateLevel(); // 滞回状态更新 if (isCutoff()) { currentPeriod_ = 0; // CUTOFF 时周期置 0，防止溢出 return false; } // 根据 level 查表设置 currentPeriod_ switch (batteryLevel_) { case BATT_HIGH: currentPeriod_ = config_.periodoAlto_ms; break; case BATT_MID: currentPeriod_ = config_.periodoMedio_ms; break; case BATT_LOW: currentPeriod_ = config_.periodoBajo_ms; break; } nextTxTime = now + currentPeriod_; return true; } return false; }3. API 接口详解
3.1 配置结构体AdaptiveTXWSN::Cfg
该结构体封装全部可调参数，必须在begin()前完成初始化。各字段含义与工程选型依据如下表：
| 字段名 | 类型 | 默认值 | 说明 | 工程选型指南 |
|---|---|---|---|---|
pinAdcBateria | uint8_t | — | ADC 通道引脚编号（如A0） | 必须与硬件分压网络物理连接一致；AVR 平台仅 A0–A7 有效 |
divisorRArriba_k | float | 100.0f | 分压上臂电阻（kΩ） | 选用 E24 系列标准值（100k、220k、470k）；阻值越大，ADC 输入阻抗影响越小，但噪声敏感度升高 |
divisorRAbajo_k | float | 33.0f | 分压下臂电阻（kΩ） | 与上臂共同决定分压比；下臂过小会增大静态功耗（如 10kΩ 在 4.2V 下耗电 0.42 mA） |
voltajeReferenciaAdc | float | 5.0f | ADC 参考电压（V） | UNO/Nano USB 供电时为 5.0 V；若改用外部 3.3V LDO 供电，必须设为3.3f |
umbralAlto_V | float | 3.90f | HIGH 状态上限电压（V） | LiPo 满电 4.2V，3.9V 对应约 85% SOC；NiMH 电池应设为 1.45V/节 |
umbralMedio_V | float | 3.60f | MID 状态中值电压（V） | LiPo 3.6V 约为 20% SOC，是续航拐点；需避开放电平台区 |
corteVoltaje_V | float | 3.40f | CUTOFF 关断电压（V） | 锂电池保护板通常在 2.5–2.8V 触发，此处设 3.4V 为 MCU 保留充足裕度 |
periodoAlto_ms | unsigned long | 5000 | HIGH 状态传输周期（ms） | 典型 WSN 信标周期；若用于环境监测，可设为30000（30s） |
periodoMedio_ms | unsigned long | 15000 | MID 状态传输周期（ms） | 建议为periodoAlto_ms的 2–3 倍，平衡数据新鲜度与功耗 |
periodoBajo_ms | unsigned long | 120000 | LOW 状态传输周期（ms） | 2 分钟是常见起点；极端低功耗场景可设为300000（5 分钟） |
3.2 核心成员函数
| 函数签名 | 返回值 | 功能说明 | 典型应用场景 |
|---|---|---|---|
void begin(const Cfg& cfg) | void | 初始化库，加载配置，执行首次 ADC 采样 | setup()中唯一必需调用 |
bool tick() | bool | 主调度函数；返回true表示到达传输窗口 | loop()中高频轮询，驱动业务逻辑 |
float lastVolts() | float | 获取最后一次tick()中读取的电池电压（V） | 串口调试、日志记录、触发低电量告警 |
BatteryLevel level() | enum BatteryLevel | 返回当前电量等级（BATT_HIGH/BATT_MID/BATT_LOW） | 动态调整传感器采样精度（如 LOW 时关闭温湿度补偿） |
bool isCutoff() | bool | 判断是否进入关断状态 | loop()中分支处理：if (isCutoff()) { enterDeepSleep(); } |
unsigned long currentPeriod() | unsigned long | 返回当前生效的传输周期（ms） | 调试验证滞回逻辑是否按预期切换 |
void setBatteryVolts(float volts) | void | 强制注入外部测量电压（覆盖 ADC 读数） | 集成专用 PMIC（如 MAX17048）时，传入其 I2C 读取的精确值 |
关键约束：
setBatteryVolts()必须在begin()之后调用，且其效果仅持续到下次tick()—— 因为tick()内部会重新调用readBatteryVolts()。若需长期使用外部电压源，应在每次tick()返回false时重复调用setBatteryVolts()，或派生子类重写readBatteryVolts()。
4. 高级应用与集成方案
4.1 与低功耗睡眠深度协同
单纯延长传输周期不足以最大化续航，必须配合 MCU 深度睡眠。以下代码展示如何在tick()返回false时，让 ATmega328P 进入 Power-down 模式（电流 < 0.1 μA）：
#include <avr/sleep.h> #include <avr/wdt.h> // WDT 中断唤醒（需在 setup() 中启用） ISR(WDT_vect) { } void enterSleep() { set_sleep_mode(SLEEP_MODE_PWR_DOWN); sleep_enable(); wdt_enable(WDTO_8S); // 启用 8 秒看门狗作为唤醒源 sleep_cpu(); // 进入睡眠 sleep_disable(); wdt_disable(); } void loop() { if (txTimer.tick()) { // 执行传感器读取与无线发送 readSensors(); sendToGateway(); } else { if (txTimer.isCutoff()) { // CUTOFF 状态：永久睡眠（需外部复位唤醒） while(1) sleep_mode(); } else { // 正常低功耗：睡眠至下次 tick() 时间点 const unsigned long now = millis(); const unsigned long sleepMs = min(txTimer.currentPeriod(), 8000UL); // WDT 最大 8s delay(sleepMs); // 粗略延时（精度要求不高时） // 或更优：enterSleep(); } } }4.2 FreeRTOS 任务调度集成
在资源充裕的 ESP32 平台上，可将tick()封装为 FreeRTOS 队列事件：
QueueHandle_t txQueue; void txTask(void *pvParameters) { for(;;) { if (txTimer.tick()) { xQueueSend(txQueue, &txTimer.lastVolts(), portMAX_DELAY); } vTaskDelay(10 / portTICK_PERIOD_MS); // 10ms 轮询粒度 } } void sensorTask(void *pvParameters) { float vBat; for(;;) { if (xQueueReceive(txQueue, &vBat, portMAX_DELAY) == pdTRUE) { // 执行高耗电操作：读取 BME280、发送 LoRa bme280.read(); lora.send(bme280.data); Serial.printf("TX @ %.2fV\n", vBat); } } } void setup() { txQueue = xQueueCreate(5, sizeof(float)); xTaskCreate(txTask, "TX_Timer", 2048, NULL, 1, NULL); xTaskCreate(sensorTask, "Sensor_TX", 4096, NULL, 2, NULL); }4.3 多电池系统扩展
对双电池备份系统，可扩展AdaptiveTXWSN支持主/备电池电压仲裁。只需新增Cfg字段pinAdcBackup，并在readBatteryVolts()中添加选择逻辑：
float AdaptiveTXWSN::readBatteryVolts() { float mainV = analogRead(config_.pinAdcBateria) * config_.voltajeReferenciaAdc / 1024.0f; mainV *= (1.0f + config_.divisorRArriba_k / config_.divisorRAbajo_k); if (config_.pinAdcBackup != 255) { // 255 为无效引脚标记 float backupV = analogRead(config_.pinAdcBackup) * config_.voltajeReferenciaAdc / 1024.0f; backupV *= (1.0f + config_.divisorRArriba_k / config_.divisorRAbajo_k); return (mainV > 3.0f) ? mainV : backupV; // 主电池有效则用主，否则切备 } return mainV; }5. 实际部署注意事项
- ADC 噪声抑制：在
A0引脚就近放置 100 nF 陶瓷电容至 GND，可降低高频干扰。若仍存在 >0.05 V 抖动，可在readBatteryVolts()中加入 4 点滑动平均滤波。 - 分压电阻功率：按 $P = V^2 / R$ 计算。100kΩ+33kΩ 在 4.2V 下总功耗仅 0.13 mW，完全可接受；但若选用 10kΩ+3.3kΩ，功耗升至 1.3 mW，将显著缩短纽扣电池寿命。
- LGPL 3.0 商业合规：若产品固件为闭源二进制，且链接了 AdaptiveTXWSN 的
.a静态库，则必须向用户提供目标文件（.o）或链接脚本，允许其替换库版本。规避方案是购买商业 MIT 许可证，或采用动态链接（ESP32 IDF 支持）。 - 长期漂移校准：电解电容老化、电阻温漂会导致数月后电压读数偏移。建议在固件中预留 OTA 升级接口，远程更新
voltajeReferenciaAdc与分压电阻值。
AdaptiveTXWSN 的价值不在于算法复杂度，而在于将嵌入式工程师对电池特性的经验直觉，固化为可复用、可验证、可审计的代码契约。当你的第 100 个部署节点在三年后仍稳定回传数据，那串Transmitiendo... VBat: 3.42V, Nivel: BAJO, Prox. TX en: 120 seg的日志，便是对这份设计最坚实的背书。
