Procházet zdrojové kódy

485发送队列改为按发送起点固定节拍,避免80保活与03读卡背靠背

- config新增SERIAL_CMD_INTERVAL(env同名,默认0.20s)
- serial_port worker节拍锚点从「命令完成+100ms空闲」改为「本条发送起点+T」
  同一队列内相邻帧起拍间隔恒定(正常应答时);超时帧耗时>T则下一条立即发不回溯
- 解决同台线架0x80秒回81后仅~100ms即发0x03、而轮间睡5s的忽近忽远
- 新增节拍单测,全量146测试通过
wenhongquan před 2 týdny
rodič
revize
bd7321e7a6
4 změnil soubory, kde provedl 84 přidání a 10 odebrání
  1. 35 0
      AGENTS.md
  2. 4 0
      backend/config.py
  3. 19 10
      backend/modules/serial_port.py
  4. 26 0
      backend/tests/test_serial_port.py

+ 35 - 0
AGENTS.md

@@ -197,6 +197,15 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 - MODBUS-RTU 协议实现在 `backend/modules/modbus_rtu.py`;串口封装在 `backend/modules/serial_port.py`。
 - 注意:硬件通信固定 6 字节(12位) 卡号,MQTT 边界拼成 8 字节(16位) `jumper_uid`(前 4 位 DTU 号 + 后 12 位卡号),适配逻辑在 `app.py` 的 `_to_mqtt_jumper_uid` / `_from_mqtt_jumper_uid`。
 
+### 485 指令统一发送队列与节拍(2026-10-30)
+
+- **所有 485 帧都在同一个队列里串行发**:`serial_port.py` 的 `SerialPort` 有一个 `_cmd_queue` + 唯一 worker 线程;`send_and_wait` / `send_raw` / `wait_response` / `send_data` 全部入队。`modbus_rtu.py` 的 `0x80` 保活、`0x03` 读卡、`0x10` 写卡、配置地址帧最终都走它——扫描线程、网页手动操作、MQTT 下发共用同一队列,物理上不会并发撞帧。
+- **节拍锚点是「发送起点」,不是「命令结束」**(2026-10-30 修正):worker 维护 `_next_cmd_time = 本条发送起点 + SERIAL_CMD_INTERVAL`,逐条按固定起拍间隔发。旧实现锚在「命令完成时刻 + 固定 100ms 总线空闲」,导致同一台线架 `0x80` 秒回 81 后仅 ~100ms 就背靠背发 `0x03`(同队列也贴脸),而轮与轮之间又睡 `poll_interval_ms`(默认 5s),节拍忽近忽远。
+- 配置:`config.py` `SERIAL_CMD_INTERVAL`(env 同名,**默认 0.20s**)。⚠️ 9600bps 下读卡(149B)/写卡(152B)单帧约 155ms,此值必须大于单帧耗时。
+- 若上一条命令本身耗时超过一个节拍(如无应答等满超时 `PANEL_QUERY_TIMEOUT=0.5s`),下一条**不补觉、立即发**(半双工不可能重叠,也不回溯过去时间);所以"固定间隔"只在正常应答时严格成立,超时那一拍会被撑长,属正常。
+- 轮询线程 `port_poll_loop` 每轮之间睡 `poll_interval_ms`(dtu_config,默认 5000ms);这是「轮间」间隔,和队列内「帧间」节拍是两层,别混淆。
+- 串口调试页时间戳只精确到秒(`%H:%M:%S`),0.2s 的相邻两帧在界面上看似同一瞬间,实为队列正常节拍。
+
 ### RS485 方向脚软件控制(2026-10-29 新增,可选)
 
 板载 TTL 转 RS485 模块若是**自动方向**且切换太慢,会出现典型症状:**DTU 发帧正常(总线上能抓到),但从机(线架)的回包一个字节都收不到**(`/proc/tty/driver/serial` 里 `tx` 涨、`rx` 不动),而同一帧用 PC 的 USB-RS485 发出去从机就正常回复。
@@ -352,6 +361,32 @@ journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
 - 更新代码后用 scp 覆盖对应文件再 `systemctl restart dzxj_dtu`。
 - 本地工作目录 = 本仓库;改代码后注意同步到设备。
 
