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)

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

2. 文本消息通信

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

3. 路由跟踪 (Trace)

• 收集SNR: 每个跳收集信号质量数据
• 路径记录: 记录完整的路由路径
• 诊断信息: 提供网络状态分析

🆚 与Meshtastic对比

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

🛠️ 协议实现要点

包编解码

// 包序列化
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网络的嵌入式项目，既保持了简洁性又提供了强大的功能扩展能力。