Getting Started

Meshtastic Guides

What you are setting up

Meshtastic is mesh firmware for LoRa boards where every node is a peer: your device relays for the mesh and the mesh relays for you, using managed flooding with a hop limit. The routing model and how it compares to MeshCore are 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 device list in the web flasher before buying.
• The Meshtastic app for Android or iOS, which connects to the node over Bluetooth. There is also a web client and a Python CLI (more below), so a phone is optional.
• 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 a mesh in range: check MeshMap for reported nodes near you. If your area looks empty, buy two boards so you have something to talk to while you recruit neighbors.

Step 1: flash the firmware

Use the web flasher to put current firmware on the board. The Flashing guide covers the flasher, ESP32 vs nRF52 differences, and the Linux serial gotchas.

Step 2: connect the app and set the region

Power the board (antenna attached first, always), pair it in the app over Bluetooth, and set the LoRa region. The firmware refuses to transmit until a region is configured, on purpose. Pick the region you are physically in; the legal side is covered in Frequencies & Regions. Then set your node's name: a long name plus a four-character short name that other nodes display in tight spaces. Both are public.

Step 3: you are already on the public channel

Out of the box, every Meshtastic node shares the same primary channel (the LongFast preset with a published default key), which makes it the de facto public channel. There is no discovery step to perform: as nodes are heard, they appear in your node list with signal info. Your first message goes here. Say hello and mention your general area; this is where the local mesh talks, and where a new node gets noticed.

Direct messages are supported and encrypted, 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 primary channel first.

Step 4: find the edge

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

The meshtastic Python package (on PyPI) drives a node over USB serial, TCP, or Bluetooth from a terminal on Windows, macOS, or Linux, Raspberry Pi included: read and change settings, send messages, dump the node list. There is also a web client that talks to the node from a WebSerial or WebBluetooth capable browser. The phone app is the comfortable path, not the only one.