第 1 章 项目介绍

本项目在 NXP FRDM-MCXN236 上构建了一套完整的物联网环境监测终端，把「时统基准、三路环境感知、边缘信号分析、图形化呈现、工业总线通信、上位机数据服务」串成一条闭环链路。设备端以裸机方式运行 LVGL 9.4 图形界面，通过 Modbus-RTU 二进制总线对外暴露全部测量值，上位机以 10 Hz 轮询入库并提供 Web 实时大屏与告警审计。

选题直接来自任务书的两项任务：任务 1「电子时钟」要求用 RTC 走时、显示时时分秒、按键调整、串口输出并支持掉电保持；任务 2「环境数据采集与显示」要求用 I2C 读传感器、周期性采集、串口输出、LED 指示状态，刷新周期不大于 1 秒，并额外考察多传感器接入、滤波、阈值报警与数据统计分析四项扩展能力。两项任务均已在实机跑通，并在此基础上做了工程化扩展——把时钟从独立功能整合为终端的时基层，把传感器采集从串口打印升级为带滤波与告警的边缘分析链路，从而让设备从「演示板」变为「可长期运行的监测终端」。

需要主动说明的是一处工程边界：本板载的 PDM 数字麦克风通道（U7 / SPK0641HT4H-1）经实测采集结果不可信——MICFIL 的 DATACH 存在满量程削顶（RMS≈12800、PEAK 恒 −32768、dBFS≈−8），且与真实环境声压无关，在安静房间内数值同样如此。判定根因位于模拟前端/增益环节而非驱动配置后，该通道已被整体下线：驱动代码由 DEMO_DMIC_ENABLE（source/demo_dmic.h:29，当前值 0）包裹，Modbus 声级寄存器区保留地址并恒返回 0，HMI 页面同步删除。我们选择放弃这一指标而非用不可信数据凑数，详见第 6 章。

第 2 章 硬件介绍

本项目的核心特征是所用传感器与显示器几乎全部为板载器件，无需外购，这既降低了搭建成本，也避免了接口冲突带来的不确定性。

开发过程中总结出的三条硬件禁区，这是本项目工程素养的直接体现：

1. 严禁驱动 P4_6（背光 BLK）。LCD-PAR-S035 模块内部对背光有默认使能电路，一旦由 MCU 驱动该引脚，就会出现「按住复位键有画面、松开立刻黑屏」的现象。官方例程将其完全悬空，本项目严格遵守，禁止调用任何背光初始化。
2. 挂载 LCD 后 P0_20 不可用作按键。该引脚是 FlexIO 数据线 D4，在板上与物理按键 SW2 硬件短接，因此 SW2 不可读写；时间调整全部改走 GT911 触摸按钮。
3. P4_19 不可驱动绿色 LED。该引脚被 FlexIO 作为 LCD 读控制线 RD# 使用，与绿色 LED 短接，因此系统状态指示只用红灯与蓝灯两色。

第四条经验来自电源域：本板 VBAT 不具备保持条件。依据官方网表 pstxnet.dat，VDD_VBAT 网络的节点为 U1.T17 + R76.2，而 VDD_MCU 网络含 R76.1，即 R76（0 Ω）把 VBAT 与主电源直连，且板上无电池、无超级电容。这直接决定了第 6 章中掉电保持的实现路线。

第 3 章 方案框图与设计思路

3.1 总体架构

系统按职责分为六层，依次为时基层、感知层、边缘分析层、呈现层、通信层与上位机：

图 1　系统总体架构：六层职责划分

架构中最需要说明的是数据回传方向：Modbus-RTU 从机严格遵循请求-响应模型，空闲时不发送任何字节；上位机以 10 Hz 轮询 FC04 读取输入寄存器 0x0000–0x002E，配合 100 ms 的采集周期，满足任务书「刷新周期不大于 1 秒」的要求。

3.2 关键设计决策

第 4 章 调试软件介绍、软件流程图与关键代码

4.1 工具链

4.2 软件流程

图 2　软件流程图：初始化与主循环

