AGENTS.md 33 KB

DZXJ DTU 项目 AGENTS.md

本文件记录本项目开发/维护时需要注意的关键信息,方便下次快速上手。

注意每次改动需要更新本文件,这非常重要!!!!!!!!

项目概览

  • 设备:Rockchip RK3588 嵌入式开发板(hostname=ido,aarch64),作为 DTU(数据传输单元)运行。
  • 应用:dzxj_dtu —— 串口(MODBUS-RTU/RS485) ↔ MQTT 网关,带 Web 管理界面(Flask + Socket.IO + Vue 前端)。
  • 代码部署位置(设备上):/root/dzxj_dtu/,代码库在本仓库。
  • 设备 IP:eth1 = 192.168.199.149(远程管理用),wlan0 = 192.168.10.3,实际 IP 见串口屏显示。
  • 系统服务:
    • dzxj_dtu.service → /root/dzxj_dtu/backend/app.py(venv Python)
    • frpc.service → FRP 客户端(stcp 映射 SSH + http 域名映射 80 端口)
    • easytier.service → EasyTier VPN(组网)
    • mosquitto.service → 本地 MQTT Broker(:1883)
    • nginx.service、mysql.service 等

第二块板:RK3562(Ubuntu,当前 192.168.10.190)

该板原为 Android 13,2026-09 已重刷为 Ubuntu 20.04 原厂镜像,sshd 自带可用,无需再自建 SSH。

  • 系统:Ubuntu 20.04.3 LTS (Focal),内核 5.10.226 aarch64,hostname=ido。
  • 网络:wlan0 DHCP,2026-10-27 为 192.168.10.190/24(曾用 .167/.189,eth 口未启用),docker0 = 172.17.0.1。
  • 登录:ssh root@192.168.10.190,密码 123456,直接 root shell。
  • 自带服务:mosquitto(:1883)、mysql(:3306 仅本地)、smbd(:139/445)、adbd(:5555 网络 adb)。
  • 已部署 dzxj_dtu(2026-09):
    • 代码 /root/dzxj_dtu/(backend + frontend/dist + venv,venv 内 gpiod==1.5.4)。服务 dzxj_dtu.service(/root/dzxj_dtu/venv/bin/python app.py,WorkingDirectory backend,开机自启),Flask 监听 0.0.0.0:5001。
    • nginx 80:站点 /etc/nginx/sites-available/dzxj_dtu.conf(root /var/www/html,代理 /api、/socket.io → :5001);前端同时放了 frontend/dist 和 /var/www/html(别忘两处都更)。
    • 2026-10-27 部署 V5 版本:backend/app.py、config.py、modules/modbus_rtu.py、modules/config_backup.py + frontend/dist(同步 /var/www/html);部署前备份在 /root/dzxj_dtu_deploy_backup_20261027_112650。验证:服务 active、/dev/ttyS8 串口已连、/api/panel/config_address_status 正常、nginx 返回新 bundle(index-7c00abba.js)。
    • 环境变量 /etc/default/dzxj_dtu:本板 DHT11 已接在 gpiochip0 line19(GPIO0_C3_d,同 149),DHT11_ENABLED=true,5s 轮询;C 读取器 backend/scripts/dht11_reader 已编译,实测 27°C/14% 正常(偶发校验失败属正常抖动)。
    • 串口:serial_config.json 指向 /dev/ttyS8 @9600(本板 RS485,实测在发 0x80 地址查询轮询);串口屏端口见下方「串口屏(Nextion)接线与刷新」。
    • MQTT:mqtt_config.json 仍是占位(localhost:1883),需在网页里配 xt.wenhq.top:8581 之类并连接,连上后才会持久化自动重连。

第三块板:RK 板(当前 192.168.199.174,严格 80/81 现网验证板)

  • 登录:ssh root@192.168.199.174,密码 123456,hostname=ido。
  • 部署:代码 /root/dzxj_dtu/(venv:/root/dzxj_dtu/venv/bin/python),服务 dzxj_dtu.service,串口 /dev/ttyUSB0 @9600(CH340 USB-RS485)。改代码备份命名 app.py.bak_YYYYMMDD_HHMMSS。
  • 2026-10-29 18:49 部署严格图解版:backend/app.py + config.py(80/81 口径、PANEL_KEEPALIVE_MISS_LIMIT=2、废弃自动 82/83、每次重新上线先 0x10 再读卡、冲突防抢占);备份 app.py.bak_20261029_184845(前一版 app.py.bak_20261029_184636)。
  • 当前绑定:devices.json = {"510012001100004c30313356": 1}(地址 1)。
  • 2026-10-29 19:11 部署读卡兜底兼容版:在严格图解版基础上加 config.py PANEL_READ_FALLBACK_KEEPALIVE(默认 true);备份 app.py.bak_20261029_191143(config 同名)。
  • 现网状态(19:13 后):现场网页先进入「配置地址」、又调 POST /api/panel/unbind 把绑定清空(devices.json={});随后 pyserial 绕过 App 直发原始帧,地址 1 的 80 探测/03 读卡均 0 字节回包、地址 2–5 也全超时——/dev/ttyUSB0 connected、CH340 在、能发不能收,判为物理层/线架侧无响应(线架断电/485 A-B 松脱或接反/停在配置地址态)。线架恢复应答后未绑定全 0 探测会自动重新注册。

