wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 29 Pull Requests 1 Actions Packages Projects 2 Releases Wiki Activity
Files
a7f526569a05fd155464ec01a35b674feedc879a
STM32F4-Base/docs/子系统设计/网络配置说明.md
T
wandering1 d1e6bb4ba7 W5波+N-19收口：FTP鉴权落地、Trap25三连定案修复(N-30)、N-20/N-23/N-26 
N-19 FTP 鉴权：
- lftpd_auth（USER/PASS 状态机 + 连续5次失败锁60s）+ SHA-256
  (user||pwd) 口令哈希；config.ini [ftp] 段 user/pwd_hash/write，
  出厂 admin/admin 在用有启动告警；lftpd_log.c 删除并入 lftpd_auth
- ftp_cfg 配置读写；台架 ftp_auth_bench.py 13/13

N-30 / Trap 25（CH395F_Trap_Records.md 四次定案全记录）：
- 修复1 closed-with-data accept：客户端发完正常 FIN 后芯片按
  FUN_PARA(0x09) §5.52② 保留 Socket+RX 缓冲，旧代码把 CLOSED 一律
  relisten 自毁缓冲 → STOR 必挂 425；改为接受"已关但可读"连接排空
- 修复2 丢 CONNECT 中断探针 net_lost_connect_probe + last_peer_port
  幽灵甄别（拆链窗口握手完成但中断丢失，双信源去抖补 accept）
- 修复3 send_list/send_nlst 批量单发：背靠背 ~60B 小段毒化芯片 TX
  （芯片报 SEND_OK 但对端全丢），整份目录一次性写入
- 证伪存档：固定沉降/Socket 轮换冷却/listen 门控（台架 v7 矩阵）
- 台架工具 test/board/ch395f_reuse_bench.{c,h} + host 脚本存档
  （不注册编译；实验分支 n30-chip-bench 保留）

N-20：Error_Handler 死循环降级（记录+复位路径）
N-23：scripts/check_registration.py 双端注册反向校验（pre-commit）
N-26：GD5F NAND 直 DMA 调用方缓冲窗口断言

验证：BUILD_OK 0/0；ftp_regression 连跑 4 轮 11/11（修复前
LIST#4/#7 100% 挂、STOR#2 曾 100% 425）；ftp_auth_bench 13/13；
@test 启动标记 PASS；ci_local L0+L0.5 全过；doc-links 通过。
登记簿 N-30 已销项。
2026-10-11 18:50:24 +08:00

18 KiB
Raw Blame History

网口设置页配置说明

版本：v2.3　日期：2026-10-11 适用工程：STM32F4-Base（STM32F407ZGTx + CH395F 以太网控制器） 范围：UI「网口设置」页可配置的网口参数（IP 地址 / 子网掩码 / 默认网关 / MAC 地址）—— 参数与默认值、持久化、生效链路、页面操作与权限。

0. 速览

项目 内容
可配置 IP 地址、子网掩码、默认网关、MAC 地址
入口 屏幕：通讯参数 → 网口设置（修改密码 123 可编辑；查看密码 000 只读）
存储 NAND Flash 文件 /config.ini（INI [network] 段，通用配置文件，掉电不丢）；旧版 /cfg/netcfg.bin 不再读取（存在则忽略，见 §3.2）
生效 按「保存」后立即生效（网络重建约 1~3s，既有 TCP 连接会断开，无需重启）
工厂默认 192.168.1.100 / 255.255.255.0 / 192.168.1.1 / 芯片内置 MAC

典型操作（改 IP）：

  1. 屏幕进入 通讯参数 → 网口设置，输入修改密码 123
  2. 选中 IP地址 行 → 回车进编辑 → ↑/↓ 调数字、←/→ 移光标 → 回车确认
  3. 选中 保存 行 → 回车 → 显示 OK
  4. 约 1~3 秒后设备在新 IP 上恢复服务（FTP / 对时 / 远程显示自动重建监听）

1. 可配置参数与工厂默认值

定义在 Drivers/BSP/NETCFG/net_cfg.h 的 net_cfg_t：

参数 字段 工厂默认 说明
IP 地址 ip[4] 192.168.1.100 静态 IP（不启用 DHCP）
子网掩码 mask[4] 255.255.255.0 /24
默认网关 gw[4] 192.168.1.1
MAC 地址 mac[6] 全零 全零 = 不覆盖芯片内置 MAC（见 §2）

