From 46bad241520d014fb2512926fa0facf7f6c63728 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 8 Oct 2025 16:48:04 +0000
Subject: [PATCH] Add documentation for custom trigger words and leaderboard
 features

Co-authored-by: SpudGunMan <12676665+SpudGunMan@users.noreply.github.com>
---
 FEATURE_CUSTOM_WORDS_STATS.md | 129 ++++++++++++++++++++++++++++++++++
 README.md                     |  49 +++++++++++++
 2 files changed, 178 insertions(+)
 create mode 100644 FEATURE_CUSTOM_WORDS_STATS.md

diff --git a/FEATURE_CUSTOM_WORDS_STATS.md b/FEATURE_CUSTOM_WORDS_STATS.md
new file mode 100644
index 0000000..924d198
--- /dev/null
+++ b/FEATURE_CUSTOM_WORDS_STATS.md
@@ -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
diff --git a/README.md b/README.md
index 1cc4861..0a67bf1 100644
--- a/README.md
+++ b/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.