Choose LetsMesh
When the installer asks which MQTT broker/preset you want, choose the current LetsMesh U.S. option if you are in the United States.
The current project documentation lists the U.S. endpoint as mqtt-us-v1.letsmesh.net.
MeshCore • Absolute beginner guide
SET UP A MESHCORE OBSERVER WITHOUT LOSING YOUR MIND.
No Linux wizardry required. No MQTT degree required. This page assumes you are starting from basically zero and tells you what to plug in, what to paste, and what “working” looks like.
First: what are we actually building?
You already have — or will have — a MeshCore repeater. We plug that repeater into a Raspberry Pi with USB. The Pi runs a small program called meshcoretomqtt. That program sends the repeater's packet data over the internet to LetsMesh, where you can view it in the analyzer.
MeshCore repeater→USB cable→Raspberry Pi→LetsMesh
That is the whole idea. Everything below is just getting those four pieces talking to each other.
Before touching anything
DO YOU HAVE THESE FOUR THINGS?
1. A Raspberry Pi
A Pi 4 is perfect. It needs Raspberry Pi OS, internet access, power and a free USB port.
2. A MeshCore repeater
Not just a Companion. This guide expects a repeater that can output packet logging data.
3. A USB data cable
Not every USB cable carries data. If nothing works later, the cable is one of the first things to swap.
4. Internet access
The Pi must be online because it sends data to LetsMesh over the internet.
STOP HERE if your MeshCore repeater is not already working.
Get the repeater working normally first. Do not troubleshoot the repeater, Raspberry Pi, USB connection and LetsMesh all at the same time. That is how a 15-minute project turns into three hours of swearing.
Get the repeater working normally first. Do not troubleshoot the repeater, Raspberry Pi, USB connection and LetsMesh all at the same time. That is how a 15-minute project turns into three hours of swearing.
One important catch
YOUR REPEATER NEEDS PACKET LOGGING.
meshcoretomqtt can only send data that the repeater gives it. The upstream project recommends building the repeater firmware with:
-D MESH_PACKET_LOGGING=1You may also see this optional debug setting:
-D MESH_DEBUG=1Translation: if you installed ordinary repeater firmware and never enabled packet logging, the Pi may connect perfectly but still have nothing useful to send. If you are unsure, check the current LetsMesh onboarding instructions before continuing.
Step 1
PLUG THE REPEATER INTO THE PI.
1
Use USB. That's it.
Plug the MeshCore repeater into a USB port on the Raspberry Pi with a known-good data cable.
Do not overthink this step. The Pi is simply going to read text/data from the repeater over USB.
Step 2
OPEN A TERMINAL ON THE PI.
2
If your Pi has a screen and keyboard, click the Terminal icon. If you normally SSH into it from another computer, that is fine too.
You should see a prompt where you can type commands. You do not need to understand every command on this page. Copy carefully and paste.
Step 3
INSTALL MESHCORETOMQTT.
3
Copy this entire line:
curl -fsSL https://raw.githubusercontent.com/Cisien/meshcoretomqtt/main/install.sh | sudo bashPaste it into the Pi terminal and press Enter.
The installer does the annoying setup work for you. It creates the program folder, Python environment, configuration files and a Linux service so the bridge can start automatically.
Beginner translation: you do not need to manually install Python packages or build your own service. Let the installer do it.
Step 4
ANSWER THE INSTALLER QUESTIONS.
Enter the 3-letter location code
The installer will ask for an IATA-style three-letter location code. This is used to organize the observer's MQTT data by area.
If you are unsure what code LetsMesh wants for your area, use the current LetsMesh onboarding page instead of guessing.
Let it find the radio
The program can auto-detect the MeshCore device public key. Newer compatible firmware also allows token authentication using the key stored on the radio.
You do not need to manually type your radio's giant public key unless the current installer specifically asks you to.
Step 5
CHECK IF IT IS RUNNING.
5
Paste this:
sudo systemctl status mctomqttLook for:
active (running)
If you see that, the program itself is running. Press Q to leave the status screen.
If it says failed: don't start randomly changing files. Go to the troubleshooting step below and read the live log first.
Step 6
CHECK LETSMESH.
6
Open the LetsMesh Analyzer and look for your observer/repeater data.
Give it a little time. Seeing the service running on the Pi does not necessarily mean data will appear on the website instantly.
Success looks like this: the Pi service is running, it stays connected to the repeater, and LetsMesh begins receiving status/packet data from your device.
Something broke?
DO THESE IN THIS ORDER.
Pi says the service failed
Run this and leave it open:
sudo journalctl -u mctomqtt -fLook for the first clear error mentioning USB/serial, authentication, MQTT or configuration.
The Pi cannot see the repeater
Try another USB data cable and another USB port before touching the software.
Service runs, but no packets appear
Re-check that your repeater firmware has packet logging enabled. This is one of the most important requirements.
LetsMesh authentication fails
Use the current LetsMesh onboarding instructions and upstream GitHub settings. Do not copy old usernames/passwords from stale tutorials.
Cheat sheet
THE ONLY COMMANDS MOST PEOPLE NEED.
Is it running?
sudo systemctl status mctomqttRestart it
sudo systemctl restart mctomqttWatch errors / live activity
sudo journalctl -u mctomqtt -fUpdate meshcoretomqtt later
curl -fsSL https://raw.githubusercontent.com/Cisien/meshcoretomqtt/main/scripts/update.sh | sudo bashWhat is MQTT? Do I need to learn it?
MQTT is just the internet messaging system this setup uses to move data from your Pi to LetsMesh. For this basic setup, no — you do not need to learn MQTT first. The installer handles the connection details.
What does the Raspberry Pi actually do?
It sits between the radio and LetsMesh. It reads packet/debug output from the repeater over USB and forwards that information over the internet.
Does this make my repeater reach farther?
No. Sending data to LetsMesh does not increase RF range. Your antenna, height, terrain, radio settings and actual repeater operation determine radio coverage.
Can I unplug the Pi after setup?
Not if you want this observer bridge to keep working. meshcoretomqtt is running on the Pi, so the Pi must stay powered, online and connected to the repeater.
Privacy
KNOW WHAT YOU ARE TURNING ON.
The upstream project says meshcoretomqtt forwards raw MeshCore packet data it receives from the repeater to the configured MQTT service. Private/secret channel content remains protected by channel keys, but this is still an internet-connected network-analysis setup.
The project also states that when token authentication is used, the repeater's private key is used locally for signing and is not transmitted or saved to disk by meshcoretomqtt.
Still stuck?
GO BACK TO THE TWO SOURCES THAT MATTER.
This guide intentionally removes the jargon. If the software changes, the LetsMesh onboarding page and the original meshcoretomqtt repository are the current sources to check.