Meshtastic Novice → Expert

[Node A] ──LoRa RF──► [Node B] ──LoRa RF──► [Node C] ──LoRa RF──► [Node D]
           5 km               8 km               6 km

Each node stores → re-transmits → decrements hop count

pip install meshtastic esptool

# Erase and flash (replace /dev/ttyUSB0 with your port)
esptool.py --port /dev/ttyUSB0 erase_flash
meshtastic --port /dev/ttyUSB0 --flash

git clone https://github.com/meshtastic/firmware
cd firmware
cp platformio_override.example.ini platformio_override.ini
# edit platformio_override.ini to select your board target
pio run -e heltec-v3 --target upload

pip install meshtastic

# Set region (determines legal frequency)
meshtastic --set lora.region EU_868

# Set modem preset (all nodes must match)
meshtastic --set lora.modem_preset LONG_FAST

# Set node role
meshtastic --set device.role ROUTER

# Set node name (shown in app + mesh)
meshtastic --set owner "WaterNode-01"
meshtastic --set owner_short "WN01"

# Confirm settings
meshtastic --info

         [ROUTER — hilltop, solar]
        /                \
[CLIENT]              [ROUTER — building rooftop]
 (phone)             /           \
                [CLIENT]       [CLIENT]
                (phone)         (sensor)

meshtastic --set lora.hop_limit 5   # increase for large area networks

# Create a private channel on slot 1 with a random PSK
meshtastic --ch-set name "WaterTeam" \
           --ch-set psk random \
           --ch-index 1

# Enable uplink to MQTT broker on this channel
meshtastic --ch-set uplink_enabled true --ch-index 1

# Show channel QR code (share with team)
meshtastic --qr

# Example channel URL format
https://meshtastic.org/e/#CgUYAyIBAQ==

# Scan in app → instantly joins channel with correct PSK

pip install meshtastic

import meshtastic
import meshtastic.serial_interface

# Connect over USB serial
iface = meshtastic.serial_interface.SerialInterface("/dev/ttyUSB0")

# Broadcast to all nodes on primary channel
iface.sendText("Hello mesh!")

# Send to specific node by ID
iface.sendText("Hello!", destinationId="!abc12345")

# List all visible nodes
for node_id, node in iface.nodes.items():
    user = node.get('user', {})
    print(f"{node_id}: {user.get('longName', 'unknown')}")
    pos = node.get('position', {})
    if pos:
        lat = pos.get('latitudeI', 0) / 1e7
        lon = pos.get('longitudeI', 0) / 1e7
        print(f"  position: {lat:.5f}, {lon:.5f}")

iface.close()

import meshtastic
import meshtastic.serial_interface
from pubsub import pub
import time

def on_receive(packet, interface):
    if 'decoded' not in packet:
        return
    msg = packet['decoded']
    if msg.get('portnum') == 'TEXT_MESSAGE_APP':
        text = msg['payload'].decode('utf-8')
        print(f"[{packet['fromId']}] {text}")
        print(f"  SNR: {packet.get('rxSnr')} dB  RSSI: {packet.get('rxRssi')} dBm")

def on_connection(interface, topic=pub.AUTO_TOPIC):
    print(f"Connected to node: {interface.myInfo}")

pub.subscribe(on_receive, "meshtastic.receive")
pub.subscribe(on_connection, "meshtastic.connection.established")

iface = meshtastic.serial_interface.SerialInterface("/dev/ttyUSB0")

try:
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    iface.close()

import meshtastic.tcp_interface

# Heltec V3 and other ESP32 boards support TCP when on WiFi
iface = meshtastic.tcp_interface.TCPInterface("192.168.1.100")
iface.sendText("Hello over TCP!")
iface.close()

meshtastic --set telemetry.environment_measurement_enabled true
meshtastic --set telemetry.environment_update_interval 300   # every 5 min
meshtastic --set telemetry.environment_screen_enabled true   # show on display

pip install meshtastic protobuf
# Proto definitions: github.com/meshtastic/protobufs

from meshtastic import mesh_pb2, telemetry_pb2, portnums_pb2

# Decode a telemetry packet's raw payload
def decode_telemetry(raw_bytes):
    tel = telemetry_pb2.Telemetry()
    tel.ParseFromString(raw_bytes)

    dm = tel.device_metrics
    if dm.battery_level:
        print(f"Battery:     {dm.battery_level}%")
        print(f"Voltage:     {dm.voltage:.2f} V")
        print(f"Ch util:     {dm.channel_utilization:.1f}%")
        print(f"Air util TX: {dm.air_util_tx:.1f}%")

    env = tel.environment_metrics
    if env.temperature:
        print(f"Temperature: {env.temperature:.1f}°C")
        print(f"Humidity:    {env.relative_humidity:.0f}%")
        print(f"Pressure:    {env.barometric_pressure:.0f} hPa")

