No description
  • Python 99.5%
  • Shell 0.5%
Find a file
2026-11-20 12:50:38 +00:00
.forgejo/workflows ci: fetch the checkout action from github.com 2026-10-21 10:35:00 +00:00
tests bridge reactions and replies both ways (#9) 2026-11-20 12:50:38 +00:00
.gitignore gitignore: keep runtime state out of the tree 2026-10-20 12:24:09 +00:00
AGENTS.md ops: listen-only, durable dedupe, backlog filter, --check (#7) 2026-11-20 12:32:56 +00:00
bot.py bridge reactions and replies both ways (#9) 2026-11-20 12:50:38 +00:00
CHANGELOG.md bridge reactions and replies both ways (#9) 2026-11-20 12:50:38 +00:00
LICENSE add LICENSE 2026-02-09 07:50:49 +00:00
README.md bridge reactions and replies both ways (#9) 2026-11-20 12:50:38 +00:00
requirements.txt core: drop manual transport failover, bump Delta Chat to 2.69.0 2026-11-20 11:56:20 +00:00

Meshdelta

Meshdelta is a WIP Meshtastic<->Delta Chat bridge

How to setup

Requirements

  1. Python

  2. deltachat-rpc-client

Configuration

  1. Create mqtt.conf and specify your values; one broker is enough for most setups
[mqtt]
host=mqtt.meshtastic.org
port=8883
username=meshdev
password=large4cats
root_topic=msh/US
userid=<random user id>
admin_email=admin@example.com

[keys]
longfast=1PG7OiApB1nwvP+rz05pAQ==

[chats]
longfast=13
  1. Copy bot's accounts dir to same place as bot.py Launch bot with python bot.py

Several brokers

Each broker lives in its own connection, subscribes with its own identity and maps its own channels onto Delta Chat chats:

[general]
brokers = home, public
admin_email = admin@example.com

[broker:home]
host = 192.168.1.10
port = 1883
username = mesh
password = secret
root_topic = msh/EU
userid = 11223344
label = Home Mail

[keys:home]
home-longfast = 1PG7OiApB1nwvP+rz05pAQ==

[chats:home]
home-longfast = 14

[broker:public]
host = mqtt.meshtastic.org
port = 8883
username = meshdev
password = large4cats
root_topic = msh/US
userid = 11223344

[keys:public]
longfast = 1PG7OiApB1nwvP+rz05pAQ==

[chats:public]
longfast = 13

Rules of the multi-broker form:

  • [general] brokers lists the brokers, in this order; without it the bot reads [mqtt]/[keys]/[chats] as one broker named default (the old single-broker file keeps working unchanged).
  • Every listed broker needs a [broker:<name>] section; [keys:<name>] and [chats:<name>] are optional when that broker bridges nothing.
  • [chats:<name>] maps channel = Delta Chat chat id.
  • A chat id may be used by one broker only. If two brokers map the same chat id the first one wins and the bot prints a warning at startup — the chat cannot tell which server you meant.
  • admin_email belongs to the account, not to a broker: put it in [general] (or in the legacy [mqtt] section).
  • Environment overrides keep working: MQTT_HOST, MQTT_PORT, … for the legacy broker, MQTT_<NAME>_HOST, MQTT_<NAME>_PORT, … for the others (MQTT_PUBLIC_HOST for [broker:public]).
  • A packet heard by two brokers is bridged once: the bot remembers (sender, packet id) pairs for five minutes, because Meshtastic relays the same packet to every gateway that hears it.
  • Brokers are independent: one being unreachable or reconnecting does not stop the others, and the bot keeps serving Delta Chat either way. A broker reconnects with exponential backoff (5 s doubling to 5 minutes) instead of hammering the server every five seconds.
  • max_text_bytes (default 227) is the per-message budget for the radio. The text is cut by UTF-8 bytes, not characters — a Cyrillic letter is two bytes — and ends with … when it did not fit. Without it a long Delta Chat message would be dropped or silently truncated by the receiver.
  • message_delay_seconds (default 2.2) paces outgoing radio messages: firmware rejects sends that are closer than ~2 seconds with RATE_LIMIT_EXCEEDED.
  • outbound_mode = listen_only makes the broker receive-only: messages still flow from the mesh into Delta Chat, but nothing is published to the radio. Useful while testing a new broker, or when a node must not transmit.
  • backlog_suppress_seconds (default 60) drops the burst a broker replays right after a reconnect: for the first 15 seconds after connecting, packets whose rx_time is older than the threshold are ignored. Packets without rx_time are never dropped on a guess.

Sender names

The mesh only announces a node's name in a NodeInfo packet, which a node sends on its own schedule (often once an hour) — that is why the phone app has a "fetch user info" button. The bridge does the same thing automatically: when a message arrives from a node it has no name for, it asks that node directly (a NODEINFO_APP packet addressed to it with want_response), remembers the reply in nodes.json, and bridges the message with the short node id as the name in the meantime. The next message from that node carries the real name.

The firmware throttles these: a node sends its info at most every 10 minutes and suppresses replies to a requester it heard within 12 hours, so a missing reply is normal. Two knobs:

  • lookup_node_info (default true) — set to false to never ask.
  • node_info_request_seconds (default 3600) — at most one request per node per window.

Reactions and replies

Meshtastic carries a reaction as a text packet with the emoji flag set: the payload is the emoji, reply_id is the packet being reacted to. The bridge keeps a bridged table in seen.sqlite3 that maps mesh packet ids to Delta Chat message ids, which is what makes those ids meaningful on both sides:

  • a tapback heard in the mesh becomes a Delta Chat reaction on the mapped message;
  • a reaction added in Delta Chat becomes a tapback in the mesh, addressed to the original packet;
  • a reply in either direction carries the corresponding id (quoted_msg in Delta Chat, reply_id in the mesh).

A reaction for a packet the bridge never saw (for example after the database was wiped) is dropped with a log line instead of being sent as a stray "👍" text on the radio.

Checking a config

python bot.py --check

Validates mqtt.conf without touching the network: channel keys decode and are 16 or 32 bytes, every mapped chat has a key, the userid fits a 32-bit node number, and the resolved chat <-> broker/channel routes are printed. Exit code 1 means a problem was found, and the list says which.

De-duplication across restarts

Packets are remembered for five minutes in seen.sqlite3 next to nodes.json, so a restart inside that window does not deliver a message twice. The file is safe to delete while the bot is stopped.

What is missing

  1. Something other?

Admin Commands

You can configure an admin_email in mqtt.conf to enable the bot administrator to manage backup mail transports (relays) via Delta Chat:

  • /transports — Show configured mail relays.
  • /addtransport <user@example.com> <password123> — Add a backup mail relay.
  • /rmtransport <user@example.com> — Remove a mail relay.

There is no primary relay to choose: Delta Chat core picks a working transport for sending and switches to another one when the current relay returns an error.

support the project - monero:48zwQPpAqkKLJSnavwE29vBx1ejWB8dexhemqXz2dWKJbWaukbREefF3pRws3dfPn3cdNAcKUNhrQPGKntNL1rkMM6EKPuo