trail-mate/docs/MESHCORE_PROTOCOL.md

Introduction to MeshCore communication protocol

📋 Overview

MeshCore is a lightweight C++ LoRa Mesh network protocol library focusing on multi-hop packet routing. Compared with Meshtastic, MeshCore pays more attention to simplicity and scalability, and is suitable for customized development of embedded projects.

🔧 Protocol architecture

Core features

• Multi-hop routing: Supports Flood and Direct routing modes
• Custom binary format: Does not use Google Protocol Buffers
• Ed25519 encryption: Complete end-to-end security support
• Lightweight design: suitable for resource-constrained embedded devices

Architectural advantages

• Compact package structure: Minimize air transmission time
• Flexible routing policy: Support multiple routing algorithms
• Strong encryption guarantee: Full node authentication
• Easy to extend: Supports custom payload types

📦 Packet structure

Header format (1 byte)

Bits:  7 6 5 4 3 2 1 0
 [Version: 2] [Type: 4] [Route: 2]

Field description:

• Route type (Bits 0-1): Determine how the packet is routed
• Payload type (Bits 2-5): Specify the data type of the payload
• Version number (Bits 6-7): Protocol version control

Complete packet structure

Fields	Size	Description
header	1 byte	route type + payload type + version
transport_codes	4 bytes*	Transport layer routing optimization code
path_len	1 byte	path field length
path	up to 64 bytes	routing path data
payload	Maximum 184 bytes	Actual transmission data

• Only exists for specific route types

🛣️ Route type

1. Flood routing (ROUTE_TYPE_FLOOD = 0x01)

• Dynamic path construction: Establish routing paths during transmission
• Network discovery: Automatically explore network topology
• Applicable scenarios: Network initialization, broadcast messages

2. Direct routing (ROUTE_TYPE_DIRECT = 0x02)

• Default path: Use the specified routing path
• Efficient transmission: Reduce routing overhead
• Applicable scenarios: point-to-point communication, known paths

3. Transport routing (extended mode)

• Flood+Transport: Flood routing with transfer encoding
• Direct+Transport: Direct routing with transfer encoding
• Optimized transmission: Improved reliability through coding

📄 Payload Types (16)

Base Communication Types

Value	Name	Description
0x00	PAYLOAD_TYPE_REQ	Request message (with hash and MAC)
0x01	PAYLOAD_TYPE_RESPONSE	Response message
0x02	PAYLOAD_TYPE_TXT_MSG	Plain text message
0x03	PAYLOAD_TYPE_ACK	Confirmation message

Advanced feature type

Value	Name	Description
0x04	PAYLOAD_TYPE_ADVERT	Node advertisement
0x05	PAYLOAD_TYPE_GRP_TXT	Group text message (not verified)
0x06	PAYLOAD_TYPE_GRP_DATA	Group datagram (not verified)
0x08	PAYLOAD_TYPE_PATH	Return path
0x09	PAYLOAD_TYPE_TRACE	Traceroute

Extended type

Value	Name	Description
0x0A	PAYLOAD_TYPE_MULTIPART	Multipart package
0x0B	PAYLOAD_TYPE_CONTROL	Control package
0x0F	PAYLOAD_TYPE_RAW_CUSTOM	Custom package

🔐 Security mechanism

Encryption architecture

• Ed25519 Public Key: 32-byte public key used for node identity
• Message Authentication: 2-byte MAC ensures data integrity
• End-to-end encryption: Supports encrypted transmission of sensitive data
• Node Fingerprint: 1-byte public key hash used for routing decisions

Key management

• Node public key: exchanged during the first communication
• Session key: derived based on the node public key
• Key cache: local storage of the public key of a known node

💬 Communication process

1. Node discovery (Advertising)

// Node advertising packet structure
struct NodeAdvert {
    uint8_t public_key[32];    // Ed25519 public key
    uint32_t timestamp;        // send timestamp
    uint8_t signature[64];     // digital signature
    uint8_t appdata[];         // optional application data
};

2. Text message communication

// Text message payload structure
struct TextMessage {
    uint32_t timestamp;        // send timestamp
    uint8_t flags;            // message flags
    uint8_t text[];           // UTF-8-encoded text
};

3. Route tracing (Trace)

• Collect SNR: Collect signal quality data for each hop
• Path record: Record the complete routing path
• Diagnostic information: Provide network status analysis

🆚 Comparison with Meshtastic

Features	MeshCore	Meshtastic
Data format	Custom binary	Google Protocol Buffers
Packet size	More compact	Relatively large
Extensibility	High (custom)	Medium (proto definition)
Parsing Speed	Fast	Medium
Cross-platform	C++ specific	Multi-language support

🛠️ Key points of protocol implementation

Packet encoding and decoding

//Packet serialization
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;
}

//Packet deserialization
bool Packet::readFrom(const uint8_t src[], uint8_t len) {
 // Implement package parsing logic
}

Routing decision

• Flood mode: Broadcast to all neighbor nodes
• Direct mode: Direct forwarding based on the path field
• Transport mode: Use encoding to optimize transmission

Deduplication mechanism

• Packet Hash: SHA256 hash is used to uniquely identify the package
• Time Window: Timestamp-based deduplication check
• Node filtering: Avoid postback to the source node

🎯Usage scenarios

1. Offline communication network

• Emergency communication: Stay connected in disaster situations
• Outdoor activities: Hiking and camping team communication
• Tactical applications: Military and security scenarios

2. Sensor network

• Environmental monitoring: Remote sensor data collection
• Industrial Internet of Things: Equipment status monitoring
• Agricultural applications: Field equipment communication

3. Customized Mesh application

• Specialized protocol: Optimized for specific application scenarios
• Lightweight implementation: Resource-constrained equipment
• Flexible expansion: Supports custom load types

📊 Performance characteristics

Network indicators

• Maximum number of hops: configurable, usually 3-5 hops
• Packet size: minimum 20 bytes, maximum 256 bytes
• Transmission delay: Depends on hop count and propagation time

Reliability features

• Auto-retry: Automatic retransmission of failed packets
• Path optimization: Dynamically select the best route
• Congestion control: Avoid network overload

🔄 Protocol extensions

Custom payload types

MeshCore supports expansion to more than 16 payload types. Developers can:

1. Define new payload formats
2. Implement corresponding encoding and decoding logic
3. Add processing function

Routing algorithm extension

• Customized routing strategy: Implement new routing algorithm
• QoS support: Service quality assurance
• Multipath routing: Parallel transmission optimization

📚 Reference resources

• Protocol specification: docs/packet_structure.md
• Payload format: docs/payloads.md
• Example code: examples/ Directory
• API Documentation: include/MeshCore.h

This protocol design is very suitable for embedded projects that require customized LoRa Mesh networks, maintaining simplicity while providing powerful function expansion capabilities.