search

SpudGunMan / meshing-around

BBS Mesh Scripts for Meshtastic
GNU General Public License v3.0
52 stars 10 forks source link

readme

Mesh Bot for Network Testing and BBS Activities

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.

Example Use

Key Features

Intelligent Keyword Responder

Dual Radio/Node Support

Advanced Messaging Capabilities

Interactive AI and Data Lookup

Proximity Alerts

Fun and Games

Radio Frequency Monitoring

Data Reporting

Robust Message Handling

Getting Started

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.

Installation

Clone the Repository

git clone https://github.com/spudgunman/meshing-around

The code is under active development, so make sure to pull the latest changes regularly!

Optional Automation of setup

Docker Installation

If you prefer to use Docker, follow these steps:

  1. Ensure your serial port is properly shared and the GPU is configured if using LLM with NVIDIA.
  2. Build the Docker image: 
    cd meshing-around
docker build -t meshing-around .
  3. Run the Docker container: 
    docker run --rm -it --device=/dev/ttyUSB0 meshing-around

Custom Install

Install the required dependencies using pip:

pip install -r requirements.txt

Copy the configuration template to config.ini and edit it to suit your needs:

cp config.template config.ini

Configuration

Copy 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-scan

Note: 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 = False

General Settings

The 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 = 0

Location Settings

The 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 = True

Module Settings

Modules can be enabled or disabled as needed.

[bbs]
enabled = False

[general]
DadJokes = False
StoreForward = False

History

The 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,4258675309

Sentry Settings

Sentry 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,4258675309

Repeater Settings

A 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]

Radio Monitoring

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 = 5

Ollama (LLM/AI) Settings

For 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 time

Scheduler

The 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))

MQTT Notes

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.

Requirements

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 pubsub

Mesh-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 wikipedia

For open-meteo use:

pip install openmeteo_requests
pip install retry_requests
pip install numpy

For the Ollama LLM:

pip install ollama
pip install langchain
pip install langchain-ollama
pip install googlesearch-python

To enable emoji in the Debian console, install the fonts:

sudo apt-get install fonts-noto-color-emoji

Full list of commands for the bot

Networking

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) ✅

Radio Propagation & Weather Forcasting

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

Bulletin Board & Mail

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) ✅

Data Lookup

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 ✅

Games (via DM)

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 ✅

Recognition

I used ideas and snippets from other responder bots and want to call them out!

Inspiration and Code Snippets

Games Ported From

Special Thanks

Tools