一个具备科研可验证性的 LoRa 多跳算法评估基线。

2026-02-25 20:14:45 +08:00
parent 8537331c6f
commit 5ee1a16574
18 changed files with 1704 additions and 47 deletions
--- a/docs/plan/phase3.md
+++ b/docs/plan/phase3.md
@@ -0,0 +1,366 @@
+下面是**下一阶段（Phase-3）明确执行清单**。
+目标不是继续“修代码”，而是把当前仿真从 **能运行的系统** 升级为 **可发表 / 可证明算法价值的实验平台**。
+
+你可以直接把下面内容作为 `next_phase.md` 交给执行 AI。
+
+---
+
+# `next_phase.md`
+
+```markdown
+# LoRa Route Py — Phase-3 任务清单
+## 目标
+当前系统已经：
+- ✅ 完整仿真框架
+- ✅ 多跳路由工作
+- ✅ 业务数据成功传输
+- ✅ 指标统计完善
+
+下一阶段目标：
+
+> 将仿真升级为 **算法评估平台（Algorithm Evaluation Platform）**
+
+核心思想：
+
+    不再证明“能跑”
+    → 而是证明“比别人好”
+
+---
+
+# Phase-3 总览
+
+新增三大能力：
+
+1. Baseline 对照算法
+2. 可重复实验框架（Experiment Runner）
+3. 自动论文级结果输出
+
+---
+
+# TASK 1 — Baseline Routing（最高优先级）
+
+## 目的
+当前只有 Gradient Routing。
+
+必须加入对照组，否则结果没有科研意义。
+
+---
+
+## 1.1 新建目录
+
+```
+
+sim/routing/
+├── gradient_routing.py
+├── flooding.py          ← NEW
+├── random_forward.py    ← NEW
+└── shortest_path.py     ← NEW（可选）
+
+```
+
+---
+
+## 1.2 Flooding Routing（必须实现）
+
+### 行为
+
+收到 DATA：
+
+```
+
+if packet_id 未见过:
+转发给所有邻居
+
+````
+
+需要：
+
+- seen_packet_cache (TTL)
+- 防止无限广播
+
+---
+
+### 接口保持一致
+
+```python
+class FloodingRouting(BaseRouting):
+    def next_hop(self, packet):
+        return BROADCAST
+````
+
+Node 不需要修改。
+
+---
+
+## 1.3 Random Forward（必须）
+
+用于验证：
+
+> gradient 是否优于随机策略
+
+逻辑：
+
+```
+随机选择一个邻居转发
+```
+
+---
+
+## 验收标准
+
+新增测试：
+
+```
+test_baseline_runs.py
+```
+
+要求：
+
+* flooding 能运行
+* random 能运行
+* 无死循环
+
+---
+
+# TASK 2 — Experiment Runner（核心）
+
+## 目标
+
+自动跑：
+
+```
+节点数 × 区域大小 × 算法
+```
+
+而不是手动运行。
+
+---
+
+## 2.1 新建
+
+```
+sim/experiments/
+    runner.py
+```
+
+---
+
+## API
+
+```python
+run_experiment(
+    routing="gradient",
+    node_count=12,
+    area_size=500,
+    sim_time=500
+)
+```
+
+返回：
+
+```python
+{
+    "pdr": float,
+    "avg_latency": float,
+    "avg_hop": float,
+    "collision_rate": float,
+}
+```
+
+---
+
+## 2.2 参数扫描
+
+自动执行：
+
+```
+nodes = [6, 9, 12, 15]
+area  = [300, 500, 800]
+routing = ["gradient", "flooding", "random"]
+```
+
+总实验：
+
+```
+4 × 3 × 3 = 36 runs
+```
+
+---
+
+# TASK 3 — 固定随机种子（重要）
+
+否则实验不可复现。
+
+---
+
+修改：
+
+```
+config.py
+```
+
+加入：
+
+```python
+RANDOM_SEED = 42
+```
+
+在 main 初始化：
+
+```python
+random.seed(Config.RANDOM_SEED)
+np.random.seed(Config.RANDOM_SEED)
+```
+
+---
+
+验收：
+
+同参数运行两次结果一致。
+
+---
+
+# TASK 4 — 新指标（Metrics v2）
+
+扩展 metrics.py：
+
+---
+
+## 必须新增
+
+### 4.1 End-to-End Latency
+
+```
+receive_time - create_time
+```
+
+输出：
+
+```
+avg_latency
+p95_latency
+```
+
+---
+
+### 4.2 Forwarding Overhead
+
+```
+total_tx / successful_packets
+```
+
+衡量能量效率。
+
+---
+
+### 4.3 Network Load
+
+```
+total_airtime / sim_time
+```
+
+---
+
+# TASK 5 — 自动结果导出
+
+新增：
+
+```
+analysis_tools/export.py
+```
+
+---
+
+## 输出 CSV
+
+```
+results.csv
+```
+
+格式：
+
+| routing | nodes | area | pdr | latency | hop |
+| ------- | ----- | ---- | --- | ------- | --- |
+
+---
+
+# TASK 6 — 自动绘图（必须）
+
+使用 matplotlib：
+
+生成：
+
+```
+results/
+├── pdr_vs_nodes.png
+├── latency_vs_nodes.png
+├── overhead_compare.png
+```
+
+---
+
+图要求：
+
+* 每条 routing 一条曲线
+* 自动 legend
+
+---
+
+# TASK 7 — Regression Tests（防退化）
+
+新增：
+
+```
+test_algorithm_compare.py
+```
+
+要求：
+
+```
+gradient.pdr >= random.pdr
+```
+
+（允许 small tolerance）
+
+---
+
+# TASK 8 — 自动实验入口
+
+新增：
+
+```
+python run_experiments.py
+```
+
+执行后：
+
+```
+✔ 运行全部实验
+✔ 输出CSV
+✔ 生成图表
+```
+
+---
+
+# Phase-3 验收标准
+
+必须全部满足：
+
+* [ ] 至少 2 个 baseline 算法
+* [ ] 自动实验 runner
+* [ ] 固定随机种子
+* [ ] CSV 自动生成
+* [ ] 自动绘图
+* [ ] gradient 与 baseline 可比较
+* [ ] 一键运行实验
+
+---
+
+# 完成后系统能力
+
+完成 Phase-3 后，你将拥有：
+
+✅ LoRa mesh 仿真平台
+✅ 算法对照实验系统
+✅ 自动论文图生成
+✅ 可直接写实验章节
--- a/docs/plan/py_plan.md
+++ b/docs/plan/py_plan.md
@@ -0,0 +1,565 @@
+下面是**可直接交给执行 AI 的 `plan.md`**。
+目标是：**严格工程化、可自动实现、可自动测试、可验证正确性**，避免模糊描述。
+
+该计划默认：
+
+* Python ≥ 3.10
+* 使用 **SimPy**
+* 面向未来 STM32WL 移植（协议一致）
+
+---
+
+# `plan.md`
+
+---
+
+# STM32WL SubGHz 多跳汇聚网络
+
+## SimPy 离散事件仿真工程计划
+
+---
+
+# 1. 项目目标
+
+构建一个 **协议级一致的离散事件仿真系统**，用于验证：
+
+* 多节点 → 单 Sink 汇聚
+* 多跳转发
+* ACK可靠传输
+* 路由自动收敛
+* LoRa 信道冲突行为
+
+仿真代码必须满足：
+
+```
+routing logic 可直接迁移到 STM32 C 状态机
+```
+
+---
+
+# 2. 总体架构
+
+采用 **事件驱动 + 分层设计**。
+
+```
+sim/
+│
+├── main.py
+├── config.py
+│
+├── core/
+│   ├── packet.py
+│   ├── event.py
+│   └── metrics.py
+│
+├── radio/
+│   ├── channel.py
+│   ├── propagation.py
+│   └── airtime.py
+│
+├── mac/
+│   └── reliable_mac.py
+│
+├── routing/
+│   └── gradient_routing.py
+│
+├── node/
+│   └── node.py
+│
+└── tests/
+    ├── test_convergence.py
+    ├── test_reliability.py
+    └── test_collision.py
+```
+
+---
+
+# 3. 核心设计原则（必须遵守）
+
+## 3.1 禁止直接调用
+
+模块之间只能通过接口通信：
+
+```
+Node → MAC → Radio → Channel
+```
+
+禁止：
+
+```
+Node 直接访问 Channel
+```
+
+---
+
+## 3.2 状态机驱动
+
+所有行为必须：
+
+```
+event-driven
+```
+
+禁止：
+
+* while True busy loop
+* sleep()
+
+只能：
+
+```
+yield env.timeout()
+```
+
+---
+
+## 3.3 STM32一致性约束（重要）
+
+函数结构必须未来可映射：
+
+| Python        | STM32      |
+| ------------- | ---------- |
+| on_receive()  | OnRxDone   |
+| send_packet() | Radio.Send |
+| timeout_event | UTIL_TIMER |
+
+---
+
+# 4. 配置系统
+
+`config.py`
+
+必须集中定义：
+
+```python
+NODE_COUNT = 12
+AREA_SIZE = 800
+
+HELLO_PERIOD = 8.0
+DATA_PERIOD = 30.0
+
+TX_POWER = 14
+RSSI_THRESHOLD = -105
+
+ACK_TIMEOUT_FACTOR = 2.5
+MAX_RETRY = 3
+
+SF = 9
+BW = 125000
+CR = 5
+```
+
+禁止硬编码参数。
+
+---
+
+# 5. Packet 模型
+
+`core/packet.py`
+
+```python
+class Packet:
+    type
+    src
+    dst
+    seq
+    hop
+    payload
+```
+
+类型：
+
+```
+HELLO = 1
+DATA  = 2
+ACK   = 3
+```
+
+---
+
+# 6. 信道模型
+
+## 6.1 Channel (`radio/channel.py`)
+
+职责：
+
+* 广播传播
+* airtime占用
+* 碰撞检测
+
+接口：
+
+```python
+transmit(packet, sender)
+```
+
+---
+
+## 6.2 碰撞规则
+
+发生碰撞条件：
+
+```
+time overlap
+AND
+|RSSI1 - RSSI2| < 6 dB
+```
+
+结果：
+
+```
+全部丢弃
+```
+
+---
+
+## 6.3 传播模型
+
+`propagation.py`
+
+```python
+RSSI =
+    TX_POWER
+    - 10*n*log10(distance)
+    + gaussian_noise
+```
+
+参数：
+
+```
+n = 2.7
+noise σ = 3
+```
+
+---
+
+# 7. Airtime 计算
+
+`radio/airtime.py`
+
+必须实现真实 LoRa airtime 公式。
+
+输出：
+
+```
+seconds
+```
+
+用于：
+
+```
+ACK timeout
+channel busy time
+energy calculation
+```
+
+---
+
+# 8. MAC 层
+
+`mac/reliable_mac.py`
+
+---
+
+## 8.1 发送流程
+
+```
+enqueue packet
+↓
+backoff
+↓
+transmit
+↓
+wait ACK
+↓
+retry or success
+```
+
+---
+
+## 8.2 Backoff
+
+```
+random(0 ~ 2s)
+```
+
+---
+
+## 8.3 ACK管理
+
+维护：
+
+```
+pending_ack[seq]
+```
+
+超时：
+
+```
+ACK_TIMEOUT = airtime × ACK_TIMEOUT_FACTOR
+```
+
+---
+
+# 9. 路由层（核心）
+
+`routing/gradient_routing.py`
+
+---
+
+## 9.1 状态
+
+```python
+self.cost
+self.parent
+self.neighbors{}
+```
+
+---
+
+## 9.2 HELLO 处理
+
+```
+new_cost =
+    neighbor_cost + 1 + link_penalty
+```
+
+```
+link_penalty =
+max(0, (RSSI_THRESHOLD - RSSI)/8)
+```
+
+---
+
+## 9.3 更新条件
+
+```
+if new_cost < cost - 1:
+    parent = sender
+```
+
+---
+
+## 9.4 数据转发
+
+```
+if not sink:
+    send to parent
+```
+
+---
+
+# 10. Node 对象
+
+`node/node.py`
+
+---
+
+## 必须实现的协程
+
+```python
+hello_task()
+data_task()
+receive_task()
+```
+
+---
+
+## 生命周期
+
+```
+start
+ ↓
+route convergence
+ ↓
+data generation
+ ↓
+forwarding
+```
+
+---
+
+# 11. Metrics 系统
+
+`core/metrics.py`
+
+必须统计：
+
+```
+sent_packets
+received_packets
+delivery_ratio
+avg_delay
+avg_hop
+retransmissions
+collisions
+convergence_time
+```
+
+---
+
+# 12. 仿真执行流程
+
+`main.py`
+
+---
+
+步骤：
+
+```
+1. 创建 env
+2. 创建 Channel
+3. 随机部署节点
+4. 指定 sink
+5. 启动节点进程
+6. env.run(sim_time)
+7. 输出 metrics
+```
+
+---
+
+# 13. 自动测试设计（关键）
+
+执行 AI 必须通过以下测试。
+
+---
+
+## Test 1 — 路由收敛
+
+`test_convergence.py`
+
+检查：
+
+```
+所有节点 parent != None
+cost 单调递增
+无环
+```
+
+最大收敛时间：
+
+```
+< 120s
+```
+
+---
+
+## Test 2 — 数据可靠性
+
+`test_reliability.py`
+
+运行：
+
+```
+1000s 仿真
+```
+
+断言：
+
+```
+PDR > 0.9
+avg_retry < 2
+```
+
+---
+
+## Test 3 — 碰撞存在性
+
+`test_collision.py`
+
+增加发送频率。
+
+断言：
+
+```
+collision_count > 0
+```
+
+证明信道模型有效。
+
+---
+
+# 14. 可视化（可选但推荐）
+
+输出：
+
+```
+topology.json
+```
+
+包含：
+
+```
+node position
+parent link
+cost
+```
+
+用于后续画图。
+
+---
+
+# 15. 日志规范
+
+必须结构化：
+
+```
+[timestamp][node][event]
+```
+
+例：
+
+```
+12.4 NODE3 ROUTE_UPDATE parent=1 cost=4
+```
+
+---
+
+# 16. 验收标准（执行AI必须满足）
+
+全部通过：
+
+* [ ] pytest 全绿
+* [ ] 无未处理异常
+* [ ] 1000s 仿真 < 10s 真实时间
+* [ ] PDR ≥ 90%
+* [ ] 网络稳定无震荡
+
+---
+
+# 17. 第一阶段实施顺序（严格按序）
+
+执行 AI 必须：
+
+```
+STEP 1 packet + config
+STEP 2 airtime
+STEP 3 channel
+STEP 4 node skeleton
+STEP 5 routing HELLO only
+STEP 6 convergence test
+STEP 7 MAC + ACK
+STEP 8 data forwarding
+STEP 9 metrics
+STEP 10 tests
+```
+
+禁止跳步骤。
+
+---
+
+# 18. 完成标志
+
+当以下成立：
+
+```
+12节点随机拓扑
+↓
+自动形成树
+↓
+稳定汇聚数据
+↓
+PDR > 90%
+```
+
+则 Python 仿真阶段完成。
--- a/docs/plan/update.md
+++ b/docs/plan/update.md
@@ -0,0 +1,486 @@
+下面是可直接交给执行 AI 的 **`update.md`**。
+它不是重新设计系统，而是**进入 Phase-2：协议验证与优化阶段**的明确任务分解。
+
+目标非常明确：
+
+> **让仿真从“能运行”升级为“可解释 + 可优化 + 可移植 STM32WL”。**
+
+---
+
+# `update.md`
+
+---
+
+# LoRa Gradient Routing 仿真工程
+
+## Phase-2 更新任务（Validation & Optimization）
+
+---
+
+# 0. 当前状态
+
+项目已完成：
+
+* 仿真框架 ✅
+* 协议运行 ✅
+* 自动测试 ✅
+* 基础统计 ✅
+
+当前问题：
+
+```
+PDR 偏低
+大量节点直连 Sink
+信道竞争严重
+```
+
+说明：
+
+```text
+系统功能正确，但协议行为尚未被验证与解释。
+```
+
+---
+
+# 1. Phase-2 目标
+
+执行 AI 必须将项目升级为：
+
+```
+Self-Explaining Simulation
+```
+
+即：
+
+* 能解释性能来源
+* 能定位瓶颈
+* 能指导参数优化
+* 能评估 STM32 可移植风险
+
+---
+
+# 2. 新增目录结构
+
+必须新增：
+
+```
+sim/
+├── analysis/
+│   ├── validation_report.md
+│   ├── topology_export.json
+│   ├── timeseries.csv
+│   └── plots/
+│
+├── analysis_tools/
+│   ├── topology.py
+│   ├── convergence.py
+│   ├── channel_analysis.py
+│   └── reliability_analysis.py
+```
+
+---
+
+# 3. 必须新增的 Metrics（核心）
+
+扩展 `metrics.py`。
+
+---
+
+## 3.1 路由稳定性指标
+
+新增统计：
+
+```python
+route_changes[node_id]
+parent_history[node_id]
+cost_history[node_id]
+```
+
+计算：
+
+```
+route_change_rate =
+    total_parent_changes / sim_time
+```
+
+验收标准：
+
+```
+收敛后 ≈ 0
+```
+
+---
+
+## 3.2 Hop 分布
+
+统计：
+
+```
+hop_count_per_packet
+```
+
+输出：
+
+```
+hop_histogram
+```
+
+必须证明：
+
+```
+存在 hop ≥ 2
+```
+
+否则判定：
+
+```
+多跳未形成
+```
+
+---
+
+## 3.3 信道利用率（必须）
+
+Channel 记录：
+
+```
+busy_time
+idle_time
+collision_time
+```
+
+计算：
+
+```
+channel_utilization =
+    busy_time / total_time
+```
+
+输出：
+
+| 利用率    | 判断  |
+| ------ | --- |
+| <30%   | 健康  |
+| 30–60% | 可接受 |
+| >70%   | 拥塞  |
+
+---
+
+## 3.4 丢包原因分解（非常重要）
+
+新增 loss 分类：
+
+```
+LOSS_COLLISION
+LOSS_NO_ROUTE
+LOSS_RETRY_EXCEEDED
+LOSS_CHANNEL_BUSY
+```
+
+输出比例。
+
+---
+
+# 4. 拓扑导出功能
+
+新增：
+
+```
+analysis/topology_export.json
+```
+
+格式：
+
+```json
+{
+  "nodes":[
+    {"id":1,"x":10,"y":22,"cost":3,"parent":0}
+  ]
+}
+```
+
+用于：
+
+* 外部绘图
+* 拓扑检查
+* 论文图生成
+
+---
+
+# 5. 时间序列记录
+
+生成：
+
+```
+analysis/timeseries.csv
+```
+
+字段：
+
+```
+time,
+avg_cost,
+route_changes,
+channel_utilization,
+pdr_window
+```
+
+采样周期：
+
+```
+1s
+```
+
+---
+
+# 6. 自动生成验证报告
+
+必须自动生成：
+
+```
+analysis/validation_report.md
+```
+
+包含以下章节。
+
+---
+
+## 6.1 Topology Analysis
+
+输出：
+
+* parent tree
+* hop distribution
+* unreachable nodes
+
+结论字段：
+
+```
+MULTIHOP_FORMED = TRUE/FALSE
+```
+
+---
+
+## 6.2 Convergence Analysis
+
+绘制：
+
+```
+time vs avg_cost
+time vs route_changes
+```
+
+计算：
+
+```
+convergence_time
+```
+
+定义：
+
+```
+route_changes < threshold 持续30s
+```
+
+---
+
+## 6.3 Channel Analysis
+
+输出：
+
+```
+collision_rate
+channel_utilization
+tx_attempt_distribution
+```
+
+判断：
+
+```
+NETWORK_STATE:
+    LIGHT_LOAD
+    SATURATED
+```
+
+---
+
+## 6.4 Reliability Breakdown
+
+表格：
+
+| 原因             | 比例 |
+| -------------- | -- |
+| collision      |    |
+| retry_exceeded |    |
+| no_route       |    |
+
+---
+
+## 6.5 STM32 Transfer Risk
+
+自动生成：
+
+| 项                       | Risk         |
+| ----------------------- | ------------ |
+| airtime realism         | LOW/MED/HIGH |
+| ACK timeout safety      |              |
+| channel saturation risk |              |
+
+---
+
+# 7. 参数扫描系统（新增）
+
+新增：
+
+```
+analysis_tools/parameter_sweep.py
+```
+
+扫描参数：
+
+```
+HELLO_PERIOD ∈ [5,10,20]
+DATA_PERIOD ∈ [20,40,60]
+BACKOFF_MAX ∈ [1,2,4]
+```
+
+输出：
+
+```
+sweep_results.csv
+```
+
+包含：
+
+```
+PDR
+avg_delay
+collision_rate
+utilization
+```
+
+---
+
+# 8. 新测试（必须新增）
+
+---
+
+## test_multihop_exists.py
+
+断言：
+
+```python
+assert max_hop >= 2
+```
+
+---
+
+## test_route_stability.py
+
+断言：
+
+```
+route_change_rate < threshold
+```
+
+---
+
+## test_channel_not_saturated.py
+
+断言：
+
+```
+utilization < 0.7
+```
+
+---
+
+# 9. 禁止事项
+
+执行 AI 禁止：
+
+```
+❌ 修改 routing 算法
+❌ 修改 cost 函数
+❌ 引入新协议
+```
+
+当前阶段只允许：
+
+```
+观察 + 测量 + 分析
+```
+
+---
+
+# 10. Phase-2 验收标准
+
+全部满足：
+
+* [ ] 自动生成 validation_report.md
+* [ ] 网络形成多跳
+* [ ] 收敛时间可测量
+* [ ] 信道利用率可计算
+* [ ] 丢包原因可分解
+* [ ] 新 tests 全通过
+
+---
+
+# 11. 完成后提交内容
+
+执行 AI 必须输出：
+
+```
+analysis/
+ ├── validation_report.md
+ ├── topology_export.json
+ ├── timeseries.csv
+ └── plots/*.png
+```
+
+---
+
+# 12. Phase-2 完成意义
+
+完成后将获得：
+
+```
+协议行为模型（Behavior Model）
+```
+
+这一步完成后才允许进入：
+
+```
+STM32WL 移植阶段
+```
+
+---
+
+# 13. 下一阶段（仅说明）
+
+Phase-3 将进行：
+
+```
+MAC 优化
+负载感知 routing
+参数自动推导
+```
+
+但当前禁止提前实施。
+
+---
+
+**执行优先级（严格顺序）：**
+
+```
+1 metrics扩展
+2 topology导出
+3 timeseries记录
+4 validation_report生成
+5 新测试
+6 参数扫描
+```
+
+---
+
+完成 Phase-2 后，将仿真结果提交用于协议级评估。