Mesh Bot is a feature-rich Python bot designed to enhance your Meshtastic network experience. It provides powerful tools for network testing, messaging, games, and more—all via text-based message delivery. Whether you want to test your mesh, send messages, or play games, mesh_bot.py has you covered.
- Automated Responses: Detects keywords like "ping" and replies with "pong" in direct messages (DMs) or group channels.
- Customizable Triggers: Monitors group channels for specific keywords and sends custom responses.
- Emergency Detection: Watches for emergency-related keywords and alerts a wider audience.
- New Node Greetings: Automatically welcomes new nodes joining the mesh.
-
Mesh Testing: Use
pingto test message delivery with realistic packets. -
Hardware Testing: The
testcommand sends incrementally sized data to test radio buffer limits. -
Network Monitoring: Alerts for noisy nodes, tracks node locations, and suggests optimal relay placement.
-
Site Survey & Location Logging: Use the
mapcommand to log your current GPS location with a custom description—ideal for site surveys, asset tracking, or mapping nodes locations. Entries are saved to a CSV file for later analysis or visualization.
- Simultaneous Monitoring: Observe up to nine networks at once.
- Flexible Messaging: Send mail and messages between networks.
- Mail Messaging: Leave messages for other devices; delivered as DMs when the device is next seen. Use
bbspost @nodeNumber #messageorbbspost @nodeShortName #message. - Message Scheduler: Automate messages such as weather updates or net reminders.
- Store and Forward: Retrieve missed messages with the
messagescommand; optionally log messages to disk. - BBS Linking: Connect multiple bots to expand BBS coverage.
- E-Mail/SMS Integration: Send mesh messages to email or SMS for broader reach.
- New Node Greetings: Automatically greet new nodes via text.
- Weather, Earthquake, River, and Tide Data: Get local alerts and info from NOAA/USGS; uses Open-Meteo for areas outside NOAA coverage.
- Wikipedia Search: Retrieve summaries from Wikipedia and Kiwix
- OpenWebUI, Ollama LLM Integration: Query the Ollama AI for advanced responses. Supports RAG (Retrieval Augmented Generation) with Wikipedia/Kiwix context and OpenWebUI integration for enhanced AI capabilities. LLM Readme
- Satellite Passes: Find upcoming satellite passes for your location.
- GeoMeasuring Tools: Calculate distances and midpoints using collected GPS data; supports Fox & Hound direction finding.
- RSS & News Feeds: Receive news and data from multiple sources directly on the mesh.
- Location-Based Alerts: Get notified when members arrive at a configured latitude/longitude—ideal for campsites, geo-fences, or remote locations. Optionally, trigger scripts, send emails, or automate actions (e.g., change node config, turn on lights, or drop an
alert.txtfile to start a survey or game). - Customizable Triggers: Use proximity events for creative applications like "king of the hill" or 🧠geocache games by adjusting the alert cycle.
- High Flying Alerts: Receive notifications when nodes with high altitude are detected on the mesh.
- Voice/Command Triggers: Activate bot functions using keywords or voice commands (see Voice Commands for "Hey Chirpy!" support).
- FEMA iPAWS/EAS Alerts: Receive Emergency Alerts from FEMA via API on internet-connected nodes.
- NOAA EAS Alerts: Get Emergency Alerts from NOAA via API.
- USGS Volcano Alerts: Receive volcano alerts from USGS via API.
- NINA Alerts (Germany): Receive emergency alerts from the xrepository.de feed for Germany.
- Offline EAS Alerts: Report EAS alerts over the mesh using external tools, even without internet.
- File Monitoring: Watch a text file for changes and broadcast updates to the mesh channel.
- News File Access: Retrieve the contents of a news file on request; supports multiple news sources or files.
- Shell Command Access: Execute shell commands via DM with replay protection (admin only).
- SNR RF Activity Alerts: Monitor radio frequencies and receive alerts when high SNR (Signal-to-Noise Ratio) activity is detected.
- Hamlib Integration: Use Hamlib (rigctld) to monitor the S meter on a connected radio.
- Speech-to-Text Broadcasting: Convert received audio to text using Vosk and broadcast it to the mesh.
- WSJT-X Integration: Monitor WSJT-X (FT8, FT4, WSPR, etc.) decode messages and forward them to the mesh network with optional callsign filtering.
- JS8Call Integration: Monitor JS8Call messages and forward them to the mesh network with optional callsign filtering.
- Meshages TTS: The bot can speak mesh messages aloud using KittenTTS. Enable this feature to have important alerts and messages read out loud on your device—ideal for hands-free operation or accessibility. See radio.md for setup instructions.
Advanced check-in/check-out and asset tracking for people and equipment—ideal for accountability, safety monitoring, and logistics (e.g., Radio-Net, FEMA, trailhead groups). Admin approval workflows, GPS location capture, and overdue alerts. The integrated inventory and point-of-sale (POS) system enables item management, sales tracking, cart-based transactions, and daily reporting, for swaps, emergency supply management, and field operations, maker-places.
- Built-in Games: Play classic games like DopeWars, Lemonade Stand, BlackJack, and Video Poker directly via DM.
- FCC ARRL QuizBot: Practice for the ham radio exam with the integrated quiz bot.
- Command-Based Gameplay: Use the
gamescommand to view available games and start playing. - Telemetry Leaderboard: Compete for fun stats like lowest battery or coldest temperature.
- Group Quizzes: Admins can start and stop quiz games for groups.
- Player Participation: Players join with
q: join, leave withq: leave, and answer questions by prefixing their answer withq:, e.g.,q: 42. - Scoring & Leaderboards: Check your score with
q: scoreand see the top performers withq: top. - Admin Controls: QuizMasters (from
bbs_admin_list) can useq: start,q: stop, andq: broadcast <message>to manage games.
- Custom Surveys: Create and manage surveys by editing JSON files in
data/survey. Multiple surveys are supported (e.g.,survey snow). - User Feedback: Users participate via DM; responses are logged for review.
- Reporting: Retrieve survey results with
survey reportorsurvey report <surveyname>.
- HTML Reports: Visualize bot traffic and data flows with a built-in HTML generator. See data reporting for details.
- Automatic Message Chunking: Messages over 160 characters are automatically split to ensure reliable delivery across multiple hops.
This project is developed on Linux (specifically a Raspberry Pi) but should work on any platform where the Meshtastic protobuf API modules are supported, and with any compatible Meshtastic hardware. For pico or low-powered devices, see projects for embedding, armbian or buildroot, also see femtofox for running on luckfox hardware. If you need a local console consider the firefly project.
🥔 Please use responsibly and follow local rulings for such equipment. This project captures packets, logs them, and handles over the air communications which can include PII such as GPS locations.
If you dont have git you will need it sudo apt-get install git
git clone https://github.com/spudgunman/meshing-around- Automated Installation: install.sh will automate optional venv and requirements installation.
- Launch Script: laynch.sh only used in a venv install, to launch the bot and the report generator.
Good for windows or OpenWebUI enabled bots
Configuration Guide modules/README.md
Games are DM only by default
Firmware 2.6 introduced PKC, enabling secure private messaging by adding necessary keys to each node. To fully utilize this feature, you should add favorite nodes—such as BBS admins—to your node’s favorites list to ensure their keys are retained. A helper script is provided to simplify this process:
- Run the helper script from the main program directory:
python3 script/addFav.py - By default, this script adds nodes from
bbs_admin_listandbbslink_whitelist - If using a virtual environment, run:
launch.sh addfav - The API will not work-fully today to set nodes this is a WIP
Additionally, you can just DM a bot to "auto favorite." If your node is set to not be messageable, DMs won't work—be advised.
To configure favorite nodes, add their numbers to your config file:
[general]
favoriteNodeList = # list of favorite nodes numbers ex: 2813308004,4258675309 used by script/addFav.py
There is no direct support for MQTT in the code, however, reports from Discord are that using meshtasticd with no radio and attaching the bot to the software node, which is MQTT-linked, allows routing. Tested working fully Firmware:2.6.11 with mosquitto.
There also seems to be a quicker way to enable MQTT by having your bot node with the enabled serial module with echo enabled and MQTT uplink and downlink. These two
I used ideas and snippets from other responder bots and want to call them out!
- Lemonade Stand
- Drug Wars
- BlackJack
- Video Poker Terminal Game
- Python Mastermind
- Golf
- ARRL Question Pool Data from https://github.com/russolsen/ham_radio_question_pool
For testing and feature ideas on Discord and GitHub, if its stable its thanks to you all.
- PiDiBi, Cisien, bitflip, nagu, Nestpebble, NomDeTom, Iris, Josh, GlockTuber, FJRPiolt, dj505, Woof, propstg, snydermesh, trs2982, F0X, Malice, mesb1, Hailo1999
- xdep: For the reporting html. 📊
- mrpatrick1991: For OG Docker configurations. 💻
- A-c0rN: Assistance with iPAWS and 🚨
- Mike O'Connell/skrrt: For eas_alert_parser enhanced by sheer.cold
- WH6GXZ nurse dude: Volcano Alerts 🌋
- mikecarper: hamtest, leading to quiz etc.. 📋
- c.merphy360: high altitude alerts. 🚀
- G7KSE: DX Spotting idea. 📻
- Growing List of GitHub Contributers
- Meshtastic Discord Community: For putting up with 🥔
- Node Backup Management: Node Slurper
Meshtastic® is a registered trademark of Meshtastic LLC. Meshtastic software components are released under various licenses, see GitHub for details. No warranty is provided - use at your own risk.