meshcore-bot/docs/path-command-config.md

Path Command Configuration Guide

This document explains all configuration parameters for the Path Command, which decodes hex path data to identify repeaters in message routing paths.

Multi-byte path support

The path command supports 1-, 2-, and 3-byte-per-hop paths (2, 4, or 6 hex characters per node).

• path with no arguments: Uses the current message’s decoded path when available (from routing info). No re-parsing; node list and hop size come from the packet.
• path <hex> with arguments:
  • Comma-separated (e.g. path 0102,5f7e): Hop size is inferred from token length. All tokens must be the same length (2, 4, or 6 hex chars). Example: 0102,5f7e → two 2-byte hops.
  • Continuous hex (e.g. path 01025f7e): The bot’s [Bot] prefix_bytes is used (2 hex chars = 1 byte, 4 = 2 bytes, 6 = 3 bytes). Use comma-separated input to force a multi-byte interpretation when the bot is in 1-byte mode.

Quick Start: Presets

The Path Command supports three presets that configure multiple related settings:

• balanced (default): Balanced approach using both graph evidence and geographic proximity
• geographic: Prioritize geographic proximity over graph evidence (better for local networks)
• graph: Prioritize graph evidence over geographic proximity (better for well-connected networks)

Set the preset using:

path_selection_preset = balanced

Core Settings

Geographic Proximity

proximity_method (simple | path)

• simple: Use proximity to bot location only
• path: Use proximity to previous/next nodes in path (more realistic routing)
• Default: simple

path_proximity_fallback (boolean)

• When path proximity can't be calculated, fall back to simple proximity
• Default: true

max_proximity_range (kilometers, 0 = disabled)

• Maximum distance for geographic proximity consideration
• Repeaters beyond this distance are filtered out or have reduced confidence
• Default: 200 (long LoRa transmission range)

recency_weight (0.0 to 1.0)

• Controls recency vs proximity weighting
• 0.0 = 100% proximity (only distance matters)
• 1.0 = 100% recency (only when last heard matters)
• 0.4 = 40% recency, 60% proximity (balanced)
• Default: 0.4

recency_decay_half_life_hours (hours)

• How quickly recency scores decay for older repeaters
• Default: 12 hours
• For 48-72 hour advert intervals, use 36-48 hours

max_repeater_age_days (days, 0 = disabled)

• Only include repeaters heard within this many days
• Helps filter out stale repeaters
• Default: 14 days

Graph-Based Selection

Prefix length and graph conflation

The graph stores edges using the bot’s prefix length ([Bot] prefix_bytes). Paths from packets can be 1-, 2-, or 3-byte encoded (per sender); when we record edges we normalize to the bot’s prefix. If the bot uses prefix_bytes=1 (2 hex chars) and the mesh often uses 2-byte paths, distinct links can be merged: e.g. 7E42→8611 and 7E99→86FF both become a single edge (7e, 86). That can overcount observations and make path resolution ambiguous when several repeaters share the same short prefix. Recommendation: set prefix_bytes to match the mesh (e.g. 2 if most traffic is 2-byte) so the graph keeps finer resolution and the mesh viewer shows one node per prefix instead of collapsing many repeaters into one.

graph_based_validation (boolean)

• Enable graph-based path validation using observed mesh connections
• Default: true

min_edge_observations (integer)

• Minimum edge observations required for graph confidence
• Higher values = more conservative (requires more evidence)
• Default: 3

graph_edge_expiration_days (days)

• Edges not observed for this many days are ignored
• Default: 7 days

graph_use_bidirectional (boolean)

• Check for reverse edges for higher confidence
• Default: true

graph_use_hop_position (boolean)

• Validate candidates appear in expected positions based on observed routing patterns
• Default: true

graph_multi_hop_enabled (boolean)

• Use 2-hop or 3-hop paths to find intermediate nodes when direct edges don't exist
• Default: true

