MSH-BOT This is a simple meshtastic bot that will reply to some given commands. It connects to a node over TCP so the node needs to be reachable on your network. The main purpose of this bot is to use it for tests in a private channel :)

Commands

/trace <node_id>    -> will traceroute the given node_id and return the number of hops and path, if no node_id is given it will trace route the sender
/ping               -> will just reply with the number of hops and snr and rssi values
/dist               -> will calculate the distance between the sender and the bot
/off <time>         -> program will disconnect from node for the given time (useful for maintenance on the node)
/help               -> will print an help message listing available commands

Configuration

Settings live in a config.toml file, the bot reads the path specified in MSHBOT_CONFIG if set, otherwise config.toml in the working dir. config.example.toml in the repository root is a template to copy.

[node]
hostname = "192.168.1.1"    # hostname of the node
target_channel = "Example"  # the channel name where the bot will reply (please do not set in main channels like longfast), note that this is case sensitive!
dm_reply_message = "Hello!" # if this is defined the bot will respond to all dms with this message, if this is not set in the config the dm functionality is disabled!
discord_webhook_url = "https://discord.com/api/webhooks/..." # if set will send all the received and sent messages through this webhook


[mesh]
hop_limit = 4               # the bot hop limit (check your local community guide for this value)
trace_route_channel = 0     # the channel where the traceroute will run (default 0), set this as your public channel if it is not 0 so the node ids in the path are not always !ffffff
trace_route_timeout = 60    # hard timeout for trace route (default 1 min)

[offline]
offline_minutes = 30        # default value for the time the node will be offline (in case a <time> value is omitted in the /off command)
disconnect_delay = 10       # delay in seconds till the program disconnects from the node
reconnect_poll = 30         # delay in seconds to retry connection to the node
probe_interval = 60         # seconds between liveness probes, also the worst case delay before a silent drop is detected

hostname and target_channel are required, everything else falls back to the defaults shown above

Install (as systemd service)

These instructions assume systemd and a dedicated service account. Adjust the paths if you prefer somewhere other than /opt.

I run this bot on a Pi Zero 2 W, where a container adds more overhead than it is worth for a single Python process. systemd is enough.

The project is built with uv. Since the pi doesn't have uv installed I usually just buld the wheel on my host and copy it over to the pi.

Build the wheel

uv build

This produces something like this: dist/msh_bot-0.1.0-py3-none-any.whl

Copy this to the pi

scp dist/msh_bot-0.1.0-py3-none-any.whl <user>@<host>:/tmp/

Create the user and dirs

sudo useradd -r -s /usr/sbin/nologin msh-bot
sudo mkdir -p /opt/msh-bot /etc/msh-bot
sudo chown msh-bot:msh-bot /opt/msh-bot

Install the wheel

sudo -u msh-bot -H /usr/bin/python3 -m venv /opt/msh-bot/venv
sudo -u msh-bot -H /opt/msh-bot/venv/bin/pip install --no-cache-dir /tmp/msh_bot-0.1.0-py3-none-any.whl

On the pi if the venv command hangs don't worry it is not stuck!

Copy config

sudo cp config.example.toml /etc/msh-bot/config.toml
sudo chown root:msh-bot /etc/msh-bot/config.toml
sudo chmod 640 /etc/msh-bot/config.toml

Then edit it with your favourite editor, for example sudo vim /etc/msh-bot/config.toml. The file is readable by the service and by root only.

Create the unit file

at /etc/systemd/system/msh-bot.service

[Unit]
Description=MSH-BOT a simple meshtastic bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=msh-bot
WorkingDirectory=/opt/msh-bot
Environment=MSHBOT_CONFIG=/etc/msh-bot/config.toml
ExecStart=/opt/msh-bot/venv/bin/msh-bot
Restart=on-failure
RestartSec=10

NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes

[Install]
WantedBy=multi-user.target

Start it

sudo systemctl daemon-reload
sudo systemctl enable --now msh-bot.service