@alteriom/painlessmesh 1.7.8 → 1.8.0

package/docs/BRIDGE_HEALTH_MONITORING.md

@@ -0,0 +1,293 @@
+# Bridge Health Monitoring & Metrics Collection
+
+## Overview
+
+The Bridge Health Monitoring feature provides comprehensive operational visibility into bridge health, connectivity quality, and performance metrics. This is essential for production deployments, troubleshooting, and capacity planning.
+
+## Features
+
+✅ **Connectivity Metrics** - Track uptime, internet connectivity, and disconnection events  
+✅ **Signal Quality** - Monitor WiFi signal strength (RSSI) statistics  
+✅ **Traffic Metrics** - Measure bytes and messages transmitted/received  
+✅ **Performance Metrics** - Calculate latency and packet loss  
+✅ **JSON Export** - Easy integration with monitoring tools  
+✅ **Prometheus Support** - Export metrics for Prometheus scraping  
+✅ **Periodic Callbacks** - Automated metric collection and reporting  
+
+## API Reference
+
+### BridgeHealthMetrics Structure
+
+```cpp
+struct BridgeHealthMetrics {
+  // Connectivity
+  uint32_t uptimeSeconds;           // Total uptime in seconds
+  uint32_t internetUptimeSeconds;   // Time with Internet connection
+  uint32_t totalDisconnects;        // Number of disconnection events
+  uint32_t currentUptime;           // Current uptime in milliseconds
+  
+  // Signal Quality
+  int8_t currentRSSI;               // Current WiFi signal strength (dBm)
+  int8_t avgRSSI;                   // Average signal strength
+  int8_t minRSSI;                   // Minimum observed signal strength
+  int8_t maxRSSI;                   // Maximum observed signal strength
+  
+  // Traffic
+  uint64_t bytesRx;                 // Total bytes received
+  uint64_t bytesTx;                 // Total bytes transmitted
+  uint32_t messagesRx;              // Total messages received
+  uint32_t messagesTx;              // Total messages transmitted
+  uint32_t messagesQueued;          // Messages currently queued
+  uint32_t messagesDropped;         // Messages that failed to send
+  
+  // Performance
+  uint32_t avgLatencyMs;            // Average message latency
+  uint8_t packetLossPercent;        // Packet loss percentage (0-100)
+  uint32_t meshNodeCount;           // Number of nodes in mesh
+};
+```
+
+### Methods
+
+#### getBridgeHealthMetrics()
+
+Get current health metrics snapshot.
+
+```cpp
+BridgeHealthMetrics metrics = mesh.getBridgeHealthMetrics();
+
+Serial.printf("Uptime: %u s\n", metrics.uptimeSeconds);
+Serial.printf("Messages RX: %u\n", metrics.messagesRx);
+Serial.printf("Avg Latency: %u ms\n", metrics.avgLatencyMs);
+```
+
+#### resetHealthMetrics()
+
+Reset all counters to zero. Useful for periodic monitoring windows.
+
+```cpp
+mesh.resetHealthMetrics();
+```
+
+**Note:** This resets counters (messages, bytes, disconnects) but keeps current state metrics (RSSI, node count).
+
+#### getHealthMetricsJSON()
+
+Export metrics as JSON string for easy integration.
+
+```cpp
+String json = mesh.getHealthMetricsJSON();
+mqttClient.publish("bridge/metrics", json.c_str());
+```
+
+**JSON Format:**
+```json
+{
+  "connectivity": {
+    "uptimeSeconds": 3600,
+    "internetUptimeSeconds": 3540,
+    "totalDisconnects": 2,
+    "currentUptime": 3600000
+  },
+  "signalQuality": {
+    "currentRSSI": -65,
+    "avgRSSI": -68,
+    "minRSSI": -75,
+    "maxRSSI": -60
+  },
+  "traffic": {
+    "bytesRx": 1048576,
+    "bytesTx": 524288,
+    "messagesRx": 1234,
+    "messagesTx": 567,
+    "messagesQueued": 0,
+    "messagesDropped": 5
+  },
+  "performance": {
+    "avgLatencyMs": 45,
+    "packetLossPercent": 1,
+    "meshNodeCount": 8
+  }
+}
+```
+
+#### onHealthMetricsUpdate()
+
+Register a periodic callback for automated monitoring.
+
+```cpp
+mesh.onHealthMetricsUpdate([](BridgeHealthMetrics metrics) {
+  // Process metrics
+  Serial.printf("Nodes: %u, Latency: %u ms\n", 
+                metrics.meshNodeCount, metrics.avgLatencyMs);
+}, 60000);  // Every 60 seconds
+```
+
+## Integration Examples
+
+### MQTT Publishing
+
+```cpp
+#include <PubSubClient.h>
+
+WiFiClient espClient;
+PubSubClient mqttClient(espClient);
+
+void metricsCallback(BridgeHealthMetrics metrics) {
+  if (mqttClient.connected()) {
+    String json = mesh.getHealthMetricsJSON();
+    mqttClient.publish("bridge/metrics", json.c_str());
+  }
+}
+
+void setup() {
+  // ... mesh setup ...
+  mesh.onHealthMetricsUpdate(metricsCallback, 60000);
+}
+```
+
+### Prometheus Exporter
+
+```cpp
+#include <ESPAsyncWebServer.h>
+
+AsyncWebServer server(80);
+
+String exportPrometheus() {
+  auto metrics = mesh.getBridgeHealthMetrics();
+  
+  String output = "";
+  output += "# HELP bridge_uptime_seconds Bridge uptime\n";
+  output += "# TYPE bridge_uptime_seconds counter\n";
+  output += "bridge_uptime_seconds " + String(metrics.uptimeSeconds) + "\n";
+  
+  output += "# HELP bridge_rssi_dbm WiFi signal strength\n";
+  output += "# TYPE bridge_rssi_dbm gauge\n";
+  output += "bridge_rssi_dbm " + String(metrics.currentRSSI) + "\n";
+  
+  // Add more metrics...
+  
+  return output;
+}
+
+void setup() {
+  // ... mesh setup ...
+  
+  server.on("/metrics", HTTP_GET, [](AsyncWebServerRequest *request){
+    request->send(200, "text/plain", exportPrometheus());
+  });
+  
+  server.begin();
+}
+```
+
+### Grafana Dashboard
+
+Use the Prometheus exporter above with Grafana to create monitoring dashboards:
+
+1. Configure Prometheus to scrape your bridge node: `http://bridge-ip/metrics`
+2. Import metrics into Grafana
+3. Create panels for:
+   - Uptime and availability
+   - Signal strength trends
+   - Traffic throughput
+   - Latency and packet loss
+   - Mesh topology changes
+
+### Cloud Logging (AWS CloudWatch, Azure Monitor, etc.)
+
+```cpp
+void metricsCallback(BridgeHealthMetrics metrics) {
+  String json = mesh.getHealthMetricsJSON();
+  
+  // Send to CloudWatch
+  httpClient.post("/cloudwatch", json);
+  
+  // Send to Azure Monitor
+  httpClient.post("/azure-monitor", json);
+}
+```
+
+## Use Cases
+
+### Production Monitoring
+
+Monitor bridge health in production deployments:
+- Track uptime and availability
+- Detect connectivity issues early
+- Analyze signal quality trends
+- Capacity planning based on traffic patterns
+
+### Troubleshooting
+
+Debug network issues:
+- Identify sources of packet loss
+- Locate signal strength problems
+- Diagnose latency spikes
+- Track disconnection patterns
+
+### Performance Optimization
+
+Optimize mesh performance:
+- Analyze traffic patterns
+- Identify bottlenecks
+- Optimize node placement based on RSSI
+- Fine-tune routing strategies
+
+## Best Practices
+
+### Monitoring Intervals
+
+- **Development:** 10-30 seconds for rapid feedback
+- **Production:** 60-300 seconds to reduce overhead
+- **Critical Systems:** 30-60 seconds with alerting
+
+### Metric Storage
+
+- Use time-series databases (InfluxDB, Prometheus)
+- Retain raw metrics for 7-30 days
+- Aggregate to hourly/daily for long-term storage
+- Set up automated retention policies
+
+### Alerting
+
+Set up alerts for:
+- Packet loss > 5%
+- Latency > 200ms
+- Signal strength < -80 dBm
+- Frequent disconnections (> 3/hour)
+- Node count drops
+
+### Resource Management
+
+On ESP8266 (limited RAM):
+- Use longer intervals (120-300 seconds)
+- Minimize callback complexity
+- Consider offloading processing to gateway
+
+On ESP32 (more RAM):
+- Can use shorter intervals (30-60 seconds)
+- More sophisticated processing possible
+- Support multiple monitoring integrations
+
+## Example: Complete Monitoring Setup
+
+See `examples/bridge/bridge_health_monitoring_example.ino` for a complete working example with:
+- Periodic metrics logging
+- MQTT integration
+- Prometheus export endpoint
+- Manual metrics queries
+
+## Version History
+
+- **v1.8.0** - Initial release
+  - Basic metrics collection
+  - JSON export
+  - Periodic callbacks
+  - MQTT and Prometheus examples
+
+## See Also
+
+- [Bridge Architecture](BRIDGE_ARCHITECTURE_IMPLEMENTATION.md)
+- [Bridge Status Feature](BRIDGE_STATUS_FEATURE.md)
+- [MQTT Bridge Examples](../examples/bridge/)

