Help & Documentation
Learn how to interpret packet data, understand scoring, and optimize your configuration
Packet Table Overview
The packet table displays real-time information about every packet your repeater receives and processes. Each row represents a single packet event, showing transmission details, signal quality metrics, and repeater processing information.
Purpose: The packet table helps you monitor network traffic, diagnose signal issues, and understand how your repeater is handling different types of packets.
Column Details
Time
Type
ACK: Acknowledgment responses
TXT: Text messages
GRP: Group messages
PATH: Path information packets
RESP: Response packets
TRACE: Trace/debug packets
Route
FLOOD: Broadcast packet intended for all nodes in range
DIRECT packets have higher priority since they're specifically addressed to your repeater. FLOOD packets are retransmitted if bandwidth allows.
Length
RSSI
Excellent: -80 to -100 dBm (strong)
Good: -100 to -120 dBm (acceptable)
Poor: -120 to -140 dBm (weak, may be unreliable)
Affects score calculation - better RSSI yields higher scores. Distance and obstacles reduce RSSI.
SNR
Excellent: SNR > 10 dB (very clean)
Good: SNR 5-10 dB (normal operation)
Poor: SNR < 5 dB (noisy environment)
Even with weak RSSI, high SNR indicates reliable reception. Critical for score calculation.
Score
TX Delay
• Airtime budget checking
• Random collision avoidance (0-5ms factor)
• Current channel utilization
• Optional quality-based prioritization (when enabled)
Longer delays may indicate congestion or airtime throttling to comply with duty cycle limits.
Status
DROPPED: Packet was rejected and not forwarded.
Drop Reasons:
- Duplicate: Packet hash already in cache. Prevents redundant retransmission.
- Empty payload: Packet has no payload data. Cannot be processed.
- Path at max size: Path field has reached maximum length. Cannot add repeater identifier.
- Duty cycle limit: Airtime budget exhausted. Cannot transmit (EU 1% duty cycle or configured limit).
- Direct: no path: Direct-mode packet lacks routing path.
- Direct: not our hop: Direct-mode packet is not addressed to this repeater node.
Scoring System
The packet score is calculated using the exact same algorithm as the C++ MeshCore implementation. It combines SNR (relative to spreading factor threshold) and packet length to produce a single quality indicator (0.0 to 1.0). This score can optionally be used for reactive delay optimization when use_score_for_tx is enabled.
The Scoring Formula
Spreading Factor Thresholds
Real-World Example
Packet Details:
- SNR:
12 dB - Spreading Factor:
SF8 - Payload Length:
100 bytes
Calculation:
Length Factor = (1 - 100/256) = 0.609
Score = 1.0 × 0.609 = 0.61 (FAIR quality)
This formula ensures that:
- Signal quality matters: Higher SNR produces higher scores, with SF-specific thresholds
- Smaller packets score higher: They consume less airtime due to shorter transmission time
- Poor SNR packets may score zero: If SNR falls below SF threshold, score = 0.0
Score Interpretation
What Affects Your Score?
Primary Factors
Signal-to-Noise Ratio (SNR)
Each 1 dB improvement in SNR can increase score by ~0.05. High interference environments significantly reduce scores. The repeater benefits from placement with clear LoS (line of sight) to minimize multipath and fading.
Packet Payload Length
Larger packets consume more airtime due to longer transmission times. A 100-byte packet scores lower than a 50-byte packet with identical SNR.
RSSI (Signal Strength)
RSSI is displayed for monitoring purposes but does NOT affect the score calculation. The C++ MeshCore algorithm uses only SNR and packet length. However, RSSI correlates with SNR - better RSSI typically means better SNR, which indirectly results in higher scores.
Environmental Factors
- Weather: Rain and fog reduce signal strength and increase noise
- Time of Day: Atmospheric conditions change, especially during dawn/dusk
- Frequency Congestion: More devices on 869 MHz = higher noise floor
- Physical Obstructions: Buildings and trees block signals, increase fading
- Antenna Orientation: Poor antenna alignment reduces SNR significantly
Environmental Issues: If you see consistently low scores across many packets, check your antenna placement, orientation, and surroundings. Poor environmental conditions are often the limiting factor, not the repeater itself.
Reactive Score-Based Delay Optimization
The repeater includes an optional reactive scoring system that dynamically prioritizes packets based on signal quality during network congestion. This feature matches the C++ MeshCore behavior for intelligent packet prioritization.
How It Works
Key Principle: When the repeater detects congestion (calculated TX delay ≥ 50ms), it automatically applies a quality-based delay multiplier to high-quality packets, giving them priority while gracefully backing off low-quality packets.
Default Behavior: This feature is disabled by default (use_score_for_tx: false). When disabled, all packets follow standard C++ MeshCore delay calculation with pure randomization.
Delay Multiplier Formula
What this means:
- Perfect packet (score 1.0): Multiplier = max(0.2, 0.0) = 0.2 → Gets 20% of base delay (fast priority)
- Good packet (score 0.7): Multiplier = max(0.2, 0.3) = 0.3 → Gets 30% of base delay
- Fair packet (score 0.5): Multiplier = max(0.2, 0.5) = 0.5 → Gets 50% of base delay
- Poor packet (score 0.2): Multiplier = max(0.2, 0.8) = 0.8 → Gets 80% of base delay (slower, backoff)
- Minimum floor: No packet gets less than 20% multiplier (prevents starvation)
Example: Reactive Scoring in Action
Scenario: Two packets arrive during congestion (base delay 100ms), tx_delay_factor=1.0
- Packet X: Excellent signal, score = 0.9
- Packet Y: Weak signal, score = 0.4
Without Reactive Scoring (disabled):
- Packet X: TX Delay = 0-500ms (pure random collision avoidance)
- Packet Y: TX Delay = 0-500ms (pure random collision avoidance)
- Result: Both may transmit at same time, causing collision
With Reactive Scoring (enabled, congestion detected):
- Packet X: Multiplier = 0.1 → TX Delay = 0-50ms (high priority, transmits first)
- Packet Y: Multiplier = 0.6 → TX Delay = 0-300ms (lower priority, waits longer)
- Result: High-quality packets forward with minimal delay; marginal packets gracefully back off
Configuration
use_score_for_tx
Options: true or false
When true: Activates quality-based delay multiplier when congestion detected (delay ≥ 50ms)
When false: Standard C++ MeshCore behavior, pure random delays, no score influence on timing
Location in config.yaml:
use_score_for_tx: false
score_threshold
Range: 0.0 - 1.0
Current Status: This value is read from config but not currently used in packet processing. It is reserved for future features.
Future Potential Uses:
- Dashboard quality alerts when average packet score drops below threshold
- Proactive packet filtering - dropping very poor quality packets upfront (below threshold)
- Quality monitoring and trend statistics in web UI
- Logging alerts for poor signal conditions
When to Enable Reactive Scoring
Enable (use_score_for_tx: true)
• High-traffic networks where collisions are frequent
• Noisy environments with poor average signal quality
• You want to prioritize high-quality packets during congestion
• Testing adaptive network behavior
• Duty-cycle constrained regions (EU) with limited bandwidth
Disable (use_score_for_tx: false)
• Low-traffic networks where congestion is rare
• You want pure C++ MeshCore compatibility
• Consistent delay behavior is more important than efficiency
• New deployments - start simple and tune later
Important: Reactive scoring only affects TX delay timing, not packet forwarding decisions. All packets still get forwarded (unless dropped for other reasons like duplicates or duty cycle). The system gracefully prioritizes quality during congestion without dropping packets, matching MeshCore's intelligent backpressure strategy.
Configuration Impact on Scoring
Your repeater's configuration settings directly affect packet scoring and processing behavior.
Radio Configuration Parameters
Spreading Factor (SF)
Current setting: SF 8
Higher SF (9-12): Better range and SNR, but slower transmission, more airtime consumed
Lower SF (7): Faster transmission, less airtime, but worse sensitivity and range
Score impact: Higher SF generally improves SNR = higher scores, but increases payload duration penalty
Bandwidth (BW)
Current setting: 62.5 kHz
Wider BW (125 kHz): Faster data rate, less airtime per byte, but worse sensitivity
Narrower BW (31.25 kHz): Better sensitivity, but slower transmission
Score impact: BW affects SNR - narrower = potentially better SNR but longer TX times
TX Power
Current setting: 14 dBm
Higher power: Better outbound range, but may increase noise at nearby receivers
Lower power: Reduces interference, saves energy, but limits outbound range
Score impact: TX power only affects outgoing transmissions, not received score
Coding Rate (CR)
Current setting: 4/8
Higher CR (4/7): Less error correction, faster transmission, more airtime efficient
Lower CR (4/8): More error correction, better resilience to interference
Score impact: Higher CR can improve SNR in clean environments, reduce it in noisy ones
Duty Cycle Configuration
Current Duty Cycle Limit: 6% max airtime per hour
This means your repeater can spend at most 3.6 minutes (21.6 seconds per minute) transmitting per hour. How this affects packet handling:
- When below limit: All packets retransmitted if they pass validation
- When approaching limit: Incoming packets may be dropped if airtime budget is exhausted
- When limit reached: All new transmissions are dropped until the duty cycle budget resets (each minute)
Important: The repeater does NOT queue packets for later transmission. When duty cycle limit is reached, packets are immediately dropped. This is by design - a repeater must forward immediately or drop the packet. Note: Packet score does not affect duty cycle enforcement - all packets are treated equally when duty cycle limit is reached.
Airtime Consumption Example
Scenario: 100-byte packet at SF8, BW 62.5 kHz, CR 4/8
Airtime: ~512 ms
At 6% duty cycle: Can transmit ~420 packets/hour maximum
Effect on score: High volume of large packets will consume budget quickly, causing lower-scored packets to be dropped
Configuration Settings Reference
The repeater is configured via config.yaml. This section explains key settings and how they affect packet performance.
Important: Packet Score (signal quality) and TX Delay (collision avoidance timing) are independent systems. Score is calculated from SNR and packet length. Delays are configured via tx_delay_factor and direct_tx_delay_factor and are based on airtime, not signal quality.
Delay Settings
tx_delay_factor
Purpose: Scales the base collision-avoidance delay for flood packets.
Formula: delay = random(0-5) × (airtime × 52/50 ÷ 2) × tx_delay_factor
Effect: Higher values = longer delays between flood packet retransmissions, reducing collisions but increasing latency. Lower values speed up propagation in low-traffic areas.
Typical range: 0.5 - 2.0 (0.5 = faster, 2.0 = collision-resistant)
direct_tx_delay_factor
Purpose: Fixed delay for direct-routed packets (packets specifically addressed to this repeater).
Effect: Direct packets wait this many seconds before retransmission. Direct packets bypass the collision-avoidance algorithm and use a fixed delay instead.
Note: Typically lower than flood delays to prioritize DIRECT packets. 0 = immediate forwarding.
Typical range: 0 - 2.0 seconds
How TX Delay is Calculated
The TX Delay shown in the packet table follows the MeshCore C++ implementation for collision avoidance:
For FLOOD packets (broadcast):
TX Delay = random(0 to 5) × (airtime_ms × 52/50 ÷ 2) × tx_delay_factor ÷ 1000
For DIRECT packets (addressed to this repeater):
TX Delay = direct_tx_delay_factor (fixed, in seconds)
Optional Reactive Scoring:
If use_score_for_tx is enabled AND delay ≥ 50ms:
TX Delay = base_delay × max(0.2, 1.0 - packet_score)
This applies a quality-based multiplier during congestion: high-score packets get shorter delays (priority), low-score packets get longer delays (backoff).
Example: FLOOD packet with 100ms airtime, tx_delay_factor=1.0, score=0.8:
• Base delay = (100 × 52/50 ÷ 2) = 52 ms
• With random(0-5) multiplier: 0-260 ms (before score adjustment)
• If ≥50ms AND score adjustment active: 0-260ms × max(0.2, 1.0-0.8) = 0-260ms × 0.2 = 0-52ms (prioritized)
Tuning: Increase tx_delay_factor in high-traffic areas to reduce collisions. Decrease in low-traffic areas for faster propagation. Enable use_score_for_tx for intelligent priority during congestion. Direct packets bypass randomization and use fixed delays.
Duty Cycle Constraints
max_airtime_per_minute
•
3600 ms/min = 100% duty cycle (US/AU FCC, no restriction)•
36 ms/min = 1% duty cycle (EU ETSI standard)•
360 ms/min = 10% duty cycle (compromise for EU testing)Effect on packet handling: Duty cycle enforcement is independent of packet score. When duty cycle limit is reached, ALL packets are dropped equally - regardless of signal quality. The system does not prioritize high-score packets; it simply refuses to transmit until the budget resets.
TX Delay impact: TX Delay shown in the packet table is unaffected by duty cycle limits. However, packets may be completely blocked (dropped) when airtime budget is exhausted. There is no queuing or delay-until-later mechanism - dropped packets are lost immediately.
Packet distribution during high traffic: When approaching or exceeding duty cycle limits (>80%), incoming packets are dropped indiscriminately based on airtime availability. The mean packet score will fluctuate based on random traffic mix, not because the system prefers high-score packets. All packets have equal probability of being dropped when budget is exhausted.
How These Work Together
Example Scenario - Packet Forwarding with Delay:
You receive 3 packets with different routes and sizes (tx_delay_factor=1.0, direct_tx_delay_factor=0.5s):
- Packet A: Route DIRECT, 50 bytes → TX Delay = 0.5 seconds (fixed)
- Packet B: Route FLOOD, 100 bytes → TX Delay = random(0-5) × 52ms × 1.0 = 0-260 ms
- Packet C: Route FLOOD, 150 bytes → TX Delay = random(0-5) × 78ms × 1.0 = 0-390 ms
Processing order (without duty cycle limits):
- Packet A: Waits 0.5s, then forwards (direct packets get fixed priority)
- Packets B & C: Random delays prevent collision, lower packet transmitted first if random lucky
If duty cycle ~95% full: Still forwards all three, but with increased TX delays. If insufficient airtime remains for a packet, it is dropped immediately (not queued)
Optimization Tips
- For high-traffic/interference: Increase
tx_delay_factorto 1.5-2.0 to reduce collisions with more randomization - For low-traffic areas: Decrease
tx_delay_factorto 0.5 for faster propagation - For priority direct packets: Lower
direct_tx_delay_factorbelow 0.5s for faster handling - For duty-cycle constrained regions (EU): Keep default settings; airtime budget enforces fairness
- Monitor TX Delay column: Increasing delays indicate network congestion or approaching duty cycle limits