工厂默认值是单一来源：net_cfg.c 顶部 NET_CFG_DEF_* 宏，同时用于 s_cfg 静态初始化与 s_defaults（引擎注册的 p_defaults 目标），避免两处漂移。

RAM 副本自启动即有效：s_cfg 以工厂默认值静态初始化（落 .data），不依赖 net_cfg_load() 是否被调用——即便存储异常，页面与网络拿到的也是有效配置而非全零。

2. MAC 地址语义

存储值 net_cfg_get_mac() 返回 网络初始化时
非全零 存储的 MAC 写入芯片 EEPROM
全零（默认） 芯片实际 MAC 影子（已回写时）；否则全零 不写，保持芯片内置 MAC
  • 芯片实际 MAC 由 netTask 在网络初始化成功后读回，经 net_cfg_set_active_mac() 存入影子区——供页面只读显示（页面不直接触 SPI）。
  • MAC 写芯片 EEPROM，每上电重放同值幂等。

3. 持久化

3.1 配置文件（INI /config.ini）

网口参数是通用配置文件 /config.ini 的一个段（NAND 卷根，UTF-8/CRLF，文本编辑器可直接改）：

; ============================================================
; STM32F4-Base 通用配置文件
; 格式: INI (UTF-8 / CRLF)，本文件为配置唯一来源
; - 以 ';' 或 '#' 开头的行为注释，保存时保留
; - 未知段/键保存时保留；缺失段/键保存时写回
; - 编辑后经 FTP 上传或设备端保存，设备 4s 沉降后自动重载
; ============================================================

[network]
ip=192.168.1.100
mask=255.255.255.0
gw=192.168.1.1
mac=00:00:00:00:00:00

出厂模板同时含 [ftp] 段（user / pwd_hash / write，见 §3.4）——本块只展示 [network] 部分。

  • 加载校验（逐键容错）：单个键值非法（越界/格式错）不影响其他键——非法键回工厂默认并留痕（parse: [network] <键> value invalid）；文件缺失 → 自动生成本模板；文件 > 4KB = 损坏 → 工厂默认 + 重建模板（坏配置不带崩网络）。
  • 保存（外科手术式）：注释 / 未知段 / 未知键逐行保留，受管键按 RAM 副本原位改写、缺失键补写；写盘 = 临时文件 /config.TMP + f_rename 原子替换（掉电不损坏目标文件）。
  • 外部变更自动重载（P4 阶段接入）：2s 轮询检测 (size, mtime) 变化、4s 沉降（连续 2 次轮询稳定）后重载 [network] 段并重建网络——FTP 上传编辑后的文件无需重启即生效。

完整设计（引擎 / 双端 / 并发模型 D15）见 docs/子系统设计/配置文件设计说明.md。

3.2 旧版二进制档 /cfg/netcfg.bin：已不再兼容（2026-10-10）

旧版格式 /cfg/netcfg.bin（28B：magic 'NCFG' + ver + CRC-16/MODBUS + 18B 字段）的"首次启动自动迁移"已于 2026-10-10 删除（net_cfg_legacy.c/h 整体移除，该格式的解析代码不再存在）。

/config.ini /cfg/netcfg.bin 行为
缺失 存在（有效或无效都一样） 生成出厂模板 → 工厂默认；旧档被忽略（不读、不删、不迁移）
缺失 缺失 生成出厂模板 → 工厂默认
存在 — 正常加载现有文件
  • 删除理由：该一次性路径把整条配置写链（net_cfg_save → cfg_file_save → cfg_store_write_atomic → f_rename → FatFS → dhara FTL）无条件挂进启动期调用图，使 defaultTask 的 armlink 静态最坏栈链 +600 B；而本仓库不存在携带旧档的设备。
  • 对使用方的影响：卷上仍残留旧档的设备升级本版本后，网口配置回落工厂默认（192.168.1.100/24、gw .1），需经 UI「网口设置」或 FTP 上传 /config.ini 重新配置。

3.3 存储后端（双端）

App/cfg/cfg_file_store.h 定义接口（带路径的文件操作），两平台各一份实现（互斥编译）：

平台 文件 位置
MCU App/cfg/cfg_file_store_mcu.c NAND 上 FatFS /config.ini（/config.TMP + f_rename 原子写）
模拟器 simulator/sim/cfg_file_store_sim.c 工作目录本地文件 sim_config.ini（fopen/rename）