串口屏(Nextion)接线与刷新(2026-10-10 重点)

  • 当前网络:本板 wlan0 为 DHCP,现为 192.168.10.190(eth 口未启用)。
  • HMI 默认文字 ≠ 实际 IP:屏工程默认 t1.txt="192.168.100.123"、t2.txt="终端 0"、t4.txt="V2.0"、g0.txt="MQTT:OK,在线终端:10"、t3.txt="备注:"。屏上一直显示 192.168.100.123 就说明 App 从未成功写过屏,不是 App 算错 IP。
  • 屏供电必须 5V(VCC 接 5V,GND 与板子共地),3.3V 供电会导致屏显示正常但串口不工作。
  • 接线方案(实测):
    • ✅ USB-TTL(CH341)转接:屏接 CH341 模块,模块插板子 USB 口 → 板子上是 /dev/ttyUSB0,读写控件全部正常(已实测)。配置 NEXTION_SCREEN_PORT=/dev/ttyUSB0。
    • ✅ 直连板子 GPIO 排针 UART9(当前方案):UART9_TX_M1/GPIO3_C2_d(pin114)、UART9_RX_M1/GPIO3_C3_d(pin115) 即 SoC 的 TTL UART9(= /dev/ttyS9,3.3V),屏 RX←板 TX、屏 TX→板 RX、GND 共地、屏 VCC 接 5V。已实测全通(读写控件正常,ttyS9 接收计数正常增长)。
    • ⚠️ 直连 UART3 不通:UART3_TX_M1/GPIO3_B7_d(pin111)、UART3_RX_M1/GPIO3_C0_d(pin112)(= /dev/ttyS3)短接回环测试通过(收发正常),但接该屏实测不通,原因未查清(不排除当时接触不良;该口也接 RS232 收发器)。
    • ❌ ttyS8 是 RS485(A/B,配线架总线,接屏不通);ttyS1 被蓝牙占用。ttyS0/2/4/5/6/7 在设备树里是 disabled(无设备节点,要用需改 DTB 并确认引脚引到了排针)。
  • 配置:屏端口在 /etc/default/dzxj_dtu(NEXTION_SCREEN_PORT=),改完 systemctl restart dzxj_dtu。
  • 屏幕刷新逻辑修复(app.py,2026-10-10):

    • 原逻辑:refresh_screen_panel() 在无 panel(panel_count=0,未发现配线架)时直接返回,IP 监测线程也要求 panels 非空 → App 永远不写屏。
    • 现逻辑:抽出 _send_screen_header()(t1 IP / t2 终端名 / t4 版本 / g0 MQTT 状态),无 panel 时也会下发:开机连屏后、IP 变化时、MQTT 状态变化时。刷新队列协议扩展:screen_refresh_queue.put((None,)) = 只刷静态信息。
    • 验证:IP 变化日志出现后,屏 t1.txt 会更新为实际 IP(/tmp/screen_poke.py <port> 可手工读写验证)。
  • frpc(2026-09 装):/opt/frp/frpc(v0.71.0)+ /opt/frp/frpc.toml + frpc.service(开机自启,已连上 frps)。

    • frps:device.wenhq.top:8580,token gx@12345678。
    • stcp:167-ssh(local 22),secretKey 167-ssh-sk → 访问端配 visitor(serverName=167-ssh)。
    • http:167-http(local 80),subDomain pxj167(如子域被占/改名,改 toml 后 systemctl restart frpc)。
  • 附:tools/rkssh/ 是此前为 Android 系统写的 Go 版 SSH 服务,Ubuntu 下用不到,保留仅作历史记录(旧 Android 记录:192.168.199.235、密码 123456)。

远程访问方式

方式 1:FRP stcp 映射 SSH(推荐)

