Quickstart

Radio to dashboard in 10 minutes

1. Get a radio

Any board on Meshtastic's supported list works. If you're buying fresh, the Seeed XIAO ESP32-S3 + Wio-SX1262 kit (~$40, 3D-printed case included) is the combination Perch is tested against daily. See the hardware guide for alternatives with keyboards, GPS, or solar.

2. Flash Meshtastic firmware

Skip this if your radio shipped with real Meshtastic. Otherwise use the official web flasher at flasher.meshtastic.org (Chrome/Edge — it talks to the board over WebSerial). Pick your exact board, flash the latest stable.

"Pre-flashed" isn't always pre-flashed. Some kits ship with a factory demo that looks alive but speaks no Meshtastic protocol. If Coop times out connecting, flash the real firmware — that exact gotcha is what got this project started.

3. Install Perch

macOS — brew install --cask stevenssparks/tap/perch, or download Perch-x.y.z-macos.zip from the releases page, unzip, drag Perch.app to Applications. Signed and notarized; Coop ships inside the bundle.
Linux / Windows — grab the static binaries from the releases page (coop + perch, amd64/arm64), then:
```
./coop &     # the engine
./perch      # the dashboard server
```
Perch serves the dashboard at http://127.0.0.1:8790; Coop's status page is at http://127.0.0.1:2667.

4. Plug in and open

Connect the radio over USB and launch Perch. Coop scans serial ports, finds the radio, runs the Meshtastic handshake, and the dashboard fills in: your node in the header, packets in the feed, nodes on the map as they're heard. First packets typically arrive within a minute in any populated area.

Use a data cable. The #1 first-run failure is a USB cable with no data lines. If no serial port appears at all, swap the cable before anything else.

5. Set your region (one time)

LoRa frequencies are regional and radios ship with region UNSET. Set it once — via Perch's radio config panel, the Meshtastic phone app, or the CLI (meshtastic --set lora.region US). The radio reboots and starts transmitting.

6. Join your local mesh

Most communities publish a channel URL or QR code. Paste it into Perch's channel manager (it imports name + pre-shared key together) and their traffic decrypts into your chat and capture. Details in Channels & keys.

That's it

From here: persistent history is already being captured (capture database), you can probe the network (mesh services), and if your radio hears less than you'd like, the MQTT observer shows the whole community mesh.

← Overview Hardware guide →