INI 格式两端一致，文件可互读；mtime 变更令牌：MCU = FAT 打包时间（fdate<<16\|ftime，分钟级粒度），模拟器 = 宿主文件 mtime（秒级）。

3.4 [ftp] 段：FTP 鉴权（2026-10-11 新增，N-19）

FTP 服务（lftpd，:21）自 N-19 起启用口令鉴权。配置与 [network] 同文件、同引擎（net_cfg_load() 内统一注册，键表与工厂默认见 Drivers/BSP/NETCFG/ftp_cfg.c/h；鉴权状态机在 Drivers/BSP/NET/lftpd/lftpd_auth.c/h，纯函数、主机侧可测）：

[ftp]
user=admin
pwd_hash=d82494f05d6917ba02f7aaa29689ccb444bb73f20380876cb05d1f37537b7892
write=1
键 类型 工厂默认 说明
user STR（≤15 字符） admin 期望用户名，大小写不敏感
pwd_hash STR（64 位 hex） d82494f05d6917ba02f7aaa29689ccb444bb73f20380876cb05d1f37537b7892（即口令 admin） SHA-256(user‖password) 摘要，hex 大小写不敏感
write UINT（0/1） 1 1 = 允许 STOR/DELE；0 = 写命令一律 550 拒（只读卷）

鉴权流程：

  1. USER：不论用户名对错一律回 331（不泄露"用户是否存在"；错用户名在 PASS 阶段仍走同耗时哈希路径拉平时间）。
  2. PASS：计算 SHA-256(期望用户名‖口令)，与 pwd_hash 恒定时间比较 → 对回 230、错回 530。
  3. 未登录命令门：登录成功前仅 USER / PASS / QUIT / FEAT / SYST / NOOP 放行，其余命令一律 530。
  4. 失败锁定：连续 5 次失败 → 锁定 60 s（窗内所有 PASS 直接 530、不再计数）；登录成功清零计数；锁定状态全局跨会话、易失（重启清零）。

改口令步骤（无 UI 入口；下载 /config.ini 编辑后上传，或经串口/烧录工具改写）：

  1. 生成新摘要 hex（对 user + 新口令 拼接串做 SHA-256；下例中 user / pwd 为占位，替换为字符串字面量，如 ('admin'+'新口令')）：

    python -c "import hashlib;print(hashlib.sha256((user+pwd).encode()).hexdigest())"

  2. 把结果写入 [ftp] 段的 pwd_hash=（hex 大小写随意）；

  3. 上传回设备——配置引擎 poll 沉降 ≈4 s 后重载，下次登录生效（既有会话不受影响）。

忘口令恢复路径：口令不可从 pwd_hash 反推（这正是哈希的意义）——经串口/烧录工具改写配置，或重烧固件回落出厂默认，然后立即改口令。

出厂默认口令告警：pwd_hash 仍为出厂值时，每次启动打 INFO 锚点 [FTP] using factory default password（改了 pwd_hash 即消失）。

诚实边界：FTP 协议明文传输口令——本方案挡的是未授权访问，不挡网络嗅探（CH395F 上实现 TLS 不现实）。pwd_hash 只防 /config.ini 泄露后的离线口令还原，盐 = 用户名（无每机随机盐，局域网威胁模型下够用）。

4. 生效链路

4.1 上电启动

sequenceDiagram
    autonumber
    participant DT as defaultTask
    participant NT as netTask
    participant CFG as net_cfg
    participant CH as CH395F

    Note over DT,NT: 上电：CubeMX 已创建任务与事件组，调度器启动
    DT->>DT: FatFS 挂载（f_mount；无卷则 f_mkfs）
    DT-->>NT: 置 SYS_EVT_STORAGE_READY（就绪屏障）
    NT->>NT: 等 SYS_EVT_STORAGE_READY（≤10s；超时用工厂默认继续）
    NT->>CFG: net_cfg_load()
    Note over CFG: 注册 [network] 段 → 读 /config.ini；缺失/非法键 → 工厂默认
    CFG-->>NT: RAM 副本（有效）
    NT->>CFG: net_cfg_get() → net_cfg_fmt_ipv4()
    CFG-->>NT: "192.168.001.100"
    NT->>CH: 初始化网络（下发 IP / 掩码 / 网关 / MAC）
    CH-->>NT: 芯片实际 MAC
    NT->>CFG: net_cfg_set_active_mac()（MAC 影子）
    NT->>NT: 置 SYS_EVT_NET_READY（广播网络就绪）