+## Windows 便携版 exe(2026-10-30)
+
+> 用途:把同一套后端+前端打成 **单文件 exe**,在 Windows 电脑上用 USB-RS485 现场调试/演示线架。
+> **不是**给 RK 板子的安装包,设备端仍跑 Linux。
+
+- **产物**:`dist/dzxj_dtu.exe`(约 14.7 MB,PE32+ x64 控制台程序,双击运行后自动开浏览器 `http://127.0.0.1:5001/`)。
+- **构建**(Windows):`packaging\build_exe.bat`(纯 ASCII,别往里写中文,UTF-8 bat 会被 cmd 解析错乱)。
+  等价命令:`python -m PyInstaller --noconfirm --clean --distpath dist --workpath build\pyinstaller packaging\dzxj_dtu.spec`
+- **入口链路**:`packaging/launcher.py`(设环境变量 → 探测 USB 串口写 `data/serial_config.json` → 后台等端口就绪开浏览器 → `import app; app.main()`)
+  → `backend/app.py` 的 `main()`(原先的 `if __name__ == '__main__'` 块已抽成函数,源码运行改为末尾 `main()`)。
+- **路径抽象**:`backend/paths.py`(新增)
+  - `RESOURCE_ROOT`:打包后 = `sys._MEIPASS`,源码运行 = 仓库根目录(`STATIC_FOLDER` 用它)。
+  - `DATA_DIR`:打包后 = **exe 同级 `data/`**(可用 `DZXJ_DATA_DIR` 覆盖),源码运行 = `backend/`。
+    `serial_config.json` / `mqtt_config.json` / `dtu_config.json` / `devices.json` / `backups/` 全部走它,
+    **否则 onefile 模式下 `__file__` 指向临时解压目录、退出即删,配置全丢**。
+  - `DEVICE_CONFIG_FILE`:`/root/dzxj_dtu/` 存在(设备)时仍用老路径,否则落 `DATA_DIR/devices.json`。
+  - `SYSTEM_ENV_FILE`:`/etc/default/` 存在时用 `/etc/default/dzxj_dtu`,否则落 `DATA_DIR/dzxj_dtu.env`。
+- **Windows 差异**:DHT11(无 GPIO)和 Nextion 串口屏(无 `/dev/ttyS9`)由 launcher 置 `DHT11_ENABLED=false` / `NEXTION_ENABLED=false` 关闭;
+  `/api/system/restart_service` 直接返回 400;`os.uname()` 换 `platform.node()`;OTA/静态 IP 等依赖 Linux 工具的功能不可用。
+- **依赖**:`packaging/requirements_windows.txt`(无 gpiod,含 pyinstaller;Werkzeug 必须钉 2.3.7,否则 Flask 2.3.3 会因 Werkzeug 3.x 缺少 `url_quote` 起不来)。
+- **已知坑**:
+  - PyInstaller 单文件 = 每次启动解压到 temp,首启 2-5s 属正常。
+  - `modules/` 是命名空间包(无 `__init__.py`),必须在 spec 的 `hiddenimports` 里逐个子模块声明。
+  - 构建机:Windows 10/11 + Python 3.10+ + Node(前端 dist 已存在时不需要 Node)。
+  - 该 Windows 构建机 SSH(`pc@192.168.20.155`)认证偶发 `Permission denied`,重试即可;`tar.exe` 解包会被拦(拒绝访问),传文件用 `scp -r`。
+
 ## 排障速查
 
 | 症状                         | 排查                                                                                                                                |

+ 4 - 0
backend/config.py

@@ -20,6 +20,10 @@ DEFAULT_SERIAL_TIMEOUT = 0.1  # 默认串口读超时时间(秒),轮询总
 DEFAULT_SERIAL_PORT = os.getenv('DEFAULT_SERIAL_PORT') or '/dev/ttyS8'
 SERIAL_RECONNECT_INTERVAL = 5  # 串口重连间隔(秒)
 SERIAL_RECONNECT_MAX_RETRIES = 5  # 串口最大重连次数
+# 串口指令统一发送节拍(秒):所有 0x80 保活 / 0x03 读卡 / 0x10 写卡 / 配置地址帧
+# 都经同一个发送队列,按「发送起点」固定间隔逐条发出,避免同台线架保活帧与读卡帧背靠背。
+# 注意 9600bps 下读卡(149B)/写卡(152B)单帧约 155ms,此值必须大于单帧耗时,默认 0.20s。
+SERIAL_CMD_INTERVAL = float(os.getenv('SERIAL_CMD_INTERVAL', '0.20'))
 # RS485 方向控制 GPIO(可选)。格式 "gpiochip0:25" 或 "gpiochip0:25:low"(low = 低电平为发送态)。
 # 用于板载 TTL 转 RS485 模块自动方向切换不可靠(发完立刻收不到回包)的场景,
 # 把模块的 DE/RE 接到该 GPIO,由软件在发送前拉 TX、发送完成后切回 RX。

+ 19 - 10
backend/modules/serial_port.py