149 上跑 frpc(仅客户端,不跑 frps),通过 stcp 模式把本地 22 端口映射到公网 frps 服务器。

  • frps 服务器:device.wenhq.top:8580,token = gx@12345678(frps 部署在外部,不在本设备)。
  • 配置:/opt/frp/frpc.toml
  • 服务:systemctl status frpc / systemctl restart frpc

frpc 配置摘要:

serverAddr = "device.wenhq.top"
serverPort = 8580
auth.method = "token"
auth.token = "gx@12345678"

[[proxies]]
name = "149-ssh"
type = "stcp"
localIP = "127.0.0.1"
localPort = 22
secretKey = "149-ssh-sk"

访问端(你的电脑)需要配置 visitor 才能连:

serverAddr = "device.wenhq.top"
serverPort = 8580
auth.method = "token"
auth.token = "gx@12345678"

[[visitors]]
name = "149-ssh"
type = "stcp"
serverName = "149-ssh"
sk = "149-ssh-sk"
bindPort = 6000

然后 ssh root@127.0.0.1 -p 6000(密码 123456)即可连到 149 的 22 端口。

方式 2:FRP http 域名映射 80 端口

frpc 里已有 http 代理,把本地 80 端口映射成 pxj 子域名:

[[proxies]]
name = "149-http"
type = "http"
localIP = "127.0.0.1"
localPort = 80
subDomain = "pxj"

通过 http://pxj.<frps主域名> 访问(具体子域解析规则由 frps 端配置决定)。

方式 3:EasyTier VPN 组网

  • 配置:/etc/systemd/system/easytier.service
  • 网络名 pxjdtu / secret 123456,peer 服务器 remote-mange.dnnbuild.com:25700
  • 必须 --no-tun 模式(本设备内核无 tun 模块,/dev/net/tun 不可用,modprobe tun 失败)。
  • 用 --port-forward tcp://0.0.0.0:2222/10.11.21.0:22 做端口转发,访问 127.0.0.1:2222 可到 MacBook 的 SSH(仅演示,10.11.21.0 是当时 peer 的虚拟 IP,会变)。
  • 状态查询:/home/admin/easytier-cli node / peer / peer-center。
  • 已知限制:--no-tun 模式下虚拟 IP(10.11.21.0/24)不会加到系统路由表,ping/直接 ssh 10.11.21.x 不通;要访问 peer 服务只能走 port-forward。想要完整虚拟网需在有 TUN 支持的设备上跑 easytier。

DHT11 温湿度读取

工作方式(重点!)

读取优先走 C 语言读取器,Python gpiod 只作回退。

  1. C 二进制读取器:/root/dzxj_dtu/backend/scripts/dht11_reader

    • 源码:backend/scripts/dht11_reader.c(用 libgpiod C API,open-drain + 高速采样)
    • 编译命令:gcc -O2 -o dht11_reader dht11_reader.c -lgpiod(设备已装 libgpiod-dev)
    • 用法:dht11_reader [chip] [line],默认 gpiochip0 19
    • 输出 JSON:{"valid":true,"humidity":43,"temperature":31,"raw":[...],"checksum":76}(温湿度为整数,无小数)
    • 二进制必须存在,否则回退到 Python gpiod,而 venv 里的 gpiod API 不兼容,会读取失败(症状:日志报 module 'gpiod' has no attribute 'Chip' 或读到 0.0)
  2. Python gpiod 回退:backend/modules/dht11_sensor.py

    • 设备 venv 装的是 pip gpiod 1.5.4,API 与系统 apt 的 python3-libgpiod 1.4.x 完全不同:
      • gpiod.Chip(...)(1.4.x) vs gpiod.chip(...)(1.5.x)
      • gpiod.LINE_REQ_DIR_OUT vs gpiod.line_request.DIRECTION_OUTPUT
      • line.request(consumer=..., type=...) vs line.request(type=...)(1.5.x 无 consumer 参数)
      • 1.5.x chip 对象无 close() 方法
    • 代码已加了兼容层(_gpiod_chip_class、常量映射),但优先靠 C 二进制,尽量别依赖这个回退。

配置(环境变量,无默认值则使用 config.py 默认)

变量 默认 说明
DHT11_ENABLED true 是否启用
DHT11_GPIO_PIN 无 GPIO line 号(设备上为19)
DHT11_GPIO_CHIP gpiochip0 GPIO chip
DHT11_POLL_INTERVAL 5 读取间隔秒
DHT11_SIMULATE false 是否模拟数据
  • GPIO 19(RK 平台 GPIO0_C3 系)接 DHT11 data 脚,DHT11 需上拉电阻(模块自带)。
  • 若 DHT11_ENABLED=true 但未配 GPIO_PIN 且非模拟,会跳过传感器启动并打 warning。

