mirror of
https://github.com/SpudGunMan/meshing-around.git
synced 2026-03-28 17:32:36 +01:00
Add documentation for custom trigger words and leaderboard features
Co-authored-by: SpudGunMan <12676665+SpudGunMan@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
129
FEATURE_CUSTOM_WORDS_STATS.md
Normal file
129
FEATURE_CUSTOM_WORDS_STATS.md
Normal file
@@ -0,0 +1,129 @@
|
||||
# Custom Trigger Words and User Statistics Features
|
||||
|
||||
## Overview
|
||||
This implementation adds two major features to meshing-around:
|
||||
|
||||
### 1. Custom Trigger Words (Localization Support)
|
||||
Allows mesh operators to configure custom trigger words in any language that behave like the built-in "ping" and "test" commands.
|
||||
|
||||
### 2. User Statistics and Leaderboards
|
||||
Automatically tracks user activity and provides competitive leaderboards to encourage mesh participation.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Custom Trigger Words
|
||||
Add to your `config.ini` under `[general]`:
|
||||
|
||||
```ini
|
||||
# Custom trigger words for ping-like responses
|
||||
customPingWords = hola,привет,bonjour,ciao
|
||||
|
||||
# Custom trigger words for test-like responses
|
||||
customTestWords = prueba,テスト,testen,测试
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
- Words are case-insensitive
|
||||
- Multiple words can be added (comma-separated)
|
||||
- Each word triggers the same response as "ping" or "test"
|
||||
- Works in both mesh_bot.py and pong_bot.py
|
||||
|
||||
### User Statistics Tracking
|
||||
Enable/disable in your `config.ini` under `[general]`:
|
||||
|
||||
```ini
|
||||
enableStatsTracking = True
|
||||
```
|
||||
|
||||
**What is tracked:**
|
||||
- Message count per user
|
||||
- Command usage per user
|
||||
- Battery levels (from telemetry)
|
||||
- Uptime (from telemetry)
|
||||
- Last seen timestamp
|
||||
- First seen timestamp
|
||||
|
||||
**Data storage:**
|
||||
Statistics are persisted in `data/user_stats.json` and automatically saved during the cleanup cycle.
|
||||
|
||||
## Using the Leaderboard
|
||||
|
||||
### Basic Commands
|
||||
- `top` or `leaderboard` - Show top 10 message senders
|
||||
- `top messages` - Top message senders (explicit)
|
||||
- `top commands` - Top command users
|
||||
- `top battery` - Lowest battery levels (who needs a charge)
|
||||
- `top online` - Most recently active users
|
||||
|
||||
### Limiting Results
|
||||
Add a number to limit results:
|
||||
- `top 5` - Show only top 5
|
||||
- `top messages 3` - Show top 3 message senders
|
||||
|
||||
### Help
|
||||
- `top?` - Show help for the top command
|
||||
|
||||
## Example Usage
|
||||
|
||||
### Custom Trigger Words
|
||||
```
|
||||
User: hola
|
||||
Bot: 🏓PONG
|
||||
SNR:8.5 RSSI:-95
|
||||
|
||||
User: prueba 3
|
||||
Bot: 🎙Testing 1,2,3
|
||||
SNR:7.0 RSSI:-98
|
||||
```
|
||||
|
||||
### Leaderboards
|
||||
```
|
||||
User: top messages
|
||||
Bot: 🏆 Most Messages:
|
||||
1. KC7MHI: 142
|
||||
2. KB7YEG: 98
|
||||
3. KF7XYZ: 76
|
||||
4. N7ABC: 52
|
||||
5. W7DEF: 41
|
||||
|
||||
User: top battery 3
|
||||
Bot: 🏆 Lowest Battery (3):
|
||||
1. KC7MHI: 15%
|
||||
2. N7ABC: 28%
|
||||
3. KB7YEG: 45%
|
||||
|
||||
User: top online
|
||||
Bot: 🏆 Most Recently Active:
|
||||
1. KC7MHI: 2m ago
|
||||
2. W7DEF: 15m ago
|
||||
3. KB7YEG: 1h ago
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Files Modified
|
||||
- `config.template` - Added new config options
|
||||
- `modules/settings.py` - Read config values
|
||||
- `modules/system.py` - Added custom words to trap_list, integrated stats saving
|
||||
- `modules/stats.py` - New module for statistics tracking
|
||||
- `mesh_bot.py` - Added custom word support, top command handler, stats tracking
|
||||
- `pong_bot.py` - Added custom word support
|
||||
- `data/trigger_words.json` - Example localization file (currently unused, for future expansion)
|
||||
|
||||
### Architecture
|
||||
1. **Trigger Detection**: Custom words are added to `trap_list` during initialization
|
||||
2. **Command Handling**: Custom words are dynamically added to command_handler dictionaries
|
||||
3. **Response Logic**: `handle_ping()` checks for custom words in addition to built-in ones
|
||||
4. **Stats Tracking**:
|
||||
- Messages tracked in TEXT_MESSAGE_APP handler
|
||||
- Commands tracked in auto_response
|
||||
- Telemetry tracked in consumeMetadata
|
||||
- Periodic save via cleanup_memory
|
||||
|
||||
## Future Enhancements
|
||||
- Time-based leaderboards (daily, weekly, monthly)
|
||||
- Team/group statistics
|
||||
- Achievement system
|
||||
- Export leaderboards to HTML report
|
||||
- Load trigger words from JSON file
|
||||
- Per-node custom responses
|
||||
49
README.md
49
README.md
@@ -10,9 +10,20 @@ Welcome to the Mesh Bot project! This feature-rich bot is designed to enhance yo
|
||||
### Intelligent Keyword Responder
|
||||
- **Automated Responses**: The bot detects keywords like "ping" and responds with "pong" in direct messages (DMs) or group channels.
|
||||
- **Customizable Triggers**: Monitor group channels for specific keywords and set custom responses.
|
||||
- **Localization Support**: Add custom trigger words in any language via `customPingWords` and `customTestWords` config options for international mesh networks.
|
||||
- **Emergency Response**: Monitor channels for keywords indicating emergencies and alert a wider audience.
|
||||
- **New Node Hello**: Greet new nodes on the mesh with a hello message
|
||||
|
||||
### User Statistics and Leaderboards
|
||||
- **Activity Tracking**: Automatically tracks user statistics including message count, command usage, battery levels, and uptime.
|
||||
- **Leaderboard Commands**: Use `top` or `leaderboard` to view rankings:
|
||||
- `top` or `top messages` - Most active message senders
|
||||
- `top commands` - Most command users
|
||||
- `top battery` - Lowest battery levels (most depleted)
|
||||
- `top online` - Most recently active users
|
||||
- `top 5` - Show top 5 instead of default 10
|
||||
- **Competitive Engagement**: Encourage mesh network participation through friendly competition.
|
||||
|
||||
### Network Tools
|
||||
- **Build, Test Local Mesh**: Ping allow for message delivery testing with more realistic packets vs. telemetry
|
||||
- **Test Node Hardware**: `test` will send incremental sized data into the radio buffer for overall length of message testing
|
||||
@@ -105,6 +116,7 @@ git clone https://github.com/spudgunman/meshing-around
|
||||
| `motd` | Displays the message of the day or sets it. Example: `motd $New Message Of the day` | ✅ |
|
||||
| `sysinfo` | Returns the bot node telemetry info | ✅ |
|
||||
| `test` | used to test the limits of data transfer `test 4` sends data to the maxBuffer limit (default 220) via DM only | ✅ |
|
||||
| `top` or `leaderboard` | Show user statistics leaderboard. Options: `top messages`, `top commands`, `top battery`, `top online`, `top 5` | ✅ |
|
||||
| `whereami` | Returns the address of the sender's location if known |
|
||||
| `whoami` | Returns details of the node asking, also returned when position exchanged 📍 | ✅ |
|
||||
| `whois` | Returns details known about node, more data with bbsadmin node | ✅ |
|
||||
@@ -239,8 +251,45 @@ ignoreDefaultChannel = False # ignoreDefaultChannel, the bot will ignore the def
|
||||
ignoreChannels = # ignoreChannels is a comma separated list of channels to ignore, e.g. 4,5
|
||||
cmdBang = False # require ! to be the first character in a command
|
||||
explicitCmd = True # require explicit command, the message will only be processed if it starts with a command word disable to get more activity
|
||||
|
||||
# Custom trigger words for localization support
|
||||
customPingWords = # comma-separated list of words that trigger ping response (e.g., hola,привет,bonjour)
|
||||
customTestWords = # comma-separated list of words that trigger test response (e.g., prueba,测试,testen)
|
||||
|
||||
# User statistics and leaderboard tracking
|
||||
enableStatsTracking = True # enable tracking of user activity for leaderboard features
|
||||
```
|
||||
|
||||
### Localization and Custom Trigger Words
|
||||
The bot supports custom trigger words in any language, allowing international mesh networks to use familiar commands. Add comma-separated words to the config:
|
||||
|
||||
```ini
|
||||
[general]
|
||||
# Example: Add Spanish and Russian ping equivalents
|
||||
customPingWords = hola,привет,bonjour
|
||||
# Example: Add Spanish and Chinese test equivalents
|
||||
customTestWords = prueba,测试,testen
|
||||
```
|
||||
|
||||
These custom words will behave exactly like "ping" and "test" commands, responding with the same messages and metrics.
|
||||
|
||||
### User Statistics and Leaderboards
|
||||
Enable activity tracking to create competitive engagement on your mesh network:
|
||||
|
||||
```ini
|
||||
[general]
|
||||
enableStatsTracking = True
|
||||
```
|
||||
|
||||
Use the `top` command to view various leaderboards:
|
||||
- `top` or `top messages` - See most active messagers
|
||||
- `top commands` - View most command users
|
||||
- `top battery` - Check who needs a charge (lowest battery)
|
||||
- `top online` - See most recently active users
|
||||
- `top 5` - Limit results to top 5 users
|
||||
|
||||
Statistics are automatically tracked for all users and persisted in `data/user_stats.json`.
|
||||
|
||||
### Location Settings
|
||||
The weather forecasting defaults to NOAA, for locations outside the USA, you can set `UseMeteoWxAPI` to `True`, to use a global weather API. The `lat` and `lon` are default values when a node has no location data, as well as the default for all NOAA, repeater lookup. It is also the center of radius for Sentry.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user