trail-mate/docs/MESHCORE_PROTOCOL.md

# MeshCore 通信协议介绍

## 📋 概述

MeshCore是一个轻量级的C++ LoRa Mesh网络协议库，专注于多跳包路由。与Meshtastic相比，MeshCore更注重**简洁性**和**可扩展性**，适合嵌入式项目的定制开发。

## 🔧 协议架构

### 核心特性
- **多跳路由**: 支持Flood和Direct两种路由模式
- **自定义二进制格式**: 不使用Google Protocol Buffers
- **Ed25519加密**: 完整的端到端安全支持
- **轻量级设计**: 适合资源受限的嵌入式设备

### 架构优势
- **紧凑包结构**: 最小化空中传输时间
- **灵活路由策略**: 支持多种路由算法
- **强加密保证**: 完整的节点身份验证
- **易于扩展**: 支持自定义负载类型

## 📦 数据包结构

### 包头格式 (1字节)

```
Bits:  7 6 5 4 3 2 1 0
       [版本:2][类型:4][路由:2]
```

**字段说明**:
- **路由类型** (Bits 0-1): 决定包的路由方式
- **负载类型** (Bits 2-5): 指定负载的数据类型
- **版本号** (Bits 6-7): 协议版本控制

### 完整包结构

| 字段 | 大小 | 描述 |
|------|------|------|
| `header` | 1字节 | 路由类型 + 负载类型 + 版本 |
| `transport_codes` | 4字节* | 传输层路由优化代码 |
| `path_len` | 1字节 | 路径字段长度 |
| `path` | 最多64字节 | 路由路径数据 |
| `payload` | 最多184字节 | 实际传输数据 |

* 仅在特定路由类型时存在

## 🛣️ 路由类型

### 1. Flood路由 (`ROUTE_TYPE_FLOOD = 0x01`)
- **动态路径构建**: 在传输过程中建立路由路径
- **网络发现**: 自动探索网络拓扑
- **适用场景**: 网络初始化、广播消息

### 2. Direct路由 (`ROUTE_TYPE_DIRECT = 0x02`)
- **预设路径**: 使用指定的路由路径
- **高效传输**: 减少路由开销
- **适用场景**: 点对点通信、已知路径

### 3. Transport路由 (扩展模式)
- **Flood+Transport**: 带传输编码的Flood路由
- **Direct+Transport**: 带传输编码的Direct路由
- **优化传输**: 通过编码提高可靠性

## 📄 负载类型 (16种)

### 基础通信类型
| 值 | 名称 | 描述 |
|----|------|------|
| `0x00` | `PAYLOAD_TYPE_REQ` | 请求消息 (带哈希和MAC) |
| `0x01` | `PAYLOAD_TYPE_RESPONSE` | 响应消息 |
| `0x02` | `PAYLOAD_TYPE_TXT_MSG` | 纯文本消息 |
| `0x03` | `PAYLOAD_TYPE_ACK` | 确认消息 |

### 高级功能类型
| 值 | 名称 | 描述 |
|----|------|------|
| `0x04` | `PAYLOAD_TYPE_ADVERT` | 节点广告 |
| `0x05` | `PAYLOAD_TYPE_GRP_TXT` | 组文本消息 (未验证) |
| `0x06` | `PAYLOAD_TYPE_GRP_DATA` | 组数据报 (未验证) |
| `0x08` | `PAYLOAD_TYPE_PATH` | 返回路径 |
| `0x09` | `PAYLOAD_TYPE_TRACE` | 路由跟踪 |

### 扩展类型
| 值 | 名称 | 描述 |
|----|------|------|
| `0x0A` | `PAYLOAD_TYPE_MULTIPART` | 多段包 |
| `0x0B` | `PAYLOAD_TYPE_CONTROL` | 控制包 |
| `0x0F` | `PAYLOAD_TYPE_RAW_CUSTOM` | 自定义包 |

## 🔐 安全机制

### 加密架构
- **Ed25519公钥**: 32字节公钥用于节点身份
- **消息认证**: 2字节MAC保证数据完整性
- **端到端加密**: 支持敏感数据加密传输
- **节点指纹**: 1字节公钥哈希用于路由决策

