Troubleshooting & Known Issues
Common Issues and Fixes
Quick Reference Table
| Problem | Solution |
|---|---|
| Repeater goes deaf after nearby RF transmissions | set agc.reset.interval 4 - resets AGC periodically (value in seconds) to recover from desensitization |
| Heltec V3 Bluetooth dropouts | Community modification (not an official MeshCore fix): replace the stock PCB antenna with a 31 mm wire antenna soldered to the BLE antenna pad. See the community write-up. |
| Duplicate public key first bytes | Generate a new keypair at gessaman.com/mc-keygen/ |
| Phone won't connect via Bluetooth | Unpair and re-pair the device; verify you are using the correct MeshCore app (not Meshtastic). Pairing is usually PIN-less; if a PIN is requested, check the device screen rather than assuming a fixed default. |
| Contacts showing ancient last-seen dates | Clock sync issue - use epochconverter.com to verify and manually set the device RTC |
| Messages not delivered | Check: matching channels/encryption keys, region set correctly for your area, antenna connected, hop limit sufficient for the path length |
| Can see nodes but can't message them | Verify matching channel name and channel secret/key on both ends; investigate asymmetric RF link (strong signal one way, weak the other - often a bad antenna on one node) |
| Battery draining fast on companion node | Enable screen timeout; disable continuous GPS or increase GPS update interval; reduce telemetry broadcast interval |
Receiver Desensitization (AGC Issue) - Detailed
This is the most common issue at sites co-located with other radio equipment. Symptoms:
- Repeater was working fine, then a nearby radio (VHF/UHF ham, GMRS, commercial) transmitted
- After that transmission, the MeshCore repeater stops relaying anything
- Rebooting the repeater restores normal operation temporarily
Root cause: the radio's AGC can remain desensitized after a strong nearby signal, requiring a periodic reset to recover. The fix:
set agc.reset.interval 4This resets the AGC every 4 seconds. The value is in seconds, rounded down to a multiple of 4 (so 17 becomes 16), and 0 disables the feature. The minimum effective value is 4 (4 seconds) — values below 4 round down to 0 and disable the AGC reset entirely. For sites with very active co-located transmitters, keep it at 4 (the minimum) rather than a smaller number. This setting persists across reboots.
Heltec V3 BLE Antenna Upgrade
The Heltec WiFi LoRa 32 V3 ships with a small PCB trace antenna for Bluetooth. This antenna has poor performance, causing:
- Frequent disconnections from the MeshCore app
- Short effective BLE range (sometimes less than 1 metre)
This is a community-sourced, at-your-own-risk hardware modification, not an official MeshCore fix. Fix: solder a 31 mm piece of wire to the BLE antenna pad. (One community write-up shorts the wire across the windings of the PCB coil antenna; the exact pad label and location vary by board revision, so verify against a current Heltec V3 schematic before soldering.) A quarter-wavelength at 2.4 GHz is approximately 31 mm (lambda/4 = c/(4f) ≈ 30.6 mm), so the wire acts as a quarter-wave monopole at 2.4 GHz. Community reports describe large, anecdotal improvements in BLE range and reliability (for example, access from ~30 m away). See the community write-up.
Duplicate Public Key First Bytes
MeshCore uses the first bytes of a node's public key as part of its addressing. In rare cases, two nodes may share the same leading bytes, causing routing confusion. If you suspect this:
- Visit gessaman.com/mc-keygen/
- Generate a fresh keypair
- Load the new keys onto your device via the CLI or app
Asymmetric RF Links
A node can hear another node's transmissions but not successfully send messages back. Common causes:
- One node has a significantly better antenna or elevation
- One node's TX power is set lower
- Obstructions are directional (e.g., a metal roof blocks signal in one direction)
Diagnosis: compare RSSI readings on both nodes. If RSSI is strong in one direction and weak in the other, the link is asymmetric. Fix by improving the weaker node's antenna, increasing its TX power, or repositioning.
Default Credentials — Change Them
Default PINs and passwords (such as a default BLE PIN of 123456 if your device uses one, and the repeater/room-server admin password password) should be changed on any node you rely on — especially deployed infrastructure — to prevent unauthorized pairing or configuration.
EasySkyMesh: Third-Party Power-Optimized MeshCore Fork
Important clarification: EasySkyMesh is a third-party derivative project based on MeshCore firmware, maintained by IoTThinks at github.com/IoTThinks/EasySkyMesh. It is not an official MeshCore firmware variant and is not available through the official MeshCore flasher at flasher.meshcore.io.
What EasySkyMesh Is
EasySkyMesh is a community-developed fork of MeshCore that adds:
- Power optimization features for battery-constrained deployments
- Additional sensor integrations not yet in mainline MeshCore
- Experimental features the maintainer intends to contribute upstream to the official MeshCore project
Should You Use It?
For most users: no. Use official MeshCore firmware from flasher.meshcore.io for reliability, active support, and compatibility with the broader MeshCore community network.
EasySkyMesh may be worth evaluating if you:
- Have a specific sensor integration need not yet in mainline MeshCore
- Are comfortable tracking a community fork that may lag behind official releases
- Want to contribute to or test pre-upstream features
Official Firmware Alternative
For power optimization with official firmware, use the powersaving CLI command available in MeshCore repeater firmware (Repeater Only): powersaving on. This enables the official sleep/wake cycle without needing a third-party firmware. (Confirm the exact firmware version that introduced this option against the release notes before relying on a specific version number.)
Source: IoTThinks GitHub repository and official MeshCore repository. Verified 2026-05-03.