系统启动后依次完成时钟与外设初始化、传感器识别与配置、LVGL 五页 HMI 构建，随后创建 100 ms 与 500 ms 两个定时器并进入主循环。主循环中 lv_timer_handler() 推进图形刷新，DEMO_ModbusPoll() 解析 Modbus 请求，另外由 W25Q64 按时落盘时间快照。

4.3 关键代码片段

① 传感器识别 —— 器件不是老款 FXLS8471（source/fxls8974.c）

#define FXLS8974_REG_WHO_AM_I      0x13U   /* 老款 FXLS8471 在 0x0F */
#define FXLS8974_REG_SENS_CONFIG1  0x15U
#define FXLS8974_WHOAMI_VALUE      0x86U

static bool fxls_probe(uint8_t addr)
{
    uint8_t whoami = 0U;
    s_i2cAddr = addr;
    if (fxls_read_regs(FXLS8974_REG_WHO_AM_I, &whoami, 1U) != kStatus_Success) return false;
    if (whoami != FXLS8974_WHOAMI_VALUE) { /* 打印实际值便于定位 */ return false; }
    return true;
}

12 位有效数据是右对齐存放，取值须 raw & 0x0FFF 后手工符号扩展，不可做 >> 4 移位——这是与老款驱动的另一处关键差异。

② iRTC 写保护——解锁与写入必须同处一个临界区（source/demo_periph.c）

/* 写保护解锁约 2 s 后自动闭锁；锁定期内写时间寄存器会触发
 * transfer error 并挂起系统。故在临界区内重新解锁后立即写入。 */
uint32_t irqMask  = DisableGlobalIRQ();
status_t unlockSt = IRTC_SetWriteProtection(RTC0, false);
status_t st       = IRTC_SetDatetime(RTC0, &dt2);
EnableGlobalIRQ(irqMask);

③ 滤波与静态倾角解算（source/demo_periph.c）

#define SENSOR_FILTER_N 8U   /* 三轴 8 点滑动平均环形缓冲，带预热标志 */

static int16_t median_filter5(int16_t *arr) { /* 温度 5 点中值，抗脉冲干扰 */ }

/* 原式 atan2(ay, sqrt(ax^2+az^2)) 分母恒 >=0，roll 被限制在 ±90°，
 * 倒置时 roll≈0 导致倾覆告警失效，且往返不可逆。
 * 改为 atan2(ay, az) 后范围扩展到 ±180°，倒置自然给出 roll=±180°。*/
s_pitch = (int16_t)(atan2f(-fx, sqrtf(fy * fy + fz * fz)) * 572.958f);
s_roll  = (int16_t)(atan2f(fy, fz) * 572.958f);

④ 3D 姿态自绘（custom/attitude3d.c）

#define ATT3D_TICK_MS    33.0f   /* 30 fps 节拍 */
#define ATT3D_PERSP_DIST 4.2f    /* 透视系数 */

/* 机体→世界：R = Ry(pitch) * Rx(roll) */
build_rot_x(s_filt_roll * 0.1f, rb);
/* 世界→视点：固定视角 Rx(+18°) * Ry(-28°)，模拟右上方俯视 */
mat3_mul(rt, ry, rv);
/* 透视除法 f = 4.2 / (4.2 - z)，背面三角形按法向剔除 */

第 5 章 功能展示图及说明第

五页界面总览。

终端共提供五个页面：CLOCK（时钟）、MONITOR（传感器监控）、SUMMARY（统计概览）、LIGHT（环境光）、TEMP（温度）。五个页面通过屏幕底部的标签页切换，每页只呈现一个主题，避免信息拥挤。

时钟页。

时钟页采用深色主题，以 48 px 琥珀色大字显示当前时、分、秒，字号在 480×320 的屏上足够醒目；页面下方为日期与温度信息面板，兼顾走时显示与环境信息一览。

三维姿态视图。

监控页中的立方体按加速度计解算出的当前姿态显示，随板卡倾斜而改变朝向；立方体的可见面判据生效，因此旋转到背面时不会出现穿插或错面。

上位机界面。

上位机为浏览器端 Web 大屏，包含 ECharts 实时波形（三轴加速度、温度、环境光）、告警审计表与历史数据表，并支持 CSV 导出。

