Getting Started
MeshCore Guides
What you are setting up
MeshCore is mesh firmware for LoRa boards with a role-based design: your personal node (a companion) talks to your phone, dedicated repeaters forward traffic, and room servers host shared channels with store-and-forward delivery. The routing model is covered in LoRa Mesh 101; this guide is the practical path to a working node.
What you need
- A supported LoRa board. See the Hardware guide. Check your board against the list in the web flasher before buying.
- The MeshCore phone app (Android or iOS), which connects to your companion node over Bluetooth LE or USB.
- A USB data cable. Charge-only cables are the classic first failure. If nothing enumerates when you plug in, suspect the cable before the board.
One board works if there is an existing mesh in range (check the official map). If your area is empty, buy two boards so you have something to talk to while you recruit neighbors.
Step 1: flash the companion firmware
Every MeshCore node gets its role at flash time. Your first board should be a companion (the BLE variant), which is the role the phone app pairs with. The Flashing guide covers the web flasher and the Linux serial gotchas.
Step 2: connect the app
Install the MeshCore app, power the board (antenna attached first, always), and add the node in the app over Bluetooth. Set two things before anything else:
- Node name. This is public. Every node in range sees it.
- Region / frequency preset. Radios only hear other radios on the same frequency and settings. Use your region's standard preset, not a custom frequency, or the local mesh cannot hear you. Band legality is covered in Frequencies & Regions.
Step 3: announce yourself
Nodes discover each other through adverts: small signed broadcasts carrying a node's name, public key, and optionally location. Send an advert from the app and watch the contact list. Nearby companions, repeaters, and rooms appear as their adverts reach you.
Step 4: say hello on the public channel
Your first message goes on the public channel: the default channel every node ships with, shared by everyone running the standard settings. Say hello and mention your general area. This is where the local mesh actually talks, and where a new node gets noticed.
Next, look for room servers in your contact list. Rooms prompt for a password when you join; some are open and the password is blank, so clicking through the prompt just works. If it does not, ask on the public channel: whoever runs the room is probably in it.
Direct messages are supported (end-to-end encrypted, routed along a learned path), but a first-contact DM to a node you found five minutes ago is messaging a stranger, and people are busy. Earn it on the public channel first.
With two of your own boards, put the second one in an upstairs window and walk away with the first until you find the edge of the link. That number is your baseline; the Range Expectations guide explains how to improve it.
The command-line route
You do not need a phone. The meshcore-cli tool drives a companion node over USB serial, BLE, or TCP from a terminal: contacts, messages, node configuration, and remote administration of repeaters. It is on PyPI, needs Python 3.10 or newer, and runs on Windows, macOS, and Linux, Raspberry Pi included. It is also the practical tool for scripting and for headless boxes.