Repeater CLI Diagnostics

The MeshCore app exposes the everyday repeater functions through menus, and those are documented in MC Repeater Tools. The CLI goes further. It gives you the raw statistics and configuration flags the app does not surface, and it is what you want when a repeater is misbehaving in a way the GUI cannot explain.

Contents

How to Reach the CLI

You can run these commands two ways:

Some commands are serial only and are marked below. They print more output than will fit in an RF packet, so they cannot be run remotely.

The default admin password is password. If you have not changed it on your repeater, do that now:

password yournewpassword

Statistics Commands

These give you a snapshot of what the repeater is experiencing right now.

System Stats

stats-core

Serial only. Battery level, uptime, queue length, debug flags.

Radio Stats

stats-radio

Serial only. Noise floor, last RSSI, last SNR, total airtime, receive errors.

Packet Stats

stats-packets

Serial only. Total packets received and sent.

A healthy repeater in a populated area should show both counters climbing. If both are frozen at zero, the repeater is hearing nothing at all: check the antenna connection and the frequency setting.

Neighbor Discovery

List Neighbors

neighbors

Shows the most recent nodes heard directly (zero-hop) by this repeater. Each line reads:

{pubkey-prefix}:{timestamp}:{snr*4}

Note the SNR is multiplied by 4. A value of -40 means an SNR of -10 dB, which is marginal. A value of +20 means +5 dB, which is a solid link.

Discover New Neighbors

discover.neighbors

Forces the repeater to send a zero-hop advert and listen for responses, refreshing its neighbor table. Use this when the neighbor list is empty or looks stale.

An empty neighbor list on a repeater that should have neighbors is a strong signal. It means the repeater is not hearing anyone, which points at the antenna, the frequency, or a high noise floor.

Packet Logging

Repeaters can log every received packet to flash. This is the most powerful tool available for intermittent problems, the kind that never happen while you are watching.

log start

Begin capturing received packets to flash.

log stop

Stop capturing.

log

Serial only. Print the captured log to the serial console. Copy this output and bring it to Discord for analysis, or line the timestamps up against messages you sent during the capture.

log erase

Clear the stored log to free the space and start a clean capture.

A typical session: run log start, reproduce the problem over 10 to 30 minutes, run log stop, then connect over serial and run log.

Radio Configuration

Check Current Settings

get radio
get freq
get tx

For the Inland NW Mesh, get radio must return:

910.525,62.5,7,5

That is 910.525 MHz, 62.5 kHz bandwidth, spreading factor 7, coding rate 5. A node on any other setting is invisible to the rest of the network, and this is worth checking early because it produces symptoms that look like a hardware fault.

Transmit power depends on the board. Most Heltec V3 and RAK boards run 14 to 22 dBm. High-power hardware such as the Station G2 has different limits: do not exceed what your board is rated for.

Fix a Mismatch

set radio 910.525,62.5,7,5
reboot

Radio changes do not take effect until the node reboots.

Test Without Committing

tempradio 910.525,62.5,7,5,30

Applies those parameters for 30 minutes, then reverts to the saved config. Useful for testing a change on a repeater you cannot easily get back to if it drops off the mesh.

Diagnosing Deafness: the AGC Fix

If a repeater sits near a strong RF source such as a cell tower, TV transmitter, or busy WiFi, the SX1262 radio's Automatic Gain Control can latch and stop hearing LoRa traffic altogether.

Symptoms: the repeater is clearly online and responds to commands, but packet counters are frozen, the neighbor list is empty, and it forwards nothing.

Fix:

set agc.reset.interval 4

This resets the AGC every 4 seconds. It is a very cheap operation and it cures most cases of deafness. The value is in seconds, rounded to a multiple of 4.

Afterwards, run stats-radio and watch whether the noise floor and RSSI values start responding again.

Routing Configuration

Repeat Flag

get repeat

Must be on for a repeater. If it is off, the node hears everything and forwards nothing, which looks exactly like a routing black hole from the outside.

set repeat on

Flood Hop Limits

get flood.max
get flood.max.advert
get flood.max.unscoped

If flood.max is set very low, such as 1 or 2, traffic originating beyond that hop range will not propagate through this repeater. One misconfigured repeater with a low flood.max.advert can stop new members' adverts from ever reaching the wider network.

Duty Cycle

get dutycycle

The default is 50%. Set very low, the repeater throttles its transmissions hard and appears slow or unresponsive whenever the network gets busy.

Path Hash Mode

get path.hash.mode

Setting this to 1 helps CoreScope tell apart repeaters whose public keys collide in the first byte.

set path.hash.mode 1

Only change this if the repeater is on firmware 1.14 or newer. Older firmware only forwards 1-byte paths, and a mismatch will silently break routing through that node. If you are not sure, leave it alone and ask in Discord first.

Checking Firmware Version

ver

Always confirm the firmware version before reporting a problem. Several issues people report are already fixed upstream. Update at flasher.meshcore.io.

Next: Using CoreScope shows you where your packets actually went.