graph_multi_hop_max_hops (integer)

• Maximum hops for multi-hop path inference
• 2 = only 2-hop paths (A->B->C)
• 3 = also try 3-hop paths (A->B->C->D)
• Default: 2

graph_prefer_stored_keys (boolean)

• Prioritize candidates whose public key matches stored keys in graph edges
• Stored keys indicate high confidence (+0.4 bonus)
• Default: true

Graph vs Geographic Selection

graph_geographic_combined (boolean)

• Combine graph and geographic scores into weighted average
• Only combines when both methods select the same repeater
• Default: false (uses graph-first fallback)

graph_geographic_weight (0.0 to 1.0)

• Weight for graph score when combining (only used if graph_geographic_combined = true)
• 0.7 = 70% graph, 30% geographic
• Default: 0.7

graph_confidence_override_threshold (0.0 to 1.0)

• When graph confidence >= this value, graph overrides geographic selection
• Lower values = geographic gets more consideration
• 1.0 = always prefer geographic when available
• 0.0 = always prefer graph
• Default: 0.7

Distance Penalties (Intermediate Hops)

graph_distance_penalty_enabled (boolean)

• Penalize graph scores for candidates creating long-distance hops
• Prevents selecting very distant repeaters even with strong graph evidence
• Default: true

graph_max_reasonable_hop_distance_km (kilometers)

• Maximum reasonable hop distance before applying penalty
• Typical LoRa transmission: < 30km
• Long LoRa transmission: up to 200km
• Default: 30 (typical transmission range)

graph_distance_penalty_strength (0.0 to 1.0)

• How much to penalize graph scores for long-distance hops
• 0.3 = 30% penalty for hops beyond max_reasonable_hop_distance
• Default: 0.3

Zero-Hop Bonus

graph_zero_hop_bonus (0.0 to 1.0)

• Bonus for repeaters heard directly by the bot (zero-hop adverts)
• Strong evidence the repeater is close, even for intermediate hops
• Based on actual observed direct communication, not proximity guessing
• Default: 0.4

Final Hop Proximity (Advanced)

The final hop (last repeater before bot) gets special proximity consideration. These settings are advanced and typically don't need adjustment.

graph_final_hop_proximity_enabled (boolean)

• Enable bot location proximity consideration for final hop
• Default: true

graph_final_hop_proximity_weight (0.0 to 1.0)

• Base weight for proximity when combining with graph score for final hop
• 0.25 = 25% proximity, 75% graph score
• Default: 0.25

graph_final_hop_max_distance (kilometers, 0 = no limit)

• Maximum distance for final hop proximity consideration
• Repeaters beyond this distance don't receive proximity bonus
• Default: 0 (no limit)

graph_final_hop_proximity_normalization_km (kilometers)

• Distance normalization for final hop proximity scoring
• Lower values = more aggressive scoring
• Default: 200 (long LoRa range)

graph_final_hop_very_close_threshold_km (kilometers)

• Repeaters within this distance get 2x proximity weight boost
• Default: 10 km

graph_final_hop_close_threshold_km (kilometers)

• Repeaters within this distance get 1.5x proximity weight boost
• Default: 30 km (typical transmission range)

graph_final_hop_max_proximity_weight (0.0 to 1.0)

• Maximum proximity weight for very close repeaters
• Default: 0.6

Path Validation Bonus

graph_path_validation_max_bonus (0.0 to 1.0)

• Maximum bonus for path validation matches
• Helps resolve prefix collisions by matching stored path patterns
• Default: 0.3

graph_path_validation_obs_divisor (float)

• Divisor for observation count bonus
• Lower values = stronger bonus from observation count
• 50.0 means 50 observations = 0.15 bonus
• Default: 50.0

Graph Persistence (Advanced)

These settings control how graph edges are stored in the database.

graph_write_strategy (immediate | batched | hybrid)