### 密钥管理
- **节点公钥**: 首次通信时交换
- **会话密钥**: 基于节点公钥派生
- **密钥缓存**: 本地存储已知节点的公钥

## 💬 通信流程

### 1. 节点发现 (Advertising)
```cpp
// 节点广告包结构
struct NodeAdvert {
    uint8_t public_key[32];    // Ed25519公钥
    uint32_t timestamp;        // 发送时间戳
    uint8_t signature[64];     // 数字签名
    uint8_t appdata[];         // 可选应用数据
};
```

### 2. 文本消息通信
```cpp
// 文本消息负载结构
struct TextMessage {
    uint32_t timestamp;        // 发送时间戳
    uint8_t flags;            // 消息标志
    uint8_t text[];           // UTF-8编码的文本
};
```

### 3. 路由跟踪 (Trace)
- **收集SNR**: 每个跳收集信号质量数据
- **路径记录**: 记录完整的路由路径
- **诊断信息**: 提供网络状态分析

## 🆚 与Meshtastic对比

| 特性 | MeshCore | Meshtastic |
|------|----------|------------|
| **数据格式** | 自定义二进制 | Google Protocol Buffers |
| **包大小** | 更紧凑 | 相对较大 |
| **扩展性** | 高 (自定义) | 中等 (proto定义) |
| **解析速度** | 快 | 中等 |
| **跨平台性** | C++专用 | 多语言支持 |

## 🛠️ 协议实现要点

### 包编解码
```cpp
// 包序列化
uint8_t Packet::writeTo(uint8_t dest[]) const {
    uint8_t i = 0;
    dest[i++] = header;
    if (hasTransportCodes()) {
        memcpy(&dest[i], &transport_codes[0], 2); i += 2;
        memcpy(&dest[i], &transport_codes[1], 2); i += 2;
    }
    dest[i++] = path_len;
    memcpy(&dest[i], path, path_len); i += path_len;
    memcpy(&dest[i], payload, payload_len); i += payload_len;
    return i;
}

// 包反序列化
bool Packet::readFrom(const uint8_t src[], uint8_t len) {
    // 实现包解析逻辑
}
```

### 路由决策
- **Flood模式**: 广播到所有邻居节点
- **Direct模式**: 根据路径字段直接转发
- **Transport模式**: 使用编码优化传输

### 去重机制
- **包哈希**: SHA256哈希用于包唯一标识
- **时间窗口**: 基于时间戳的去重检查
- **节点过滤**: 避免向源节点回传

## 🎯 使用场景

### 1. 离线通信网络
- **应急通信**: 灾难情况下保持连接
- **户外活动**: 徒步、露营团队通信
- **战术应用**: 军事和安全场景

### 2. 传感器网络
- **环境监测**: 远程传感器数据收集
- **工业物联网**: 设备状态监控
- **农业应用**: 田间设备通信

### 3. 自定义Mesh应用
- **专用协议**: 特定应用场景优化
- **轻量级实现**: 资源受限设备
- **灵活扩展**: 支持自定义负载类型

## 📊 性能特点

### 网络指标
- **最大跳数**: 可配置，通常3-5跳
- **包大小**: 最小20字节，最大256字节
- **传输延迟**: 取决于跳数和传播时间

### 可靠性特性
- **自动重试**: 失败包自动重传
- **路径优化**: 动态选择最佳路由
- **拥塞控制**: 避免网络过载

## 🔄 协议扩展

### 自定义负载类型
MeshCore支持扩展到16种以上的负载类型，开发者可以：
1. 定义新的负载格式
2. 实现对应的编解码逻辑
3. 添加处理函数

### 路由算法扩展
- **自定义路由策略**: 实现新的路由算法
- **QoS支持**: 服务质量保证
- **多路径路由**: 并行传输优化

## 📚 参考资源

- **协议规范**: `docs/packet_structure.md`
- **负载格式**: `docs/payloads.md`
- **示例代码**: `examples/` 目录
- **API文档**: `include/MeshCore.h`

这个协议设计非常适合需要定制LoRa Mesh网络的嵌入式项目，既保持了简洁性又提供了强大的功能扩展能力。