验证

/root/dzxj_dtu/backend/scripts/dht11_reader gpiochip0 19
# 期望输出: {"valid":true,"humidity":xx,"temperature":xx,...}
journalctl -u dzxj_dtu | grep -E 'DHT11|环境传感器'
# 正常: "DHT11 本地传感器数据已处理: 温度=31.0°C, 湿度=43.0%"

MQTT 相关(重点)

  • 本地 mosquitto broker 跑在 :1883。
  • 应用连接的是外部 MQTT(经网页配置):当前 xt.wenhq.top:8581。
  • MQTT 配置会持久化到 /root/dzxj_dtu/backend/mqtt_config.json:
    • 通过 Web /api/mqtt/connect 连接成功后自动 save_mqtt_config()。
    • 服务重启后 __main__ 里会 auto_connect_mqtt() 读取该文件自动重连。
    • 若没有该文件或连接失败,MQTT 不会自动连接,需在网页手动连一次。
  • 关键函数(backend/app.py):save_mqtt_config() / load_mqtt_config() / auto_connect_mqtt() / mqtt_connect()(API /api/mqtt/connect)。
  • MQTT 客户端封装:backend/modules/mqtt_client.py(paho-mqtt==1.6.1,重连无限尝试,max_reconnect_attempts=0)。
  • 主题前缀默认 线架系统,DTU 协议主题格式:{topic_prefix}/{customer_id}/dtu/{dtu_id}/{topic}。

串口 / RS485

  • 设备串口:/dev/ttyS8 @ 9600,连接配置持久化在 /root/dzxj_dtu/backend/serial_config.json。
  • 2026-10-29 现网状态:app 跑在 /dev/ttyUSB0(CH340 USB-RS485),因为板载 ttyS8 的 485 收发器实测「能发不能收」——DTU 发查询后 tx 涨、rx 一动不动,同一帧用 USB-485 从总线发就一切正常。详见下方「RS485 方向脚软件控制」。
  • 服务启动时 auto_connect_serial() 自动重连。
  • 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。

RS485 方向脚软件控制(2026-10-29 新增,可选)

板载 TTL 转 RS485 模块若是自动方向且切换太慢,会出现典型症状:DTU 发帧正常(总线上能抓到),但从机(线架)的回包一个字节都收不到(/proc/tty/driver/serial 里 tx 涨、rx 不动),而同一帧用 PC 的 USB-RS485 发出去从机就正常回复。

  • 实现:serial_port.py 的 Rs485Direction 类,把所有写路径统一收口到 _rs485_write():配置了方向 GPIO 时,发送前拉 TX 电平 → ser.write()+flush()(tcdrain 等最后一位发完)→ 立刻切回 RX 电平。
  • 配置(环境变量,/etc/default/dzxj_dtu):
    • SERIAL_RS485_DIR_GPIO=gpiochip0:25(格式 chip:line;低电平为发送态则写 gpiochip0:25:low)
    • SERIAL_RS485_DIR_PRE_DELAY=0.001(切到发送态后等待秒数)
    • SERIAL_RS485_DIR_POST_DELAY=0.001(发完等待秒数再切回接收)
  • 未配置该变量时行为与原来完全一致(不控制方向);gpiod 缺失/申请失败会自动降级,不影响串口主流程。
  • 前提:485 模块必须有可接出的 DE/RE 脚;纯自动流向模块(无 DE 脚)无法软件修复,只能换模块或用 USB-RS485。
  • 注意:RK3562 EVB3562 的 ttyS8 只复用了 TX/RX 两个脚(uart8m0-xfer),RTS 没有引出来,设备树也没有 rs485 属性,所以不能靠内核 RS485/RTS 模式解决。

V5 协议(2026-10-23)重点

协议文档:DTU和节点之间协议 V5.docx。寄存器地址:

地址 内容 说明
0x0000 网络通断 保留不用(已去除)
0x0001 24 个 RGB 灯 保留不用(灯由配线架自己控制)
0x0002 批量卡号读 标准 0x03 读 72 寄存器 = 144 字节,24 路×6 字节
0x0003 设置卡号 0x10 写 144 字节,24 路×6 字节

地址保活 / 协商(80 ↔ 81,82/83 已废弃,2026-10-29 按图解重写):

