Roles and firmware variants

In MeshCore the role is the firmware. There is no set role command — you decide at flash time, and changing your mind means reflashing. Pick wrong and the node works perfectly while being unreachable by the tool you expected to use.

Six builds exist. Two are infrastructure, one is the client radio in three connection flavours, and three are specialist.

Infrastructure — “gateway” roles

Both expose the same text CLI over USB and both are screenless-friendly. Neither has Bluetooth of any kind — that surprises people, so it is worth saying plainly: you cannot pair a phone to a repeater.

Client — companion radio, three flavours

Specialist

Choosing

• Infrastructure at a site, meant to relay for everyone → Repeater.
• The same, but you also want stored messages people can retrieve → Room Server.
• Your own radio, driven from your phone → Companion BLE.
• A radio you want a computer to poll, log, or automate → Companion USB (cabled) or Companion WiFi (networked).

Flashing

The procedure is the same for a gateway and a companion node; only the firmware you select differs. The hardware precautions below apply to both, and the board-target one is the mistake that costs the most time.

1. Pick the firmware

   From the MeshCore releases, take the build matching both your exact board and your chosen role from the tables above. Roles ship as separate downloads — there is no single image you configure afterwards.

2. Open the flasher

   flasher.meshcore.io in Chrome or Edge. It talks to the board over USB only, and needs no install.

   File formats differ by chip: ESP32 takes .bin, nRF52 takes an OTA .zip. Grab the matching .uf2 as well if one exists — that is your recovery path.

3. Enter bootloader mode if the board needs it

   Varies by hardware: hold BOOT while connecting on many ESP32 boards, double-tap RESET on nRF52. Most boards are handled automatically by the flasher.

4. Recovery route for nRF52

   If the board will not enumerate or a flash fails partway, double-tap RESET. The Adafruit nRF52 bootloader mounts a small USB drive; drag the .uf2 onto it and the board reboots itself. This works even when the application firmware is bricked, because the bootloader lives in protected flash.

5. Confirm what came up

   For a gateway, open the serial console and ask its version. A response confirms both the flash and the board target:

   ver     -> v1.17.1-d929643 (Build: 14-Aug-2026)
   board   -> RAK 3401

   For a companion node, silence on serial is expected for the BLE build — confirm it over Bluetooth instead. For Companion USB, confirm with meshcli -s <port> infos.

The three web tools

MeshCore has three separate browser tools, and they are not interchangeable. Most confusion about “I can’t find my node in the web interface” is someone in the wrong one for their firmware role.

The config tool gives repeaters a full settings GUI, a manual CLI box, JSON import/export, and over-the-air firmware updates. The web client is a complete replacement for the phone app — messaging, contacts, node map, settings — which makes it the practical way to drive a companion node from a desktop.

Chrome, Edge, or another Chromium browser is the safe choice; WebSerial and WebBluetooth are what these pages rely on. Firefox works over WiFi, where no such API is needed, and Safari is reported reliable on Mac and iOS.

Web / WiFi access to a node

This is the flasher option you have seen listed and found nothing written about. It is real, it is genuinely useful, and it is thinly documented for a specific reason worth knowing before you commit to it.

What it gives you

A Companion WiFi build joins your wireless network and exposes the companion interface over TCP on port 5000, accepting multiple clients at once. The node can then sit anywhere on the LAN — no cable, no Bluetooth range limit — and you reach it from:

• A browser at app.meshcore.nz, choosing the network connection
• The CLI: meshcli -t <ip> -p 5000
• Your own code — meshcore.js takes new TCPConnection("10.1.0.226", 5000)

On a node with a display there is a Network (TCP) page showing connection status, the node’s IP, the port, and the SSID it joined. A long press toggles TCP on and off.

Worth it for a fixed node at a known site where you want browser access without walking over to it. Not worth it for anything you carry.

Configuring a gateway

Repeaters and room servers share one configuration surface: a text CLI at 115200 8N1 over USB, reachable from PuTTY, from config.meshcore.io, or from a script.

The console echoes what you type and answers with ->. There is no help and no ? — both return Unknown command. The CLI reference below is the actual command surface.

A freshly flashed gateway is anonymous, unsecured, and on default radio settings. Do these in order — the password first, because until you set it the node accepts the published default from anyone in earshot.

1. Lock it down

   The default admin password is password and it is public knowledge. Anyone who can hear the node can otherwise reconfigure it. There is no getter — get password is not valid, by design.

   password <something-only-you-know>
   set guest.password <guest-password>

2. Name it

   This is what appears in everyone’s contact list, so make it identify the site rather than the person.

   set name W2MMD Clubhouse