@@ -195,17 +195,23 @@ class SerialPort:
         # 同步接收模式:send_and_wait 活动时暂停后台读取线程,防止响应被读线程抢走
         self._sync_receive_active = False
         self._sync_lock = threading.Lock()
-        # 串口发送队列:所有发送指令统一排队,按最小间隔逐个发送,避免总线冲突
+        # 串口发送队列:所有发送指令统一排队,按固定节拍(发送起点间隔)逐个发送,
+        # 既避免总线冲突,也保证相邻指令(如 0x80 保活 与 0x03 读卡)不会背靠背贴得太近。
         self._cmd_queue = queue.Queue()
-        self._cmd_min_interval = 0.10  # 相邻指令最小间隔 100ms
-        self._last_cmd_time = 0
+        self._cmd_min_interval = 0.20  # 相邻指令「发送起点」最小间隔(秒),默认值
+        try:
+            import config as _app_config
+            self._cmd_min_interval = float(getattr(_app_config, 'SERIAL_CMD_INTERVAL', 0.20))
+        except Exception:
+            pass
+        self._next_cmd_time = 0.0  # 下一条指令允许开始发送的时刻(发送起点锚点)
         self._cmd_worker_thread = threading.Thread(target=self._cmd_worker, daemon=True)
         self._cmd_worker_thread.start()
         # 启动后台重连监控线程,确保断线后可持续自动恢复
         self._start_reconnect_monitor()
 
     def _cmd_worker(self):
-        """串口发送队列工作线程:统一按最小间隔逐个发送指令"""
+        """串口发送队列工作线程:统一按「发送起点」固定节拍逐个发送指令"""
         logger.info("启动串口发送队列工作线程")
         while True:
             try:
@@ -213,12 +219,17 @@ class SerialPort:
                 if item is None:
                     break
 
-                # 确保相邻指令最小间隔
-                elapsed = time.time() - self._last_cmd_time
-                if elapsed < self._cmd_min_interval:
-                    time.sleep(self._cmd_min_interval - elapsed)
+                # 以「开始发送的时刻」为锚保证等间隔:把本条命令排到上一条起拍之后
+                # 满一个节拍。若上一条命令本身耗时超过一个节拍(如读卡等满超时),
+                # 则不补觉、立刻发(半双工总线上不可能重叠,也不回溯过去的时间)。
+                now = time.time()
+                if now < self._next_cmd_time:
+                    time.sleep(self._next_cmd_time - now)
 
                 cmd_type = item.get('type')
+                # 记录本条「发送起点」,下一条以此为基准排满一个节拍
+                send_start = time.time()
+                self._next_cmd_time = send_start + self._cmd_min_interval
                 try:
                     if cmd_type == 'send_and_wait':
                         result = self._do_send_and_wait(
@@ -241,8 +252,6 @@ class SerialPort:
                     logger.error(f"执行串口命令失败: {e}")
                     result = {'error': str(e)}
 
-                self._last_cmd_time = time.time()
-
                 callback = item.get('callback')
                 if callback:
                     callback(result)

+ 26 - 0
backend/tests/test_serial_port.py

@@ -155,6 +155,32 @@ class TestSerialPort:
         self.serial_port.data_callback("Test data")
         self.data_callback.assert_called_with("Test data")
 
+    @patch('modules.serial_port.serial.Serial')
+    def test_command_start_times_paced_by_interval(self, mock_serial):
+        """队列内相邻指令的「发送起点」间隔应被节拍限制(不再背靠背)。"""
+        mock_instance = _make_serial_instance()
+        written_at = []
+
+        def _record_write(data):
+            written_at.append(time.monotonic())
+            return len(data)
+
+        mock_instance.write.side_effect = _record_write
+        mock_serial.return_value = mock_instance
+        self.serial_port.connect('COM1', 9600)
+
+        # 固定节拍 0.2s(send_raw 不等应答,write 几乎瞬时完成)
+        self.serial_port._cmd_min_interval = 0.2
+        self.serial_port._next_cmd_time = 0.0
+
+        self.serial_port.send_raw(b'\x01\x80' + b'\x00' * 12 + b'\x54\x01')
+        self.serial_port.send_raw(b'\x01\x03\x00\x02\x00\x48\xe4\x3c')
+
+        assert len(written_at) == 2
+        gap = written_at[1] - written_at[0]
+        # 第二条必须被排到第一条起拍之后约一个节拍(允许调度误差),不能背靠背
+        assert 0.18 <= gap < 0.4, f"相邻发送起点间隔异常: {gap:.3f}s"
+
 
 if __name__ == "__main__":
     pytest.main(["-v", __file__])