@alteriom/painlessmesh 1.9.16 → 1.9.18

package/CHANGELOG.md

@@ -13,6 +13,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+## [1.9.18] - 2025-12-21
+
+### Added
+
+- **Internet Connectivity Check Enhancement** - Bridge nodes now verify actual internet access before processing HTTP requests
+  - Added `hasActualInternetAccess()` function that performs DNS resolution to detect router internet issues
+  - Gateway checks both WiFi association AND DNS resolution before attempting HTTP requests
+  - Provides early failure detection when router has no WAN connection
+  - Clear, actionable error messages help users troubleshoot connectivity problems:
+    - "Gateway WiFi not connected" - ESP not associated with WiFi network
+    - "Router has no internet access - check WAN connection" - WiFi OK but router offline
+  - Minimal performance impact: ~100ms DNS check vs 30+ second HTTP timeout
+  - New test suite with 22 assertions covering connectivity scenarios
+  - Documentation: ISSUE_INTERNET_CONNECTIVITY_CHECK.md
+  - Backward compatible: No API changes required
+
+## [1.9.17] - 2025-12-21
+
+### Changed
+
+- **Documentation Enhancement** - Professional-grade documentation improvements
+  - Removed all phase terminology (Phase 1, Phase 2) for clearer product positioning
+  - Reorganized package types in proper numerical order (200-614) for better discoverability
+  - Enhanced package type descriptions with clearer use cases and benefits
+  - Improved Advanced Features section with comprehensive feature list
+  - Updated README to production-level quality suitable for enterprise adoption
+  - Clarified message type taxonomy (Protocol-Level vs Application-Level)
+
+### Documentation
+
+- **Package Type Organization** - All 19 application-level package types now listed in numerical order
+  - Core IoT Packages (200, 202, 400)
+  - Advanced Monitoring (204, 605)
+  - Mesh Topology & Management (600-604)
+  - Bridge Failover & High Availability (610-614)
+- **Feature Clarity** - Advanced features now prominently displayed including:
+  - Broadcast OTA distribution
+  - MQTT bridge integration
+  - Automatic bridge failover
+  - Multi-bridge coordination
+  - Message queueing for offline resilience
+
 ## [1.9.16] - 2025-12-20
 
 ### Changed

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.16** - Maintenance release with documentation improvements and code refinements
+**Version 1.9.18** - Internet connectivity check enhancement with DNS resolution verification
 
 [![CI/CD Pipeline](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/ci.yml)
 [![Documentation](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/docs.yml)
@@ -46,7 +46,7 @@ This fork includes specialized packages for structured IoT communication:
   - Command tracking with unique IDs
   - Perfect for remote device control
 
-**Advanced Monitoring Packages (Phase 2):**
+**Advanced Monitoring Packages:**
 
 - **`MetricsPackage`** (Type 204) - Comprehensive performance metrics (SENSOR_METRICS per mqtt-schema v0.7.2+)
   - CPU usage and processing metrics
@@ -64,13 +64,7 @@ This fork includes specialized packages for structured IoT communication:
   - Crash tracking and reboot reason codes
   - Actionable recommendations
 
-**Mesh Topology & Management (Phase 2):**
-
-- **`EnhancedStatusPackage`** (Type 604) - Detailed mesh status (MESH_STATUS per mqtt-schema v0.7.2+)
-  - Complete mesh statistics (node count, connections, messages)
-  - Performance metrics (latency, packet loss, throughput)
-  - Alert flags and error reporting
-  - Firmware verification with MD5 hash
+**Mesh Topology & Management:**
 
 - **`MeshNodeListPackage`** (Type 600) - Node discovery and inventory (MESH_NODE_LIST per mqtt-schema v0.7.2+)
   - List of all mesh nodes with status (offline/online/unreachable)
@@ -99,7 +93,13 @@ This fork includes specialized packages for structured IoT communication:
   - Gateway node identification
   - Enables heterogeneous mesh networks
 
-**Bridge Failover & High Availability (v1.8.0):**
+- **`EnhancedStatusPackage`** (Type 604) - Detailed mesh status (MESH_STATUS per mqtt-schema v0.7.2+)
+  - Complete mesh statistics (node count, connections, messages)
+  - Performance metrics (latency, packet loss, throughput)
+  - Alert flags and error reporting
+  - Firmware verification with MD5 hash
+
+**Bridge Failover & High Availability:**
 
 - **`BridgeStatusPackage`** (Type 610) - Bridge health monitoring (BRIDGE_STATUS per mqtt-schema v0.7.3+)
   - Internet connectivity status
@@ -119,6 +119,13 @@ This fork includes specialized packages for structured IoT communication:
   - Takeover reason and timestamp
   - Seamless failover notification
 
+- **`BridgeCoordinationPackage`** (Type 613) - Multi-bridge coordination (BRIDGE_COORDINATION per mqtt-schema v0.7.3+)
+  - Bridge priority levels (1-10)
+  - Role assignment (primary/secondary/standby)
+  - Peer bridge discovery
+  - Load balancing metrics
+  - Hot standby redundancy
+
 - **`NTPTimeSyncPackage`** (Type 614) - NTP time synchronization (TIME_SYNC_NTP per mqtt-schema v0.7.3+)
   - Unix timestamp from NTP server
   - Accuracy/precision in milliseconds
@@ -127,7 +134,7 @@ This fork includes specialized packages for structured IoT communication:
 
 All packages provide type-safe serialization, automatic JSON conversion, and mesh-wide broadcasting or targeted messaging. They align with mqtt-schema v0.7.3+ for enterprise IoT integration.
 
-#### 🚀 Phase 2 Features (v1.7.0+)
+#### 🚀 Advanced Features
 
 **Broadcast OTA Distribution**
 
@@ -145,7 +152,7 @@ All packages provide type-safe serialization, automatic JSON conversion, and mes
 
 See [BRIDGE_TO_INTERNET.md](BRIDGE_TO_INTERNET.md) for complete documentation.
 
-#### 🔄 Automatic Bridge Failover (v1.8.0)
+#### 🔄 Automatic Bridge Failover
 
 **High Availability for Critical Systems**
 
@@ -538,12 +545,15 @@ These are the message types used by applications built on painlessMesh:
 - **📱 ESP32 & ESP8266** - Full support for both platforms
 - **🛡️ Memory Efficient** - Optimized for resource-constrained devices
 
-### Advanced Features (v1.7.0+)
+### Advanced Features
 
 - **📡 Broadcast OTA** - Efficient firmware distribution for large meshes (50-100+ nodes)
 - **🌉 MQTT Bridge** - Professional monitoring with Grafana/InfluxDB/Prometheus
 - **📊 Topology Visualization** - D3.js, Cytoscape.js, Node-RED examples
 - **🎯 Production Ready** - Enterprise-grade stability and performance
+- **🔄 Automatic Bridge Failover** - RSSI-based election for high availability
+- **🌐 Multi-Bridge Coordination** - Load balancing and geographic redundancy
+- **💾 Message Queueing** - Zero data loss during Internet outages
 
 ## Examples & Use Cases
 
@@ -553,18 +563,16 @@ These are the message types used by applications built on painlessMesh:
 - **Event Coordination** - Synchronized displays, distributed processing
 - **Bridge Networks** - Connect mesh to WiFi/Internet/MQTT - [📖 Bridge Guide](BRIDGE_TO_INTERNET.md)
 
-## Latest Release: v1.9.6 (December 10, 2025)
+## Latest Release: v1.9.17 (December 21, 2025)
 
-**TCP Connection Improvements & Documentation Update**
+**Documentation Enhancement & Package Organization**
 
-- ⚡ **TCP Connection Retry Improvements** - Enhanced reliability with exponential backoff (#231)
-  - Increased stabilization delay (100ms → 500ms)
-  - Increased retry delay (500ms → 1000ms) with exponential backoff
-  - More retry attempts (3 → 5) for better connection establishment
-- 📚 **Comprehensive Documentation Review** - Updated README.md for completeness and accuracy
-- 🔄 **Version Consistency** - Aligned version numbers across all distribution channels
+- 📚 **Production-Level Documentation** - Removed phase terminology for clearer product positioning
+- 📦 **Complete Package Catalog** - All 19 application-level package types documented in numerical order
+- 🎯 **Enhanced Feature Clarity** - Improved Advanced Features section with comprehensive capability list
+- ✨ **Professional Quality** - Documentation suitable for enterprise adoption and production deployments
 
-**Recent Key Features (v1.9.0 - v1.9.5):**
+**Recent Key Features (v1.9.0 - v1.9.16):**
 
 - 🔍 **Mesh Connectivity Detection** - New `hasActiveMeshConnections()` and `getLastKnownBridge()` APIs
 - 🌉 **Improved Bridge Detection** - `getPrimaryBridge()` returns last known bridge when disconnected

package/examples/sendToInternet/README.md

@@ -146,6 +146,35 @@ mesh.sendToInternet("https://api.callmebot.com/...", "", callback);
 3. Check HTTP status code in callback (200 = success)
 4. URL-encode special characters in the message
 
+### Gateway shows "no internet access" but WiFi is connected
+
+**Symptom:** Error message "Router has no internet access - check WAN connection"
+
+**Cause:** The gateway node is connected to WiFi but the router itself has no internet connectivity. This is detected through DNS resolution testing.
+
+**Solutions:**
+1. **Check router WAN connection:**
+   - Verify router's internet LED indicator
+   - Check router's WAN port cable connection
+   - Ensure modem is powered and connected
+
+2. **Check ISP service:**
+   - Verify your internet service is active
+   - Test internet on other devices connected to same router
+   - Contact ISP if service is down
+
+3. **Router configuration:**
+   - Verify router has obtained WAN IP address
+   - Check router's internet connection status page
+   - Restart router if necessary
+
+**Technical Details:**
+The gateway performs two connectivity checks:
+1. `WiFi.status() == WL_CONNECTED` - Verifies WiFi association
+2. DNS resolution test - Verifies actual internet routing
+
+If WiFi is connected but DNS fails, it indicates the router has no upstream internet connection. This prevents unnecessary HTTP request timeouts and provides early error detection.
+
 ### Understanding HTTP Status Codes
 
 The callback provides `httpStatus` to indicate the result:

package/library.json

@@ -6,7 +6,7 @@
     "type": "git",
     "url": "https://github.com/Alteriom/painlessMesh"
   },
-  "version": "1.9.16",
+  "version": "1.9.18",
   "frameworks": [
     "arduino"
   ],

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.9.16
+version=1.9.18
 author=Coopdis,Scotty Franzyshen,Edwin van Leeuwen,Germán Martín,Maximilian Schwarz,Doanh Doanh,Alteriom
 maintainer=Alteriom
 sentence=A painless way to setup a mesh with ESP8266 and ESP32 devices with Alteriom extensions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alteriom/painlessmesh",
-  "version": "1.9.16",
+  "version": "1.9.18",
   "description": "painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices. This Alteriom fork includes additional packages for sensor data (SensorPackage), device commands (CommandPackage), and status monitoring (StatusPackage). It handles routing and network management automatically, so you can focus on your application. The library uses JSON-based messaging and syncs time across all nodes, making it ideal for coordinated behaviour like synchronized light displays or sensor networks reporting to a central node.",
   "keywords": [
     "arduino",

package/src/AlteriomPainlessMesh.h

@@ -29,10 +29,10 @@
 /**
  * @brief AlteriomPainlessMesh library version information
  */
-#define ALTERIOM_PAINLESS_MESH_VERSION "1.9.16"
+#define ALTERIOM_PAINLESS_MESH_VERSION "1.9.18"
 #define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 1
 #define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 9
-#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 16
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 18
 
 /**
  * @brief Library description and usage information

package/src/arduino/wifi.hpp

@@ -2120,6 +2120,61 @@ class Mesh : public painlessmesh::Mesh<Connection> {
     router::broadcast<protocol::Variant, Connection>(variant, (*this), 0);
   }
 
+  /**
+   * Check if gateway has actual internet connectivity
+   * 
+   * Tests DNS resolution to detect scenarios where WiFi is connected
+   * but the router has no internet access. This provides early detection
+   * before attempting HTTP requests that would timeout or fail.
+   * 
+   * @return true if internet is accessible, false otherwise
+   */
+  bool hasActualInternetAccess() {
+    using namespace logger;
+    
+    // First check WiFi connection
+    if (WiFi.status() != WL_CONNECTED) {
+      return false;
+    }
+    
+    // Check if we have a valid local IP
+    if (WiFi.localIP() == IPAddress(0, 0, 0, 0)) {
+      return false;
+    }
+    
+    // Try to resolve a well-known DNS name
+    // Using Google's servers as they have high availability globally
+    IPAddress result;
+    
+#if defined(ESP32) || defined(ESP8266)
+    // Both ESP32 and ESP8266 support WiFi.hostByName()
+    int dnsResult = WiFi.hostByName("www.google.com", result);
+    
+    // Check if DNS resolution succeeded
+    if (dnsResult != 1) {
+      Log(COMMUNICATION, "hasActualInternetAccess(): DNS resolution failed (code=%d)\n", dnsResult);
+      return false;
+    }
+    
+    // Additional validation: Check if resolved IP is valid
+    // Some ESP8266 versions may return success but set IP to 255.255.255.255 on error
+    if (result == IPAddress(0, 0, 0, 0) || result == IPAddress(255, 255, 255, 255)) {
+      TSTRING resultStr = result.toString();
+      Log(COMMUNICATION, "hasActualInternetAccess(): Invalid DNS result IP: %s\n", resultStr.c_str());
+      return false;
+    }
+#else
+    // Other platforms: assume internet is available if WiFi connected
+    // (no reliable way to test without platform-specific APIs)
+    return true;
+#endif
+    
+    TSTRING resultStr = result.toString();
+    Log(COMMUNICATION, "hasActualInternetAccess(): Internet connectivity verified (resolved to %s)\n", 
+        resultStr.c_str());
+    return true;
+  }
+
   /**
    * Helper method to send gateway acknowledgment
    */
@@ -2196,8 +2251,16 @@ class Mesh : public painlessmesh::Mesh<Connection> {
           }
 
           // Check Internet connectivity
+          // First check WiFi status for quick fail
           if (WiFi.status() != WL_CONNECTED) {
-            sendGatewayAck(pkg, false, 0, "Gateway not connected to Internet");
+            sendGatewayAck(pkg, false, 0, "Gateway WiFi not connected");
+            return true;  // Consume package - we handled it (with error)
+          }
+          
+          // Then check actual internet access (DNS resolution)
+          // This detects when WiFi is connected but router has no internet
+          if (!hasActualInternetAccess()) {
+            sendGatewayAck(pkg, false, 0, "Router has no internet access - check WAN connection");
             return true;  // Consume package - we handled it (with error)
           }
 
@@ -2263,20 +2326,35 @@ class Mesh : public painlessmesh::Mesh<Connection> {
               Log(COMMUNICATION, "HTTP request completed: code=%d\n", httpCode);
             } else if (httpCode >= 200 && httpCode < 300) {
               // Other 2xx codes - ambiguous success
+              // HTTP 203 is retryable, so log at COMMUNICATION level to reduce noise
               char errorBuf[128];
               snprintf(errorBuf, sizeof(errorBuf), 
                       "Ambiguous response - HTTP %d may indicate cached/proxied response, not actual delivery", 
                       httpCode);
               error = TSTRING(errorBuf);
-              Log(ERROR, "HTTP request ambiguous: code=%d (treated as failure)\n", httpCode);
+              Log(COMMUNICATION, "HTTP request ambiguous: code=%d (treated as failure, will retry)\n", httpCode);
+            } else if (httpCode >= 500 && httpCode < 600) {
+              // 5xx server errors are retryable, log at COMMUNICATION level
+              char errorBuf[32];
+              snprintf(errorBuf, sizeof(errorBuf), "HTTP %d", httpCode);
+              error = TSTRING(errorBuf);
+              Log(COMMUNICATION, "HTTP server error: code=%d (will retry)\n", httpCode);
+            } else if (httpCode == 429) {
+              // HTTP 429 rate limit is retryable, log at COMMUNICATION level
+              char errorBuf[32];
+              snprintf(errorBuf, sizeof(errorBuf), "HTTP %d", httpCode);
+              error = TSTRING(errorBuf);
+              Log(COMMUNICATION, "HTTP rate limit: code=%d (will retry)\n", httpCode);
             } else {
-              // 1xx, 3xx, 4xx, 5xx
+              // 1xx, 3xx, 4xx (except 429) - non-retryable, log at ERROR level
               char errorBuf[32];
               snprintf(errorBuf, sizeof(errorBuf), "HTTP %d", httpCode);
               error = TSTRING(errorBuf);
               Log(ERROR, "HTTP request failed: code=%d\n", httpCode);
             }
           } else {
+            // Network errors (httpCode <= 0) are retryable but indicate serious issues
+            // Keep at ERROR level as they may indicate gateway connectivity problems
             error = http.errorToString(httpCode);
             Log(ERROR, "HTTP request failed: %s\n", error.c_str());
           }

package/src/painlessMesh.h

@@ -5,8 +5,8 @@
  * @file painlessMesh.h
  * @brief Main header file for Alteriom painlessMesh library
  * 
- * @version 1.9.16
- * @date 2025-12-20
+ * @version 1.9.18
+ * @date 2025-12-21
  * 
  * painlessMesh is a user-friendly library for creating mesh networks with 
  * ESP8266 and ESP32 devices. This Alteriom fork includes additional packages