Advanced MeshCore Topics

• MeshCore Path Discovery Deep Dive
• MeshCore Network Troubleshooting Reference

MeshCore Path Discovery Deep Dive

A detailed look at MeshCore's path discovery and route management system, based on verified information from the official MeshCore repository.

The Core Mechanism

MeshCore's routing uses two phases that together eliminate the channel waste of pure flooding while maintaining the reliability of flood-based initial contact:

Phase 1: Flood with Path Recording

Every ROUTE_TYPE_FLOOD packet that travels through a repeater has its path recorded at the destination. The destination node knows the exact sequence of repeaters the packet passed through because each repeater appends its identity to a path record in the packet.

Phase 2: Path Return via PAYLOAD_TYPE_PATH

The destination sends a PAYLOAD_TYPE_PATH response back to the original sender. This packet contains the ordered list of repeaters from the flood path. The path packet itself uses direct routing if a reverse path is known, otherwise floods back.

Phase 3: Stored Direct Routes

The sender stores the learned path and uses it for all subsequent messages to that destination using ROUTE_TYPE_DIRECT. The path remains valid until a direct-routed message fails (no acknowledgement within timeout), at which point the sender falls back to flooding and re-learns the path.

Path Hash Modes

MeshCore supports configurable path hash modes (set path.hash.mode CLI command), which affects how path uniqueness is determined and how aggressively the routing table is compacted. Modes 0, 1, and 2 are available. This allows tuning for networks where repeater positions change frequently vs. stable fixed infrastructure.

Flood Limits

To prevent unbounded flooding, MeshCore allows configuration of flood.max (max number of repeaters a flood packet passes through, 0 - 64) and flood.advert.interval. These limit worst-case channel usage during path discovery.

Regional Scoping

Transport route types (ROUTE_TYPE_TRANSPORT_FLOOD and ROUTE_TYPE_TRANSPORT_DIRECT) include a region/transport code that allows multi-region networks to scope traffic appropriately. ISO country codes are the standard region identifiers.

Source: docs/packet_format.md and CLI reference in the official MeshCore repository. Verified 2026-05-03.

MeshCore Network Troubleshooting Reference

A systematic approach to troubleshooting MeshCore network issues saves time and frustration. This reference covers the most common problems and their diagnostic approaches.

Diagnostic Framework

When a problem is reported, ask these questions in order:

1. Is the problem isolated to one node pair, or affecting all nodes?
2. Is the problem one-directional or bidirectional?
3. Did it work before? What changed?
4. Is the issue at the RF layer (no signal) or the protocol layer (signal present, no delivery)?

Problem: Node Not Seen by Others

Symptoms: A node is powered on but doesn't appear in other nodes' neighbor lists or can't communicate with anyone.

Diagnostics:

• Check: Is the node's LoRa radio initialized? (Serial CLI: status)
• Check: Is the frequency/preset matching other nodes? (Verify with get lora)
• Check: Is the antenna connected? (Transmit without antenna = immediate hardware risk on some boards)
• Check: Is the channel key matching? (Different key = nodes don't recognize each other's packets)
• Check: Is there a hardware failure? (Try a different known-good node at the same location)

Problem: Messages Not Delivered

Symptoms: Nodes can see each other but messages don't arrive, or arrive with high latency.

• SNR below -15 dB: Signal is present but too weak. Add a repeater or improve antennas.
• High channel utilization: Too many nodes flooding the network. Check for misconfigured flooding, reduce hop limit.
• Path discovery failure: path discovery flood is flooding but path response is not returning. One-way link - the return path may be blocked by terrain or a directional antenna pointing wrong way.
• Room server not receiving messages: Check that room server's attached LoRa node is on the correct channel and hearing the network.

Problem: Room Server Clients Not Syncing

Symptoms: App connects to room server but doesn't show recent messages or shows empty history.

• Check room server connectivity: ssh pi@room-server journalctl -u meshcore-roomserver -n 50
• Check message count: messages count from room server CLI
• Check port: Default port 5005 - is the firewall allowing connections?
• Check key: Room key must match between app configuration and server configuration

Problem: Repeater Goes Offline Periodically

Symptoms: A backbone repeater disappears from the network at irregular intervals, then reappears.

• Power issue: Insufficient solar charging, battery capacity degradation. Check voltage logs.
• Firmware watchdog: nRF52840 watchdog timer should prevent lockups but may be triggering reboots on firmware bugs. Check for panic/reset logs in serial output.
• Thermal issue: Summer heat causing processor throttling or thermal shutdown. Check enclosure temperature.
• Memory leak: Known issue in some firmware versions with long uptime. If reboot schedule resolves it, update firmware or add a periodic reboot cron job.

Useful CLI Diagnostic Sequence

# Connect to node serial console
screen /dev/ttyUSB0 115200

# Full status check:
status # Overall health
repeaters # List heard repeaters and their signal
stats # Packet counts (received/forwarded/dropped)

# Check a specific path:
# (Send a traceroute to see path to another node)
traceroute !targetNodeId

# Check room server connectivity:
federation list # Shows federation peers and last sync time
clients # Shows connected clients