4.2 保存后立即生效

保存网口参数后，设备立即按新参数重建网络，无需重启。

机制：请求 → netTask 重建 → 代次号 → 服务自愈

约束与对策：网络重建会复位 CH395F，所有监听 Socket 随之失效；而三个 TCP 服务（FTP :21 / 对时 :8888 / 远程显示 :7003）的监听由各自任务持有。为此引入"网络代次号"——各服务检测到代次变化后主动重建监听，在新 IP 上恢复服务。

sequenceDiagram
    participant UI as 网口设置页
    participant CFG as net_cfg
    participant NT as netTask
    participant NS as net_socket
    participant SVC as FTP/对时/远程显示

    UI->>CFG: 保存行 ENTER → net_cfg_save()（写盘）
    CFG->>NT: net_cfg_request_apply() → 回调置 SYS_EVT_NET_RECONFIG
    NT->>NT: 主循环检测到该位 → 重建网络（新 IP/掩码/网关/MAC）
    NT->>NS: net_generation_inc()（代次号 +1，此刻网络已可用）
    NT->>SVC: 重新广播 SYS_EVT_NET_READY
    SVC->>SVC: 轮询发现代次变化 → 关闭旧监听 → 重建监听（新 IP）

三个服务的自愈点：

服务 端口 检测位置 自愈方式
FTP 21 lftpd_inet_accept() 代次变化 → 返回 -1 → lftpd_start 外层循环重建监听
对时 8888 time_sync_task() 的 accept 循环 代次变化 → 关旧监听 → 回外层重建
远程显示 7003 ui_net_sink_poll() 代次变化 → 关旧监听/客户端 → 重建

关键设计点：

  1. SPI 归 netTask 独占：UI 只置事件位，不直接操作 CH395F。
  2. 代次号在链路就绪后才递增：避免服务在网络未就绪时抢先重建，也避免 uiTask 阻塞在消息队列上冻结界面。
  3. 无回调 = 空操作：模拟器不注册应用回调，行为退化为"仅写盘"。
  4. 既有连接必断：IP 变更导致连接不可达，属网络层语义。

5. 页面操作（网口设置页）

菜单路径：通讯参数 → 网口设置（菜单节点 30，行尾 #P 需密码）。页面模块 Drivers/BSP/UI/ui_page_net_cfg.c。

5.1 页面布局

行 名称 值格式
0 IP地址 192.168.001.100（每段 %03u 补零，定长 11 字符）
1 子网掩码 255.255.255.000
2 默认网关 192.168.001.001
3 MAC地址 A4:94:B6:12:34:56（6 字节十六进制，冒号分隔）
4 保存 ENTER → 保存后显示 OK / ERR

5.2 权限

ui_pwd_def.h 编译期密码：

输入的密码 授予权限 页面行为
查看密码 000 UI_PERM_VIEW 只读：ENTER 无效，仅可浏览
修改密码 123 UI_PERM_MODIFY 可编辑：ENTER 进编辑模式

5.3 编辑模式

ENTER 进入选中地址行 → ↑/↓ 调活动字节（0..255 环绕）、←/→ 移字节光标（首↔末环绕）、ENTER 确认退出。调整实时落 RAM 副本（net_cfg_set），只有保存行 ENTER 才写盘并应用（net_cfg_save + net_cfg_request_apply）；ESC 退出不写盘、改动丢弃（重启后恢复上次保存值）。

值格式与解析约定：页面写定长 %03u 字符串 → 网络初始化按十进制逐段解析、容忍前导零（如 "001" → 1）。

6. 文件与 API 索引

