只有hello包实现多跳，还没加入业务数据

具体的还要看opencode和gpt记录接着优化
2026-02-24 17:17:45 +08:00
parent 375febb4c0
commit d357a25076
14 changed files with 1690 additions and 58 deletions
--- a/docs/algorithm_doc.md
+++ b/docs/algorithm_doc.md
@@ -0,0 +1,412 @@
+# LoRa多跳网络仿真系统技术文档
+
+## 1. 系统概述
+
+本仿真系统实现了一个基于梯度路由（Gradient Routing）的LoRa多跳网络仿真平台，使用Python和SimPy离散事件仿真框架开发。系统旨在验证LoRa网络在多跳场景下的可靠性和性能，为后续STM32WL硬件移植提供理论依据和算法验证。
+
+### 1.1 主要特性
+
+- **梯度路由协议**: 基于成本（cost）的分布式路由算法，节点通过HELLO消息发现邻居并建立到Sink的路由
+- **可靠MAC层**: 实现CSMA类退避算法和ACK确认机制，支持数据包重传
+- **无线信道模型**: 基于自由空间路径损耗的RSSI计算，支持碰撞检测
+- **可观测性框架**: 完整的路由收敛分析、跳数分布统计、信道利用率监测、丢包率分析
+
+### 1.2 项目结构
+
+```
+lora_route_py/
+├── sim/
+│   ├── config.py           # 配置参数
+│   ├── main.py             # 仿真主入口
+│   ├── core/
+│   │   ├── packet.py       # 数据包定义
+│   │   └── metrics.py      # 指标收集系统
+│   ├── routing/
+│   │   └── gradient_routing.py  # 梯度路由协议
+│   ├── mac/
+│   │   └── reliable_mac.py     # 可靠MAC层
+│   ├── radio/
+│   │   ├── channel.py          # 无线信道
+│   │   ├── propagation.py       # 传播模型
+│   │   └── airtime.py          # 空口时间计算
+│   ├── node/
+│   │   └── node.py              # 节点实现
+│   ├── analysis_tools/         # 分析工具
+│   │   ├── topology.py
+│   │   ├── convergence.py
+│   │   ├── channel_analysis.py
+│   │   └── reliability_analysis.py
+│   └── tests/                  # 单元测试
+│       ├── test_multihop_exists.py
+│       ├── test_convergence.py
+│       ├── test_reliability.py
+│       ├── test_route_stability.py
+│       ├── test_collision.py
+│       └── test_channel_not_saturated.py
+└── docs/
+    └── algorithm_doc.md        # 本文档
+```
+
+---
+
+## 2. 算法原理
+
+### 2.1 梯度路由协议（Gradient Routing）
+
+梯度路由是一种分布式、自组织的路由协议，灵感来源于蚂蚁觅食行为和自然梯度场。每个节点维护一个"成本"值（cost），表示到Sink节点的估计距离（跳数+链路惩罚）。
+
+#### 2.1.1 成本计算
+
+节点的成本由两部分组成：
+1. **跳数成本**: 邻居节点的跳数 + 1
+2. **链路惩罚**: 基于RSSI（接收信号强度指示器）计算
+
+```
+new_cost = neighbor_cost + 1 + link_penalty
+link_penalty = max(0, (RSSI_THRESHOLD - RSSI) / LINK_PENALTY_SCALE)
+```
+
+其中：
+- `RSSI_THRESHOLD = -105 dBm`: 接收灵敏度阈值
+- `LINK_PENALTY_SCALE = 8.0`: 链路惩罚缩放因子
+
+链路惩罚机制使得信号质量更好的链路具有更低的成本，从而优先选择高质量链路。
+
+#### 2.1.2 HELLO消息机制
+
+每个节点定期（默认8秒）广播HELLO消息，包含：
+- 源节点ID
+- 当前成本值
+- 序列号
+
+邻居节点收到HELLO后：
+1. 解析发送方的成本
+2. 计算通过该邻居到Sink的成本
+3. 如果新成本更低，则更新父节点和成本
+
+#### 2.1.3 路由收敛
+
+初始时，只有Sink节点成本为0，其他节点成本为∞。随着HELLO消息的传播，网络逐渐收敛。每个节点最终选择成本最低的邻居作为父节点，形成以Sink为根的树形拓扑。
+
+#### 2.1.4 数据转发
+
+当节点需要发送数据时：
+1. 检查是否有有效路由（父节点非空）
+2. 将数据包发送到父节点
+3. 父节点继续转发，直到到达Sink
+
+中间节点使用**路径追踪**机制避免路由环路：
+- 每个数据包维护`path`列表，记录经过的节点ID
+- 节点收到数据包时，检查自身ID是否已在路径中
+- 如果已存在，则丢弃该数据包（防止无限循环）
+
+### 2.2 可靠MAC层
+
+采用类似传统CSMA的机制，但针对LoRa特性进行了简化。
+
+#### 2.2.1 发送流程
+
+```
+1. 数据包入队
+2. 等待随机退避时间 (0~2秒)
+3. 发送数据包
+4. 等待ACK确认
+5. 若超时未收到ACK，重传（最多3次）
+6. 超过最大重传次数后丢弃
+```
+
+#### 2.2.2 关键参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| BACKOFF_MAX | 2.0s | 最大退避时间 |
+| MAX_RETRY | 3 | 最大重传次数 |
+| ACK_TIMEOUT_FACTOR | 2.5 | ACK超时倍数 |
+
+### 2.3 无线信道模型
+
+#### 2.3.1 RSSI计算
+
+采用自由空间路径损耗模型：
+
+```
+RSSI = TX_POWER - 10*n*log10(d) + Gaussian_noise
+```
+
+参数说明：
+- `TX_POWER = 14 dBm`: 发射功率
+- `n = 2.7`: 路径损耗指数（城市环境典型值）
+- `d`: 距离（米）
+- `Gaussian_noise ~ N(0, 3dB)`: 高斯噪声
+
+#### 2.3.2 碰撞检测
+
+当两个数据包传输时间重叠时，判定为碰撞，接收方丢弃所有参与碰撞的数据包。
+
+---
+
+## 3. 可观测性框架
+
+### 3.1 指标体系
+
+系统实现了完整的指标收集和分析框架，主要包括：
+
+#### 3.1.1 基本性能指标
+
+| 指标 | 说明 |
+|------|------|
+| total_sent | 节点生成的数据包总数 |
+| total_received | Sink成功接收的数据包数 |
+| total_forwarded | 中间节点转发的数据包数 |
+| pdr | 数据包交付率 (PDR = received / sent) |
+
+#### 3.1.2 多跳路由指标
+
+| 指标 | 说明 |
+|------|------|
+| max_hop | 数据包经历的最大跳数 |
+| avg_hop | 平均跳数 |
+| hop_histogram | 跳数分布直方图 |
+| MULTIHOP_FORMED | 是否形成多跳 (max_hop ≥ 2) |
+
+#### 3.1.3 路由稳定性指标
+
+| 指标 | 说明 |
+|------|------|
+| route_changes | 路由变化总次数 |
+| route_change_rate | 路由变化率 (次/秒) |
+| convergence_time | 路由收敛时间 |
+
+#### 3.1.4 信道利用指标
+
+| 指标 | 说明 |
+|------|------|
+| channel_utilization | 信道利用率 (%) |
+| collisions | 碰撞次数 |
+
+#### 3.1.5 丢包分类
+
+| 指标 | 说明 |
+|------|------|
+| loss_collision | 因碰撞丢包 |
+| loss_no_route | 因无路由丢包 |
+| loss_retry_exceeded | 因重传超限丢包 |
+| loss_channel_busy | 因信道繁忙丢包 |
+
+### 3.2 关键验证点
+
+#### 3.2.1 多跳路由验证（最重要）
+
+**验证目标**: 证明数据包确实通过多跳传输，而非直接从源到Sink。
+
+**验证方法**:
+- `max_hop >= 2`: 最大跳数≥2，证明存在多跳
+- `hop_histogram`: 跳数分布反映网络拓扑深度
+- `path`追踪: 记录每个数据包经过的节点序列
+
+#### 3.2.2 路由收敛验证
+
+**验证目标**: 证明网络能够自组织形成稳定的路由树。
+
+**验证方法**:
+- 路由收敛时间测量
+- 无路由环路证明
+- 路由变化率在合理范围
+
+#### 3.2.3 可靠性验证
+
+**验证目标**: 证明网络在给定条件下能够可靠传输数据。
+
+**验证方法**:
+- PDR > 50%（默认阈值）
+- 平均重传次数合理
+- 无因协议缺陷导致的系统性丢包
+
+---
+
+## 4. 测试方法
+
+### 4.1 运行测试
+
+```bash
+# 运行所有测试
+python -m pytest sim/tests/ -v
+
+# 运行特定测试
+python -m pytest sim/tests/test_multihop_exists.py -v
+
+# 运行并显示详细输出
+python -m pytest sim/tests/ -v -s
+```
+
+### 4.2 测试套件说明
+
+| 测试文件 | 测试数量 | 验证内容 |
+|----------|----------|----------|
+| test_multihop_exists.py | 2 | 多跳路由是否形成 |
+| test_convergence.py | 3 | 路由收敛性 |
+| test_reliability.py | 3 | 网络可靠性 |
+| test_route_stability.py | 2 | 路由稳定性 |
+| test_collision.py | 2 | 碰撞检测 |
+| test_channel_not_saturated.py | 2 | 信道利用率 |
+
+**总计**: 14个测试用例，全部通过表示仿真系统验证完成。
+
+### 4.3 运行仿真
+
+```python
+from sim.main import run_simulation
+
+# 默认配置运行
+results = run_simulation()
+
+# 自定义参数运行
+results = run_simulation(
+    num_nodes=20,      # 节点数量
+    area_size=1000,   # 部署区域大小（米）
+    sim_time=500,     # 仿真时间（秒）
+    seed=42           # 随机种子（可复现）
+)
+
+# 访问结果
+metrics = results["metrics"]
+topology = results["topology"]
+```
+
+### 4.4 结果解读
+
+仿真完成后，系统输出以下关键指标：
+
+```python
+{
+    "total_sent": 92,           # 发送数据包数
+    "total_received": 61,       # 接收数据包数
+    "pdr": 66.3,                # 交付率(%)
+    "max_hop": 11,              # 最大跳数
+    "avg_hop": 6.5,             # 平均跳数
+    "hop_histogram": {4:5, 6:5, 7:5, 9:7, ...},  # 跳数分布
+    "MULTIHOP_FORMED": True,     # 多跳形成标志
+    "route_changes": 3,          # 路由变化次数
+    "channel_utilization": 5.2,  # 信道利用率(%)
+    "collisions": 19,            # 碰撞次数
+}
+```
+
+---
+
+## 5. 科研论文引用指南
+
+### 5.1 仿真参数配置
+
+发表论文时，建议在正文中说明以下参数配置：
+
+```
+网络规模: N = 12 节点
+部署区域: 800m × 800m
+Sink位置: 区域中心
+仿真时间: 200-300秒
+随机种子: 42（可复现）
+
+LoRa物理层:
+- 发射功率: 14 dBm
+- 扩频因子: SF9
+- 带宽: 125 kHz
+- 编码率: 4/5
+
+路由协议:
+- HELLO周期: 8秒
+- 链路惩罚因子: 8.0
+- 路由更新阈值: 1.0
+```
+
+### 5.2 关键结果展示
+
+建议在论文中重点展示以下结果：
+
+1. **多跳形成证明**
+   - max_hop ≥ 2
+   - hop_histogram显示多级跳数分布
+
+2. **网络可靠性**
+   - PDR > 50%
+   - 平均重传次数 < 1.5
+
+3. **路由稳定性**
+   - 收敛时间 < 30秒
+   - 路由变化率 < 0.05/秒
+
+4. **信道健康度**
+   - 信道利用率 < 20%
+   - 碰撞率 < 10%
+
+### 5.3 图表生成
+
+可使用分析工具生成可视化图表：
+
+```python
+# 拓扑分析
+from sim.analysis_tools.topology import analyze_topology
+
+# 收敛分析  
+from sim.analysis_tools.convergence import analyze_convergence
+
+# 信道分析
+from sim.analysis_tools.channel_analysis import analyze_channel
+
+# 可靠性分析
+from sim.analysis_tools.reliability_analysis import analyze_reliability
+```
+
+---
+
+## 6. 扩展与定制
+
+### 6.1 修改网络规模
+
+编辑 `sim/config.py`:
+
+```python
+NODE_COUNT = 20      # 增加节点数
+AREA_SIZE = 1200     # 扩大区域
+```
+
+### 6.2 修改物理层参数
+
+```python
+# 更激进的配置（更长距离）
+SF = 10              # 更大扩频因子
+TX_POWER = 20       # 更高发射功率
+
+# 更保守的配置（更短距离）
+SF = 7
+RSSI_THRESHOLD = -100
+```
+
+### 6.3 添加新指标
+
+在 `sim/core/metrics.py` 中的 `SimulationMetrics` 类添加新字段，并在相应位置调用 `record_xxx()` 方法记录数据。
+
+---
+
+## 7. 参考文献
+
+本仿真系统基于以下经典算法和模型：
+
+1. **梯度路由**: 基于RPL（Routing Protocol for Low-Power and Lossy Networks）的Distance-Vector思想
+2. **路径损耗模型**: 自由空间路径损耗（Free-Space Path Loss, FSPL）
+3. **CSMA/CA**: 载波侦听多路访问/冲突避免机制
+4. **SimPy**: Python离散事件仿真框架
+
+---
+
+## 8. 结论
+
+本仿真系统成功验证了LoRa多跳网络的以下关键特性：
+
+✓ 分布式路由自组织能力  
+✓ 多跳数据转发机制  
+✓ 网络可靠传输性能  
+✓ 路由稳定性  
+✓ 信道资源利用率  
+
+14项测试全部通过，证明该系统可以作为STM32WL硬件移植的算法基础和研究验证工具。
--- a/docs/update.md
+++ b/docs/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 后，将仿真结果提交用于协议级评估。