6 章 项目中遇到的难题及解决方法

难题 1：加速度计「完全读不到数据」

• 现象：按老款 FXLS8471 的寄存器图去读 WHO_AM_I@0x0F，返回值全 0，三轴数据恒为 0，误判为器件未焊或 I2C 不通。
• 根因：本板实际搭载的是 FXLS8974CF，寄存器映射与老款不同——ID 寄存器在 0x13（值 0x86），控制寄存器 SENS_CONFIG1 在 0x15，且 12 位数据右对齐存放。
• 解法：写一段全寄存器 dump 逐地址扫描，定位到 0x13 处有稳定响应；参照 Linux 内核驱动 drivers/iio/accel/fxls8962af-core.c 确认器件 ID 与位域定义，据此重写驱动。
• 验证：串口稳定打印 [fxls] FXLS8974 found at 0x18 (WHO_AM_I=0x86)，三轴读数随倾斜连续变化。

难题 2：点击 SAVE 偶发整机挂死

• 现象：进入调整界面操作数秒后再点 SAVE，系统偶发直接卡死，停在总线传输错误上。
• 根因：MCXN236 的 iRTC 硬件写保护（STATUS[WRITE_PROT_EN]）在解锁约 2 秒后自动重新闭锁。用户操作数秒后点击 SAVE，此时写保护早已闭锁，强行写寄存器触发 Transfer Error 而挂起总线。
• 解法：在写入时间寄存器前，必须在临界区内重新调用 IRTC_SetWriteProtection(RTC0, false)，使解锁与写入在数微秒内完成。
• 验证：连续多次调时保存均正常，日志出现 [save] s4 unlock st=0 write st=0 status=0x0 并紧接 SAVED & exit adj。

难题 3：任务书要求的「掉电后时间能够保持」在硬件上不成立

• 现象：反复测试断电重启，时间总是回到默认值。
• 根因：这是硬件层面的限制，不是软件 bug。查官方网表 pstxnet.dat 发现 VDD_VBAT 与 VDD_MCU 经 R76（0 Ω）直连，板上无电池、无超级电容，真断电时 iRTC 必然失去保持条件。
• 解法：将时间快照落盘到板载 W25Q64 外部 Flash，采用单线 SPI（1-1-1）模式走 P3_20~P3_23 四根线——经核对网表，这四根线在 pin_mux.c 中无任何配置、属纯空闲，与 LCD 的 FlexIO 占用完全不重叠，LCD 固件零改动。
• 验证：JEDEC ID 读回 EF 40 17；标定落盘返回 STORE_OK 且 seq 递增；重烧固件（仅动片内 Flash sector 0–45）后快照 14:30:00 仍存活；周期落盘（临时缩至 5 s）实测 22 s 内 seq 自动 2→6；强制注入恢复镜像后 RESTORED 置位且 iRTC 被正确改写为快照值并继续走时。
• 遗留项：真正的物理拔电测试仍待完成，这是当前唯一未覆盖的验收点。

难题 4：片内 Flash 自编程完全不可用

• 现象：按参考手册 FMU 命令序列编程，最基础的只读命令 RD1SCR（手册上限 50 µs）也不返回。
• 根因：逐条排除了 FSTAT 状态、命令序列、地址对齐、ACCERR/PVIOL 错误位、安全/非安全别名、缓存一致性、等待时间、从 SRAM 执行等因素，均未改变现象。最硬的证据是：把探针放进开机流程后板子直接起不来——只要有命令在飞（CMDP=1、CCIF=0），Flash 阵列就取不到指令，整机停摆至硬件复位。
• 解法：放弃片内 FMU 路线，转用外部 W25Q64（见难题 3），并清理了相关驱动与诊断钩子。
• 验证：外部 Flash 方案全链路实测通过，且 LCD 与主程序逻辑零改动。

难题 5：麦克风数据通路「正常」但数值不可信

