# 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硬件移植的算法基础和研究验证工具。