dandri/meshcore-bot
1
0
Fork 0
mirror of https://github.com/agessaman/meshcore-bot.git synced 2026-06-01 05:14:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md to be factual and concise

Browse Source 
- Remove promotional language and focus on technical details
- Update configuration examples to match actual config.ini structure
- Add accurate list of available commands
- Include proper template variables for keyword responses
- Add architecture section explaining plugin system
- Simplify installation and usage instructions
- Remove outdated protocol examples and focus on current functionality
- Add proper attribution to MeshLink bot by K7MHI Kelly Keeton
This commit is contained in:
agessaman
2025-09-06 11:46:00 -07:00
parent de92fdfdd2
commit f47bf87549
1 changed files with 93 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+93 -162
View File
@@ -1,18 +1,18 @@
# MeshCore Bot Framework
# MeshCore Bot
A Python framework for creating bots that connect to MeshCore networks via serial port or BLE. This bot can respond to messages containing specific keywords, manage user bans, send scheduled messages, and support future integrations with external data sources like weather and tide APIs.
A Python bot that connects to MeshCore mesh networks via serial port or Bluetooth Low Energy. The bot responds to messages containing configured keywords, executes commands, and provides various data services including weather, solar conditions, and satellite pass information.
## Features
- **Multi-Protocol Support**: Connect via serial port or Bluetooth Low Energy (BLE)
- **Keyword Response System**: Configurable keyword-response pairs with template variables
- **Rate Limiting**: Configurable rate limiting to prevent spam
- **User Management**: Ban/unban users with persistent configuration
- **Scheduled Messages**: Send messages at specific times
- **DM Support**: Respond to direct messages
- **Comprehensive Logging**: Colored console output and file logging
- **CLI Interface**: Interactive and command-line management tools
- **Extensible Architecture**: Easy to add new features and integrations
- **Connection Methods**: Serial port or Bluetooth Low Energy (BLE)
- **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
- **CLI Management**: Command-line interface for bot management
## Requirements
@@ -22,7 +22,7 @@ A Python framework for creating bots that connect to MeshCore networks via seria
## Installation
1. Clone or download this repository:
1. Clone the repository:
```bash
git clone <repository-url>
cd meshcore-bot
@@ -33,19 +33,21 @@ cd meshcore-bot
pip install -r requirements.txt
```
3. Configure the bot by editing `config.ini` (a default config will be created if it doesn't exist)
3. Copy and configure the bot:
```bash
cp config.ini.example config.ini
# Edit config.ini with your settings
```
## Configuration
The bot uses a `config.ini` file for all settings. Here's an overview of the configuration sections:
The bot uses `config.ini` for all settings. Key configuration sections:
### Connection Settings
### Connection
```ini
[Connection]
connection_type = serial # serial or ble
serial_port = /dev/ttyUSB0 # Serial port path
serial_baudrate = 115200 # Baud rate
ble_device_name = MeshCore # BLE device name
timeout = 30 # Connection timeout
```
@@ -53,49 +55,40 @@ timeout = 30 # Connection timeout
```ini
[Bot]
bot_name = MeshCoreBot # Bot identification name
node_id = # Leave empty for auto-assignment
enabled = true # Enable/disable bot
passive_mode = false # Only listen, don't respond
rate_limit_seconds = 10 # Rate limiting interval
rate_limit_seconds = 2 # Rate limiting interval
startup_advert = flood # Send advert on startup
```
### Keywords and Responses
### Keywords
```ini
[Keywords]
# Format: keyword = response_template
# Available variables: {hops}, {path}, {sender}, {channel}, {content}, {timestamp}
test = "Message received! Hops: {hops}, Path: {path}, From: {sender}"
weather = "Weather info: {content}"
help = "Available commands: test, weather, help"
# 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"
```
### Channel Management
### Channels
```ini
[Channels]
monitor_channels = general,test,emergency # Channels to monitor
respond_to_dms = true # Enable DM responses
```
### User Management
### External Data APIs
```ini
[Banned_Users]
banned_users = user1,user2 # Comma-separated list
```
### Scheduled Messages
```ini
[Scheduled_Messages]
# Format: time = channel:message
08:00 = general:Good morning! Weather update coming soon.
12:00 = general:Lunch time reminder
18:00 = general:Evening update
[External_Data]
# API keys for external services
n2yo_api_key = # Satellite pass data
airnow_api_key = # Air quality data
```
### Logging
```ini
[Logging]
log_level = INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
log_file = meshcore_bot.log # Log file path (empty for console only)
log_file = meshcore_bot.log # Log file path
colored_output = true # Enable colored console output
```
@@ -103,114 +96,66 @@ colored_output = true # Enable colored console output
### Running the Bot
1. **Basic Usage**:
```bash
python meshcore_bot.py
```
2. **With custom config**:
```bash
python meshcore_bot.py --config my_config.ini
```
### CLI Management
The bot includes a comprehensive CLI for management:
The bot includes a CLI for management:
1. **Interactive Mode**:
```bash
# Interactive mode
python bot_cli.py --interactive
```
2. **Command Line Mode**:
```bash
# Show bot status
# Command line mode
python bot_cli.py status
# Add a keyword
python bot_cli.py keywords add "hello" "Hello there! How can I help?"
# Ban a user
python bot_cli.py users ban "spam_user"
# Send a message
python bot_cli.py send general "Hello everyone!"
# Add scheduled message
python bot_cli.py schedule add "09:00" general "Good morning!"
```
### Interactive CLI Commands
### Available Commands
When running in interactive mode, you can use these commands:
The bot responds to these commands:
- `status` - Show bot status and configuration
- `keywords` - List all keyword-response pairs
- `add-keyword <keyword> <response>` - Add new keyword
- `remove-keyword <keyword>` - Remove keyword
- `ban <user_id>` - Ban a user
- `unban <user_id>` - Unban a user
- `banned` - List banned users
- `send <channel> <message>` - Send message to channel
- `schedule` - List scheduled messages
- `add-schedule <time> <channel> <message>` - Add scheduled message
- `remove-schedule <time>` - Remove scheduled message
- `help` - Show help
- `quit` or `exit` - Exit CLI
- `test` - Test message response
- `ping` - Ping/pong response
- `help` - Show available commands
- `hello` - Greeting response
- `cmd` - List available commands
- `wx <location>` - Weather information
- `aqi <location>` - Air quality index
- `sun` - Sunrise/sunset times
- `moon` - Moon phase and times
- `solar` - Solar conditions
- `hfcond` - HF band conditions
- `satpass <NORAD>` - Satellite pass information
- `advert` - Send network advert
## Message Response Templates
When configuring keyword responses, you can use these template variables:
Keyword responses support these template variables:
- `{hops}` - Number of hops the message traveled
- `{path}` - Two-character path identifiers
- `{sender}` - Sender's node ID
- `{channel}` - Channel name
- `{content}` - Original message content
- `{connection_info}` - Connection details (direct/routed)
- `{snr}` - Signal-to-noise ratio
- `{timestamp}` - Message timestamp
- `{path}` - Message routing path
Example:
```ini
[Keywords]
test = "Message received! Hops: {hops}, Path: {path}, From: {sender}"
weather = "Weather for {sender}: {content}"
echo = "You said: {content}"
```
## Protocol Adaptation
The bot includes a flexible protocol adapter that can handle multiple message formats:
1. **JSON Format** (preferred):
```json
{
"type": "text",
"sender": "node1",
"channel": "general",
"content": "Hello world",
"hops": 2,
"path": "AB",
"timestamp": "2024-01-01T12:00:00Z"
}
```
2. **Pipe-Separated Format**:
```
MSG|node1|general|Hello world|2|AB|msg_001|2024-01-01T12:00:00Z
```
3. **Space-Separated Format**:
```
MSG node1 general Hello world 2 AB
test = "Message received from {sender} | {connection_info}"
ping = "Pong!"
help = "Bot Help: test, ping, help, hello, cmd, wx, aqi, sun, moon, solar, hfcond, satpass"
```
## Hardware Setup
### Heltec V3 Setup
### Serial Connection
1. Flash MeshCore firmware to your Heltec V3 device using the [MeshCore Flasher](https://flasher.meshcore.co.uk)
2. Connect the device via USB
3. Update the `config.ini` with the correct serial port:
1. Flash MeshCore firmware to your device
2. Connect via USB
3. Configure serial port in `config.ini`:
```ini
[Connection]
connection_type = serial
@@ -219,10 +164,10 @@ MSG node1 general Hello world 2 AB
# serial_port = /dev/tty.usbserial-* # macOS
```
### BLE Setup
### BLE Connection
1. Ensure your MeshCore device supports BLE
2. Update the `config.ini`:
2. Configure BLE in `config.ini`:
```ini
[Connection]
connection_type = ble
@@ -236,16 +181,15 @@ MSG node1 general Hello world 2 AB
1. **Serial Port Not Found**:
- Check device connection
- Verify port name in config
- Try listing available ports: `python -c "import serial.tools.list_ports; print([p.device for p in serial.tools.list_ports.comports()])"`
- List available ports: `python -c "import serial.tools.list_ports; print([p.device for p in serial.tools.list_ports.comports()])"`
2. **BLE Connection Issues**:
- Ensure device is discoverable
- Check device name in config
- Verify BLE permissions on your system
- Verify BLE permissions
3. **Message Parsing Errors**:
- Check the protocol format in `meshcore_protocol.py`
- Verify message format from your MeshCore device
- Check protocol format in `meshcore_protocol.py`
- Enable DEBUG logging for detailed information
4. **Rate Limiting**:
@@ -254,47 +198,41 @@ MSG node1 general Hello world 2 AB
### Debug Mode
Enable debug logging for detailed information:
Enable debug logging:
```ini
[Logging]
log_level = DEBUG
```
## Extending the Bot
## Architecture
### Adding External Data Sources
The bot uses a modular plugin architecture:
The bot is designed to be easily extended. To add weather or tide data:
- **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
1. Create a new module (e.g., `weather_integration.py`)
2. Implement data fetching functions
3. Add configuration options to `config.ini`
4. Integrate with the main bot class
### Adding New Commands
Example weather integration:
1. Create a new command file in `modules/commands/`
2. Inherit from `BaseCommand`
3. Implement the `execute()` method
4. The plugin loader will automatically discover and load the command
Example:
```python
class WeatherIntegration:
def __init__(self, api_key: str):
self.api_key = api_key
from .base_command import BaseCommand
from ..models import MeshMessage
class MyCommand(BaseCommand):
name = "mycommand"
keywords = ['mycommand']
description = "My custom command"
async def get_weather(self, location: str) -> str:
# Implement weather API call
return f"Weather for {location}: Sunny, 22°C"
```
### Custom Message Handlers
You can extend the message processing by adding custom handlers:
```python
class CustomMessageHandler:
def __init__(self, bot):
self.bot = bot
async def handle_message(self, message: MeshMessage):
# Custom message processing logic
if "custom_command" in message.content:
await self.bot.send_message(message.channel, "Custom response!")
async def execute(self, message: MeshMessage) -> bool:
await self.send_response(message, "Hello from my command!")
return True
```
## Contributing
@@ -302,20 +240,13 @@ class CustomMessageHandler:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
4. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.
This project is licensed under the MIT License.
## Acknowledgments
- [MeshCore Project](https://github.com/meshcore-dev/MeshCore) for the mesh networking protocol
- The MeshCore community for documentation and examples
## Support
- Check the [MeshCore documentation](https://github.com/meshcore-dev/MeshCore)
- Join the MeshCore Discord for community support
- Open an issue on this repository for bug reports or feature requests
- Adapted from MeshLink bot by K7MHI Kelly Keeton 2024