文件 职责
Drivers/BSP/NETCFG/net_cfg.h/.c 配置核心：RAM 副本 + 工厂默认 + 加载/保存编排 + MAC 影子 + IPv4 格式化（[network] 段注册）
App/cfg/cfg_file.h/.c 通用配置文件引擎（双端共享核心：解析/校验/外科保存/模板/沉降轮询）
App/cfg/cfg_file_store.h 存储后端接口（带路径的文件操作）
App/cfg/cfg_file_store_mcu.c MCU 后端：FatFS /config.ini（/config.TMP + f_rename 原子写）
simulator/sim/cfg_file_store_sim.c 模拟器后端：本地 sim_config.ini
Drivers/BSP/UI/ui_page_net_cfg.c 网口设置内容页（显示 / 编辑 / 保存）
Drivers/BSP/UI/ui_pwd_def.h 编译期密码（查看 000 / 修改 123）
App/task/net_task.c 上电加载配置 + 消费"立即应用"请求重建网络
Drivers/BSP/NET/net_socket.h/.c 网络代次号（服务自愈依据）

对外 API（net_cfg.h）：

API 说明
net_cfg_load() 注册 [network] 段 + 从 /config.ini 加载到 RAM 副本；缺失/非法键回退工厂默认（恒返回 0）
net_cfg_save() 经 cfg_file 引擎写 /config.ini（外科手术式保存）；0 成功 / -1 失败
net_cfg_request_apply() 请求立即应用（页面保存成功后调用）
net_cfg_set_apply_cb() 注册"立即应用"平台回调
net_cfg_get() 取 RAM 副本只读指针（恒非空）
net_cfg_set() 更新 RAM 副本（不写盘）
net_cfg_set_active_mac() 回写芯片实际 MAC 影子（netTask 调）
net_cfg_get_mac() 取显示用 MAC（存储非零 → 存储；否则影子；否则全零）
net_cfg_fmt_ipv4() 4 字节 → "192.168.001.100" 定长字符串

7. 陷阱

  1. 保存即生效，但连接会断：保存后重建网络（约 1~3s），既有 TCP 连接（FTP / 对时 / 远程显示）会断开并自动重建监听——IP 变更的必然结果，非缺陷。
  2. MAC 全零是哨兵，不是"MAC 为 0"：要恢复芯片内置 MAC，把 MAC 字段改回全零并保存。
  3. 配置存在 NAND 上：存储挂载失败时 net_cfg_load 回退工厂默认，网络仍能起，但保存会失败（页面显示 ERR）。
  4. 变更令牌是分钟级：FAT 时间为分钟粒度——同分钟内重写同长度文件，轮询检测不到变化（罕见；下次保存/改长度即恢复检测）。
  5. 改配置需"修改密码"：查看密码 000 进页面是只读，ENTER 无效（防误改）。
  6. 新增 TCP 服务需处理重建：须在其监听循环中检测 net_get_generation() 变化并重建监听，否则网络重建后不再可达（见 §4.2）。

8. 相关文档

主题 文档
CH395F 已知陷阱 docs/问题记录/CH395F_Trap_Records.md
网络测试指南 docs/测试说明/CH395F_Test_Guide.md
启动顺序 / 就绪屏障 docs/架构设计/项目启动顺序管理.md
项目分层架构 docs/架构设计/项目架构总览.md
内容页框架（含网口设置页） docs/UI设计/内容页架构.md

9. 变更记录

日期 变更
2026-10-11 v2.3：新增 §3.4 [ftp] 段（N-19 FTP 鉴权）——user / pwd_hash（SHA-256(user‖password)）/ write 字段表、鉴权流程（USER 恒 331 / 恒定时间比较 / 未登录命令门 / 5 败锁 60 s）、改口令步骤与忘口令恢复路径、出厂默认口令启动告警、明文嗅探边界
2026-10-10 v2.2：删除旧档 NCFG 迁移——net_cfg_legacy.c/h 整体移除、cfg_store_legacy_path() 撤销；旧档 /cfg/netcfg.bin 若存在则被忽略（不读、不删、不迁移），配置回落工厂默认。理由：该一次性路径把整条配置写链挂进启动期调用图，defaultTask 静态最坏栈链 +600 B，且本仓库无携带旧档的设备
2026-09-14 v2.1：存储迁移至通用配置文件 /config.ini（INI [network] 段，cfg_file 引擎：逐键校验 / 外科手术式保存 / 原子写 / 旧档首启迁移 / 沉降轮询）；net_cfg_store.* 弃用（由 cfg_file_store.* 取代）；对外 API 不变
2026-09-10 MAC 显示改为常识格式 A4:94:B6:12:34:56（冒号分隔，17 字符）；页面布局左移（名 x=4 / 值 x=54）以容纳 102px 宽度，编辑光标段偏移随之为 3i
Reference in New Issue View Git Blame Copy Permalink