示例12:UART串口通信
2026-10-04源码校对：当前接线、端口分配和发送方式见本页“实验概述”及后续章节。以下带日期的“开发中”段落保留为当时记录；其中测试进度不代表当前门禁结论。统一候选仍须完成软件门禁，硬件验收为 NOT_RUN。
开发中：硬件接收错误锁存（2026-10-04，待统一测试/发布）
现有通用UART接收新增硬件错误观察：SDK通知FIFO溢出、接收缓冲满、帧错误、奇偶错误或BREAK后，该接收代际锁存失效。后续读取返回失败，未执行的规则与派生动作继续通过原来源检查拒绝；同次已读缓冲的后续文本帧也重新检查，不能把已观察错误后的尾部拼成有效规则帧。运行状态显示 UART_RX_FAULT_LATCHED，规则页分别显示五类“首故障”累计计数。每次接收代际只记录首先观察到的一项，不能据此推算丢失字节/帧总数。
先核对接线、波特率、数据位、奇偶与停止位，再显式停用/启用UART以恢复。内部同配置重启同样先结束旧驱动、清空旧缓冲，再建立新代际；迟到旧回调不能影响新代际，启动失败保持不可接收。不会自动恢复、重放旧数据或撤销已写输出。此观察器只覆盖通用UART；Modbus、蜂窝等专用协议端口保持各自驱动，不计入这里的硬件首故障统计。
可靠性边界：已安装Arduino Core 3的错误通知来自异步事件任务；公开注册接口返回 void，任务创建失败只能在SDK日志看到，事件队列还可能延迟或丢失通知。因此注册成功不能证明监控任务已运行；API明确给出 hardwareErrorDeliveryConfirmed=false，零计数不能证明线路正常。通知到达前已经交付的数据/动作无法追溯撤销，检查与物理输出也不是原子操作。本增量不承诺检出所有电气错误；未核验的旧SDK拒绝启用通用UART错误观察路径，不静默冒充支持。源码、实际方法提取运行回归与页面回归均已准备，尚未集中执行；未连接、刷写或操作设备，实物错误注入及恢复验收保持 NOT_RUN。
开发中：脚本与分组采集沿用原串口来源（2026-10-03 10:53，未测试/发布）
UART触发的命令脚本在每条命令、等待及主要复合步骤间检查原来源，失效或无法确认则结束本次脚本并停止规则余项。分组传感器采集在成员读取和整组发布前检查，失败组显示 uart_source_unconfirmed，不会把已读到的部分值作为成功整组发布。普通非UART触发保持原入口语义。
已写输出和已启动闪烁/呼吸任务不自动撤销；来源检查不是所有硬件、缓存和网络操作的原子提交。其它异步任务、单次采样内部与系统多阶段动作还未全面覆盖。源码及回归仅准备未运行，没有发布或操作设备，不能据此认定实物保护闭环已经完成。
开发中：共享电机命令继承串口来源（2026-10-03 10:22，未测试/发布）
UART规则提交到共享电机队列后，命令仍保留原串口来源，开始执行、等待处理器及分步读写时重新核对；来源变化或无法确认时结束命令，显示 uart_source_unconfirmed，外层规则停止余项。电机结果事件也保留来源，下级规则不能把退役串口事件当普通新输入。普通手动停止不会合并进可能因串口退役而被拒绝的旧停止命令，仍受原有容量、锁及总线条件约束。
检查与输出不是原子操作，已经开始的事务和实际写入不会撤回；写入ACK不表示电机物理到位或停止。本轮没有新增自动停车，独立电机MQTT报告的实例/映射绑定和失败保留仍需接续。源码及回归准备未运行，未发布或访问设备，脚本等其它回调、内存测量和实物验收继续待办。
开发中：串口来源变化时停止后续Modbus子命令（2026-10-03 09:51，未测试/发布）
UART触发的Modbus混合动作会在等待处理器、读取批次及控制命令间隔之后重新核对原串口来源。首次无法确认即结束本次动作并停止规则余项，轨迹显示 uart_source_unconfirmed；不会因随后恢复而在同批次继续。继电器/PWM/PID控制通知及规则系统重启通知也保留原来源，不能当成无关新事件。
已完成的写入、已提交的电机任务和已发出的报告不会撤回，底层已进入的事务/读取批次也可能继续到返回。共享电机结果、脚本等异步回调仍未全部覆盖；检查与实际输出不是原子操作。本增量及新增11组回归准备均待集中验证，未发布或操作设备，不代替接线、设备身份与实物验收。
开发中：事件联动继承串口来源（2026-10-03 08:52，未测试/发布）
UART文本规则的“触发事件”动作，以及异步/同步完成和取消事件，会把原串口来源继续传给下级规则。原串口已停止/重新初始化、配置变化或来源无法确认时，不再把旧事件当普通新事件继续联动；父规则的失败/取消记录仍保留，已经执行的动作不会回滚。普通非UART事件维持原入口行为。
事件触发可能同步运行其它规则；若这些规则改变了原来源，后续事件MQTT发布回调也会拒绝旧来源。提交事件不等于子规则执行成功或平台收到消息。复合动作内部的Modbus控制结果、系统事件及脚本回调还未全部绑定，检查与实际硬件/网络操作也不是原子事务。相关源码和回归用例仅准备，尚未集中测试、发布或实物验收。
开发中：排队期间的来源变化（2026-10-03 07:57，未测试/发布）
UART文本触发规则后会携带收帧时的配置版本与本地接收编号，等待执行或同步降级时保留原编号。串口停止/重新初始化、配置变化或无法确认来源时，拒绝准入或停止余下动作；每个动作开始及其等待延时后均重新检查。执行记录的 uart_source_unconfirmed 表示来源无法确认，可能是锁忙，不必然代表串口硬件故障；此前已执行的动作不会回滚。
这项改动仍未测试或发布，不能保证检查之后硬件绝不变化；显式事件/完成事件由上方08:52节接续，复合动作与底层回调仍未覆盖全部来源链。原子输出准入、协议故障、完整诊断和实物恢复继续待验收，不以排队字段存在作为通信成功证据。
开发中：规则文本接收状态（2026-10-03 07:25，未测试/发布）
外设执行页面增加本次启动的文本接收诊断：提交规则匹配尝试、超长帧、无效字节帧、读取失败、来源变化、发布时来源未确认及序列化失败。沿用页面刷新请求，不额外访问串口；旧固件缺少状态、请求失败或字段不完整时显示“未确认”，不能当成没有丢帧。
这些是所有参与规则文本接收源的独立累计事件，不能相加为丢帧总数；重启清零，计数达到上限后显示下限。零计数也不证明通信正常，提交匹配不代表规则执行或对端成功。诊断不覆盖Modbus/4G、手动二进制读取、硬件接收溢出或协议校验；未启用规则接收时没有这类观测。
源码及回归准备未集中测试，没有发布固件/Web或实物验证。来源绑定到规则排队/执行、完整故障恢复与长期稳定性仍待验收。本状态不包含原始串口载荷；其它匹配/执行日志仍可能记录规则值，不能据此认定全链路已脱敏。
开发中：串口重启后的数据来源（2026-10-03 06:51，未测试/发布）
通用UART每次实际初始化都会获得新的接收编号，配置没有变化也会更新。停止或初始化失败后编号失效；恢复后，不把旧驱动残留的半帧接到新接收流。规则文本接收会核对配置版本和接收编号，变化时丢弃至下一文本边界，不能保证恢复后第一帧保留。
这是本地驱动生命周期标记，不是设备对端身份、校验和或实际通信成功证明。相关源码和回归尚未集中验证，未发布固件/Web，也未操作设备。来源标记贯穿规则排队/执行、硬件RX溢出及协议故障诊断仍待完成。
开发中：规则文本接收边界（2026-10-03，未测试/发布）
规则的通用UART文本数据源按CR/LF或空闲边界收帧，最多160字节，中文按UTF-8字节计数。超长或含NUL的帧整帧丢弃，不将前缀/尾部当成独立规则输入；收到换行，或串口成功空读且至少500ms没有新字节后，才接收下一帧。持续输入不会因为达到160字节自动触发规则。
读取失败或部分帧期间配置版本变化也会丢弃至边界，避免拼接不同配置下的数据。分帧器日志会给出超长/无效字节原因，不打印原始载荷；其它规则日志不在此承诺内。完整配置和硬件恢复验收尚未完成。此入口是文本分帧，不是Modbus、二进制协议解码或对端身份校验；手动二进制读取仍使用独立接口。
以上源码及回归代码尚未集中验证，没有发布或在设备执行。同配置重启代际和局部诊断由上方新节接续；硬件缓冲溢出、完整质量诊断和排队规则来源绑定仍待完成。
实验概述
通用UART外设用于与外部设备交换串口数据。可用硬件控制器数量取决于芯片和当前资源占用；固件保留UART0供日志/控制台，通用外设从其余可用控制器分配。外设ID是逻辑名称，命名为 uart1 不会强制使用硬件UART1。
Modbus/RS485与通用UART由不同入口管理，不能把同一控制器同时用于协议栈和自定义文本。modbus / rs485 开头的外设ID属于协议保留约定，应通过协议配置核对。
硬件接线示例
下表仅用GPIO17/16说明信号顺序，不代表这组引脚适用于所有classic ESP32模块。启用前按目标板资源预检和实际接线选择，带PSRAM等模块尤其需核对占用。
| ESP32信号 | 示例GPIO | 连接对端 |
|---|---|---|
| RX | GPIO17 | 对端TX |
| TX | GPIO16 | 对端RX |
| GND | GND | 共地 |
ESP32使用3.3V逻辑电平，接RS232、RS485或不兼容电平设备时需要对应收发器。USB CDC是USB接口，不等同于物理UART0；开启USB CDC也不解除当前通用UART的UART0保留策略。
JSON配置示例
以下为外设配置片段，保持禁用；引脚数组顺序是 RX、TX。导入和启用前先核对板卡、资源占用和参数，不按外设名称猜测物理控制器。
{
"peripherals": [
{
"id": "uart_demo",
"name": "外部文本串口",
"type": 1,
"enabled": false,
"pinCount": 2,
"pins": [17, 16],
"params": {
"baudRate": 9600,
"dataBits": 8,
"stopBits": 1,
"parity": 0
}
}
]
}| 参数 | 当前配置校验 |
|---|---|
baudRate | 1～5000000；对端和实际硬件能否稳定使用该速率另行验证 |
dataBits | 5、6、7、8 |
stopBits | 1、2 |
parity | 0=无、1=奇、2=偶 |
运行状态中的控制器编号、帧格式和本地连接状态用于核对分配结果；本地初始化成功不表示对端已连接或通信正确。
外设执行：平台值发送
- 先配置并核对
uart_demo外设，在现场授权范围内启用。 - 新建禁用规则，触发器选择“平台触发”“设置模式”，数据源标识与平台下发字段对应。
- 动作选择“串口发送”（动作29），目标选择
uart_demo。发送平台原值时选择使用接收值；需要固定前后缀时使用明确的$value文本模板。 - 保存并复核后决定是否启用。以
Hello UART为例，当前示例的TX为GPIO16；发送结果和对端接收内容分别确认。
规则单次展开载荷最多 256字节，中文按UTF-8字节计数；空载荷或超限会拒绝。JSON文本封装不能改变已声明的目标外设，也不是Modbus报文生成器。
UART_LOCAL_ACCEPTED_PEER_UNVERIFIED仅表示本地驱动接受全部字节，不证明对端收到或执行。UART_WRITE_UNCONFIRMED可能已发出部分数据，不应盲目重试；固件不会自动追加换行或读取对端回复。
接收与验收边界
规则文本接收按CR/LF或确认空闲边界收帧，单帧最多160字节。超过长度或含NUL的帧整帧丢弃；500ms空闲边界必须由成功空读确认。此规则帧上限和发送256字节上限都不是硬件接收缓冲区容量承诺。
登录后的 GET /api/peripherals/read?id=uart_demo 是手动收取接口，每次最多读取当前缓冲的128字节，不等待完整帧。它与规则接收消费同一UART接收流；上方历史记录的“独立接口”不表示独立缓冲或旁路复制。规则接收期间不要把它用作轮询状态探针，否则规则可能缺字节或边界。仅查看本地运行状态可用 GET /api/peripherals/status?id=uart_demo；该UART状态入口不收取RX，返回的计数/可读字节数是本地快照，不证明对端或帧完整。
手动收取成功时，data.readQuality=bytes 或 no_data、data.length 和 data.hex说明本次收取结果，data.frameVerified=false。有数据时仅对可打印ASCII及CR/LF/TAB提供 data.text，二进制及非ASCII字节应使用hex；no_data不代表线路健康。UART_BUSY、UART_CONFIG_CHANGED、UART_NOT_READY表示本次未收取；UART_READ_FAILED、UART_STATE_UNAVAILABLE或响应内存失败可能已消耗字节，不能自动重试或把失败当作“没有收到”。
串口停用、重建或来源无法确认时，相关规则停止后续动作；已开始的传输和已产生的物理效果不能撤回。接收诊断不覆盖所有硬件溢出或协议故障，也不证明通信健康。
当前设备身份、交叉接线、实际收发、停启恢复与长稳均为 NOT_RUN。本页和上方保留的历史开发记录不能作为设备已部署或实物已通过的证明。