权威口径见仓库外图解 /Users/wenhongquan/Downloads/DTU与配线架通信协议图解.html(80/81 口径)。 仅保留 80 请求 ↔ 81 应答一对帧,不发 82、83。

  • 保活请求 16B:[addr][0x80][12字节 UID 域][CRC_L][CRC_H]
    • UID 域 = 绑定①(addr↔UID)的值;已绑定地址始终带绑定 UID,未绑定地址填 12 字节全 0(探测)
  • 应答 16B:[addr][0x81][12字节线架自身 UID][CRC_L][CRC_H]
    • 0x81 最高位为 1,不是 MODBUS 异常帧(解析时不能按 fc & 0x80 判异常)
    • 收到 81 后本地用返回 UID 对照绑定①核对身份,匹配即建立在线,不发确认帧
  • 82/83 已废弃:纸面 V5 文档里的 [addr][0x82][UID][CRC] / [addr][0x83][UID][CRC] 现场固件不用;自动注册/接管流程不再调用,仅保留 confirm_address() 与两个手动调试 HTTP 接口
  • 文档样例(CRC 已核对):01 80+12×00 → 54 01;81 样例 01 81 51 00 12 00 11 00 00 4C 30 31 33 56 D0 D3
  • 实现:modbus_rtu.py 的 build_address_query_request / parse_address_query_response;客户端 query_address(addr, uid=None)。confirm_address()/build_address_confirm_request 仅留作手动调试

批量读卡恢复标准 MODBUS 0x03(帧内不再带 UID):

  • 请求 8B:[addr][0x03][0x00][0x02][0x00][0x48][CRC_L][CRC_H](文档样例 01 03 00 02 00 48 E4 3C)
  • 响应 149B:[addr][0x03][0x90][144字节卡数据][CRC_L][CRC_H]
  • 过渡期兼容旧 V4 的 161B 响应(帧尾多 12B UID,解析时忽略,不参与绑定)
  • 实现:build_read_cards_request(addr) 与 read_all_antenna_cards(addr);常量 LEGACY_UID_RESPONSE_LEN=161

配置地址状态(刷配置卡设置线架地址,V5 新增):

  • DTU 广播进入配置地址状态:aa b7 00 07 80 00 00 ff 00 00 02 64 03(CONFIG_ADDRESS_ENTER_FRAME,硬编码)
  • 线架读到配置卡后应答 8B:55 00 00 02 ANTLIST ADDR XOR 03
    • ANTLIST = 读到配置卡的天线号,ADDR = 线架采纳的新地址,XOR = 55^00^00^02^ANTLIST^ADDR^03
    • 解析时在接收缓冲里扫描有效 8 字节帧(parse_config_address_response),容忍前面的杂散字节
  • DTU 收到应答后把新地址记为 pending_address,恢复轮询后优先探测该地址并自动注册/换架接管

设置卡号协议(非标准 MODBUS 0x10,重点!):

  • 实物帧格式(现网按此实现,已验证 ACK 正常):[addr][0x10][0x00][0x03][0x00][0x90][144字节数据][CRC_L][CRC_H]
    • 无 byte count 字段(与标准 MODBUS 0x10 不同),数量字段 0x0090=144 直接表示字节数,整帧 152B
    • ⚠️ 图解里 0x10 帧图在数量后多画了一个 90(byte count),但现网固件按无 byte count 的 152B 帧应答正常(ACK 01 10 00 03 00 90 30 65)。不要改成带 byte count,否则写卡会失败。
  • 24 路卡号同时发送,每路 6 字节;无卡/未用端口 = FF FF FF FF FF FF(全 FF 占位,不参与读回比对)
  • 响应帧:[addr][0x10][0x00][0x03][0x00][0x90][CRC_L][CRC_H](标准 0x10 响应,8 字节)
  • 实现:modbus_rtu.py 的 ModbusRTUClient.set_card_mapping(device_address, card_mappings)
  • HTTP API:POST /api/modbus/set_card_mapping(支持完整 24 路或单端口模式)
  • MQTT 命令:SYNC_PORT_MAPPING / SYNC_ALL_MAPPING 更新本地期望后自动下发硬件
  • 下发时机(图解):新注册 / 换架接管 / 掉线重新上线 / DTU 重启后首次上线,都要先经 0x10 重下绑定②,再恢复 0x03 读卡;由 _sync_card_mappings_once() + panel_mappings_synced 保证每次在线会话只重下一次

同步卡号流程:

  1. MQTT 收到 SYNC_PORT_MAPPING/SYNC_ALL_MAPPING → 更新 port_state 期望值 + 持久化 dtu_config.json
  2. 构建 24 路 card_mappings:目标端口填新卡号,其余从 port_mappings 读取现有期望(保留),未配置填 0xFF
  3. 调用 set_card_mapping 通过串口下发到配线架硬件
  4. 下发失败返回 error_code=1008

