🤖 MeshCore Bots

A bot is a Python script that connects to a MeshCore radio and automatically responds to messages on the mesh — answering commands, bridging data to the internet, publishing to MQTT, and much more. Bots run 24/7 on a small computer tethered to a radio and require no human operator once deployed.

Around Puget Sound you can already find shared community bots on channels like #bot, #bot-tacoma, and #bot-islands. Type help on any of those channels to get a live command list from the bot.

Key Reasons to Run a Bot

Hardware: Do You Need a Raspberry Pi?

No, a Raspberry Pi is not required — the bot is a plain Python script that runs on any computer with Python 3.7+. That said, a Pi is a very popular choice for good reasons:

Connecting the Bot to Your Radio

Three connection methods are supported:

• Serial (USB) — plug the radio into the Pi with a USB cable; configure serial_port = /dev/ttyUSB0. Most reliable option.
• BLE (Bluetooth) — wireless, but less stable for long-running bots. Useful when the radio is glued inside an enclosure.
• TCP/IP — connect to a radio (or Room Server) over the network. Handy when the bot and radio are on the same LAN but in different enclosures, or when connecting to a remote Room Server.

MQTT Bridging in Detail

The Packet Capture service plugin subscribes to all mesh traffic and publishes decoded packets to any MQTT broker. This gives you:

• Persistent message history beyond the Room Server's 16-message queue limit.
• Home Assistant integration — create automations triggered by mesh events (e.g. a member checks in → turn on a light).
• Grafana / InfluxDB dashboards — long-term signal quality graphs, node activity heatmaps, channel usage analytics.
• Cross-network bridging — republish mesh traffic from one region to another via a shared MQTT broker, effectively extending your mesh over the internet.

To enable MQTT, run Mosquitto (or any MQTT broker) on the same Pi, then add a [PacketCapture] section to config.ini pointing at the broker. No extra hardware is required.

Available Commands

The agessaman/meshcore-bot project (v0.8.3, 99 ★, MIT license) ships the following built-in commands:

Installation

Four deployment options, from simplest to most production-ready:

1. Quick start (dev / testing)

git clone https://github.com/agessaman/meshcore-bot
cd meshcore-bot
pip install -r requirements.txt
cp config.ini.example config.ini   # or config.ini.minimal-example
# edit config.ini — set serial port, bot name, channels
python3 meshcore_bot.py

2. Systemd service (recommended for Pi)

sudo ./install-service.sh
sudo nano /opt/meshcore-bot/config.ini
sudo systemctl start meshcore-bot
sudo systemctl status meshcore-bot

The service auto-starts on boot and restarts on failure. Logs go to /opt/meshcore-bot/ by default.

3. Docker Compose

mkdir -p data/{config,databases,logs,backups}
cp config.ini.example data/config/config.ini
# edit data/config/config.ini
docker compose up -d --build

Easiest option for NAS or home-server deployments. Serial port access requires mapping /dev/ttyUSB0 into the container — see the Docker deployment docs.

4. NixOS flake

{ inputs.meshcore-bot.url = "github:agessaman/meshcore-bot/"; }

services.meshcore-bot = {
  enable = true;
  settings.Connection.connection_type = "serial";
  settings.Connection.serial_port = "/dev/ttyUSB0";
  settings.Bot.bot_name = "VashonBot";
};

Service Plugins

Beyond commands, background service plugins run continuously alongside the bot:

• Packet Capture — captures & publishes all mesh packets to MQTT brokers.
• Discord Bridge — one-way webhook; mesh messages appear in a Discord channel.
• Map Uploader — reports node adverts to map.meshcore.dev.
• Weather Service — pushes scheduled forecasts, NWS alerts, and lightning detection to configured channels.

Custom service and command plugins are straightforward to write — inherit from BaseCommand or BaseServicePlugin, drop your file in modules/commands/ or modules/service_plugins/, and the plugin loader picks it up automatically.