diff --git a/README.md b/README.md index e8dbb1f..080323a 100644 --- a/README.md +++ b/README.md @@ -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 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 ` - Add new keyword -- `remove-keyword ` - Remove keyword -- `ban ` - Ban a user -- `unban ` - Unban a user -- `banned` - List banned users -- `send ` - Send message to channel -- `schedule` - List scheduled messages -- `add-schedule