3. Set the radio

   Frequency, bandwidth, spreading factor and coding rate in one command. All four must match the rest of your mesh exactly or the node is deaf and mute — not degraded, silent. Requires a reboot.

   set radio 919.5,500,10,5
   set path.hash.mode 1
   set tx 22
   reboot

   To trial a change on a node you cannot easily reach, use tempradio f,bw,sf,cr,<minutes> instead — it applies without saving and reverts on its own.

4. Place it and set the clock

   Position feeds the map. Note there is no time query — bare time returns Unknown command; it only takes an epoch argument.

   set lat 39.716999
   set lon -75.2099533
   time <epoch>
   clock

   Get the epoch from date +%s on Linux. On Windows use [int][DateTimeOffset]::UtcNow.ToUnixTimeSeconds() — PowerShell’s Get-Date -UFormat %s computes from local time and will set the node hours off. The config tool pushes the browser’s clock for you, which avoids the whole problem.

5. Make it discoverable

   Zero-hop adverts in minutes, flood adverts in hours, then one manual advert so anything nearby can add it immediately.

   set advert.interval 60
   set flood.advert.interval 12
   advert                 -> OK - Advert sent

   advert.interval has a floor

   The firmware accepts 60–240 minutes only, or 0 to disable. Anything lower is rejected outright:

   set advert.interval 30
   Error: interval range is 60-240 minutes

   60 is as often as a gateway can announce itself. This range is not in the published documentation — it was found on the device.

6. Check it hears the mesh

   Give it real time on air first — an hour or more at a quiet site.

   neighbors

Administering one remotely

A gateway can be driven over the mesh rather than the cable. The client must first hear an advert from it, which is why advert.interval 0 makes a node effectively unreachable. Then log in with the admin password and issue commands by RF. Both the phone app and meshcore-cli can do this.

Configuring a companion node

Nothing from the previous section applies here. Companion firmware has no text CLI and does not appear in the config tool. Three ways in, depending on which flavour you flashed:

The scriptable path

meshcore-cli installs from PyPI as pip install meshcore-cli and runs as meshcli. It speaks the binary companion protocol, which is the only thing these nodes answer.

Chain them in one non-interactive call, -j for JSON:

meshcli -s /dev/ttyACM0 -j infos set name MNFQ-MC advert contacts

Backing one up

The app’s Export Config screen writes out identity, radio settings, channels and contacts. Do this before changing radio settings. The export contains the private identity key, which is the one unrecoverable item: lose it and the node returns with a new public key and every contact in the mesh loses it. Anyone holding that export can impersonate the node, so keep it somewhere safe.

CLI reference

Gateways only — repeater and room server. Verified against a live repeater on firmware v1.17.1. The n/a rows are traps worth knowing, not omissions.

Status and identity

Radio

Network behaviour

Security and lifecycle

Monitoring

Gateway telemetry hides behind three hyphenated commands. They are easy to miss — status, stats and get stats all return Unknown command. Each returns JSON, so they drop into a logger with no parsing work.

Also clear stats to zero the counters, and log start / log / log stop to capture received packets to flash and dump them. All of these are serial only; over the mesh you get a smaller set.

Reading them: recv with recv_errors at zero means nothing is arriving at all; errors climbing means the node hears traffic it cannot decode, which points at a radio-parameter mismatch. A sensible noise floor proves the receiver is alive and measuring even when nothing is heard.

Companion telemetry

Companion nodes report through meshcore-cli instead: self_telemetry for the node you are connected to, and req_status / req_telemetry / req_neighbours against a named gateway over the mesh. cmd <gateway> <command> sends raw CLI by RF.

meshcli -s /dev/ttyACM0 -j login <adminpw> \
  req_status "W2MMD Clubhouse" \
  req_telemetry "W2MMD Clubhouse"

Network profile and FCC compliance

Every node on a mesh must share its radio parameters exactly. The profile below is MeshCore 500, adopted by PhillyMesh in August 2026 after the group concluded that the common defaults are not FCC compliant.

set radio 919.5,500,10,5
set path.hash.mode 1
reboot

Path hash mode

A repeater’s path hash is the first N bytes of its public key — a truncated fingerprint identifying it in a packet’s recorded route. path.hash.mode chooses how many bytes each hop consumes:

The path field in a MeshCore packet is capped at 64 bytes, so wider hashes trade maximum hop count for fewer collisions between repeaters. One byte gives only 256 possible IDs, which on a growing regional mesh produces genuine clashes; two bytes effectively eliminates them while still allowing 32 hops — far more than any real route needs. That is why PhillyMesh standardised on mode 1.

