Welcome to the Mesh Bot project! This feature-rich bot is designed to enhance your Meshtastic network experience with a variety of powerful tools and fun features, connectivity and utility through text-based message delivery. Whether you're looking to perform network tests, send messages, or even play games, this bot has you covered.
- Automated Responses: The bot traps keywords like "ping" and responds with "pong" in direct messages (DMs) or group channels.
- Customizable Triggers: Monitor group channels for specific keywords and set custom responses.
- Simultaneous Monitoring: Monitor two networks at the same time.
- Flexible Messaging: send mail and messages, between networks.
- Mail Messaging: Leave messages for other devices, which are sent as DMs when the device is seen.
- Scheduler: Schedule messages like weather updates or reminders for weekly VHF nets.
- Store and Forward: Replay messages with the
messagescommand, and log messages locally to disk. - Send Mail: Send mail to nodes using
bbspost @nodeNumber #messageorbbspost @nodeShortName #message.
- NOAA location Data: Get localized weather(alerts) and Tide information. Open-Meteo is used for wx only outside NOAA coverage.
- Wiki Integration: Look up data using Wikipedia results.
- Ollama LLM AI: Interact with the Ollama LLM AI for advanced queries and responses.
- Location-Based Alerts: Get notified when members arrive back at a configured lat/long, perfect for remote locations like campsites.
- Built-in Games: Enjoy games like DopeWars, Lemonade Stand, BlackJack, and VideoPoker.
- Command-Based Gameplay: Issue
gamesto display help and start playing.
- SNR RF Activity Alerts: Monitor a radio frequency and get alerts when high SNR RF activity is detected.
- Hamlib Integration: Use Hamlib (rigctld) to watch the S meter on a connected radio.
- HTML Generator: Visualize bot traffic and data flows with a built-in HTML generator for data reporting.
- Message Chunking: Automatically chunk messages over 160 characters to ensure higher delivery success across 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.
git clone https://github.com/spudgunman/meshing-aroundThe code is under active development, so make sure to pull the latest changes regularly!
- Automated Installation:
install.shwill automate optional venv and requirements installation. - Launch Script:
launch.shwill activate and launch the app in the venv
If you prefer to use Docker, follow these steps:
- Ensure your serial port is properly shared and the GPU is configured if using LLM with NVIDIA.
- Build the Docker image:
cd meshing-around docker build -t meshing-around .
- Run the Docker container:
docker run --rm -it --device=/dev/ttyUSB0 meshing-around
Install the required dependencies using pip:
pip install -r requirements.txtCopy the configuration template to config.ini and edit it to suit your needs:
cp config.template config.iniCopy the config.template to config.ini and set the appropriate interface for your method (serial/ble/tcp). While BLE and TCP will work, they are not as reliable as serial connections. There is a watchdog to reconnect TCP if possible. To get the BLE MAC address, use:
meshtastic --ble-scanNote: The code has been tested with a single BLE device and is written to support only one BLE port.
# config.ini
# type can be serial, tcp, or ble.
# port is the serial port to use; commented out will try to auto-detect
# hostname is the IP address of the device to connect to for TCP type
# mac is the MAC address of the device to connect to for BLE type
[interface]
type = serial
# port = '/dev/ttyUSB0'
# hostname = 192.168.0.1
# mac = 00:11:22:33:44:55
# Additional interface for dual radio support. See config.template for more.
[interface2]
enabled = FalseThe following settings determine how the bot responds. By default, the bot will not spam the default channel. Setting respond_by_dm_only to True will force all messages to be sent via DM, which may not be desired. Setting it to [False] will allow responses in the channel for all to see. If you have no default channel you can set this value to -1 or any unused channel index.
[general]
respond_by_dm_only = True
defaultChannel = 0The weather forecasting defaults to NOAA, but for locations outside the USA, you can set UseMeteoWxAPI "Go to definition") to True to use a global weather API. The lat and lon are default values when a node has no location data. It is also the default used for Sentry.
[location]
enabled = True
lat = 48.50
lon = -123.0
UseMeteoWxAPI = TrueModules can be enabled or disabled as needed.
[bbs]
enabled = False
[general]
DadJokes = False
StoreForward = FalseThe history command shows the last commands the user ran, and [lheard] reflects the last users on the bot.
enableCmdHistory = True # history command enabler
lheardCmdIgnoreNodes = # command history ignore list ex: 2813308004,4258675309Sentry Bot detects anyone coming close to the bot-node.
SentryEnabled = True # detect anyone close to the bot
SentryRadius = 100 # radius in meters to detect someone close to the bot
SentryChannel = 9 # holdoff time multiplied by seconds(20) of the watchdog
SentryHoldoff = 2 # channel to send a message to when the watchdog is triggered
sentryIgnoreList = # list of ignored nodes numbers ex: 2813308004,4258675309A repeater function for two different nodes and cross-posting messages. The [repeater_channels] is a list of repeater channels that will be consumed and rebroadcast on the same number channel on the other device, node, or interface. Each node should have matching channel numbers. The channel names and PSK do not need to be the same on the nodes. Use this feature responsibly to avoid creating a feedback loop.
[repeater] # repeater module
enabled = True
repeater_channels = [2, 3]A module allowing a Hamlib compatible radio to connect to the bot. When functioning, it will message the configured channel with a message of in use. Requires hamlib/rigctld to be running as a service.
[radioMon]
enabled = False
rigControlServerAddress = localhost:4532
sigWatchBroadcastCh = 2 # channel to broadcast to can be 2,3
signalDetectionThreshold = -10 # minimum SNR as reported by radio via hamlib
signalHoldTime = 10 # hold time for high SNR
signalCooldown = 5 # the following are combined to reset the monitor
signalCycleLimit = 5For Ollama to work, the command line ollama run 'model' needs to work properly. Ensure you have enough RAM and your GPU is working as expected. The default model for this project is set to gemma2:2b. Ollama can be remote Ollama Server
# Enable ollama LLM see more at https://ollama.com
ollama = True # Ollama model to use (defaults to gemma2:2b)
ollamaModel = gemma2 #ollamaModel = llama3.1
ollamaHostName = http://localhost:11434 # server instance to use (defaults to local machine install)Also see llm.py for changing the defaults of:
# LLM System Variables
llmEnableHistory = True # enable history for the LLM model to use in responses adds to compute time
llmContext_fromGoogle = True # enable context from google search results helps with responses accuracy
googleSearchResults = 3 # number of google search results to include in the context more results = more compute timeThe Scheduler is enabled in the settings.py by setting scheduler_enabled = True. The actions and settings are via code only at this time. See mesh_bot.py around line 425 to edit the schedule. See schedule documentation for more.
#Send WX every Morning at 08:00 using handle_wxc function to channel 2 on device 1
schedule.every().day.at("08:00").do(lambda: send_message(handle_wxc(0, 1, 'wx'), 2, 0, 1))
#Send a Net Starting Now Message Every Wednesday at 19:00 using send_message function to channel 2 on device 1
schedule.every().wednesday.at("19:00").do(lambda: send_message("Net Starting Now", 2, 0, 1))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. 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 methods have been mentioned as allowing MQTT routing for the project.
Python 3.8? or later is needed (dev on latest). The following can be installed with pip install -r requirements.txt or using the install.sh script for venv and automation:
pip install meshtastic
pip install pubsubMesh-bot enhancements:
pip install pyephem
pip install requests
pip install geopy
pip install maidenhead
pip install beautifulsoup4
pip install dadjokes
pip install geopy
pip install schedule
pip install wikipediaFor open-meteo use:
pip install openmeteo_requests
pip install retry_requests
pip install numpyFor the Ollama LLM:
pip install ollama
pip install langchain
pip install langchain-ollama
pip install googlesearch-pythonTo enable emoji in the Debian console, install the fonts:
sudo apt-get install fonts-noto-color-emoji| Command | Description | ✅ Works Off-Grid |
|---|---|---|
ping, ack, test |
Return data for signal. Example: ping 15 #DrivingI5 (activates auto-ping every 20 seconds for count 15) |
✅ |
whereami |
Returns the address of the sender's location if known | |
whoami |
Returns details of the node asking, also returned when position exchanged 📍 | ✅ |
motd |
Displays the message of the day or sets it. Example: motd $New Message Of the day |
✅ |
lheard |
Returns the last 5 heard nodes with SNR. Can also use sitrep |
✅ |
history |
Returns the last commands run by user(s) | ✅ |
cmd |
Returns the list of commands (the help message) | ✅ |
| Command | Description | |
|---|---|---|
sun and moon |
Return info on rise and set local time | ✅ |
solar |
Gives an idea of the x-ray flux | |
hfcond |
Returns a table of HF solar conditions | |
tide |
Returns the local tides (NOAA data source) | |
rlist |
Returns a table of nearby repeaters from RepeaterBook | |
wx and wxc |
Return local weather forecast (wxc is metric value), NOAA or Open Meteo for weather forecasting | |
wxa and wxalert |
Return NOAA alerts. Short title or expanded details |
| Command | Description | |
|---|---|---|
bbshelp |
Returns the following help message | ✅ |
bbslist |
Lists the messages by ID and subject | ✅ |
bbsread |
Reads a message. Example: bbsread #1 |
✅ |
bbspost |
Posts a message to the public board or sends a DM(Mail) Examples: bbspost $subject #message, bbspost @nodeNumber #message, bbspost @nodeShortName #message |
✅ |
bbsdelete |
Deletes a message. Example: bbsdelete #4 |
✅ |
bbsinfo |
Provides stats on BBS delivery and messages (sysop) | ✅ |
| Command | Description | |
|---|---|---|
wiki: |
Searches Wikipedia and returns the first few sentences of the first result if a match. Example: wiki: lora radio |
|
askai and ask: |
Ask Ollama LLM AI for a response. Example: askai what temp do I cook chicken |
✅ |
messages |
Replays the last messages heard, like Store and Forward | ✅ |
| Command | Description | |
|---|---|---|
joke |
Tells a joke | ✅ |
lemonstand |
Plays the classic Lemonade Stand finance game | ✅ |
dopewars |
Plays the classic drug trader game | ✅ |
blackjack |
Plays Blackjack (Casino 21) | ✅ |
videopoker |
Plays basic 5-card hold Video Poker | ✅ |
mastermind |
Plays the classic code-breaking game | ✅ |
golfsim |
Plays a 9-hole Golf Simulator | ✅ |
uno |
Plays Uno card game against the bot or with others on the mesh near you! | ✅ |
I used ideas and snippets from other responder bots and want to call them out!
- xdep: For the reporting tools.
- Nestpebble: For new ideas and enhancements.
- mrpatrick1991: For Docker configurations.
- PiDiBi: For looking at test functions and other suggestions like wxc, CPU use, and alerting ideas.
- Cisien, bitflip, and Hailo1999: For testing and feature ideas on Discord and GitHub.
- Meshtastic Discord Community: For tossing out ideas and testing code.
- Node Backup Management: Node Slurper