566 lines
6.2 KiB
Markdown
566 lines
6.2 KiB
Markdown
下面是**可直接交给执行 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 仿真阶段完成。
|