Skip to content

Search guides, devices and posts

Back to Meshtastic

Meshtastic Channels & MQTT

A channel is a name plus a key. Anyone with both can read and send on it. MQTT copies chosen channels to an internet server, so you can watch your mesh from anywhere or link two meshes together.

Checked October 2026 against Meshtastic 2.7.26 (stable) and Meshtastic 2.8.1 (alpha).

How Channels Work

Every node has eight channel slots: one PRIMARY (index 0) and up to seven SECONDARY (1 to 7). Two nodes share a channel when the name and key match. On 2.8.1, the Use AEAD setting has to match too.

Every node ships on the same default PRIMARY channel (LongFast in the US) with a published key. That's deliberate: new nodes find each other straight away. It also means anyone can read that channel.

PRIMARY (index 0)

Carries your node's routine broadcasts. Its name also picks the radio's frequency slot, unless the slot is set by hand. Rename it and your node moves to a different frequency from everyone else in your area, which is a common reason people suddenly see no one.

SECONDARY (1 to 7)

Extra channels on the same frequency, for private groups. This is where a family or team channel belongs: you stay on the local mesh and get a private room on top of it.

What 2.8 changes about channels

  • Position and telemetry broadcasts are off by default until you turn them on.
  • On a channel with a public key (no key, the default key, or a one-byte key), position precision is capped at 15 bits, roughly 700 m.
  • 2.8.1 adds Use AEAD: authenticated encryption (AES-CCM) that rejects altered or forged packets. It's experimental, off by default, needs a key, and every node on the channel must turn it on or they can't read each other.
  • Broadcasts are signed. See packet signing explained.

Make a Private Channel

In the app

  1. Open the channel settings: Settings, then Channels on Android; Settings, then Radio Configuration, then Channels on iPhone and iPad.
  2. Add a new SECONDARY channel and give it a name (under 12 bytes).
  3. Generate a random key for it and save.
  4. Share it with the QR code, in person.

With the CLI

# New secondary channel with a random 256-bit key

meshtastic --ch-add "Family"

# Change the key on channel 1 later

meshtastic --ch-index 1 --ch-set psk random

# Show a QR code for every channel

meshtastic --qr-all

--ch-add takes names up to 10 characters and can't be combined with --ch-index. Key values: random, default, none, or your own key.

Keys, Encryption and QR Codes

Encryption

  • Channels use AES in CTR mode: a 16-byte key gives AES-128, a 32-byte key AES-256. The default key is AES-128 and public.
  • Direct messages between nodes on 2.5 or newer use the nodes' own public keys, not the channel key.
  • A key mismatch shows up as a lock icon in the apps. Our lock icons guide explains each one.

QR codes and channel URLs

  • A code holds channel names, keys and the LoRa settings. Posting one publicly publishes the key.
  • meshtastic --seturl <url> replaces all your channels and LoRa settings.
  • meshtastic --ch-add-url <url> keeps yours, adds the new channels as secondaries, and still applies the URL's LoRa settings.
  • meshtastic --qr shows only the PRIMARY channel; --qr-all shows all of them.

Remote admin: use admin keys, not an admin channel

The old way to manage a node remotely was a channel named "admin". Current firmware ignores it unless security.admin_channel_enabled is turned on, which it isn't by default. Meshtastic recommends admin keys instead: add your controlling node's public key to the remote node's admin keys in its Security settings. Our CLI guide shows the commands.

MQTT: Your Mesh on the Internet

A node with an internet connection can act as a gateway. It copies traffic from channels you choose up to an MQTT broker (uplink), and can send broker traffic back into the mesh (downlink). Our MQTT setup guide goes step by step.

Uplink

Mesh to broker. Turned on per channel; off by default.

Downlink

Broker to mesh. Also per channel and off by default.

Getting online

Wi-Fi on ESP32 boards, Ethernet on some (like a RAK4631 with the RAK13800), or the phone's connection through client proxy, which also works on nRF52 boards.

The public broker

Defaults: mqtt.meshtastic.org, username meshdev, password large4cats, port 1883 (8883 with TLS). Leave those as they are; a blank username or password is sent as blank, and the default address with any port other than 1883 or 8883 is rejected as invalid. The public broker also limits what it passes:

  • Traffic it sends into a mesh goes zero hops: only nodes next to a gateway hear it.
  • On the default key, it passes only core packet types (text, position, node info, telemetry, map reports, routing).
  • On the default key, only imprecise positions (10 to 16 bits) are shared.

Why other nodes don't show up on MQTT

When the broker isn't on a private network, a gateway only uploads other people's packets if they turned on OK to MQTT in their LoRa settings, and it's off by default. Your own node's packets go up either way. Range test and detection sensor packets never go to the public broker, and packets that already came from MQTT aren't sent back up.

Topics

Encrypted packets are published to:

msh/US/2/e/LongFast/!a1b2c3d4

msh/US is the root topic and region, 2/e is fixed (protocol version, encrypted), then the channel name, and last the gateway's node ID, not the sender's. Direct messages go under 2/e/PKI, map reports under 2/map.

JSON output and Home Assistant

Firmware 2.7 can also publish plain JSON (mqtt.json_enabled, not on nRF52 boards), which is what most Home Assistant setups read. 2.8 removed JSON output from the firmware. JSON is also unencrypted, so use it only on a broker you control.

Channels and MQTT FAQ

How many channels can a Meshtastic node have?

Eight: one PRIMARY (index 0) and up to seven SECONDARY (indexes 1 to 7). Each has its own name and key.

How do I make a private Meshtastic channel?

Add a SECONDARY channel with a random key and share it in person. In the CLI, meshtastic --ch-add "Family" creates one with a random 256-bit key. Keep the PRIMARY channel as it is, because renaming it moves your node to a different frequency slot than the rest of your area.

Is Meshtastic encrypted?

Channel messages are encrypted with AES in CTR mode: AES-128 with a 16-byte key, AES-256 with a 32-byte key. The default channel's key is published, so anyone can read it. Direct messages between nodes on 2.5 or newer use public-key encryption instead. Firmware 2.8.1 adds an optional authenticated mode per channel (Use AEAD).

What is in a Meshtastic channel QR code or URL?

The channel names and keys, plus the LoRa settings (region and preset). Anyone with the code can read and send on those channels, so treat it like a password. Applying a full channel URL replaces your channels and LoRa settings; adding one keeps your channels, adds the new ones as secondaries, and also applies the URL's LoRa settings.

What is the Meshtastic MQTT server and password?

The default public broker is mqtt.meshtastic.org, username meshdev, password large4cats, on port 1883 (8883 with TLS). Leave those defaults in place rather than blanking them. The firmware rejects the default address with any port other than 1883 or 8883.

Why isn't my Meshtastic MQTT working?

The usual causes: uplink isn't turned on for the channel; other people's packets aren't uploaded to a public broker unless they turned on OK to MQTT, which is off by default; the node has no internet connection (Wi-Fi, Ethernet, or the phone's connection via client proxy); or you're expecting JSON output, which 2.8 removed.