# 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 can damage 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 configured with 0-hop advertisements is only visible to nodes within direct radio range. If you're testing from a distant location, it won't appear. Connect via USB serial and confirm advertisement hop setting: ``` meshcli info # Check advert_hops value ``` Change to flood if you want the repeater visible network-wide: ``` meshcli set advert-hops flood ``` ### 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 interval is 12 hours. Force an immediate advertisement via serial CLI: ``` advert # Serial CLI command to immediately broadcast an 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 ``` meshcli info # Look for "role: repeater" ``` A node set to "client" role will not relay messages for other nodes. Must be set to "repeater" or "router" for active forwarding. ### 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: Hop limit If the destination node is more than 3 hops away from the sender (across multiple repeaters), and the hop limit is set to the default of 3, some paths may be cut off. Check and increase if needed: ``` meshcli set hop-limit 5 ``` ## Problem: Repeater was working but stopped ### Check: Power system The most common cause of intermittent repeater failure. For solar-powered nodes: - Battery voltage below 3.2V (LiFePO4) means it's nearly discharged - check 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 the leading 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 1. **Antenna connected?** Transmitting into an open or disconnected SMA port causes VSWR problems and poor radiation. 2. **Correct antenna for 915 MHz?** An 868 MHz antenna on a US repeater will have higher SWR and reduced efficiency. Test with a NanoVNA (see the Antennas & RF section). 3. **Antenna mount location:** An antenna at 10 feet has dramatically less coverage than one at 30 feet. Every additional meter of height helps. 4. **Coax cable length and quality:** A 15-foot run of cheap RG58 can lose 3+ dB at 915 MHz. Use LMR-200 or better and keep runs short. 5. **Obstructions at antenna level:** Metal roof edges, HVAC equipment, or tree branches within a few feet of the antenna scatter and attenuate signal significantly. 6. **TX power setting:** Verify TX power hasn't been accidentally lowered: `meshcli info` # 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
SymptomTry firstIf that fails
Node working but wrong settingsReconfigure via meshcore-cli or serial CLIFactory reset + reconfigure
Boot-looping or immediate crashPower cycle; hold reset during bootReflash firmware
BLE not discoverablePower cycle; V3: check BLE antennaReflash
Firmware corruption after interrupted flash - Reflash (required)
Unknown configuration stateFactory reset via serial: `factory-reset`Reflash if serial inaccessible
## Before reflashing: document your current config If the device is still accessible, record its configuration before wiping: ``` meshcli info > node_config_backup.txt # Records: name, ID, role, preset, TX power, position, advert settings ``` ## Reflash via MeshCore web flasher (recommended) 1. Connect device to PC via USB 2. Open [meshcore.io/flasher](https://meshcore.io/flasher) in Chrome or Edge (WebSerial required) 3. Click "Connect" and select your device's serial port 4. Select device type and firmware variant (Repeater) 5. Click Flash and wait (~2 minutes) 6. 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:** Station G2 requires 9 - 19V DC or a 15V USB-C PD source. It will NOT flash or boot reliably on a standard 5V USB cable. Use a USB-C PD charger that supports 15V or a proper DC power supply. ## Post-reflash configuration After flashing, the device has factory defaults. Reconfigure for repeater operation: ``` # Apply regional preset meshcli set preset usa # Set role meshcli set role repeater # Set name (use your documented name) meshcli set name "REPEATER-NAME" # Set position meshcli set lat 47.6062 --lon -122.3321 --alt 150 # Set advertisement mode meshcli set advert-hops flood meshcli set advert-interval 720 # Set TX power (adjust for your antenna + EIRP compliance) meshcli set txpower 27 # Verify meshcli info # Reboot meshcli reboot ``` ## When the device is completely unresponsive If USB serial doesn't appear and the device shows no activity: 1. **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. 2. **Try a different USB port.** USB hubs can cause issues; try a direct port on the computer. 3. **Install the correct driver:** Heltec V4 requires the CH340 USB driver on Windows. RAK4631 and T-Echo use standard USB CDC (usually auto-installs). 4. **Check for physical damage:** Inspect the USB port for bent pins or corrosion. A damaged USB port prevents flashing. 5. **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: 1. **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. 2. **Antenna check:** Disconnect the antenna from the repeater and check for physical damage (bent connector, water ingress at connector). Re-connect securely. 3. **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. 4. **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 detailed packet statistics: stats detail # Show all heard nodes and their last SNR/RSSI: repeaters verbose # Show free memory and uptime: sysinfo # Force a route discovery to a specific node: # (Use this to test if the repeater can route to a specific destination) ping !targetNodeId # Check if firmware has panic logs: logs errors ``` ## Power System Deep Diagnostics Solar-powered repeaters frequently experience issues traced to power rather than RF: ``` # Check voltage history if logging is enabled: # On Pi-based systems, check power monitoring data: cat /var/log/power-monitor.log | tail -100 # Check if voltage dips correlate with transmission events: # Low battery may cause brownout during TX (TX current spike drops voltage below # regulator minimum, causing a reset) ``` 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 radio init status on serial boot. "SX1262 OK" confirms the radio chip initialized. "SX1262 FAIL" or no radio status = hardware problem. - **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)