dandri/meshcore-bot
1
0
Fork 0
mirror of https://github.com/agessaman/meshcore-bot.git synced 2026-08-27 21:10:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README and command reference with new features and services

Browse Source 
- 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.
This commit is contained in:
agessaman
2026-04-25 19:21:23 -07:00
parent dbc07880ee
commit a60b35f567
6 changed files with 162 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -1
View File
@@ -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
docs/command-reference.md
+146 -2
View File
@@ -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 <lat>,<lon>
```
**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 <question>
```
**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 <subcommand> [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.
docs/configuration.md
+1 -1
View File
@@ -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
docs/getting-started.md
+5 -5
View File
@@ -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`.
docs/index.md
+4 -1
View File
@@ -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 |
docs/service-plugins.md
+3
View File
@@ -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 |