meshtastic --set mqtt.enabled true
meshtastic --set mqtt.address "your-broker.com"
meshtastic --set mqtt.port 1883
meshtastic --set mqtt.username "user"
meshtastic --set mqtt.password "pass"
meshtastic --set mqtt.root "msh/PK"          # topic prefix
meshtastic --set mqtt.json_enabled true       # also publish decoded JSON
meshtastic --set mqtt.encryption_enabled true # keep packets encrypted on broker

msh/PK/2/e/LongFast/!abcd1234       # encrypted protobuf
msh/PK/2/json/LongFast/!abcd1234    # decoded JSON (if json_enabled)
msh/PK/2/stat/!abcd1234             # node status

import paho.mqtt.client as mqtt
import json

def on_connect(client, userdata, flags, rc):
    print(f"Connected, rc={rc}")
    client.subscribe("msh/PK/2/json/#")

def on_message(client, userdata, msg):
    try:
        data = json.loads(msg.payload)
        node_id = data.get('from')
        payload = data.get('payload', {})
        portnum = data.get('type')
        print(f"Node {node_id} [{portnum}]: {payload}")
    except json.JSONDecodeError:
        pass  # encrypted packet, skip

client = mqtt.Client()
client.on_connect = on_connect
client.on_message = on_message
client.connect("your-broker.com", 1883)
client.loop_forever()

Host:  mqtt.meshtastic.org
Port:  1883  (plain)  /  8883  (TLS)
Topic: msh/world/#

Flow example:

[MQTT in node]  →  [JSON parse]  →  [Switch on type]
                                    ├── telemetry  →  [InfluxDB write]
                                    ├── position   →  [Map widget]
                                    └── text       →  [Dashboard text]

npm install @meshtastic/js

import { Client } from "@meshtastic/js";

const client = new Client();

// Serial connection (Node.js or browser via Web Serial API)
const connection = client.createSerialConnection();
await connection.connect({
  port: "/dev/ttyUSB0",
  baudRate: 115200,
  concurrentLogOutput: false
});

// Send a text message
await connection.sendText("Hello from JS!");

// Listen for text messages
connection.events.onTextPacketReceived.subscribe((packet) => {
  console.log(`From ${packet.from}: ${packet.message}`);
  console.log(`SNR: ${packet.rxSnr}, RSSI: ${packet.rxRssi}`);
});

// Listen for position updates
connection.events.onPositionPacketReceived.subscribe((packet) => {
  const { latitudeI, longitudeI, altitude } = packet.data;
  console.log(`Position: ${latitudeI/1e7}, ${longitudeI/1e7}, ${altitude}m`);
});

# Scan for nearby Meshtastic nodes over BLE
meshtastic --ble-scan

import meshtastic.ble_interface
import asyncio

async def main():
    # Use MAC address from ble-scan output
    iface = meshtastic.ble_interface.BLEInterface("AA:BB:CC:DD:EE:FF")
    iface.sendText("Hello over BLE!")

    # Get node info
    print(iface.myInfo)

    await asyncio.sleep(5)
    iface.close()

asyncio.run(main())

from pubsub import pub
import meshtastic.serial_interface
import sqlite3, time

DB = sqlite3.connect("positions.db")
DB.execute("""CREATE TABLE IF NOT EXISTS pos
    (ts INTEGER, node TEXT, lat REAL, lon REAL, alt INTEGER)""")
DB.commit()

def on_receive(packet, interface):
    if 'decoded' not in packet:
        return
    decoded = packet['decoded']
    if decoded.get('portnum') != 'POSITION_APP':
        return
    pos = decoded.get('position', {})
    lat = pos.get('latitudeI', 0) / 1e7
    lon = pos.get('longitudeI', 0) / 1e7
    alt = pos.get('altitude', 0)
    node = packet['fromId']
    DB.execute("INSERT INTO pos VALUES (?,?,?,?,?)",
               (int(time.time()), node, lat, lon, alt))
    DB.commit()
    print(f"[{node}] {lat:.5f}, {lon:.5f}  alt={alt}m")

pub.subscribe(on_receive, "meshtastic.receive")
iface = meshtastic.serial_interface.SerialInterface()

while True:
    time.sleep(1)

def on_receive(packet, interface):
    rssi = packet.get('rxRssi', 'n/a')
    snr  = packet.get('rxSnr',  'n/a')
    hops = packet.get('hopStart', 3) - packet.get('hopLimit', 3)
    print(f"RSSI: {rssi} dBm  SNR: {snr} dB  Hops: {hops}")

# On the sending node:
meshtastic --set range_test.enabled true
meshtastic --set range_test.sender 60    # send ping every 60 seconds
meshtastic --set range_test.save true    # save results CSV to SD card

Meshtastic node ──BLE──► Phone running ATAK / WinTAK
                                    ↓
                          TAK server (local or cloud)
                                    ↓
                          Shared Situation Awareness Map