Skip to content

How MMRelay Works

Jump to bottom
Jeremiah K edited this page Aug 17, 2026 · 6 revisions

How MMRelay Works

MMRelay is a self-hosted bridge between a Meshtastic meshnet and Matrix. It runs continuously on a computer or server, connects to a Meshtastic node, and logs in to Matrix with a dedicated bot account.

The important idea is simple:

Meshtastic meshnet ⇄ Meshtastic node ⇄ MMRelay ⇄ Matrix rooms

Only traffic covered by MMRelay's configuration crosses that boundary.

The pieces

Meshtastic meshnet

A meshnet is the local Meshtastic network. Its radios (also commonly called nodes or devices) communicate over the mesh and may relay packets for one another.

MMRelay does not need a direct connection to every node. It communicates with the mesh through one Meshtastic node that is available to the MMRelay service. For an always-on bridge, dedicating a node to MMRelay is usually the simplest and most predictable setup, although the node is still a normal participant in the Meshtastic mesh.

The Meshtastic connection

MMRelay supports three connection modes to that node:

  • Serial — the node is attached directly to the MMRelay host.
  • BLE — the MMRelay host connects to the node over Bluetooth Low Energy.
  • TCP / network — the node is reachable by IP, commonly through Wi-Fi or Ethernet depending on its firmware and hardware.

These are alternative ways to connect MMRelay to its Meshtastic node; they are not separate relay stages.

MMRelay

MMRelay is the bridge service. It runs on infrastructure you control, receives eligible traffic from either side, applies its configured mapping and relay rules, and sends the resulting traffic to the other side.

MMRelay is not a Matrix client plugin and is not a public relay endpoint that other users configure remotely.

Matrix

MMRelay logs in with a dedicated Matrix bot account and joins the rooms listed in its configuration. Those rooms can be on matrix.org or another homeserver; the important part is that the bot account can access them.

Mapping Matrix rooms to Meshtastic channels

The matrix_rooms section maps a Meshtastic channel to a Matrix room:

matrix_rooms:
  - id: "#field-ops:example.org"
    meshtastic_channel: 0
  - id: "#weather:example.org"
    meshtastic_channel: 1

Meshtastic firmware provides eight channels per node, numbered 0–7. MMRelay requires at least one mapped channel and supports mapping up to all eight. Within one MMRelay instance the mapping is 1:1: one Meshtastic channel maps to one Matrix room.

To bridge multiple meshnets into a shared Matrix room, run one MMRelay instance per meshnet and map each instance's channel to the same room. Relayed messages carry custom fields (meshtastic_longname, meshtastic_meshnet) so the origin meshnet and sender stay visible in the room.

Unmapped rooms and channels are not automatically bridged simply because the bot or Meshtastic node can see them.

Meshtastic → Matrix

For an eligible packet on a configured channel:

  1. The Meshtastic mesh delivers the packet to the node connected to MMRelay.
  2. MMRelay applies its packet-routing and room-mapping rules.
  3. MMRelay posts the message into the Matrix room mapped to that channel using the bot account.
  4. The Meshtastic sender, meshnet, channel, and related information can be preserved as message attribution and event metadata.

The Matrix event sender is the MMRelay bot. A Meshtastic long name or node ID shown in the message is attribution supplied by the relay; it is not a Matrix-authenticated identity.

Matrix → Meshtastic

For eligible traffic in a configured Matrix room:

  1. MMRelay receives the Matrix event as its bot account.
  2. MMRelay finds the Meshtastic channel associated with that room.
  3. MMRelay formats the message for Meshtastic and passes it to its connected node.
  4. The node transmits it onto the configured mesh channel.

Matrix sender information can be included in the relayed message so mesh users can see where it came from.

Identity and trust boundary

Matrix and Meshtastic have different identity systems. MMRelay bridges messages; it does not turn a Meshtastic node identity into a verified Matrix identity.

That means anyone able to send relay-eligible traffic on a bridged Meshtastic channel can cause the MMRelay bot to post corresponding traffic into its mapped Matrix room. Operators should therefore bridge only channels and rooms whose participants they intend to connect.

Matrix end-to-end encryption protects Matrix traffic and the MMRelay bot's Matrix device identity. It does not authenticate Meshtastic sender names across the bridge.

Where to go next

Clone this wiki locally