Troubleshooting
- Diagnosing MeshCore Repeater Problems
- Reflashing and Factory Reset
- Advanced MeshCore Repeater Diagnostics
Diagnosing MeshCore Repeater Problems
A systematic approach to diagnosing MeshCore repeater issues. Work from the physical layer up: radio first, then configuration, then network behavior.
Quick pre-diagnosis checklist
- Is the device powered? (check LED, screen, or measure supply voltage)
- Is an antenna connected? (transmitting without an antenna is poor practice and stresses the radio)
- Is the antenna connected to the LoRa SMA port, not the BLE u.FL? (Heltec V3/V4 have separate connectors)
- Is the device running repeater firmware, not Meshtastic or blank?
- Is it configured with the correct preset for your regional network?
Problem: Repeater is not appearing in MeshCore app contacts
Scenario A: Repeater has zero-hop advertisements
A repeater sending only zero-hop adverts (not flood adverts) is visible only to nodes within direct radio range. If you're testing from a distant location, it won't appear. Connect via USB serial and check the role and flood-advert configuration:
get role # Confirm the node's configured role
get flood.advert.interval # Flood advert cadence in hours (0 = zero-hop only)
To make the repeater visible network-wide, enable periodic flood adverts by setting a non-zero interval (default 12 hours), or send one immediately:
set flood.advert.interval 12 # Send a flood advert every 12 hours
advert # Send a flood advert immediately
Scenario B: Wrong preset
A repeater on a different preset than your phone is on cannot be heard. The phone and repeater must use identical preset settings (same SF, BW, CR, frequency). Verify both devices use the USA/Canada preset.
Scenario C: Not yet advertised
A freshly configured repeater won't be visible until it broadcasts its first advertisement. Default flood-advert interval is 12 hours. Force an immediate advertisement via the serial CLI:
advert # Serial CLI command to immediately broadcast a flood advertisement
Scenario D: Out of radio range
Test with a device you control. Bring it within 100 feet of the repeater (direct physical proximity, no obstacles). If it appears in contacts at that range, the repeater is working and the issue is range/placement. If it still doesn't appear at 100 feet, it's a configuration or hardware issue.
Problem: Repeater visible but messages not routing through it
Check: Repeater role set correctly
get role # Returns the node's configured role
A device running Companion (client) firmware will not relay messages for other nodes. To forward packets the device must run Repeater firmware (or Room Server firmware). The forwarding role is determined by which firmware variant you flash, not by a runtime command.
Check: Path discovery is completing
MeshCore must complete a route discovery (path discovery/acknowledgment exchange) before messages can be delivered. If messages are failing immediately after the repeater appears in contacts, path discovery may not have completed. Wait 60 seconds after first seeing the repeater, then try sending.
Check: Flood hop maximum
MeshCore uses path-based routing rather than a Meshtastic-style per-message hop-limit. The flood hop maximum (flood.max) defaults to 64, so there is no low default to "raise" — three to five hops is a practical reliability target, not a configured limit. If you have a specific reason to cap flood propagation, you can adjust it:
get flood.max # Read the current flood hop maximum (default 64)
set flood.max 64 # Range 0-64
Problem: Repeater was working but stopped
Check: Power system
The most common cause of intermittent repeater failure. For solar-powered nodes:
- Battery voltage low: for a single LiFePO4 cell, ~3.2 V is the normal mid-charge plateau — concern begins below ~3.0 V and the cell is empty near 2.5 V. For a 4-cell (12 V) LiFePO4 pack, nominal is ~12.8 V and it is nearly discharged around 12.0 V. Check the solar panel and charge controller.
- Charge controller LED indicators: verify charging when sun is on the panel
- Winter: reduced daylight hours may be insufficient for the panel size. Consider adding battery capacity for winter.
- Snow or debris covering the panel: physically inspect
Check: Firmware crash or lock
Firmware can occasionally hang, especially after a power interruption during a write operation. A full power cycle (disconnect and reconnect power) usually resolves this. If the device is cycling rapidly (power LED flashing repeatedly), it may be boot-looping - likely a firmware corruption requiring reflash.
Check: Physical damage
Water intrusion is a common cause of permanent field failure. Signs: corrosion on the PCB, moisture beads inside the enclosure, condensation on components. Once water has infiltrated, the board often needs replacement. Prevention is much easier than cure - inspect enclosure seals annually.
Problem: Range is less than expected
- Antenna connected? Transmitting into an open or disconnected SMA port causes VSWR problems and poor radiation.
- Correct antenna for 915 MHz? An 868 MHz (EU-band) antenna on a US repeater will have higher SWR and reduced efficiency. US operation must stay within the 902-928 MHz ISM band under 47 CFR 15.247. Test with a NanoVNA (see the Antennas & RF section).
- Antenna mount location: An antenna at 10 feet has dramatically less coverage than one at 30 feet. Every additional meter of height helps.
- Coax cable length and quality: RG-58 loses roughly 0.5 dB/m at 915 MHz, so a 15-foot run loses about 2-2.5 dB and a ~50-foot run approaches 3 dB. Use LMR-200/240 or better and keep runs short.
- Obstructions at antenna level: Metal roof edges, HVAC equipment, or tree branches within a few feet of the antenna scatter and attenuate signal significantly.
- TX power setting: Verify TX power hasn't been accidentally lowered:
get tx
Reflashing and Factory Reset
When a MeshCore repeater becomes unreachable, misconfigured, or boot-loops, reflashing is the recovery option. This page covers reflash procedures for all common device families.
When to reflash vs. when to reconfigure
| Symptom | Try first | If that fails |
|---|---|---|
| Node working but wrong settings | Reconfigure via meshcore-cli or the serial CLI | Factory reset + reconfigure |
| Boot-looping or immediate crash | Power cycle; hold reset during boot | Reflash firmware |
| BLE not discoverable | Power cycle; V3: check BLE antenna | Reflash |
| Firmware corruption after interrupted flash | - | Reflash (required) |
| Unknown configuration state | Factory reset via serial: erase (destructive — wipes the device filesystem) | Reflash if serial inaccessible |
Before reflashing: document your current config
If the device is still accessible, record its configuration before wiping. There is no single config-dump command in the MeshCore CLI — read each value with its own get command (typed into the serial console, or via the meshcore-cli host tool) and save the output:
# Capture each setting and save to a file
get name
get role
get freq
get radio
get tx
get lat
get lon
get flood.advert.interval
# Copy the console output into node_config_backup.txt
Reflash via MeshCore web flasher (recommended)
- Connect device to PC via USB
- Open flasher.meshcore.io in Chrome or Edge (WebSerial required)
- Click "Connect" and select your device's serial port
- Select device type and firmware variant (Repeater)
- Click Flash and wait (~2 minutes)
- Device reboots automatically when complete
Entering bootloader/DFU mode (when auto-detect fails)
ESP32-based devices (Heltec V3, V4, T-Beam)
nRF52840-based devices (RAK4631, T-Echo, Nano G2 Ultra)
Double-tap the reset button quickly. The device enters DFU mode and appears as a USB drive named "BOOT" or similar. Copy the .uf2 firmware file to this drive to flash.
Alternatively, use the web flasher which handles DFU automatically for most nRF52840 devices.
Station G2
Power requirement: The Station G2 generally expects a higher input than a standard 5V USB cable (commonly a 9–19V DC or USB-C PD source). Confirm the exact input-voltage range against the manufacturer's datasheet for your unit before powering it — feeding the wrong voltage can destroy hardware. If a board fails to flash on a plain 5V cable, an under-powered supply is a likely cause.
Post-reflash configuration
After flashing, the device has factory defaults. Note that the repeater role is determined by the firmware variant you flashed (flash the Repeater build) — there is no command to change the role; you can only read it with get role. Reconfigure the radio and identity using the serial console (or meshcore-cli):
# Apply the USA/Canada radio plan (910.525 MHz / BW 62.5 kHz / SF7 / CR5).
# You can select the preset in the MeshCore app, or set the raw params directly:
set radio 910.525,62.5,7,5
reboot
# Confirm the role (set by the flashed firmware, read-only):
get role
# Set name (use your documented name)
set name "REPEATER-NAME"
# Set position (latitude and longitude are separate commands;
# there is no altitude setting in the firmware):
set lat 47.6062
set lon -122.3321
# Advertisements: send one flood advert now, and set the periodic
# flood advert interval in HOURS (default 12, range 3-168):
advert
set flood.advert.interval 12
# Set TX power in dBm. Real command is "set tx" (documented range 1-22 dBm;
# the SX1262 PA tops out near 22 dBm). 22 matches the build guides.
# Total EIRP = TX power + antenna gain - feedline loss; keep it within the
# FCC 47 CFR 15.247 limits for 902-928 MHz. With an antenna over 6 dBi you
# must reduce conducted power dB-for-dB, so lower this below 22 as gain rises.
set tx 22
# Verify the key settings:
get role
get radio
get freq
get tx
get name
# Reboot
reboot
When the device is completely unresponsive
If USB serial doesn't appear and the device shows no activity:
- Try a different USB cable. Many micro-USB and USB-C cables are charge-only and have no data lines. Use a known-good data cable.
- Try a different USB port. USB hubs can cause issues; try a direct port on the computer.
- Check the USB driver if needed: The Heltec V4 (ESP32-S3) uses native USB and does not require a CH340/CP210x bridge driver — it enumerates as a standard USB CDC serial device on Windows 10/11. (The V3 used a CP2102 bridge.) RAK4631 and T-Echo also use standard USB CDC. If a unit fails to enumerate, check the cable and DFU/download mode rather than a bridge driver.
- Check for physical damage: Inspect the USB port for bent pins or corrosion. A damaged USB port prevents flashing.
- Last resort: Some boards can be recovered via JTAG/SWD with a debug probe. Consult the manufacturer's documentation.
Advanced MeshCore Repeater Diagnostics
When basic troubleshooting hasn't resolved a repeater issue, these advanced diagnostic techniques help identify hardware failures, RF problems, and protocol-level issues.
Systematic RF Path Verification
Before concluding a repeater has failed, verify the RF path independently:
- Local RF check: Bring a test node within 1 meter of the suspect repeater. Can it hear the repeater's transmissions? If yes, the repeater is transmitting. If no, the repeater may not be transmitting.
- Antenna check: Disconnect the antenna from the repeater and check for physical damage (bent connector, water ingress at connector). Re-connect securely.
- Cable check: If using a remote antenna with coax, check the cable for damage, kinks, or water ingress at connectors. Substituting a known-good short cable bypasses cable issues.
- SWR check: If you have a NanoVNA, check antenna SWR. A sudden SWR change vs. baseline indicates antenna or cable change (ice loading, lightning damage, physical damage).
Firmware Diagnostic Commands
# Show packet counters (received / sent):
stats-packets
# Show radio statistics (RSSI, SNR, airtime, RX errors):
stats-radio
# List nearby neighbors heard via advert, with SNR.
# Output is the 8 most recent adverts, each line encoded as
# {pubkey-prefix}:{timestamp}:{snr*4} (SNR only, not RSSI):
neighbors
# Show core stats (battery, uptime, queue length, debug flags):
stats-core
# Print the captured RX log to the serial terminal.
# Use "log start" / "log stop" to control capture, then read it
# back and look for error lines:
log
MeshCore has no serial ping command and no per-node forced route-discovery command. To exercise routing to a specific destination, send a message to that contact from a client and observe whether a path establishes. Zero-hop neighbor discovery (on firmware that supports it) is discover.neighbors.
Power System Deep Diagnostics
Solar-powered repeaters frequently experience issues traced to power rather than RF:
# Check battery, uptime and queue length over the serial CLI:
stats-core
# On boards with power management, the last reset cause and boot
# voltage can be read (where supported by your firmware build):
get pwrmgt.bootreason
get pwrmgt.bootmv
# Low battery can cause a brownout during TX: the TX current spike
# drops voltage below the regulator minimum and the board resets.
# There is no Linux log file on the device to read; use stats-core
# (or an external voltage logger) to track voltage history.
Signs of power-related resets:
- Repeater uptime counter resets during evening/night hours (low SOC)
- Resets correlate with high-traffic periods (many TX events = high current draw)
- Stable operation after adding a larger battery or bypass capacitor at the node power input
Isolating Radio Hardware Failure
If you suspect the SX1262 radio chip has failed:
- Verify SPI communication: Most MeshCore firmware reports a radio-init status line on the serial boot log. A successful SX1262 init is logged; an init-failure line or no radio status at all suggests a hardware problem. The exact wording varies by firmware version — check your boot log rather than searching for one fixed string.
- Substitution test: Swap the suspect board with a known-good board. If the problem follows the board, it's a hardware failure.
- Visual inspection: Check for cold solder joints on the LoRa module, corrosion on SPI pins, or physical damage to the radio module.
When to Declare Hardware Dead
Replace the hardware rather than continuing to debug when:
- The board fails to initialize the radio after firmware reflash
- The board has confirmed water ingress damage (corrosion on PCB, discolored/burned SMD components)
- The board passes diagnostics but still fails in production consistently after replacing all external factors (antenna, cable, power)
- The cost of continued debug time exceeds the cost of a replacement board ($30-60)