LED 控制变化:

  • V4 起 LED 由配线架自控,DTU 轮询中不再自动下发 LED 状态(已移除 set_rgb_led 自动同步逻辑)
  • 原「LED 调试」页面已改为「卡号设置测试」页面(路由 /led-debug,组件 LedDebug.vue)
  • 页面功能:选终端 + 选端口 + 输入 12 位 hex 卡号 + 设置/清除 + 读卡验证

线架注册模型(V5,2026-10-23 重构,重点)

模型(80/81 口径,2026-10-29 按图解重写):DTU 按配置的地址段定时顺序轮询(默认 1-50,存 dtu_config.json 的 address_range)。两级绑定都存在 DTU 侧:绑定① addr↔UID(devices.json,结构 {uid: addr});绑定② 该地址下 端口↔卡号(dtu_config.json 的 port_mappings,未用端口全 FF)。线架地址必须现场刷配置卡设置(管理页「配置地址」),DTU 不自动分配地址。

扫描状态机(app.py 的 _sweep_panel_addresses(),一轮按地址升序,已绑定/未绑定同一轮顺序发,1→N):

  1. 已绑定地址(链路1 保活 → 链路2 读卡):发「地址+绑定 UID」的 0x80(始终带 UID,绝不发全 0):
    • 收到 匹配 81(UID=绑定①)→ 在线,清保活失败计数。若为重新上线/本会话还没下发过(服务重启、掉线恢复、刚接管),先经 0x10 重下绑定②,再发 0x03 读卡;稳态在线则直接读卡。
    • 连续 PANEL_KEEPALIVE_MISS_LIMIT(=2)次收不到匹配 81 → 判离线,立即停止该机 0x03 读卡(地址灯/端口灯蓝闪由线架自控);离线后仍每轮发带 UID 的 80 等恢复,重新收到匹配 81 才按上一条「先 0x10 再读卡」恢复。
    • 第 1 次保活缺失(计数=1,尚未离线)本轮仍读卡一次;读卡失败本身不改变在线状态(在线完全由 80/81 决定),只告警。
    • 收到的 81 UID 与绑定①不同:见下方「冲突 / 换架接管」。
  2. 未绑定地址:每轮对地址段内全部未绑定地址发 12 字节全 0 的 0x80 探测(不因别的线架离线而暂停)→ 收到 81(自身 UID)即本地建立绑定①并上线,不发 82/83,随后先 0x10 下绑定②再读卡(_register_new_panel)。
  3. 待探测地址(_panel_config_addr_state.pending_address):配置地址成功后优先探测,命中则 _register_new_panel(..., allow_move=True)(允许 UID 从旧地址迁移绑定与映射)。

冲突 / 换架接管(图解第七、八节):

  • 情形一 · 原机仍在线 → 真冲突,不替换:同地址收到不同 UID 的 81,但原绑定 UID 还没连续 2 次无匹配 81(仍在线)→ 不更新绑定①、不下发绑定②、不读卡,记 panel_conflict[pid]=新UID 并告警;原机本轮无匹配 81 照常累计。
  • 情形二 · 原机离线 → 自动换架接管(_takeover_panel()):原绑定 UID 已连续 2 次无匹配 81(离线)后,同地址的新 UID 持续回 81 → 更新绑定①为 addr↔新UID、panel_id 不变(继承绑定② port_mappings 全部期望)、清冲突;先经 0x10 把绑定②下发新机,再读卡(端口状态静默对齐,不误报事件);自定义 panel_id_mapping 自动补新 UID→原 panel_id;不发 82/83。
  • 替换后若老机又上线(81 UID 与当前绑定不符):新机在线按冲突告警、不静默回切。

关键内存状态:panel_keepalive_miss {pid:int}(连续无匹配 81 次数)、panel_mappings_synced set()(本在线会话已重下绑定②的面板,离线/解绑/接管时清除)、panel_conflict {pid:new_uid}。