set path.hash.mode 1

Why 500 kHz

These meshes operate as unlicensed Part 15 devices rather than under an amateur licence — the default encrypted channels would be a problem under Part 97, which prohibits obscuring the meaning of a transmission. That puts them under 47 CFR §15.247, where digital modulation in the 902–928 MHz band must have a minimum 6 dB bandwidth of 500 kHz.

That one rule disqualifies most familiar presets. MeshCore’s own US default of 910.525, 62.5, 7, 5 is 62.5 kHz — eight times narrower than the floor. On the Meshtastic side the same rule leaves only LongTurbo.

The 1W output is not the problem: §15.247 permits up to 1 watt conducted in this band for digital modulation, which is what a booster module is built for. Antenna gain above 6 dBi requires a corresponding power reduction.

The W2MMD Clubhouse node

A worked example of everything above: the club’s own MeshCore repeater. Note the distinction — this is a MeshCore data node, unrelated to the club’s voice repeaters, and invisible to every Meshtastic tool including the MeshMon dashboard.

Reaching it

Repeater firmware, so: config.meshcore.io in Chrome or Edge on the machine holding the USB cable (WebSerial needs a local connection), a serial console at 115200, or remotely over the mesh with the admin password once something has heard its advert. No Bluetooth — the repeater build has none.

Node-specific notes

• TX 22 is correct — do not raise it. +22 dBm is the SX1262’s own hardware ceiling; the RAK13302’s SKY66122 amplifier takes that to roughly 30 dBm at the antenna. The node is already at full output.
• Two antennas, mechanically interchangeable connectors. The flat PCB antenna belongs on the RAK3401 (2.4 GHz, idle under repeater firmware); the SMA whip via IPEX-to-SMA belongs on the RAK13302 (915 MHz, 1W). MHF1 and IPEX/U.FL will seat in either socket — crossing them puts 1W into a 2.4 GHz PCB antenna and kills the amplifier.
• Flash only the RAK_3401 target. Never RAK4631, for the SPI1 and pin-31 reasons in the flashing section.
• The clock needs re-setting after any reboot, including every set radio. It has run correctly across USB unplugs because the battery keeps it alive.
• Windows gives one program exclusive use of a serial port. The config tool, a PuTTY window, or a stray Python process will lock everyone else out with Access is denied.

Status as of 3 Sep 2026

As last read on 3 Sep: battery 4175 mV, noise floor −88 dBm, receiver alive and measuring, recv 0 with recv_errors also 0 — it had heard nothing at all.

It is now on the superseded profile. PhillyMesh revised MeshCore 500 on 6 October, so this node and the club’s companion nodes all sit on a frequency nothing else is using. Firmware v1.17.1 is still the current release, so no firmware update is needed first — only the retune:

set radio 919.5,500,10,5
set path.hash.mode 1
reboot
# the reboot wipes the clock — set it again afterwards
time <epoch>

Until that is done, the zero recv count says nothing useful about coverage.

Troubleshooting

The node boots but answers nothing on serial

Work down in this order:

• It may be a companion build. Companion BLE is silent on USB by design; Companion USB answers only the binary protocol, never text. Neither is a fault.
• Line states. Opening a serial port asserts DTR and RTS, which holds an ESP32 in reset. Open with both deasserted, then pulse RTS to boot into the application.
• Board-target mismatch. Wrong variant means a clean boot and no working I/O. Reflash with the exact target.
• Charge-only cable. Enumerates nothing, looks like a dead board.

The node is alive but hears nothing

• Radio mismatch. get radio must match the rest of the mesh on all four values. One wrong number is total silence, not reduced range.
• Adverts off. Nothing can route to a node that never announces itself.
• Nobody there. On a newly adopted profile, an empty neighbors may simply mean no one else is on it yet. Check recv_errors: zero alongside zero recv means an empty band, not a broken receiver.
• Antenna and feedline. Confirm the SMA cable is on the LoRa module and not the BLE socket — the connectors mate either way.

“Access is denied” opening the port

Windows gives one program at a time exclusive use of a serial port. Close the other terminal, browser tab, or script.

Forgotten admin password

No recovery and no getter. Set a new one over USB with password <new> — physical access is the intended override. Do not reach for erase: that changes the public key, and every contact in the mesh loses the node’s identity.

Don’t point Meshtastic tools at any of this

Separate protocol. The meshtastic CLI and the MeshMon collector cannot read a MeshCore node and will error on the port. Equally, MeshCore nodes are invisible to the MeshMon dashboard by design — not a fault to chase.