• 现象：PDM/MICFIL 能正常出流（EDMA 静态环形链、16 kHz），但 DATACH 数据 RMS≈12800、PEAK 恒为 −32768、dBFS≈−8，在安静房间亦然，与真实声压无关；且使能 PDM 错误中断会引发 IRQ 风暴拖死 CPU。
• 根因：MICFIL 的 DATACH 满量程削顶，根因在模拟前端/增益环节，不是驱动配置问题，改代码无法解决。
• 解法：整体下线该通道——驱动实现由 DEMO_DMIC_ENABLE（置 0）包裹，编译为桩函数；Modbus 声级寄存器块保留地址、恒返回 0；HMI 删去对应页面。
• 验证：整机资源反而下降（Flash −7.7 KB / SRAM −4.6 KB），且因消除了 IRQ 风暴，系统稳定性提升。
• 附带修正：单线 SPI 调试中曾连踩 5 个「看着对、实际没生效」的坑——只开 kCLOCK_Port3 漏开 kCLOCK_Gpio3；port_pin_config_t 用位置初始化导致字段错位一位；SCK 配成「初始高」违反 SPI Mode 0 空闲低；自检函数结尾误恢复引脚电平；JEDEC ID 前多发 3 个 dummy 字节。教训是：此类字段随 feature 宏变化的结构体，一律用具名初始化。

难题 6：切换到详情页时整机卡死

• 现象：切页瞬间整机僵死，且无 HardFault 记录。
• 根因：lv_bar 指示条的圆角(2) 小于背景圆角(3)，触发 LVGL 的 radius_issue 分支，每帧申请 388×4 字节的 ARGB8888 缓冲（约 24.8 KB），超过当时剩余的 16.8 KB 堆空间。
• 解法：把圆角统一为 3，并改走无动态分配的直绘路径。
• 验证：连续 30 次五页轮切无卡死。

难题 7：倾角解算公式不可逆、倒置告警失效

• 现象：(60°, 40°) 姿态往返测量误差达 21.25°；板卡完全倒置时 roll 读数为 0，导致倾覆告警不触发。
• 根因：原式 atan2(ay, √(ax²+az²)) 的分母恒非负，roll 被限制在 ±90°，且不可逆。
• 解法：改为 atan2(ay, az)，量程扩展到 ±180°。
• 验证：往返误差 0.0°，倒置时正确给出 roll=±180°。静置读数 pitch +1.0° / roll +0.9°，|a|≈1115 mg（器件固有零偏），0.1° 分辨率。

难题 8：上位机遥测线程静默退出

• 现象：/api/status 显示已连接，但曲线长时间不动。
• 根因：struct.unpack 的格式串少了一个 H（漏了 th_bright 字段），按 32 字节解析实际 30 字节的数据，每次轮询都抛异常并终止线程。
• 解法：格式更正为 >4H2HhH3hHHHhh，并在轮询循环外包 try/except。
• 验证：数据持续入库，10 Hz 稳定。

第 7 章 心得体会

一、读手册不如读网表。 「掉电保持」到底成不成立，反复试断电永远得不出结论——直到在官方 pstxnet.dat 里查到 VBAT 经 R76 0 Ω 直连主电源、板上无电池也无超级电容，问题才被定性为硬件限制而非软件缺陷，并直接推出了外部 Flash 落盘的补偿路线。这比盲目试错高效得多。

二、可观测性就是生命线。 我们在设计阶段就规划好了 [fxls]、[save]、[motion]、[ext] 等关键打印与完整的 Modbus 寄存器映射。正因为有这些埋点，难题 1、2、5 都能在几分钟内定位到根因；反之，现场故障只能靠猜。

三、「能跑通」不等于「能用」。 麦克风通道是最典型的例子：数据通路「正常」、驱动「能用」，但数值不可信。此时继续上报反而会污染告警逻辑与验收结论。果断下线并保留源码作为「诚实工程」的证据，比硬凑指标专业得多。

四、嵌入式里每一 KB 都要算账。 去掉麦克风省下 12 KB，3D 姿态改纯图元自绘只多花 36 B 内存，两次取舍都让资源余量维持在可接受范围。当前 Flash 占用约 373 KB / 512 KB（71.3%），SRAM 约 149.8 KB / 224 KB（65.3%），且已为时间持久化预留了独立的 Flash 区段。