@alteriom/painlessmesh 1.8.15 → 1.9.1

package/docs/SIMULATOR_TESTING.md

@@ -1,408 +0,0 @@
-# Simulator-Based Testing for painlessMesh
-
-## Overview
-
-painlessMesh includes integration with the [painlessMesh-simulator](https://github.com/Alteriom/painlessMesh-simulator) to enable large-scale testing of examples and firmware without physical hardware.
-
-The simulator allows you to:
-- 🚀 Test with 100+ virtual nodes simultaneously
-- 🔧 Validate actual firmware code in a controlled environment
-- 📋 Configure test scenarios with YAML files
-- 🌐 Simulate realistic network conditions (latency, packet loss, partitions)
-- 📊 Collect metrics and analyze performance
-- 🔄 Integrate with CI/CD pipelines
-
-## Architecture
-
-```
-painlessMesh Repository
-├── src/                          # Library code
-├── examples/                     # Example sketches
-│   ├── basic/
-│   │   ├── basic.ino            # Original Arduino sketch
-│   │   └── test/simulator/      # Simulator tests
-│   │       ├── firmware/        # Firmware adapter
-│   │       ├── scenarios/       # YAML test scenarios
-│   │       └── CMakeLists.txt   # Build configuration
-│   └── [other examples]/
-└── test/
-    └── simulator/               # painlessMesh-simulator (submodule)
-```
-
-## Quick Start
-
-### 1. Initialize Simulator Submodule
-
-```bash
-cd test
-git submodule update --init simulator
-```
-
-### 2. Install Dependencies
-
-**Ubuntu/Debian:**
-```bash
-sudo apt-get install cmake ninja-build libboost-dev libboost-program-options-dev libyaml-cpp-dev
-```
-
-**macOS:**
-```bash
-brew install cmake ninja boost yaml-cpp
-```
-
-**Windows:**
-See [test/simulator/BUILD_WINDOWS_STATUS.md](../test/simulator/BUILD_WINDOWS_STATUS.md)
-
-### 3. Run a Test
-
-```bash
-cd test/simulator
-mkdir build && cd build
-cmake -G Ninja ..
-ninja
-
-# Run basic example test
-bin/painlessmesh-simulator --config ../../../examples/basic/test/simulator/scenarios/basic_mesh_test.yaml
-```
-
-## Example Test Structure
-
-### Basic Example
-
-The `examples/basic/` example includes complete simulator tests:
-
-**Files:**
-- `test/simulator/firmware/basic_firmware.hpp` - Firmware adapter
-- `test/simulator/scenarios/basic_mesh_test.yaml` - Test configuration
-- `test/simulator/README.md` - Detailed instructions
-
-**Test Scenario (basic_mesh_test.yaml):**
-```yaml
-simulation:
-  name: "Basic Example Test"
-  duration: 60
-
-nodes:
-  - template: "basic_example"
-    count: 10
-    config:
-      mesh_prefix: "whateverYouLike"
-      mesh_password: "somethingSneaky"
-
-validation:
-  - check: "all_nodes_connected"
-    timeout: 30
-  - check: "messages_delivered"
-    min_messages_per_node: 5
-```
-
-**Run it:**
-```bash
-cd examples/basic/test/simulator
-mkdir build && cd build
-cmake -G Ninja .. && ninja
-bin/painlessmesh-simulator --config ../scenarios/basic_mesh_test.yaml
-```
-
-## Creating Tests for Your Example
-
-### Step 1: Create Directory Structure
-
-```bash
-cd examples/your_example
-mkdir -p test/simulator/firmware test/simulator/scenarios
-```
-
-### Step 2: Create Firmware Adapter
-
-Create `test/simulator/firmware/your_firmware.hpp`:
-
-```cpp
-#pragma once
-#include "simulator/firmware/firmware_base.hpp"
-#include <painlessMesh.h>
-
-class YourFirmware : public FirmwareBase {
-public:
-    void setup(painlessMesh* mesh, Scheduler* userScheduler) override {
-        mesh_ = mesh;
-        
-        // Copy your setup() logic from the .ino file
-        mesh_->init("YourPrefix", "password", userScheduler, 5555);
-        mesh_->onReceive([this](uint32_t from, String& msg) {
-            // Your receive callback
-        });
-        
-        // Add your tasks, etc.
-    }
-
-    void loop() override {
-        // Copy your loop() logic
-        if (mesh_) mesh_->update();
-    }
-
-    const char* getName() const override {
-        return "YourExample";
-    }
-
-private:
-    painlessMesh* mesh_;
-};
-```
-
-### Step 3: Create Test Scenario
-
-Create `test/simulator/scenarios/your_test.yaml`:
-
-```yaml
-simulation:
-  name: "Your Example Test"
-  duration: 60
-
-nodes:
-  - template: "your_firmware"
-    count: 10
-
-validation:
-  - check: "all_nodes_connected"
-    timeout: 30
-```
-
-### Step 4: Create CMakeLists.txt
-
-Copy from `examples/basic/test/simulator/CMakeLists.txt` and adapt paths.
-
-### Step 5: Run Test
-
-```bash
-cd test/simulator/build
-bin/painlessmesh-simulator --config ../../../examples/your_example/test/simulator/scenarios/your_test.yaml
-```
-
-## Test Scenarios
-
-### Available Validations
-
-```yaml
-validation:
-  # Mesh formation
-  - check: "all_nodes_connected"
-    timeout: 30
-  
-  # Message delivery
-  - check: "messages_delivered"
-    min_messages_per_node: 5
-    timeout: 60
-  
-  # Time synchronization
-  - check: "time_synchronized"
-    max_time_diff_ms: 10000
-    timeout: 45
-  
-  # Custom metrics
-  - check: "custom_metric"
-    metric_name: "your_metric"
-    min_value: 100
-```
-
-### Network Conditions
-
-```yaml
-network:
-  latency:
-    min_ms: 10
-    max_ms: 100
-  bandwidth_kbps: 256
-  packet_loss_percent: 5
-
-events:
-  # Network partition
-  - type: "network_partition"
-    time: 30
-    duration: 15
-    groups: [[0,1,2], [3,4,5]]
-  
-  # Node failures
-  - type: "node_crash"
-    time: 45
-    nodes: [2, 5]
-  
-  # Node recovery
-  - type: "node_restart"
-    time: 50
-    nodes: [2, 5]
-```
-
-### Topology Options
-
-```yaml
-topology:
-  type: "random"      # Random connections
-  # OR
-  type: "ring"        # Ring topology
-  # OR
-  type: "star"        # Star topology
-  # OR
-  type: "mesh"        # Full mesh
-  # OR
-  type: "tree"        # Tree topology
-  
-  connectivity: 0.7   # For random: 70% connectivity
-```
-
-## Metrics and Analysis
-
-### Collected Metrics
-
-The simulator automatically collects:
-- Messages sent/received per node
-- Topology changes
-- Connection count
-- Time synchronization drift
-- Custom application metrics
-
-### Output Format
-
-Results are saved as CSV:
-
-```csv
-timestamp,node_id,messages_sent,messages_received,connections,time_drift_ms
-0,6481,0,0,0,150000
-1,6481,1,0,2,145000
-2,6481,1,3,2,140000
-...
-```
-
-### Analysis
-
-```python
-import pandas as pd
-
-df = pd.read_csv('results/test_results.csv')
-
-# Messages per node
-print(df.groupby('node_id')['messages_received'].sum())
-
-# Average connections
-print(df.groupby('timestamp')['connections'].mean())
-
-# Time sync performance
-print(df.groupby('timestamp')['time_drift_ms'].max())
-```
-
-## CI/CD Integration
-
-### GitHub Actions Integration
-
-Simulator tests are integrated into the CI/CD pipeline in `.github/workflows/ci.yml`:
-
-**The `simulator-tests` job:**
-- Runs on every push and pull request
-- Builds the simulator from the submodule
-- Executes example test scenarios
-- Uploads results as artifacts
-
-**Configuration:**
-```yaml
-simulator-tests:
-  name: Simulator Integration Tests
-  runs-on: ubuntu-latest
-  steps:
-    - uses: actions/checkout@v4
-      with:
-        submodules: recursive
-    
-    - name: Install dependencies
-      run: |
-        sudo apt-get install cmake ninja-build libboost-dev libboost-program-options-dev libyaml-cpp-dev
-    
-    - name: Build simulator
-      run: |
-        cd test/simulator
-        mkdir build && cd build
-        cmake -G Ninja .. && ninja
-    
-    - name: Run tests
-      run: |
-        cd test/simulator/build
-        bin/painlessmesh-simulator --config \
-          ../../../examples/basic/test/simulator/scenarios/basic_mesh_test.yaml
-```
-
-This ensures example sketches are validated on every code change.
-
-## Examples with Simulator Tests
-
-### Currently Available
-
-- ✅ `examples/basic/` - Basic mesh formation and broadcasting
-
-### Coming Soon
-
-- ⏳ `examples/startHere/` - Getting started example
-- ⏳ `examples/echoNode/` - Echo server/client
-- ⏳ `examples/bridge/` - Internet bridge functionality
-- ⏳ `examples/mqttBridge/` - MQTT integration
-
-## Documentation
-
-- **Simulator Repository**: https://github.com/Alteriom/painlessMesh-simulator
-- **Getting Started**: [test/simulator/GETTING_STARTED.md](../test/simulator/GETTING_STARTED.md)
-- **Integration Guide**: [test/simulator/docs/INTEGRATING_INTO_YOUR_PROJECT.md](../test/simulator/docs/INTEGRATING_INTO_YOUR_PROJECT.md)
-- **Configuration Reference**: [test/simulator/docs/CONFIGURATION_GUIDE.md](../test/simulator/docs/CONFIGURATION_GUIDE.md)
-
-## Troubleshooting
-
-### Submodule not initialized
-
-```bash
-cd test
-git submodule update --init simulator
-```
-
-### Build errors
-
-```bash
-# Check dependencies
-sudo apt-get install cmake ninja-build libboost-dev libyaml-cpp-dev
-
-# Clean rebuild
-cd test/simulator
-rm -rf build
-mkdir build && cd build
-cmake -G Ninja ..
-ninja
-```
-
-### Simulation timeouts
-
-Increase timeout in YAML:
-```yaml
-simulation:
-  duration: 120  # Increase from 60
-```
-
-### Memory issues with large meshes
-
-Reduce node count or increase system resources.
-
-## Benefits
-
-✅ **Fast iteration** - Test in seconds vs hours of hardware testing
-✅ **Reproducible** - Same scenario always produces same results  
-✅ **Scalable** - Test with 100+ nodes on a laptop
-✅ **Automated** - Integrate with CI/CD
-✅ **Cost-effective** - No hardware required
-✅ **Realistic** - Same code runs on hardware and simulator
-
-## Contributing
-
-To add simulator tests for more examples:
-
-1. Create test structure in `examples/your_example/test/simulator/`
-2. Adapt the .ino logic into a firmware adapter
-3. Create test scenarios with validation criteria
-4. Document in README.md
-5. Submit pull request
-
-See existing examples for patterns to follow.

package/docs/VERSION_MANAGEMENT.md

@@ -1,213 +0,0 @@
-# Version Management in AlteriomPainlessMesh
-
-This document explains how versioning works in the AlteriomPainlessMesh library and clarifies common questions about version numbers in different files.
-
-## 📋 Version Number Locations
-
-The library version is maintained in multiple files across the repository:
-
-### 1. **Official Version Files** (Source of Truth)
-
-These files define the official library version:
-
-- **`library.properties`** - Arduino Library Manager version
-- **`library.json`** - PlatformIO Library Registry version  
-- **`package.json`** - NPM package version
-
-**All three files must always have the same version number.**
-
-### 2. **Header File Version Comments** (Documentation)
-
-These are **documentation comments** that indicate when the header file documentation was last updated:
-
-- **`src/painlessMesh.h`** - `@version` in header comment
-- **`src/AlteriomPainlessMesh.h`** - `ALTERIOM_PAINLESS_MESH_VERSION` defines
-
-**Important:** Version numbers in header file comments reflect the overall library version at the time the header was documented, not file-specific versioning.
-
-## ❓ Common Questions
-
-### Q: Does the version in `painlessMesh.h` mean the file hasn't changed since that version?
-
-**A: No.** The version comment in header files indicates the library version when the header documentation was last reviewed/updated, not the last time the file was modified.
-
-**Example:**
-```cpp
-/**
- * @file painlessMesh.h
- * @version 1.8.7
- * @date 2025-11-12
- */
-```
-
-This means:
-- ✅ The library version is 1.8.7
-- ✅ The header documentation is current as of version 1.8.7
-- ❌ It does NOT mean the file hasn't been modified since 1.8.7
-
-### Q: Why might header version comments be out of sync?
-
-**A:** During rapid development, header file documentation may not be updated every release. The comments are updated when:
-- Significant API changes are made
-- Documentation requires updating
-- Major version milestones are reached
-- Version consistency review is performed
-
-### Q: Which version number should I trust?
-
-**A:** Always refer to the official version files:
-1. `library.properties` - Official Arduino version
-2. `library.json` - Official PlatformIO version
-3. `package.json` - Official NPM version
-4. GitHub releases - Tagged release versions
-
-Header file comments are for documentation reference only.
-
-## 🔄 Version Update Process
-
-### When Releasing a New Version:
-
-1. **Update Official Version Files** (required)
-   ```bash
-   ./scripts/bump-version.sh patch  # or minor, major
-   ```
-   This updates: `library.properties`, `library.json`, `package.json`
-
-2. **Update CHANGELOG.md** (required)
-   - Move items from `[Unreleased]` to new version section
-   - Add release date
-
-3. **Update Header File Comments** (recommended)
-   - Update `@version` in `src/painlessMesh.h`
-   - Update version defines in `src/AlteriomPainlessMesh.h`
-
-4. **Commit and Tag** (required)
-   ```bash
-   git commit -m "release: vX.Y.Z - Brief description"
-   git push origin main
-   ```
-   GitHub Actions will automatically create the tag.
-
-## 📝 Version Comment Best Practices
-
-### In Header Files:
-
-**Good Practice:**
-```cpp
-/**
- * @file painlessMesh.h
- * @brief Main header file for Alteriom painlessMesh library
- * 
- * @version 1.8.7
- * @date 2025-11-12
- * 
- * painlessMesh is a user-friendly library for creating mesh networks...
- */
-```
-
-**What This Means:**
-- The library is at version 1.8.7
-- Header documentation was reviewed/updated on 2025-11-12
-- Always synchronized with library version during releases
-
-### In Implementation Files:
-
-Implementation files (`.cpp`, `.hpp`) typically do not need version comments. Version information in these files can be misleading and is unnecessary since:
-- Git history tracks all changes with timestamps
-- Version is centrally managed in the official version files
-- Per-file versioning creates maintenance overhead
-
-## 🎯 Version Management Workflow
-
-### Developer Workflow:
-
-1. **Check Current Version**
-   ```bash
-   grep "version=" library.properties
-   ```
-
-2. **Make Changes**
-   - Implement features/fixes
-   - Update documentation as needed
-   - Add entries to CHANGELOG.md under `[Unreleased]`
-
-3. **Prepare Release**
-   ```bash
-   ./scripts/release-agent.sh  # Validate release readiness
-   ./scripts/bump-version.sh patch  # Update version
-   ```
-
-4. **Update Documentation**
-   - Review and update header file version comments
-   - Ensure CHANGELOG.md has the new version section
-   - Verify all documentation references are current
-
-5. **Release**
-   ```bash
-   git add library.properties library.json package.json CHANGELOG.md src/*.h
-   git commit -m "release: v1.8.7 - Brief description"
-   git push origin main
-   ```
-
-### Automated Process:
-
-GitHub Actions automatically handles:
-- ✅ Git tag creation
-- ✅ GitHub release with notes
-- ✅ NPM publishing
-- ✅ PlatformIO registry update
-- ✅ Documentation deployment
-
-## 🔍 Version History Tracking
-
-### To Check File History:
-
-Use Git to see actual file modification history:
-
-```bash
-# See all commits that modified a file
-git log --oneline -- src/painlessMesh.h
-
-# See detailed changes to a file
-git log -p -- src/painlessMesh.h
-
-# See when a file was last modified
-git log -1 --format="%ai %an" -- src/painlessMesh.h
-```
-
-### To Check Version History:
-
-```bash
-# List all version tags
-git tag -l "v*"
-
-# See changes in a specific version
-git show v1.8.7
-
-# Compare two versions
-git diff v1.8.6..v1.8.7
-```
-
-## 📚 Related Documentation
-
-- **[CHANGELOG.md](../CHANGELOG.md)** - Complete version history with changes
-- **[RELEASE_GUIDE.md](../RELEASE_GUIDE.md)** - Detailed release process
-- **[GitHub Releases](https://github.com/Alteriom/painlessMesh/releases)** - Official release notes
-
-## 🎓 Summary
-
-**Key Takeaways:**
-
-1. **Official version** = `library.properties` / `library.json` / `package.json`
-2. **Header comments** = Documentation reference, not file-specific versions
-3. **Git history** = Actual source of truth for file modifications
-4. **CHANGELOG.md** = Human-readable version history
-5. **GitHub releases** = Tagged versions with release notes
-
-**When in doubt:** Check `library.properties` for the official library version, and use `git log` to see actual file modification history.
-
----
-
-**Version Management Process Owner:** @Alteriom  
-**Last Updated:** 2025-11-12  
-**Document Version:** 1.0