From a60b35f567acf3e905046ff7ca62e2a1cde99b96 Mon Sep 17 00:00:00 2001 From: agessaman Date: Sat, 25 Apr 2026 19:21:23 -0700 Subject: [PATCH] docs: update README and command reference with new features and services - Removed caution section from README to streamline information. - Added new services to README: Earthquake Service, Repeater Prefix Collision Service, and MQTT Weather Relay. - Expanded command reference documentation with new commands: `version`, `status`, `aurora`, `magic8`, `catfact`, `reload`, `channelpause`, `channelresume`, `greeter`, `announcements`, and `schedule`. - Updated getting started guide to reflect changes in Python version requirement and installation instructions. - Enhanced service plugins documentation to include new services and clarify existing ones. --- README.md | 4 +- docs/command-reference.md | 148 +++++++++++++++++++++++++++++++++++++- docs/configuration.md | 2 +- docs/getting-started.md | 10 +-- docs/index.md | 5 +- docs/service-plugins.md | 3 + 6 files changed, 162 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ca4c861..d19a8f7 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ A Python bot that connects to MeshCore mesh networks via serial port, BLE, or TCP/IP. The bot responds to messages containing configured keywords, executes commands, and provides various data services including weather, solar conditions, and satellite pass information. A web viewer provides a browser-based dashboard for monitoring and managing the bot. -## Caution > [!CAUTION] > Before installing this bot, please take a moment to _truly_ consider if your mesh needs another bot. If there are already several bots on your mesh, it is likely that you are adding congestion without adding value. @@ -37,6 +36,9 @@ A Python bot that connects to MeshCore mesh networks via serial port, BLE, or TC - **Packet Capture**: Capture and publish packets to MQTT brokers ([docs](docs/packet-capture.md)) - **Map Uploader**: Upload node adverts to map.meshcore.dev ([docs](docs/map-uploader.md)) - **Weather Service**: Scheduled forecasts, alerts, and lightning detection ([docs](docs/weather-service.md)) +- **Earthquake Service**: Scheduled USGS earthquake alerts for a configured region ([docs](docs/earthquake-service.md)) +- **Repeater Prefix Collision Service**: Detect and alert on repeater prefix collisions ([docs](docs/repeater-prefix-collision-service.md)) +- **MQTT Weather Relay**: Publish weather data from custom MQTT topics (configured via `MqttWeather` + `[Weather]`) - **Webhook Service**: Accept inbound HTTP POST payloads and relay to channels or DMs ## Requirements diff --git a/docs/command-reference.md b/docs/command-reference.md index 07b79b8..b29b602 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -97,6 +97,32 @@ cmd --- +### `version` + +Show the bot's current software version. + +**Usage:** +``` +version +``` + +**Response:** Version string for the running MeshCore bot build. + +--- + +### `status` + +Show current bot and radio status details. + +**Usage:** +``` +status +``` + +**Response:** Runtime status summary (connection/health information). + +--- + ## Information Commands ### `channels` @@ -302,6 +328,20 @@ sun --- +### `aurora` + +Get aurora visibility/forecast conditions for configured or provided coordinates. + +**Usage:** +``` +aurora +aurora , +``` + +**Response:** Aurora activity and visibility guidance for the requested location. + +--- + ### `moon` Get moon phase information and moonrise/moonset times for the bot's configured location. @@ -498,6 +538,25 @@ roll 1000 --- +### `magic8` + +Ask the Magic 8-Ball a yes/no question. + +**Usage:** +``` +magic8 +``` + +**Examples:** +``` +magic8 will the mesh be busy tonight? +magic8 should I deploy another node? +``` + +**Response:** A randomized Magic 8-Ball style answer. + +--- + ## Entertainment Commands ### `joke` @@ -557,6 +616,19 @@ ls -l /secret/base --- +### `catfact` + +Get a random cat fact. + +**Usage:** +``` +catfact +``` + +**Response:** A short random cat fact. + +--- + ## Sports Commands ### `sports` @@ -683,8 +755,6 @@ mt **Response:** List of all unique routing paths discovered during the 6-second listening period. ---- - ## Command Syntax ### Prefix @@ -847,6 +917,50 @@ advert --- +### `reload` + +Reload supported runtime configuration without restarting the bot. + +**Usage:** +``` +reload +``` + +**Response:** Confirms reload success or reports validation/loading errors. + +**Note:** Admin DM command. Connection/radio settings still require a process restart. + +--- + +### `channelpause` / `channelresume` + +Temporarily pause or resume bot reactions on public channels. + +**Usage:** +``` +channelpause +channelresume +``` + +**Response:** Confirms whether channel handling is paused or resumed. + +**Note:** Admin DM command. DMs continue to work while channel responses are paused. + +--- + +### `greeter` + +Show greeter behavior and configuration guidance. + +**Usage:** +``` +greeter +``` + +**Response:** Describes greeter mode and points to `[Greeter_Command]` settings in config. + +--- + ### `feed` Manage RSS feed and API feed subscriptions (Admin only). @@ -882,5 +996,35 @@ feed test https://example.com/feed.xml --- +### `announcements` + +Manage announcement ACL and related announcement settings. + +**Usage:** +``` +announcements [args] +``` + +**Response:** Shows current announcement ACL or confirms changes. + +**Note:** Admin access required. + +--- + +### `schedule` + +View configured scheduled messages and advert interval. + +**Usage:** +``` +schedule +``` + +**Response:** Lists upcoming scheduled posts and current advert timing. + +**Note:** DM-only command by default. + +--- + For more information about configuring the bot, see the main [README](https://github.com/agessaman/meshcore-bot/blob/main/README.md) file. diff --git a/docs/configuration.md b/docs/configuration.md index d1d8cd8..6d69c62 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -132,7 +132,7 @@ The Path command has many options (presets, proximity, graph validation, etc.). ## Service plugin configuration -Service plugins (Discord Bridge, Packet Capture, Map Uploader, Weather Service) each have their own section and are documented under [Service Plugins](service-plugins.md). +Service plugins (Discord Bridge, Telegram Bridge, Packet Capture, Map Uploader, Weather Service, Earthquake Service, Repeater Prefix Collision Service, and Webhook Service) each have their own section and are documented under [Service Plugins](service-plugins.md). The MQTT weather relay uses the `MqttWeather` section plus custom topic keys under `[Weather]`. ## Config validation diff --git a/docs/getting-started.md b/docs/getting-started.md index 0850f0e..02355be 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,7 +4,7 @@ Get meshcore-bot running on your machine in a few minutes. ## Requirements -- **Python 3.7+** +- **Python 3.10+** - **MeshCore-compatible device** (Heltec V3, RAK Wireless, etc.) - **Connection**: USB cable, BLE, or TCP/IP to the device @@ -15,7 +15,7 @@ Get meshcore-bot running on your machine in a few minutes. ```bash git clone https://github.com/agessaman/meshcore-bot.git cd meshcore-bot - pip install -r requirements.txt + make dev ``` 2. **Configure** @@ -36,7 +36,7 @@ Get meshcore-bot running on your machine in a few minutes. 3. **Run** ```bash - python3 meshcore_bot.py + .venv/bin/python meshcore_bot.py ``` ## Inspect effective config safely @@ -44,8 +44,8 @@ Get meshcore-bot running on your machine in a few minutes. Use these commands to inspect the resolved config with sensitive keys redacted: ```bash -python3 meshcore_bot.py --show-config --config config.ini -python3 meshcore_bot.py --show-config-json --config config.ini +.venv/bin/python meshcore_bot.py --show-config --config config.ini +.venv/bin/python meshcore_bot.py --show-config-json --config config.ini ``` Also available in the web UI at `/admin/config`. diff --git a/docs/index.md b/docs/index.md index d652a6b..9e7bfa6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,7 +25,7 @@ Documentation for the MeshCore bot: setup, configuration, commands, and services | Document | Description | |----------|-------------| | [Repeater Commands](repeater-commands.md) | Repeater management DM commands | -| [Feed Management](feeds.md) | RSS/REST feeds and posting to channels | +| [Feed Management](FEEDS.md) | RSS/REST feeds and posting to channels | | [Web Viewer](web-viewer.md) | Web-based data viewer and API | ## Service Plugins @@ -34,6 +34,9 @@ Documentation for the MeshCore bot: setup, configuration, commands, and services |----------|-------------| | [Service Plugins overview](service-plugins.md) | Enable and configure background services | | [Discord Bridge](discord-bridge.md) | One-way bridge to Discord | +| [Telegram Bridge](telegram-bridge.md) | One-way bridge to Telegram | +| [Earthquake Service](earthquake-service.md) | Scheduled earthquake alerts from USGS | | [Packet Capture](packet-capture.md) | Packet capture and MQTT | | [Map Uploader](map-uploader.md) | Uploading to map.meshcore.dev | | [Weather Service](weather-service.md) | Scheduled weather and alerts | +| [Repeater Prefix Collision Service](repeater-prefix-collision-service.md) | Detect repeater prefix collisions | diff --git a/docs/service-plugins.md b/docs/service-plugins.md index e329fc2..5d26d86 100644 --- a/docs/service-plugins.md +++ b/docs/service-plugins.md @@ -5,9 +5,12 @@ Service plugins extend the bot with background services that run alongside the m | Plugin | Description | |--------|-------------| | [Discord Bridge](discord-bridge.md) | One-way webhook bridge to post mesh messages to Discord channels | +| [Telegram Bridge](telegram-bridge.md) | One-way bridge to post mesh messages to Telegram chats/channels | | [Packet Capture](packet-capture.md) | Capture packets from the mesh and publish them to MQTT brokers | | [Map Uploader](map-uploader.md) | Upload node advertisements to [map.meshcore.dev](https://map.meshcore.dev) for network visualization | | [Weather Service](weather-service.md) | Scheduled weather forecasts, weather alerts, and lightning detection | +| MQTT Weather Relay (`MqttWeather`) | Relay weather data to custom MQTT topics configured under `[Weather]` | +| Webhook Service (`Webhook`) | Accept inbound HTTP POST payloads and relay to mesh channels or DMs | | [Earthquake Service](earthquake-service.md) | Earthquake alerts for a configured region (USGS API, defaults: California) | | [Repeater Prefix Collision Service](repeater-prefix-collision-service.md) | Alerts when a newly heard repeater prefix collides with an existing repeater prefix |