• immediate: Write each edge update immediately (safer, higher I/O)
• batched: Accumulate updates, flush periodically (better performance)
• hybrid: Immediate for new edges, batched for increments (balanced)
• Default: hybrid

graph_batch_interval_seconds (seconds)

• How often to flush pending edge updates (only for batched/hybrid)
• Default: 30

graph_batch_max_pending (integer)

• Maximum pending updates before forcing a flush
• Default: 100

graph_startup_load_days (days, 0 = load all)

• Load only edges seen in last N days on startup
• 0 = load all edges (use on servers with ample RAM)
• Default: 14 (set to 0 in config.ini to load all)

graph_capture_enabled (boolean)

• When false, no new edge data is collected from packets and the background batch writer thread is not started — reducing CPU and RAM overhead
• Edges already in the database are still used for path validation
• Set to false on devices that don't use the path command
• Default: true

Probabilistic Topology Engine (Shadow/Cutover)

These settings control the additive topology engine used for shadow-mode validation and optional cutover.

topology_engine_mode (legacy | shadow | new)

• legacy: Keep existing graph/geographic selection only
• shadow: Run topology model in parallel and store legacy-vs-model comparisons
• new: Use topology model as primary selector with legacy fallback
• Default: legacy

topology_shadow_sample_rate (0.0 to 1.0)

• Sampling rate for writing shadow comparisons
• 1.0 writes all comparisons; lower values reduce DB churn on busy nodes
• Default: 1.0

topology_ghost_enabled (boolean)

• Allow low-confidence unresolved selections to be tracked as ghost hypotheses
• Ghost nodes are stored in a supplemental table and do not alter legacy data
• Default: true

topology_ghost_min_confidence (0.0 to 1.0)

• Minimum confidence required before topology selections are treated as non-ghost
• Lower values accept more model choices; higher values are more conservative
• Default: 0.35

topology_max_candidates_per_prefix (integer)

• Maximum number of repeater candidates considered per prefix during decode
• Lower values reduce CPU; higher values improve ambiguity exploration
• Default: 12

topology_advert_anchor_enabled (boolean)

• Enable advert-origin soft-prior scoring for topology evaluation paths (shadow/backfill)
• Uses observed_paths.public_key for advert rows as a bounded signal; never a hard lock
• Default: false

topology_advert_anchor_weight (0.0 to 1.0)

• Relative strength of advert-origin soft prior when enabled
• Higher values increase influence of origin-linked evidence, but still bounded by max adjustment
• Default: 0.2

topology_advert_anchor_max_adjustment (0.0 to 0.5)

• Hard cap on per-step score adjustment from advert-origin prior
• Keeps prior additive and prevents it from overwhelming graph/recency evidence
• Default: 0.08

topology_advert_anchor_freshness_hours (integer hours)

• Maximum age for origin evidence before prior is treated as stale/neutral
• Default: 168 (7 days)

Preset Configurations

balanced (Default)

• Uses both graph evidence and geographic proximity
• Graph confidence threshold: 0.7
• Distance penalties: enabled (30km threshold)
• Final hop proximity: enabled
• Good for: Most networks with mixed connectivity

geographic

• Prioritizes geographic proximity
• Graph confidence threshold: 0.5 (lower, gives geographic more weight)
• Distance penalties: enabled (30km threshold, stronger penalty)
• Final hop proximity: enabled with higher weight
• Good for: Local networks where repeaters are close together

graph

• Prioritizes graph evidence
• Graph confidence threshold: 0.9 (higher, graph wins more often)
• Distance penalties: enabled (50km threshold, weaker penalty)
• Final hop proximity: enabled with lower weight
• Good for: Well-connected networks with strong graph evidence

Typical LoRa Transmission Ranges

• Typical transmission: < 30km
• Long transmission: up to 200km
• Very close: < 10km (often direct line-of-sight)

These ranges inform the default distance thresholds used throughout the path selection algorithm.