管理页面/API:

  • 页面「线架管理」/panel-manage(PanelManage.vue):已注册线架表格(地址/UID/状态/最后响应/端口)+ 删除绑定 + 「扫描新线架」+「配置地址」
  • 「配置地址」弹窗:步骤引导(发指令 → 刷配置卡 → 自动注册)+ 状态轮询(config.running/antenna/address/error/raw)
  • GET /api/modbus/stored_devices:返回 panels[](含 panel_id/status=online|missing|offline|conflict/conflict_uid/keepalive_miss/last_seen/端口统计)+ address_range + scan 状态
  • POST /api/panel/unbind {address|panel_id}:解除绑定(仅解除;线架仍在总线上时下轮扫描会重新绑定)
  • POST /api/panel/scan / GET /api/panel/scan_status:手动全量扫描地址段内未绑定地址
  • POST /api/panel/config_address {timeout?} / GET /api/panel/config_address_status:进入配置地址状态 / 查询进度(成功返回 antenna/address)
  • POST /api/modbus/query_address {address, uid?}:手工 0x80 查询调试;POST /api/modbus/confirm_address(0x82,已废弃,仅手工调试,自动流程不调用)
  • 「实时状态」页「发现终端」按钮调用扫描接口
  • 已移除 V4 自动广播发现(auto_discover_loop / run_discovery_sync / check_assigned_devices_online)、confirm_loop(0x44 保活)以及 /api/modbus/broadcast_query、/api/modbus/auto_configure 接口

注意事项:

  • ⚠️ 新线架地址必须刷配置卡设置(管理页「配置地址」),DTU 不会再自动分配地址
  • ⚠️ 配置地址一次只能配一台:操作期间持有 address_config.config_lock,地址段轮询暂停,超时默认 60s(PANEL_CONFIG_ADDRESS_TIMEOUT,可传 timeout 5~300s)
  • ⚠️ 需线架固件支持:0x80/0x81 保活(含对「带绑定 UID 的 0x80」回应匹配 81)+ 配置地址广播应答(55 ... 03)。现网这批固件不回带 UID 的 81,靠兼容开关救活(见下);纯图解严格口径需升级固件。
  • 🔧 读卡兜底兼容开关(config.py PANEL_READ_FALLBACK_KEEPALIVE,环境变量同名,默认 true):开启后,81 连续缺失即将判离线 / 已离线等恢复时,先补发一次 0x03 读卡探测——读卡有应答即判在线并清零保活计数(离线恢复时仍先经 0x10 重下绑定②),读卡也无应答才判/维持离线。这样现网「不回带 UID 81、但读卡正常」的固件可正常在线;同地址回不同 UID 的 81 仍按严格冲突处理(不做读卡兜底)。将来固件支持点名 81 后,置 false 即回到纯图解口径(在线完全由 80/81 决定)。
  • 绑定之外的地址(超地址段)如有绑定仍会轮询,但不再探测新地址
  • 相关常量:config.py 的 DEFAULT_ADDRESS_RANGE / PANEL_KEEPALIVE_MISS_LIMIT(=2) / PANEL_READ_FALLBACK_KEEPALIVE(默认 true,读卡兜底兼容) / PANEL_PROBE_TIMEOUT / PANEL_QUERY_TIMEOUT / PANEL_READ_TIMEOUT / PANEL_CONFIG_ADDRESS_TIMEOUT

运行数据备份 / 恢复(2026-10-13)

目的:更换新 DTU 设备时一键还原全部运行数据,无需重新设置。

  • 整机备份包(GET /api/backup/export,?download=1 下载)包含:
    • dtu_config.json(身份/端口映射/地址段/uid_prefix 等)、serial_config.json、mqtt_config.json、/root/dzxj_dtu/devices.json(线架绑定表)
    • /etc/default/dzxj_dtu 环境变量文件(可选,DHT11/串口屏等;恢复后需重启服务生效)
    • effective_uid_prefix:导入时若配置无显式 uid_prefix 会固化它(换机后 MAC 变化不影响 jumper_uid 前缀,保证平台卡号一致)
  • 导入恢复(POST /api/backup/import,支持上传文件/JSON,dry_run=1 预览)→ 写文件 + 内存生效 + 串口/MQTT 自动重连 + 绑定表重建 + 注册上报
  • 设备内自动快照:每次写配置前快照到 backend/backups/(内容去重、30s 节流、每类保留 20 份);接口 GET /api/backup/list、POST /api/backup/restore_snapshot、GET /api/backup/download?name=、POST /api/backup/delete;配置文件损坏时加载会自动回退最新快照
  • 页面:/backup-restore(菜单「数据备份」,BackupRestore.vue):导出下载 / 导入恢复(预览确认)/ 快照列表(恢复/下载/删除)
  • POST /api/system/restart_service:重启 dzxj_dtu 服务(恢复环境变量后用)
  • 换机流程:旧机「数据备份」页导出下载 → 新机(同版本代码)导入恢复 → 若含环境变量文件则重启服务 → 线架地址保持不变,扫描自动重新绑定
  • 实现:backend/modules/config_backup.py(快照/原子写/bundle 校验)+ app.py 的 4 个 save 函数全部走"快照→原子写"

