Troubleshooting 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) Hold the BOOT button, press and release RESET, then release BOOT. The device enters download mode and should appear as a serial port. Some devices require the BOOT button held while inserting the USB cable. 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 These commands are entered over the device's serial/terminal CLI (the same console used elsewhere in this book). The authoritative command reference is docs.meshcore.io/cli_commands — the commands below match it. A MeshCore repeater runs firmware on a microcontroller (nRF52840 or ESP32); there is no Linux shell or filesystem on the device, so only these serial CLI commands work. # 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)