A Python bot that connects to MeshCore mesh networks via serial port or BLE. The bot responds to messages containing configured keywords, executes commands, and provides various data services including weather, solar conditions, and satellite pass information.
- Connection Methods: Serial port or BLE (Bluetooth Low Energy)
- Keyword Responses: Configurable keyword-response pairs with template variables
- Command System: Plugin-based command architecture with built-in commands
- Rate Limiting: Configurable rate limiting to prevent network spam
- User Management: Ban/unban users with persistent storage
- Scheduled Messages: Send messages at configured times
- Direct Message Support: Respond to private messages
- Logging: Console and file logging with configurable levels
- Python 3.7+
- MeshCore-compatible device (Heltec V3, RAK Wireless, etc.)
- USB cable or BLE capability
- Clone the repository:
git clone <repository-url>
cd meshcore-bot- Install dependencies:
pip install -r requirements.txt- Copy and configure the bot:
cp config.ini.example config.ini
# Edit config.ini with your settings- Run the bot:
python3 meshcore_bot.pyFor production deployment as a system service:
- Install as systemd service:
sudo ./install-service.sh- Configure the bot:
sudo nano /opt/meshcore-bot/config.ini- Start the service:
sudo systemctl start meshcore-bot- Check status:
sudo systemctl status meshcore-botSee SERVICE-INSTALLATION.md for detailed service installation instructions.
The bot uses config.ini for all settings. Key configuration sections:
[Connection]
connection_type = serial # serial or ble
serial_port = /dev/ttyUSB0 # Serial port path
timeout = 30 # Connection timeout[Bot]
bot_name = MeshCoreBot # Bot identification name
enabled = true # Enable/disable bot
rate_limit_seconds = 2 # Rate limiting interval
startup_advert = flood # Send advert on startup[Keywords]
# Format: keyword = response_template
# Variables: {sender}, {connection_info}, {snr}, {timestamp}, {path}
test = "Message received from {sender} | {connection_info}"
help = "Bot Help: test, ping, help, hello, cmd, wx, aqi, sun, moon, solar, hfcond, satpass"[Channels]
monitor_channels = general,test,emergency # Channels to monitor
respond_to_dms = true # Enable DM responses[External_Data]
# API keys for external services
n2yo_api_key = # Satellite pass data
airnow_api_key = # Air quality data[Logging]
log_level = INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
log_file = meshcore_bot.log # Log file path
colored_output = true # Enable colored console outputpython meshcore_bot.pyThe bot responds to these commands:
test- Test message responseping- Ping/pong responsehelp- Show available commandshello- Greeting responsecmd- List available commandswx <location>- Weather informationaqi <location>- Air quality indexsun- Sunrise/sunset timesmoon- Moon phase and timessolar- Solar conditionshfcond- HF band conditionssatpass <NORAD>- Satellite pass informationadvert- Send network advert
Keyword responses support these template variables:
{sender}- Sender's node ID{connection_info}- Connection details (direct/routed){snr}- Signal-to-noise ratio{timestamp}- Message timestamp{path}- Message routing path
Example:
[Keywords]
test = "Message received from {sender} | {connection_info}"
ping = "Pong!"
help = "Bot Help: test, ping, help, hello, cmd, wx, aqi, sun, moon, solar, hfcond, satpass"- Flash MeshCore firmware to your device
- Connect via USB
- Configure serial port in
config.ini:[Connection] connection_type = serial serial_port = /dev/ttyUSB0 # Linux # serial_port = COM3 # Windows # serial_port = /dev/tty.usbserial-* # macOS
- Ensure your MeshCore device supports BLE
- Configure BLE in
config.ini:[Connection] connection_type = ble ble_device_name = MeshCore
-
Serial Port Not Found:
- Check device connection
- Verify port name in config
- List available ports:
python -c "import serial.tools.list_ports; print([p.device for p in serial.tools.list_ports.comports()])"
-
BLE Connection Issues:
- Ensure device is discoverable
- Check device name in config
- Verify BLE permissions
-
Message Parsing Errors:
- Enable DEBUG logging for detailed information
- Check meshcore library documentation for protocol details
-
Rate Limiting:
- Adjust
rate_limit_secondsin config - Check logs for rate limiting messages
- Adjust
Enable debug logging:
[Logging]
log_level = DEBUGThe bot uses a modular plugin architecture:
- Core modules (
modules/): Shared utilities and core functionality - Command plugins (
modules/commands/): Individual command implementations - Plugin loader: Dynamic discovery and loading of command plugins
- Message handler: Processes incoming messages and routes to appropriate handlers
- Create a new command file in
modules/commands/ - Inherit from
BaseCommand - Implement the
execute()method - The plugin loader will automatically discover and load the command
Example:
from .base_command import BaseCommand
from ..models import MeshMessage
class MyCommand(BaseCommand):
name = "mycommand"
keywords = ['mycommand']
description = "My custom command"
async def execute(self, message: MeshMessage) -> bool:
await self.send_response(message, "Hello from my command!")
return True- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
This project is licensed under the MIT License.
- MeshCore Project for the mesh networking protocol
- Some commands adapted from MeshingAround bot by K7MHI Kelly Keeton 2024