部署与更新

  • 代码在 /root/dzxj_dtu/,后端在 backend/,前端构建产物在 frontend/dist/。
  • 前端静态文件服务位置(重要,别传错!):
    • Flask 5001:app.py 的 STATIC_FOLDER = frontend/dist,直接服务该目录
    • nginx 80:root /var/www/html,服务该目录
    • backend/static/ 目录不被任何服务使用,传到这里等于白传
    • 部署前端时必须同时覆盖 frontend/dist/ 和 /var/www/html/ 两个目录
  • 服务使用 venv:/root/dzxj_dtu/venv/bin/python(依赖见 backend/requirements.txt,注意 gpiod 是 pip 1.5.4)。
  • 常用操作:

    # 通过 frp 连上后
    systemctl restart dzxj_dtu
    journalctl -u dzxj_dtu -f
    systemctl status frpc easytier mosquitto
    
  • 更新代码后用 scp 覆盖对应文件再 systemctl restart dzxj_dtu。

  • 本地工作目录 = 本仓库;改代码后注意同步到设备。

排障速查

症状 排查
SSH 连不上 149 先ping 192.168.199.149;再试 ssh -p 6000 root@127.0.0.1(frp stcp);若直接 IP 通但 6000 不通,查 systemctl status frpc
frpc 起不来 journalctl -u frpc;注意 stcp 配置字段是 secretKey(不是 sk),老版本报 unknown field "sk"
温湿度读到 0.0 或报 gpiod 错 确认dht11_reader 二进制存在且可执行;dht11_reader gpiochip0 19 手测
easytier 组网后虚拟 IP 不通 --no-tun 模式限制,虚拟 IP 不进路由表,只能走 port-forward
MQTT 重启后没自动连 确认/root/dzxj_dtu/backend/mqtt_config.json 存在;存在则看 auto_connect_mqtt 日志
新线架扫描不到 检查「DTU 配置」地址段是否覆盖其地址、串口是否连接;新线架需先用「线架管理 → 配置地址」刷配置卡设置地址。未绑定地址现在每轮全段顺序探测(全 0),不会因别的线架缺失而暂停
换架后未自动接管 严格图解口径:必须原机先连续 2 次无匹配 81 判离线,同地址新 UID 持续回 81 才会接管(_takeover_panel,先 0x10 再读卡)。看日志是否有冲突告警→「判定离线并停止读卡」→「按离线替换接管」;原机仍在线时只记冲突不替换。另查地址段是否包含该地址、固件是否回带 UID 的 81
配置地址一直等待/超时 确认线架已上电、配置卡放在目标天线、串口在线;默认 60s 超时,可重试;成功后看日志"线架配置地址完成: 天线=x 地址=y"
配置被改坏/丢失 「数据备份」页从自动快照恢复(backend/backups/,每类保留 20 份)
线架不回带 UID 的 81 默认开启读卡兜底(PANEL_READ_FALLBACK_KEEPALIVE=true):81 连续缺失时补发 0x03 读卡,读卡有应答即判在线,故现网这批只回全 0 探测、不回点名 81 但读卡正常的固件可正常使用;仅当读卡也无应答才判离线。要切纯图解口径(在线完全靠 81)把该开关置 false(需固件支持点名 81)。若 81/0x03 都收不到(/api/data/serial 无 01 03 90...),看 grep -E "^\s*8:" /proc/tty/driver/serial:发查询时 tx 涨 rx 不动 = 板载 485 收不到回包 → 配 SERIAL_RS485_DIR_GPIO 或改用 /dev/ttyUSB0(USB-RS485 已验证可通)

注意事项(重要)

  • 不要在本设备上装/启用 tun:内核无 tun 模块,easytier 必须 --no-tun。
  • frps 不在本设备:只跑 frpc,别在本机部署 frps 或删除 frpc。
  • stcp 配置字段是 secretKey,不是 sk(frp 0.70 报错)。
  • 设备的 root 密码是 123456(本机/测试环境)。
  • 改 app.py 后必须重启 dzxj_dtu 才生效。
  • Web 管理页面端口 5001(Flask),前端由 nginx 提供 80 端口。
  • 线架注册依赖固件:需支持 V5 的 0x80/0x81 地址查询与配置地址广播应答;仅支持 V4 的旧固件无法注册。
  • 新线架地址不再自动分配:必须用「线架管理 → 配置地址」刷配置卡设置,一次只配一台。
  • 换机流程:旧机导出备份 → 新机导入恢复(含环境变量时重启服务),详见「运行数据备份 / 恢复」。
  • 删除绑定 ≠ 注销线架:线架仍在总线上会被重新绑定;要停用某台请同时断电/拆线。