本文件记录本项目开发/维护时需要注意的关键信息,方便下次快速上手。
注意每次改动需要更新本文件,这非常重要!!!!!!!!
hostname=ido,aarch64;⚠️ 早期文档误记为 RK3588,2026-11-03 经 /proc/device-tree/model 核实为 RK3562),作为 DTU(数据传输单元)运行。dzxj_dtu —— 串口(MODBUS-RTU/RS485) ↔ MQTT 网关,带 Web 管理界面(Flask + Socket.IO + Vue 前端)。/root/dzxj_dtu/,代码库在本仓库。192.168.199.149(eth,远程管理用)与 192.168.10.5(wlan,DHCP 会变)可同时存在于同一台机;实际 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 等该板原为 Android 13,2026-09 已重刷为 Ubuntu 20.04 原厂镜像,sshd 自带可用,无需再自建 SSH。
hostname=ido。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。/etc/nginx/sites-available/dzxj_dtu.conf(root /var/www/html,代理 /api、/socket.io → :5001);前端同时放了 frontend/dist 和 /var/www/html(别忘两处都更)。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_config.json 仍是占位(localhost:1883),需在网页里配 xt.wenhq.top:8581 之类并连接,连上后才会持久化自动重连。adb devices 见 USB 设备(adb 自报名 mako/Nexus_4,实际是 RK3562 Ubuntu 板),adb shell 直接 root(uid=0);hostname=ido、内核 5.10.226 aarch64、Ubuntu 20.04。当次 eth0 IP=192.168.1.125(docker0=172.17.0.1,与 wlan 192.168.10.190 不是同一会话/网段,按 hostname -I 为准)。adbd、Nextion 在 ttyS9、DHT11 正常、serial_config.json 曾指 /dev/ttyUSB0、目录/服务布局一致。2026-10-31 13:59 经 adb 部署节拍+映射+前端修复版(提交 bd7321e+1df50f7+09e72d8):
backend/app.py、config.py、modules/serial_port.py;前端 dist 同时覆盖 /root/dzxj_dtu/frontend/dist 和 /var/www/html,entry index-f0289edd.js(含 PortMapping-f2b7d011.js)。app.py/config.py/serial_port.py 均存 *.bak_20261031_135813;前端两目录存 *.bak_20261031_135904。from paths import(设备无 paths.py 会起不来)。部署用 git show HEAD:backend/app.py 导出;设备 venv python -m py_compile 通过、grep from paths import=0 后才重启。adb push 到 /tmp → adb shell cp 覆盖(chown root:root、chmod 644)→ systemctl restart dzxj_dtu。xt.wenhq.top:8581;DHT11 29°C/27%、Nextion ttyS9 正常;/api/panel/mappings 200;启动自动清理 44 条历史 null 端口映射;nginx 80 与 5001 均 200,新 chunk 可访问。/dev/ttyUSB0 不存在(未插 USB-RS485),串口显示未连接,属硬件未接,非软件问题;需要时插 USB-RS485 或在网页把串口改回板载 /dev/ttyS8(注意 ttyS8 历史上「能发不能收」)。2026-11-03 RS485 方向脚配置(adb serial faeb8ddfc39b2ded,IP 192.168.10.5 与 192.168.199.149 同机!):
192.168.199.149(root/123456,同时持有 192.168.10.5)设备树实际是 Rockchip RK3562 IDO EVB3562 V2(cat /proc/device-tree/model),不是项目概览里一直写的 RK3588;它和经 adb 操作的第二块板是同一台(env/备份时间戳一致)。下文 GPIO line 号、ff260000.gpio 等均为 RK3562 实测。flush/tcdrain 等最后一位发完后立刻切回接收;程序启动/连接默认低电平。ff260000.gpio,32 线),C 组偏移 16,C4 = line 20(C3=line19 即 DHT11 已验证)。已排除复用冲突:uart6(ff6b0000) disabled、无 /dev/spidev*、pwm1(ff700020) 无导出通道;gpioset gpiochip0 20=0/1 可正常申请切换。用现有 Rs485Direction(serial_port.py,纯配置无需改代码),在 /etc/default/dzxj_dtu 追加:
SERIAL_RS485_DIR_GPIO=gpiochip0:20
SERIAL_RS485_DIR_PRE_DELAY=0.010
SERIAL_RS485_DIR_POST_DELAY=0
高电平为发送态(spec 不加 :low)。
时序对应:to_tx() 置高→sleep(PRE) → write()+flush() → to_rx()(POST=0 立刻拉低);open() 申请为输出后立即 _set(False),故启动默认低。
最终串口用 /dev/ttyS8 @9600(板载 RS485,ff6e0000.serial):最初临时在 /dev/ttyS3(ff690000.serial,pinctrl m1=UART3 GPIO3_B7/C0) 验证,后按现场要求改为 ttyS8。曾被误设成 ttyS8@115200,已通过 POST /api/serial/connect 改回 9600 并持久化。备份:env/serial_config 均有 *.bak_20261103_110031(ttyS3 期)与 *.bak_20261103_153610(改回 9600 前)。
验证:重启后自动 connected=/dev/ttyS8@9600、方向脚默认 gpio-20 (dzxj_dtu_rs485_dir) out lo(/sys/kernel/debug/gpio);临时 POST=0.1 时发一帧抓到 out lo→out hi(保持)→out lo(ttyS8 实测同样动作),已改回 0;开机自启恢复正常。
⚠️ 当前 ttyS8 仍 rx:0(tx 正常涨):软件拉脚已证实,收不到回包属物理层——需现场确认 485 收发器的 DE/RE 真的接到 GPIO0_C4(line20)、A/B 未接反/松动、线架已上电。这正是历史上 ttyS8「能发不能收」的现象,方向脚接对后应恢复。
调试技巧:该脚被服务占用时 gpioget/gpioset 报 Device or resource busy;看实时电平用 /sys/kernel/debug/gpio(grep gpio-20)。抓发送高电平窗口可临时把 SERIAL_RS485_DIR_POST_DELAY 调大(如 0.1)再触发查询,验证完改回重启。/dev/mem mmap 在该内核被禁(Permission denied)。
f5b6307ad44bf190,eth0 192.168.129.153)adb devices 见 f5b6307ad44bf190(仍自报 mako/Nexus_4),adb shell 直接 root;Ubuntu 20.04、Python 3.8.10、内核 aarch64,hostname ido,eth0=192.168.129.153,docker0=172.17.0.1。与第二块板不是同一台(adb serial、IP 均不同)。app.py 10-27,serial_port.py 7-31;无读卡兜底/节拍/映射接口);venv 依赖齐(Flask 2.3.3 + Werkzeug 3.0.6、Flask-SocketIO 5.6.1、pyserial 3.5、paho 1.6.1、gpiod 1.5.4,无 eventlet/gevent);nginx 配在默认站点,已代理 /api、/socket.io→:5001,root /var/www/html。devices.json / dtu_config.json(无绑定、无映射),升级无数据风险;mqtt_config.json 指本地 localhost:1883(板上 mosquitto 在跑),serial_config.json 指 /dev/ttyUSB0。bd7321e+1df50f7+09e72d8),手法/校验同上:
app.py/config.py/modules/serial_port.py 需更新(modbus_rtu.py/config_backup.py/mqtt_client.py 已与 HEAD 一致);前端 dist 同步两处,entry index-f0289edd.js。*.bak_20261031_140401;前端两目录 *.bak_20261031_140422。localhost:1883 已连;Nextion ttyS9 正常、IP 已上屏;/api/panel/mappings 200(空);nginx 80 / chunk 200。scripts/dht11_reader gpiochip0 19 能占用线但 could not find response pulse(传感器无响应脉冲)= 没接/接线错/缺上拉,不是软件问题。运行中还会先报 dht11_reader 退出码 1,回退 Python gpiod 再报 request() got an unexpected keyword argument 'consumer'(gpiod 1.5.4 已知不兼容,靠 C 读取器);回退失败过程会短暂占用 gpiochip0 line19。接好 DHT11(data→gpiochip0 line19、共地、带上拉、VCC)后 C 读取器即恢复。/dev/ttyUSB0(未插 USB-RS485),板载 ttyS8/ttyS9 在;要用线架插 USB-RS485 或网页改串口。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。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)。config.py PANEL_READ_FALLBACK_KEEPALIVE(默认 true);备份 app.py.bak_20261029_191143(config 同名)。POST /api/panel/unbind 把绑定清空(devices.json={});随后 pyserial 绕过 App 直发原始帧,地址 1 的 80 探测/03 读卡均 0 字节回包、地址 2–5 也全超时——/dev/ttyUSB0 connected、CH340 在、能发不能收,判为物理层/线架侧无响应(线架断电/485 A-B 松脱或接反/停在配置地址态)。线架恢复应答后未绑定全 0 探测会自动重新注册。192.168.10.190(eth 口未启用)。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。/dev/ttyUSB0,读写控件全部正常(已实测)。配置 NEXTION_SCREEN_PORT=/dev/ttyUSB0。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_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,)) = 只刷静态信息。t1.txt 会更新为实际 IP(/tmp/screen_poke.py <port> 可手工读写验证)。frpc(2026-09 装):/opt/frp/frpc(v0.71.0)+ /opt/frp/frpc.toml + frpc.service(开机自启,已连上 frps)。
device.wenhq.top:8580,token gx@12345678。167-ssh(local 22),secretKey 167-ssh-sk → 访问端配 visitor(serverName=167-ssh)。167-http(local 80),subDomain pxj167(如子域被占/改名,改 toml 后 systemctl restart frpc)。附:tools/rkssh/ 是此前为 Android 系统写的 Go 版 SSH 服务,Ubuntu 下用不到,保留仅作历史记录(旧 Android 记录:192.168.199.235、密码 123456)。
149 上跑 frpc(仅客户端,不跑 frps),通过 stcp 模式把本地 22 端口映射到公网 frps 服务器。
device.wenhq.top:8580,token = gx@12345678(frps 部署在外部,不在本设备)。/opt/frp/frpc.tomlsystemctl status frpc / systemctl restart frpcfrpc 配置摘要:
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 端口。
frpc 里已有 http 代理,把本地 80 端口映射成 pxj 子域名:
[[proxies]]
name = "149-http"
type = "http"
localIP = "127.0.0.1"
localPort = 80
subDomain = "pxj"
通过 http://pxj.<frps主域名> 访问(具体子域解析规则由 frps 端配置决定)。
/etc/systemd/system/easytier.servicepxjdtu / 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。读取优先走 C 语言读取器,Python gpiod 只作回退。
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{"valid":true,"humidity":43,"temperature":31,"raw":[...],"checksum":76}(温湿度为整数,无小数)module 'gpiod' has no attribute 'Chip' 或读到 0.0)Python gpiod 回退:backend/modules/dht11_sensor.py
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_OUTPUTline.request(consumer=..., type=...) vs line.request(type=...)(1.5.x 无 consumer 参数)close() 方法_gpiod_chip_class、常量映射),但优先靠 C 二进制,尽量别依赖这个回退。| 变量 | 默认 | 说明 |
|---|---|---|
DHT11_ENABLED |
true |
是否启用 |
DHT11_GPIO_PIN |
无 | GPIO line 号(设备上为19) |
DHT11_GPIO_CHIP |
gpiochip0 |
GPIO chip |
DHT11_POLL_INTERVAL |
5 |
读取间隔秒 |
DHT11_SIMULATE |
false |
是否模拟数据 |
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%"
:1883。xt.wenhq.top:8581。/root/dzxj_dtu/backend/mqtt_config.json:
/api/mqtt/connect 连接成功后自动 save_mqtt_config()。__main__ 里会 auto_connect_mqtt() 读取该文件自动重连。backend/app.py):save_mqtt_config() / load_mqtt_config() / auto_connect_mqtt() / mqtt_connect()(API /api/mqtt/connect)。backend/modules/mqtt_client.py(paho-mqtt==1.6.1,重连无限尝试,max_reconnect_attempts=0)。线架系统,DTU 协议主题格式:{topic_prefix}/{customer_id}/dtu/{dtu_id}/{topic}。/dev/ttyS8 @ 9600,连接配置持久化在 /root/dzxj_dtu/backend/serial_config.json。/dev/ttyUSB0(CH340 USB-RS485),因为板载 ttyS8 的 485 收发器实测「能发不能收」——DTU 发查询后 tx 涨、rx 一动不动,同一帧用 USB-485 从总线发就一切正常。详见下方「RS485 方向脚软件控制」。auto_connect_serial() 自动重连。backend/modules/modbus_rtu.py;串口封装在 backend/modules/serial_port.py。jumper_uid(前 4 位 DTU 号 + 后 12 位卡号),适配逻辑在 app.py 的 _to_mqtt_jumper_uid / _from_mqtt_jumper_uid。serial_port.py 的 SerialPort 有一个 _cmd_queue + 唯一 worker 线程;send_and_wait / send_raw / wait_response / send_data 全部入队。modbus_rtu.py 的 0x80 保活、0x03 读卡、0x10 写卡、配置地址帧最终都走它——扫描线程、网页手动操作、MQTT 下发共用同一队列,物理上不会并发撞帧。_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 的相邻两帧在界面上看似同一瞬间,实为队列正常节拍。板载 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(发完等待秒数再切回接收)ttyS8 只复用了 TX/RX 两个脚(uart8m0-xfer),RTS 没有引出来,设备树也没有 rs485 属性,所以不能靠内核 RS485/RTS 模式解决。协议文档: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。
[addr][0x80][12字节 UID 域][CRC_L][CRC_H]
[addr][0x81][12字节线架自身 UID][CRC_L][CRC_H]
fc & 0x80 判异常)[addr][0x82][UID][CRC] / [addr][0x83][UID][CRC] 现场固件不用;自动注册/接管流程不再调用,仅保留 confirm_address() 与两个手动调试 HTTP 接口01 80+12×00 → 54 01;81 样例 01 81 51 00 12 00 11 00 00 4C 30 31 33 56 D0 D3modbus_rtu.py 的 build_address_query_request / parse_address_query_response;客户端 query_address(addr, uid=None)。confirm_address()/build_address_confirm_request 仅留作手动调试批量读卡恢复标准 MODBUS 0x03(帧内不再带 UID):
[addr][0x03][0x00][0x02][0x00][0x48][CRC_L][CRC_H](文档样例 01 03 00 02 00 48 E4 3C)[addr][0x03][0x90][144字节卡数据][CRC_L][CRC_H]build_read_cards_request(addr) 与 read_all_antenna_cards(addr);常量 LEGACY_UID_RESPONSE_LEN=161配置地址状态(刷配置卡设置线架地址,V5 新增):
aa b7 00 07 80 00 00 ff 00 00 02 64 03(CONFIG_ADDRESS_ENTER_FRAME,硬编码)55 00 00 02 ANTLIST ADDR XOR 03
ANTLIST = 读到配置卡的天线号,ADDR = 线架采纳的新地址,XOR = 55^00^00^02^ANTLIST^ADDR^03parse_config_address_response),容忍前面的杂散字节pending_address,恢复轮询后优先探测该地址并自动注册/换架接管设置卡号协议(非标准 MODBUS 0x10,重点!):
[addr][0x10][0x00][0x03][0x00][0x90][144字节数据][CRC_L][CRC_H]
0x0090=144 直接表示字节数,整帧 152B90(byte count),但现网固件按无 byte count 的 152B 帧应答正常(ACK 01 10 00 03 00 90 30 65)。不要改成带 byte count,否则写卡会失败。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)POST /api/modbus/set_card_mapping(支持完整 24 路或单端口模式)SYNC_PORT_MAPPING / SYNC_ALL_MAPPING 更新本地期望后自动下发硬件_sync_card_mappings_once() + panel_mappings_synced 保证每次在线会话只重下一次同步卡号流程:
SYNC_PORT_MAPPING/SYNC_ALL_MAPPING → 更新 port_state 期望值 + 持久化 dtu_config.jsonport_mappings 读取现有期望(保留),未配置填 0xFFset_card_mapping 通过串口下发到配线架硬件LED 控制变化:
set_rgb_led 自动同步逻辑)/led-debug,组件 LedDebug.vue)模型(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):
PANEL_KEEPALIVE_MISS_LIMIT(=2)次收不到匹配 81 → 判离线,立即停止该机 0x03 读卡(地址灯/端口灯蓝闪由线架自控);离线后仍每轮发带 UID 的 80 等恢复,重新收到匹配 81 才按上一条「先 0x10 再读卡」恢复。_register_new_panel)。_panel_config_addr_state.pending_address):配置地址成功后优先探测,命中则 _register_new_panel(..., allow_move=True)(允许 UID 从旧地址迁移绑定与映射)。冲突 / 换架接管(图解第七、八节):
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。关键内存状态: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,已废弃,仅手工调试,自动流程不调用)auto_discover_loop / run_discovery_sync / check_assigned_devices_online)、confirm_loop(0x44 保活)以及 /api/modbus/broadcast_query、/api/modbus/auto_configure 接口backend/dtu_config.json 的 port_mappings[panel_id],键端口号 1-24,值 12 位大写 hex;空/清除一律删除键,不再写 null(_store_port_mapping())。启动时 _prune_null_port_mappings() 一次性清掉历史 null/空脏数据并落盘。cards_written(恒为全 24 路)落盘。现单端口模式(POST /api/modbus/set_card_mapping 只传 port_id)只落目标这一条;硬件 0x10 帧仍带全 24 口(硬件基底→平台期望→目标口),未配端口保持硬件现值,这是协议要求不是污染。完整模式(传 card_mappings)才全量落盘。/port-mapping(菜单「端口映射」,PortMapping.vue):按面板卡片列出 1-24 口映射,支持新增/编辑/删除/清空全部;线架在线+串口连接时操作同步下发硬件(保留其它端口现值),离线/未注册只存平台记录,重新上线由 _sync_card_mappings_once 自动下发。页面 10s 轮询。GET /api/panel/mappings:全部面板映射(含 registered=false 的未注册残留组,便于清理)POST /api/panel/mapping {panel_id|address, port, card_uid|null}:单口增改删(空=删除),在线经 _push_single_port_hardware() 下发;硬件失败不回滚期望,响应里 hardware.synced/message 告警POST /api/panel/clear_mappings {panel_id|address}:删该面板全部映射 + 在线时 24 口全发 0xFF;线架管理页操作列也有「清空映射」SYNC_PORT_MAPPING / SYNC_ALL_MAPPING 的落盘同样走 _store_port_mapping()(清除删键)。unbind(删绑定①)不清 port_mappings,换架接管靠继承它;要彻底清端口映射用新页面/接口。注意事项:
address_config.config_lock,地址段轮询暂停,超时默认 60s(PANEL_CONFIG_ADDRESS_TIMEOUT,可传 timeout 5~300s)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目的:更换新 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/。app.py 的 STATIC_FOLDER = frontend/dist,直接服务该目录root /var/www/html,服务该目录backend/static/ 目录不被任何服务使用,传到这里等于白传frontend/dist/ 和 /var/www/html/ 两个目录/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。
本地工作目录 = 本仓库;改代码后注意同步到设备。
用途:把同一套后端+前端打成 单文件 exe,在 Windows 电脑上用 USB-RS485 现场调试/演示线架。 不是给 RK 板子的安装包,设备端仍跑 Linux。
dist/dzxj_dtu.exe(约 14.7 MB,PE32+ x64 控制台程序,双击运行后自动开浏览器 http://127.0.0.1:5001/)。packaging\build_exe.bat(纯 ASCII,别往里写中文,UTF-8 bat 会被 cmd 解析错乱)。
等价命令:python -m PyInstaller --noconfirm --clean --distpath dist --workpath build\pyinstaller packaging\dzxj_dtu.specpackaging/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。/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 起不来)。modules/ 是命名空间包(无 __init__.py),必须在 spec 的 hiddenimports 里逐个子模块声明。pc@192.168.20.155)认证偶发 Permission denied,重试即可;tar.exe 解包会被拦(拒绝访问),传文件用 scp -r。| 症状 | 排查 |
|---|---|
| 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 已验证可通) |
--no-tun。secretKey,不是 sk(frp 0.70 报错)。123456(本机/测试环境)。app.py 后必须重启 dzxj_dtu 才生效。5001(Flask),前端由 nginx 提供 80 端口。