package/docs/CREATE_MISSING_RELEASES.md

@@ -0,0 +1,321 @@
+# Creating Missing GitHub Releases for v1.7.8 and v1.7.9
+
+## Problem
+
+Versions 1.7.8 and 1.7.9 have:
+- ✅ CHANGELOG.md entries (complete release notes)
+- ✅ Release summary documentation (docs/releases/RELEASE_SUMMARY_v1.7.x.md)
+- ✅ Version numbers in library files (library.properties, library.json, package.json)
+- ❌ **Missing GitHub Releases** (no tags, no release pages)
+
+This means:
+- Users cannot download these specific versions from GitHub
+- Release automation may not have run properly
+- NPM/GitHub Packages may not have been published
+
+## Solution: Create GitHub Releases Retroactively
+
+### Option 1: Automated Script (Recommended)
+
+We've created a script to automate the process:
+
+```bash
+./scripts/create-missing-releases.sh
+```
+
+**What it does:**
+1. Extracts release notes from CHANGELOG.md
+2. Creates git tags (v1.7.8, v1.7.9)
+3. Pushes tags to GitHub
+4. Creates GitHub releases with proper release notes
+5. Provides links to verify releases
+
+**Requirements:**
+- GitHub CLI (`gh`) installed: https://cli.github.com/
+- Authenticated with GitHub: `gh auth login`
+- Write access to the repository
+
+**Running the script:**
+
+```bash
+# Navigate to repository root
+cd /path/to/painlessMesh
+
+# Run the script
+./scripts/create-missing-releases.sh
+
+# Follow the prompts
+# - Confirm you want to proceed
+# - If releases exist, choose whether to recreate them
+```
+
+### Option 2: Manual Process
+
+If you prefer to create releases manually or the script doesn't work:
+
+#### Step 1: Extract Release Notes
+
+```bash
+# Extract v1.7.8 notes
+awk '/^## \[1\.7\.8\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > release_notes_1.7.8.txt
+
+# Extract v1.7.9 notes  
+awk '/^## \[1\.7\.9\]/ {flag=1; next} /^## \[/ {flag=0} flag' CHANGELOG.md > release_notes_1.7.9.txt
+```
+
+#### Step 2: Create Tags and Releases via GitHub CLI
+
+**For v1.7.8:**
+```bash
+# Create and push tag
+git tag -a v1.7.8 -m "painlessMesh v1.7.8"
+git push origin v1.7.8
+
+# Create GitHub release
+gh release create v1.7.8 \
+  --repo Alteriom/painlessMesh \
+  --title "painlessMesh v1.7.8" \
+  --notes-file release_notes_1.7.8.txt
+```
+
+**For v1.7.9:**
+```bash
+# Create and push tag
+git tag -a v1.7.9 -m "painlessMesh v1.7.9"
+git push origin v1.7.9
+
+# Create GitHub release
+gh release create v1.7.9 \
+  --repo Alteriom/painlessMesh \
+  --title "painlessMesh v1.7.9" \
+  --notes-file release_notes_1.7.9.txt
+```
+
+#### Step 3: Create Releases via GitHub Web UI
+
+If you don't have GitHub CLI:
+
+1. **Go to**: https://github.com/Alteriom/painlessMesh/releases/new
+2. **For v1.7.8**:
+   - Tag: `v1.7.8`
+   - Release title: `painlessMesh v1.7.8`
+   - Description: Copy content from `CHANGELOG.md` section `[1.7.8]`
+   - Click "Publish release"
+3. **For v1.7.9**:
+   - Tag: `v1.7.9`
+   - Release title: `painlessMesh v1.7.9`
+   - Description: Copy content from `CHANGELOG.md` section `[1.7.9]`
+   - Click "Publish release"
+
+## Verification
+
+After creating the releases, verify:
+
+### 1. Check GitHub Releases Page
+```bash
+# View releases via CLI
+gh release list --repo Alteriom/painlessMesh
+
+# Or visit in browser
+# https://github.com/Alteriom/painlessMesh/releases
+```
+
+**Expected output:**
+```
+v1.7.9  painlessMesh v1.7.9  Latest  2025-11-08
+v1.7.8  painlessMesh v1.7.8          2025-11-05
+```
+
+### 2. Check Tags
+```bash
+git fetch --tags
+git tag -l | grep -E "v1.7.[89]"
+```
+
+**Expected output:**
+```
+v1.7.8
+v1.7.9
+```
+
+### 3. Verify Release Notes
+Visit each release page and confirm:
+- ✅ Release notes match CHANGELOG.md content
+- ✅ Date is correct (v1.7.8: Nov 5, 2025; v1.7.9: Nov 8, 2025)
+- ✅ Release is marked as "Latest" for v1.7.9
+
+## Publishing Packages
+
+After creating the GitHub releases, you may want to publish packages to NPM and GitHub Packages.
+
+### Check if Already Published
+
+```bash
+# Check NPM
+npm view @alteriom/painlessmesh versions
+
+# Check if 1.7.8 and 1.7.9 are listed
+```
+
+### Publish if Missing
+
+If versions are not published:
+
+```bash
+# Option 1: Trigger manual publish workflow
+gh workflow run manual-publish.yml --repo Alteriom/painlessMesh
+
+# Option 2: Manual NPM publish (requires NPM token)
+npm publish --access public
+```
+
+## Why This Happened
+
+The releases were likely missed because:
+
+1. **Commits didn't trigger release workflow** - The release workflow triggers on:
+   - Commits to `main` branch
+   - Changes to version files OR commit message starting with `release:`
+   - If neither condition was met, no release was created
+
+2. **Version was bumped without triggering release** - The version files were updated but:
+   - Commit message didn't start with `release:`
+   - Or changes were pushed to a different branch first
+
+3. **Workflow may have failed** - Check GitHub Actions history for failed workflows
+
+## Preventing Future Issues
+
+### Ensure Releases Trigger Properly
+
+The release workflow (`.github/workflows/release.yml`) triggers when:
+
+1. **Automatic trigger** (recommended):
+   - Modify `library.properties`, `library.json`, or `package.json`
+   - Commit changes to `main` branch
+   - Workflow automatically detects version bump and creates release
+
+2. **Manual trigger**:
+   - Commit message starts with `release:`
+   - Example: `git commit -m "release: v1.8.0 - New features"`
+
+### Best Practices for Future Releases
+
+1. **Use the bump-version script:**
+   ```bash
+   ./scripts/bump-version.sh patch  # or minor, major
+   ```
+
+2. **Update CHANGELOG.md** with release notes
+
+3. **Use release agent to validate:**
+   ```bash
+   ./scripts/release-agent.sh
+   ```
+
+4. **Commit with proper message:**
+   ```bash
+   git add library.properties library.json package.json CHANGELOG.md
+   git commit -m "release: v1.8.0 - Brief description"
+   git push origin main
+   ```
+
+5. **Verify workflow runs:**
+   - Go to: https://github.com/Alteriom/painlessMesh/actions
+   - Watch the "Automated Release" workflow
+   - Confirm it completes successfully
+
+6. **Check release was created:**
+   ```bash
+   gh release list --repo Alteriom/painlessMesh
+   ```
+
+### Monitoring Release Success
+
+After pushing a release commit, verify:
+
+- ✅ GitHub Actions workflow runs successfully
+- ✅ Git tag is created and pushed
+- ✅ GitHub release is created with notes
+- ✅ NPM package is published
+- ✅ GitHub Packages is updated
+- ✅ Wiki is synchronized (if enabled)
+
+View the workflow run:
+```bash
+gh run list --workflow=release.yml --repo Alteriom/painlessMesh
+```
+
+## Troubleshooting
+
+### "Tag already exists" Error
+
+If tags exist but releases don't:
+```bash
+# Delete existing tags (careful!)
+git tag -d v1.7.8
+git push origin :refs/tags/v1.7.8
+
+# Then recreate using the script
+./scripts/create-missing-releases.sh
+```
+
+### "Permission denied" Error
+
+You need write access to the repository:
+- Verify you're authenticated: `gh auth status`
+- Check your permissions on the repository
+- Contact repository owner for access
+
+### Script Fails
+
+If the automated script fails:
+1. Check error messages
+2. Verify GitHub CLI is installed: `gh --version`
+3. Verify you're authenticated: `gh auth login`
+4. Try manual process (Option 2 above)
+
+### Release Notes Are Empty
+
+If release notes extraction fails:
+1. Verify CHANGELOG.md format matches expected pattern
+2. Check that version sections exist: `## [1.7.8]` and `## [1.7.9]`
+3. Manually copy content from CHANGELOG.md
+
+## Additional Resources
+
+- **Release Guide**: See `RELEASE_GUIDE.md` for complete release process
+- **GitHub Releases**: https://github.com/Alteriom/painlessMesh/releases
+- **GitHub CLI Docs**: https://cli.github.com/manual/
+- **Release Workflow**: `.github/workflows/release.yml`
+
+## Summary
+
+**To create missing releases:**
+
+```bash
+# Quick method (automated)
+./scripts/create-missing-releases.sh
+
+# Verify
+gh release list --repo Alteriom/painlessMesh
+
+# Publish packages if needed
+gh workflow run manual-publish.yml --repo Alteriom/painlessMesh
+```
+
+**To prevent future issues:**
+
+```bash
+# Always use this workflow for releases:
+./scripts/bump-version.sh patch
+# Update CHANGELOG.md
+./scripts/release-agent.sh  # Validate
+git add . && git commit -m "release: vX.Y.Z - Description"
+git push origin main
+# Watch GitHub Actions to confirm success
+```
+
+---
+
+**Questions?** Open an issue with the `ci/cd` label.

package/docs/README.md

@@ -36,7 +36,7 @@ Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh
 - [Basic Examples](tutorials/basic-examples.md) - Simple mesh networking examples
 - [Custom Packages](tutorials/custom-packages.md) - Creating your own message types
 - [Sensor Networks](tutorials/sensor-networks.md) - Building IoT sensor networks
-- [Bridge Applications](tutorials/bridge-apps.md) - Connecting mesh to external networks
+- [Bridge to Internet](../BRIDGE_TO_INTERNET.md) - Connecting mesh to WiFi/Internet/MQTT
 
 ### Alteriom Extensions
 
@@ -63,6 +63,7 @@ Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh
 ### Troubleshooting
 
 - [Common Issues](troubleshooting/common-issues.md) - Solutions to frequent problems
+- [ESP32-C6 Compatibility](troubleshooting/ESP32_C6_COMPATIBILITY.md) - ESP32-C6 specific issues and solutions
 - [Debugging Guide](troubleshooting/debugging.md) - Tools and techniques for debugging
 - [FAQ](troubleshooting/faq.md) - Frequently asked questions
 - [Network Issues](troubleshooting/network-issues.md) - Connectivity and mesh topology problems