@alteriom/painlessmesh 1.8.14 → 1.9.0

package/BRIDGE_TO_INTERNET.md

@@ -0,0 +1,229 @@
+# Bridging painlessMesh to Internet via Router
+
+You can bridge your mesh network to the Internet by creating a **gateway node** that connects to both the mesh network and your WiFi router simultaneously.
+
+## Quick Start (Recommended: Auto Channel Detection)
+
+The **new bridge-centric approach** automatically detects your router's channel and configures the mesh accordingly. No manual channel configuration required!
+
+```cpp
+#include "painlessMesh.h"
+
+#define MESH_PREFIX     "MyMeshNetwork"
+#define MESH_PASSWORD   "somethingSneaky"
+#define MESH_PORT       5555
+
+// Your router credentials
+#define ROUTER_SSID     "YourRouterSSID"
+#define ROUTER_PASSWORD "YourRouterPassword"
+
+Scheduler userScheduler;
+painlessMesh mesh;
+
+void setup() {
+  Serial.begin(115200);
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  // Single call does everything:
+  // 1. Connects to router and detects its channel
+  // 2. Initializes mesh on detected channel
+  // 3. Sets node as root/bridge
+  // 4. Maintains router connection
+  mesh.initAsBridge(MESH_PREFIX, MESH_PASSWORD,
+                    ROUTER_SSID, ROUTER_PASSWORD,
+                    &userScheduler, MESH_PORT);
+  
+  mesh.onReceive(&receivedCallback);
+}
+
+void loop() {
+  mesh.update();
+}
+
+void receivedCallback(uint32_t from, String& msg) {
+  Serial.printf("Received from mesh node %u: %s\n", from, msg.c_str());
+  // Forward to Internet services (HTTP, MQTT, etc.)
+}
+```
+
+**Expected Output:**
+```
+=== Bridge Mode Initialization ===
+Step 1: Connecting to router YourRouterSSID...
+✓ Router connected on channel 6
+✓ Router IP: 192.168.1.100
+Step 2: Initializing mesh on channel 6...
+STARTUP: init(): Mesh channel set to 6
+Step 3: Establishing bridge connection...
+=== Bridge Mode Active ===
+  Mesh SSID: MyMeshNetwork
+  Mesh Channel: 6 (matches router)
+  Router: YourRouterSSID
+  Port: 5555
+```
+
+### Regular Nodes with Auto-Detection
+
+Regular mesh nodes can also auto-detect the mesh channel:
+
+```cpp
+void setup() {
+  Serial.begin(115200);
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  // channel=0 means auto-detect
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, 
+            WIFI_AP_STA, 0);
+  
+  mesh.onReceive(&receivedCallback);
+}
+```
+
+**Expected Output:**
+```
+STARTUP: Auto-detecting mesh channel...
+CONNECTION: Scanning all channels for mesh 'MyMeshNetwork'...
+CONNECTION: Found mesh on channel 6 (RSSI: -45)
+STARTUP: Mesh channel auto-detected: 6
+```
+
+### Automatic Channel Re-synchronization
+
+Nodes automatically follow the mesh if the bridge changes channels:
+
+- When nodes can't find the mesh on their current channel for ~30 seconds, they trigger a full channel scan
+- If the mesh is found on a different channel, nodes automatically switch to that channel
+- This ensures the mesh stays connected even if the bridge switches channels (e.g., during bridge election)
+
+For detailed information about channel synchronization, see [Channel Synchronization Documentation](docs/CHANNEL_SYNCHRONIZATION.md).
+
+## Manual Configuration (Legacy Approach)
+
+If you prefer the traditional approach or need more control, you can still manually configure the channel:
+
+```cpp
+void setup() {
+  Serial.begin(115200);
+  mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+  
+  // Initialize mesh with AP+STA mode on specific channel
+  mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT, WIFI_AP_STA, 6);
+  
+  // Connect to your router
+  mesh.stationManual(ROUTER_SSID, ROUTER_PASSWORD);
+  mesh.setHostname("MESH_BRIDGE");
+  
+  // Configure as root/bridge node
+  mesh.setRoot(true);
+  mesh.setContainsRoot(true);
+  
+  mesh.onReceive(&receivedCallback);
+}
+```
+
+## Important Requirements
+
+### WiFi Channel Behavior
+
+#### With initAsBridge() (Recommended)
+
+The new `initAsBridge()` method automatically handles all channel detection and configuration:
+
+1. Connects to your router first in STA mode
+2. Detects the router's actual channel
+3. Initializes the mesh AP on the detected channel
+4. Maintains both connections on the same channel
+
+**No manual channel configuration needed!** Just provide your router and mesh credentials.
+
+#### With Manual Configuration
+
+When using the legacy `stationManual()` approach, the library will automatically handle channel switching. The ESP32/ESP8266 will:
+
+1. Initially operate the mesh AP on your specified channel (e.g., channel 6)
+2. Automatically switch to the router's channel when connecting via `stationManual()`
+3. The mesh AP channel will adjust to match the router's channel
+
+**Note:** While ESP32/ESP8266 hardware can only operate on one channel at a time in AP+STA mode, the WiFi stack automatically coordinates this. When connected to a router on a different channel, the mesh AP will operate on that channel instead.
+
+**Best Practices:**
+
+- Use `initAsBridge()` for new projects - it handles everything automatically
+- Use channels 1, 6, or 11 (non-overlapping 2.4GHz channels) if not using a router
+- Regular nodes should use `channel=0` to auto-detect the mesh
+- For optimal performance, you may choose to configure your router to use your preferred mesh channel
+
+### Other Requirements
+
+1. **WIFI_AP_STA Mode**: This enables simultaneous AP (for mesh) and Station (for router) operation.
+
+2. **Root Configuration**:
+   - Call `mesh.setRoot(true)` on the bridge node
+   - Call `mesh.setContainsRoot(true)` on all mesh nodes for optimal routing
+
+3. **ESP32-C6 Compatibility**: If using ESP32-C6 or experiencing crashes with `tcp_alloc` errors, ensure you have AsyncTCP v3.3.0+ installed. See the [ESP32-C6 Compatibility Guide](docs/troubleshooting/ESP32_C6_COMPATIBILITY.md) for details.
+
+## Complete Examples
+
+We provide several working bridge examples in the repository:
+
+- **Basic Bridge**: `examples/bridge/bridge.ino`
+- **MQTT Bridge**: `examples/mqttBridge/mqttBridge.ino` - Bridges mesh to MQTT broker
+- **Web Server Bridge**: `examples/webServer/webServer.ino` - Provides web interface
+- **Enhanced MQTT Bridge**: `examples/bridge/enhanced_mqtt_bridge_example.ino` - Advanced MQTT integration with metrics and health monitoring
+
+## Forwarding Data to Internet
+
+Once the bridge is established, you can forward mesh data to Internet services:
+
+```cpp
+void receivedCallback(uint32_t from, String& msg) {
+  // Check if connected to router
+  if (WiFi.status() == WL_CONNECTED) {
+    // Forward to MQTT broker
+    mqttClient.publish("mesh/data", msg.c_str());
+    
+    // Or send via HTTP
+    HTTPClient http;
+    http.begin("http://myserver.com/api/data");
+    http.POST(msg);
+    http.end();
+  }
+}
+```
+
+## Architecture Diagram
+
+```text
+Internet
+   |
+Router (WiFi)
+   |
+Bridge Node (AP+STA mode)
+   |
+Mesh Network
+ / | \
+Node1 Node2 Node3...
+```
+
+## Frequently Asked Questions
+
+### Why does `mesh.init()` require a separate `mesh.stationManual()` call?
+
+Great question! The library now offers **three ways** to connect a bridge:
+
+1. **Original**: `init()` + `stationManual()` (most flexible)
+2. **Convenience**: Pass credentials directly to `init()` (new feature)
+3. **Modern**: Use `initAsBridge()` with auto-detection (recommended)
+
+See [Station Credentials Design Rationale](docs/design/STATION_CREDENTIALS_DESIGN.md) for detailed explanations and comparisons.
+
+## Additional Resources
+
+- [painlessMesh Wiki](https://github.com/Alteriom/painlessMesh/wiki)
+- [Bridge Examples](https://github.com/Alteriom/painlessMesh/tree/main/examples/bridge)
+- [MQTT Bridge Example](https://github.com/Alteriom/painlessMesh/tree/main/examples/mqttBridge)
+- [Configuration API Reference](https://github.com/Alteriom/painlessMesh/wiki)
+- [Station Credentials Design](docs/design/STATION_CREDENTIALS_DESIGN.md) - Why three approaches exist
+
+Feel free to ask if you need help with specific use cases like MQTT integration, web servers, or custom data forwarding!

package/CHANGELOG.md

@@ -5,7 +5,95 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.9.0] - 2025-11-30
+
+### Added
+
+- **Mesh Connectivity Detection** - New APIs to detect mesh connection state
+  - `hasActiveMeshConnections()` - Check if node has active mesh connections
+  - `getLastKnownBridge()` - Get last known bridge regardless of timeout
+  - Allows distinguishing between "bridge unavailable" vs "disconnected from mesh"
+
+- **Improved Bridge Detection** - Enhanced `getPrimaryBridge()` behavior
+  - When disconnected from mesh, returns last known bridge instead of nullptr
+  - Stale bridge info is better than no info for reconnection scenarios
+  - `hasInternetConnection()` now uses last known state when disconnected
+
+- **Election Guard** - Skip election trigger when node is disconnected from mesh
+  - Prevents unnecessary elections when issue is local connectivity
+  - More accurate diagnosis of bridge availability problems
+
+- **Configurable Bridge Election Timing** - New API methods to prevent split-brain scenarios
+  - `setElectionStartupDelay(delayMs)` - Configure startup delay before first election (default: 60s, min: 10s)
+  - `setElectionRandomDelay(minMs, maxMs)` - Configure random delay range for elections (default: 1-3s)
+  - Longer delays allow more time for mesh formation when nodes start simultaneously
+  - Prevents race condition where multiple nodes become bridges in isolation
+  - All timing parameters are user-configurable without hard-coded values
+  - **Impact**: Users can now tune election timing for their specific deployment scenarios
+
+### Fixed
+
+- **Bridge Discovery** - Fixed regular nodes unable to discover bridge nodes in bridge failover examples
+  - **Root Cause**: Regular nodes were using default channel=1 instead of channel=0 (auto-detect)
+  - Bridge nodes operate on router's WiFi channel (e.g., channel 6), not channel 1
+  - Nodes on fixed channel cannot discover bridges on different channels
+  - **Solution**: Updated examples to use `channel=0` for automatic mesh channel detection
+  - **Affected Examples**: 
+    - `bridge_failover/bridge_failover.ino` - Both regular node and fallback initialization
+    - `multi_bridge/regular_node.ino` - Regular node initialization
+    - `bridgeAwareSensorNode/bridgeAwareSensorNode.ino` - Sensor node initialization
+    - `ntpTimeSyncNode/ntpTimeSyncNode.ino` - Time sync node initialization
+  - **Documentation**: Added channel detection explanation to bridge_failover README
+  - **Impact**: Regular nodes now properly discover and connect to bridges regardless of router channel
+  - Users experiencing "No primary bridge available!" / "Known bridges: 0" should update to this version
+
+- **Split-Brain Prevention** - Addressed race condition when multiple nodes start simultaneously
+  - **Root Cause**: 60-63s window insufficient for mesh formation before elections start
+  - Both nodes detect "no bridge", run isolated elections, each wins and becomes bridge
+  - **Solution**: Added configurable timing parameters (see Added section above)
+  - **Documentation**: Added comprehensive troubleshooting section to bridge_failover README
+  - **Recommended Settings**: 90s startup delay + 10-30s random delay for simultaneous startups
+  - **Alternative**: Stagger node startup by 10-20 seconds or use pre-designated bridge mode
+
+### Changed
+
+- **Examples Consolidated** - Reduced from 32 to 14 essential examples
+  - Removed 18 redundant/developmental examples
+  - Kept: alteriom, basic, bridge, bridge_failover, logClient/Server, mqttBridge, namedMesh, otaReceiver/Sender, priority, sharedGateway, startHere, webServer
+  - Cleaner, more maintainable example set focusing on core functionality
+
+- **Documentation Consolidated** - Cleaned up repository documentation
+  - Removed obsolete release notes, issue resolution docs, and development artifacts
+  - Retained: README.md, CHANGELOG.md, CONTRIBUTING.md, RELEASE_GUIDE.md, BRIDGE_TO_INTERNET.md
+  - Cleaner root directory with only essential documentation
+
+## [1.8.15] - 2025-11-23
+
+### Added
+
+- **Simulator Integration** - Integrated painlessMesh-simulator for automated example validation
+  - Added painlessMesh-simulator as git submodule at `test/simulator/`
+  - Created YAML-based test scenarios for example validation
+  - Configured CI/CD to automatically run simulator tests on every push/PR
+  - Validates mesh formation, message broadcasting, and time synchronization with 5+ virtual nodes
+  - Provides framework for testing with 100+ nodes without hardware
+  - Resolves GitHub issue #163
+  - Merged via PR #164
+
+### Documentation
+
+- **Release Readiness Assessment** - Created comprehensive release readiness plan
+  - `RELEASE_READINESS_PLAN.md` - Complete audit of test infrastructure, performance issues, and security
+  - Confirmed library is production-ready with all 119+ test assertions passing
+  - Documented Issue #161 resolution (architectural clarification, not a bug)
+  - `TESTING_WITH_SIMULATOR.md` - Quick start guide for simulator
+  - `docs/SIMULATOR_TESTING.md` - Complete simulator integration guide with CI details
+
+### Fixed
+
+- **Build System** - Fixed references to removed test files in CMakeLists.txt
+- **CI/CD** - Added missing libboost-program-options-dev dependency for simulator build
+- **Documentation** - Updated all simulator paths and dependency lists
 
 ## [1.8.14] - 2025-11-21
 

package/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+We try to follow the [git flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) development model. Which means that we have a `develop` branch and `master` branch. All development is done under feature branches, which are (when finished) merged into the development branch. When a new version is released we merge the `develop` branch into the `master` branch.
+
+## Git flow
+
+If you would like to use [git flow tools](http://danielkummer.github.io/git-flow-cheatsheet/) you are more than welcome to. We use it and it's pretty nifty. If you see a `feature\` prefix on a comment then that is git flow automating branch creation. It does need more typing than just plain git so I suggest creating shell aliases for the commands.
+
+## Submit a pull request:
+
+* If your push triggered a 'you just pushed...' message from GitLab then click on the button provided by that pop up to create a pull request.
+* If not, then create a pull request and point it to your branch.
+* Make sure that you're attempting to merge into `develop` and not `master`.
+* Get your code reviewed by another contributor. If there are no contributors who possess the same set of skills then get them to review it anyway but explain what the code does beforehand and why. Use it as an opportunity for discussion around the feature set, to transfer knowledge, and to possibly [rubber duck](https://en.wikipedia.org/wiki/Rubber_duck_debugging) your code.
+* Once the code is reviewed then have your reviewer merge your code.
+
+NOTE: Tests *must* pass in order for the code to be merged.
+
+NOTE: Always do a `git pull` on `develop` before you start working to capture the latest changes.
+
+## Testing Requirements
+
+### Running Tests
+
+Before submitting a pull request, ensure all tests pass:
+
+```bash
+# Build and run unit/integration tests
+cmake -G Ninja .
+ninja
+run-parts --regex catch_ bin/
+
+# Run simulator tests (for examples)
+cd test/simulator
+mkdir build && cd build
+cmake -G Ninja .. && ninja
+bin/painlessmesh-simulator --config ../../../examples/basic/test/simulator/scenarios/basic_mesh_test.yaml
+```
+
+### Adding Tests for New Features
+
+When adding new features or examples:
+
+1. **Unit Tests**: Add tests in `test/catch/` for new components
+2. **Integration Tests**: Add to `test/boost/tcp_integration.cpp` for core functionality
+3. **Simulator Tests**: Create test scenarios in `examples/your_example/test/simulator/` for new examples
+4. **Documentation**: Update relevant test documentation
+
+### Example Validation with Simulator
+
+All example sketches should have simulator tests that validate behavior with multiple virtual nodes:
+
+1. Create firmware adapter in `examples/your_example/test/simulator/firmware/`
+2. Create YAML test scenarios in `examples/your_example/test/simulator/scenarios/`
+3. Document test setup in `examples/your_example/test/simulator/README.md`
+
+See [Simulator Testing Guide](docs/SIMULATOR_TESTING.md) for complete instructions.
+
+This ensures examples:
+- Work as documented with multiple nodes
+- Handle edge cases properly
+- Don't regress with library changes
+- Serve as validated references for users
+
+## Versioning
+
+This project will try its best to adhere to [semver](http://semver.org/) i.e, a codified guide to versioning software. When a new feature is developed or a bug is fixed the version will need to be bumped to signify the change. 
+
+The semver string is built like this:
+
+Major.Minor.Patch
+
+A major version bump means that a massive change took place and that application will probably have to be redeployed because a *backwards incompatible* version was released. Example: A library => model relationship change which requires previous configuration options to become invalid.
+
+A minor version is a *backwards compatible* addition or change to the core software. Most development activity will be this type of version bump. Example: A new feature or model.
+
+A patch version is a *backwards compatible* bug fix or application configuration change.
+
+Documentation doesn't require a version bump.