@alteriom/painlessmesh 1.9.5 → 1.9.7

package/CHANGELOG.md

@@ -5,6 +5,78 @@ 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]
+
+### Added
+
+- TBD
+
+### Changed
+
+- TBD
+
+### Fixed
+
+- TBD
+
+## [1.9.7] - 2025-12-13
+
+### Fixed
+
+- **External Device WiFi AP Connection** (#231) - Fixed DHCP and AP initialization issues preventing phones and computers from connecting to bridge
+  - **Root Cause**: When AP was restarted during channel changes, DHCP server was not properly reinitialized due to incomplete WiFi stack reset
+  - **Symptom**: External devices (Android phones, Windows 11 computers) cannot connect to mesh WiFi AP or fail to receive IP addresses via DHCP
+  - **Solution**: Improved AP restart sequence and DHCP initialization:
+    - Added explicit `WiFi.enableAP(true)` for ESP32 to ensure DHCP server starts
+    - Changed `softAPdisconnect(false)` to `softAPdisconnect(true)` for proper DHCP shutdown
+    - Increased timing delays: 200ms before AP restart + 100ms stabilization after
+    - Added logging for AP configuration to aid debugging
+  - **Impact**: External devices can now reliably connect to bridge AP for debugging and testing
+
+### Documentation
+
+- **External Device Connection Guide** - New comprehensive guide for connecting phones/computers to mesh AP
+  - Complete connection instructions for Android, Windows, macOS, Linux
+  - Troubleshooting section for common connection issues
+  - Security best practices and warnings
+  - Example debug sessions with network tools
+  - Added to bridge examples with detailed setup notes
+
+## [1.9.6] - 2025-12-10
+
+### Fixed
+
+- **TCP Connection Retry Improvements** (#231) - Improved TCP connection reliability with increased retries and exponential backoff
+  - **Root Cause**: Nodes experience endless loop of WiFi connect → TCP error -14 → WiFi disconnect because the TCP retry mechanism wasn't sufficient for real-world mesh conditions
+  - **Symptom**: Mesh connections never fully establish; nodes can discover and get IP from bridge but TCP connection consistently fails
+  - **Solution**: Improved TCP connection retry parameters and added exponential backoff:
+    - Increased `TCP_CONNECT_STABILIZATION_DELAY_MS` from 100ms to 500ms (more time for network stack to stabilize after IP acquisition)
+    - Increased `TCP_CONNECT_RETRY_DELAY_MS` from 500ms to 1000ms (base delay between retries)
+    - Increased `TCP_CONNECT_MAX_RETRIES` from 3 to 5 (more retry attempts before giving up)
+    - Added exponential backoff: retry delays are 1s, 2s, 4s, 8s, 8s (capped) for attempts 1-5
+  - **Impact**: More reliable mesh connection establishment, especially when bridge TCP server is temporarily busy or network is congested
+
+### Documentation
+
+- **README.md Comprehensive Review** - Updated main README for completeness and accuracy
+  - Updated version references from 1.9.2 to 1.9.6
+  - Verified all documentation links and references
+  - Confirmed package type documentation accuracy
+  - Validated installation instructions
+  - Updated "Latest Release" section with current features
+  - Fixed ArduinoJson v7 code examples (DynamicJsonDocument → JsonDocument)
+  - Updated dependency versions in documentation (ArduinoJson 6.x→7.x, TaskScheduler 3.x→4.x)
+  - Corrected API Documentation links (GitLab → GitHub Pages)
+  - Fixed Contributing section references (master→main, GitLab→GitHub)
+
+### Changed
+
+- **Version Consistency** - Synchronized version numbers across all distribution files
+  - Updated library.properties to v1.9.6
+  - Updated library.json to v1.9.6
+  - Updated package.json to v1.9.6
+  - Ensures consistent versioning for NPM, PlatformIO, and Arduino Library Manager
+
 ## [1.9.5] - 2025-12-03
 
 ### Fixed
@@ -22,6 +94,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Nodes that fail initial bridge setup can now retry automatically via mesh connection monitoring
   - **Impact**: More reliable bridge establishment in challenging network conditions
 
+- **Isolated Bridge Retry Delay After Failed Promotion** - Fixed slow retry after failed bridge promotion
+  - **Root Cause**: When bridge promotion fails, `init()` is called which resets `consecutiveEmptyScans` to 0. The isolated retry task would then wait for 6+ new empty scans (90 seconds) before retrying.
+  - **Symptom**: After a failed bridge promotion, retries only happen every ~2 minutes instead of ~60 seconds
+  - **Solution**: Added `_isolatedRetryPending` flag that is set when promotion fails. This flag allows the next retry attempt to skip the empty scan threshold check.
+  - **Impact**: Faster retry after failed promotion - retries happen at the normal 60 second interval instead of waiting for scan accumulation
+
 ## [1.9.4] - 2025-12-03
 
 ### Fixed

package/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # 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.
+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 `main` 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 `main` branch.
 
 ## Git flow
 
@@ -8,9 +8,9 @@ If you would like to use [git flow tools](http://danielkummer.github.io/git-flow
 
 ## 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 your push triggered a 'you just pushed...' message from GitHub 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`.
+* Make sure that you're attempting to merge into `develop` and not `main`.
 * 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.
 

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.2** - Consolidated release across all distribution channels
+**Version 1.9.6** - Latest release with TCP connection improvements and documentation updates
 
 [![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)
@@ -418,7 +418,7 @@ void loop() {
 }
 
 void receivedCallback(uint32_t from, String& msg) {
-    DynamicJsonDocument doc(1024);
+    JsonDocument doc;  // ArduinoJson v7
     deserializeJson(doc, msg);
     
     if (doc["type"] == 200) { // SensorPackage
@@ -553,15 +553,24 @@ 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.0 (November 30, 2025)
+## Latest Release: v1.9.6 (December 10, 2025)
 
-**Major Update: Improved Bridge Detection, Consolidated Examples & Documentation**
+**TCP Connection Improvements & Documentation Update**
+
+- ⚡ **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
+
+**Recent Key Features (v1.9.0 - v1.9.5):**
 
 - 🔍 **Mesh Connectivity Detection** - New `hasActiveMeshConnections()` and `getLastKnownBridge()` APIs
 - 🌉 **Improved Bridge Detection** - `getPrimaryBridge()` returns last known bridge when disconnected
-- ⚡ **Election Guard** - Skip election trigger when node is disconnected from mesh
-- 📦 **Consolidated Examples** - Reduced from 32 to 14 essential examples
-- 📚 **Cleaned Documentation** - Removed obsolete docs, kept only essentials
+- ⚡ **Enhanced TCP Reliability** - Exponential backoff and increased retries for mesh connections
+- 🛡️ **Race Condition Fixes** - Improved bridge status and connection validation
+- 📦 **Consolidated Examples** - Streamlined to 14 essential examples
 - ⚙️ **Configurable Election Timing** - Prevent split-brain with `setElectionStartupDelay()` and `setElectionRandomDelay()`
 
 **[📋 Full CHANGELOG](CHANGELOG.md)**
@@ -572,7 +581,7 @@ These are the message types used by applications built on painlessMesh:
 - **[Common Issues](docs/troubleshooting/common-issues.md)** - Troubleshooting guide
 - **[GitHub Issues](https://github.com/Alteriom/painlessMesh/issues)** - Bug reports and feature requests  
 - **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)** - Community support
-- **[API Documentation](http://painlessmesh.gitlab.io/painlessMesh/index.html)** - Generated API docs
+- **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)** - Generated API docs
 
 ## Development
 
@@ -590,7 +599,7 @@ run-parts --regex catch_ bin/  # Run tests
 ### Requirements
 
 - **ESP32/ESP8266**: Arduino Core 2.0.0+
-- **Dependencies**: ArduinoJson 6.x, TaskScheduler 3.x  
+- **Dependencies**: ArduinoJson 7.x, TaskScheduler 4.x  
 - **Development**: CMake, Ninja, Boost (for desktop testing)
 
 ### CI/CD Pipeline
@@ -628,7 +637,7 @@ See [RELEASE_GUIDE.md](RELEASE_GUIDE.md) for complete release documentation.
 
 ## 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. For more details see the [CONTRIBUTING](https://gitlab.com/painlessMesh/painlessMesh/blob/master/CONTRIBUTING.md) file.
+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 `main` 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 `main` branch. For more details see the [CONTRIBUTING.md](CONTRIBUTING.md) file.
 
 ## Funding
 
@@ -638,199 +647,66 @@ If you like the library please consider supporting its development. Your contrib
 
 **[Donate via PayPal](https://www.paypal.com/paypalme/domlavoie)** • [dominic.lavoie@gmail.com](mailto:dominic.lavoie@gmail.com)
 
-## 📚 Complete Documentation
-
-> **� [Visit the Full Documentation Website](https://alteriom.github.io/painlessMesh/)**
-
-### 🚀 Getting Started
-
-**New to AlteriomPainlessMesh?** Start with these essential guides:
-
-| Guide | Description | Link |
-|-------|-------------|------|
-| **🎯 Quick Start** | Get your first mesh running in 5 minutes | [📖 Start Here](https://alteriom.github.io/painlessMesh/#/getting-started/quickstart) |
-| **💾 Installation** | Arduino IDE, PlatformIO, and more | [📖 Install Guide](https://alteriom.github.io/painlessMesh/#/getting-started/installation) |
-| **🌐 First Mesh** | Build a real multi-node network | [📖 Build Now](https://alteriom.github.io/painlessMesh/#/getting-started/first-mesh) |
-
-### 📖 API Documentation
-
-**Complete reference for all classes, functions, and features:**
-
-| Section | Description | Link |
-|---------|-------------|------|
-| **🔧 Core API** | painlessMesh class reference and methods | [📖 Core API](https://alteriom.github.io/painlessMesh/#/api/core-api) |
-| **📦 Doxygen API** | Auto-generated complete API documentation | [📖 Browse API](https://alteriom.github.io/painlessMesh/#/api/doxygen) |
-| **⚙️ Configuration** | All mesh configuration options | [📖 Configure](https://alteriom.github.io/painlessMesh/#/api/configuration) |
-| **🔄 Callbacks** | Event handling and callback patterns | [📖 Events](https://alteriom.github.io/painlessMesh/#/api/callbacks) |
-
-### 🎯 Alteriom Extensions
-
-**IoT-ready packages for production applications:**
-
-| Package | Purpose | Documentation |
-|---------|---------|---------------|
-| **📊 SensorPackage** | Environmental data collection | [📖 Sensor Docs](https://alteriom.github.io/painlessMesh/#/alteriom/overview) |
-| **⚡ CommandPackage** | Device control and automation | [📖 Command Docs](https://alteriom.github.io/painlessMesh/#/alteriom/overview) |
-| **📈 StatusPackage** | Health monitoring and diagnostics | [📖 Status Docs](https://alteriom.github.io/painlessMesh/#/alteriom/overview) |
-
-### 🏗️ Advanced Topics
-
-**Deep dive into architecture and advanced usage:**
-
-| Topic | Description | Link |
-|-------|-------------|------|
-| **🌳 Architecture** | How painlessMesh works internally | [📖 Architecture](https://alteriom.github.io/painlessMesh/#/architecture/mesh-architecture) |
-| **🌉 Bridge to Internet** | Connect mesh to WiFi/Internet/MQTT | [📖 Bridge Guide](BRIDGE_TO_INTERNET.md) |
-| **🔌 Plugin System** | Create custom message packages | [📖 Plugins](https://alteriom.github.io/painlessMesh/#/architecture/plugin-system) |
-| **🎓 Tutorials** | Step-by-step examples and patterns | [📖 Tutorials](https://alteriom.github.io/painlessMesh/#/tutorials/basic-examples) |
-| **🛠️ Troubleshooting** | Common issues and solutions | [📖 Help](https://alteriom.github.io/painlessMesh/#/troubleshooting/common-issues) |
-
-### 📝 Quick Reference
+## 📚 Documentation
 
-**Bookmark these for daily development:**
+### 📖 Essential Guides
 
-- **[📋 Class Index](https://alteriom.github.io/painlessMesh/#/api/doxygen/classes)** - All classes with methods
-- **[⚙️ Function Index](https://alteriom.github.io/painlessMesh/#/api/doxygen/functions)** - All functions and globals  
-- **[📁 File Structure](https://alteriom.github.io/painlessMesh/#/api/doxygen/files)** - Source code organization
-- **[❓ FAQ](https://alteriom.github.io/painlessMesh/#/troubleshooting/faq)** - Frequently asked questions
+| Document | Description |
+|----------|-------------|
+| **[📘 User Guide](USER_GUIDE.md)** | **Complete comprehensive guide** - Everything you need to know |
+| **[🌉 Bridge Guide](BRIDGE_TO_INTERNET.md)** | Connect mesh to Internet, MQTT, and cloud services |
+| **[📋 Documentation Hub](.github/DOCUMENTATION.md)** | Central navigation for all documentation resources |
+| **[🌐 Online Docs](https://alteriom.github.io/painlessMesh/)** | Interactive documentation website with API reference |
 
-**📖 Examples:**
+### 🚀 Quick Links
 
-- **[Basic Example](examples/basic/basic.ino)** - Essential patterns and techniques
-- **[Alteriom Sensor Node](examples/alteriom/alteriom.ino)** - IoT sensor packages
-- **[Bridge Example](examples/bridge/bridge.ino)** - Connect mesh to Internet
+**New to AlteriomPainlessMesh?**
+- [Quick Start](docs/getting-started/quickstart.md) - Get your first mesh running in 5 minutes
+- [Installation](docs/getting-started/installation.md) - Arduino IDE and PlatformIO setup
+- [First Mesh](docs/getting-started/first-mesh.md) - Build a multi-node network
 
-**📋 Complete Documentation Index:** [docs/README.md](docs/README.md)
+**Reference Documentation:**
+- [Core API](docs/api/core-api.md) - painlessMesh class methods
+- [Alteriom Extensions](docs/alteriom/overview.md) - SensorPackage, CommandPackage, StatusPackage
+- [Examples](examples/) - 16 working examples for common scenarios
 
-## painlessMesh API Summary
+**Need Help?**
+- [FAQ](docs/troubleshooting/faq.md) - Frequently asked questions
+- [Common Issues](docs/troubleshooting/common-issues.md) - Troubleshooting guide
+- [GitHub Issues](https://github.com/Alteriom/painlessMesh/issues) - Bug reports and support
 
-Here's a quick API overview.
+## 🔧 Quick API Reference
 
+**Core Methods:**
 ```cpp
 #include "painlessMesh.h"
 
 painlessMesh mesh;
-```
-
-### Member Functions
-
-#### void painlessMesh::init(String ssid, String password, uint16_t port = 5555, WiFiMode_t connectMode = WIFI_AP_STA, _auth_mode authmode = AUTH_WPA2_PSK, uint8_t channel = 1, phy_mode_t phymode = PHY_MODE_11G, uint8_t maxtpw = 82, uint8_t hidden = 0, uint8_t maxconn = 4)
-
-Add this to your setup() function.
-Initialize the mesh network. This routine does the following things.
-
-- Starts a wifi network
-- Begins searching for other wifi networks that are part of the mesh
-- Logs on to the best mesh network node it finds… if it doesn’t find anything, it starts a new search in 5 seconds.
-
-`ssid` = the name of your mesh.  All nodes share same AP ssid. They are distinguished by BSSID.
-`password` = wifi password to your mesh.
-`port` = the TCP port that you want the mesh server to run on. Defaults to 5555 if not specified.
-[`connectMode`](https://gitlab.com/painlessMesh/painlessMesh/wikis/connect-mode:-WIFI_AP,-WIFI_STA,-WIFI_AP_STA-mode) = switch between WIFI_AP, WIFI_STA and WIFI_AP_STA (default) mode
-
-#### void painlessMesh::stop()
-
-Stop the node. This will cause the node to disconnect from all other nodes and stop/sending messages.
-
-#### void painlessMesh::update( void )
-
-Add this to your loop() function
-This routine runs various maintenance tasks... Not super interesting, but things don't work without it.
-
-#### void painlessMesh::onReceive( &amp;receivedCallback )
-
-Set a callback routine for any messages that are addressed to this node. Callback routine has the following structure.
-
-`void receivedCallback( uint32_t from, String &amp;msg )`
-
-Every time this node receives a message, this callback routine will the called. “from” is the id of the original sender of the message, and “msg” is a string that contains the message. The message can be anything. A JSON, some other text string, or binary data.
-
-#### void painlessMesh::onNewConnection( &amp;newConnectionCallback )
-
-This fires every time the local node makes a new connection. The callback has the following structure.
-
-`void newConnectionCallback( uint32_t nodeId )`
 
-`nodeId` is new connected node ID in the mesh.
+// Initialize mesh
+mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
 
-#### void painlessMesh::onChangedConnections( &amp;changedConnectionsCallback )
+// Main loop - call this in loop()
+mesh.update();
 
-This fires every time there is a change in mesh topology. Callback has the following structure.
+// Send messages
+mesh.sendBroadcast("Hello everyone!");
+mesh.sendSingle(nodeId, "Hello specific node");
 
-`void onChangedConnections()`
+// Get information
+uint32_t myId = mesh.getNodeId();
+std::list<uint32_t> nodes = mesh.getNodeList();
 
-There are no parameters passed. This is a signal only.
+// Register callbacks
+mesh.onReceive(&receivedCallback);
+mesh.onNewConnection(&newConnectionCallback);
+mesh.onChangedConnections(&changedConnectionCallback);
 
-#### bool painlessMesh::isConnected( nodeId )
-
-Returns if a given node is currently connected to the mesh.
-
-`nodeId` is node ID that the request refers to.
-
-#### void painlessMesh::onNodeTimeAdjusted( &amp;nodeTimeAdjustedCallback )
-
-This fires every time local time is adjusted to synchronize it with mesh time. Callback has the following structure.
-
-`void onNodeTimeAdjusted(int32_t offset)`
-
-`offset` is the adjustment delta that has been calculated and applied to local clock.
-
-#### void onNodeDelayReceived(nodeDelayCallback_t onDelayReceived)
-
-This fires when a time delay measurement response is received, after a request was sent. Callback has the following structure.
-
-`void onNodeDelayReceived(uint32_t nodeId, int32_t delay)`
-
-`nodeId` The node that originated response.
-
-`delay` One way network trip delay in microseconds.
-
-#### bool painlessMesh::sendBroadcast( String &amp;msg, bool includeSelf = false)
-
-Sends msg to every node on the entire mesh network. By default the current node is excluded from receiving the message (`includeSelf = false`). `includeSelf = true` overrides this behavior, causing the `receivedCallback` to be called when sending a broadcast message.
-
-returns true if everything works, false if not. Prints an error message to Serial.print, if there is a failure.
-
-#### bool painlessMesh::sendSingle(uint32_t dest, String &amp;msg)
-
-Sends msg to the node with Id == dest.
-
-returns true if everything works, false if not.  Prints an error message to Serial.print, if there is a failure.
-
-#### String painlessMesh::subConnectionJson()
-
-Returns mesh topology in JSON format.
-
-#### std::list<uint32_t> painlessMesh::getNodeList()
-
-Get a list of all known nodes. This includes nodes that are both directly and indirectly connected to the current node.
-
-#### uint32_t painlessMesh::getNodeId( void )
-
-Return the chipId of the node that we are running on.
-
-#### uint32_t painlessMesh::getNodeTime( void )
-
-Returns the mesh timebase microsecond counter. Rolls over 71 minutes from startup of the first node.
-
-Nodes try to keep a common time base synchronizing to each other using [an SNTP based protocol](https://gitlab.com/painlessMesh/painlessMesh/wikis/mesh-protocol#time-sync)
-
-#### bool painlessMesh::startDelayMeas(uint32_t nodeId)
-
-Sends a node a packet to measure network trip delay to that node. Returns true if nodeId is connected to the mesh, false otherwise. After calling this function, user program have to wait to the response in the form of a callback specified by `void painlessMesh::onNodeDelayReceived(nodeDelayCallback_t onDelayReceived)`.
-
-nodeDelayCallback_t is a function in the form of `void (uint32_t nodeId, int32_t delay)`.
-
-#### void painlessMesh::stationManual( String ssid, String password, uint16_t port, uint8_t *remote_ip )
-
-Connects the node to an AP outside the mesh. When specifying a `remote_ip` and `port`, the node opens a TCP connection after establishing the WiFi connection.
-
-Note: The mesh must be on the same WiFi channel as the AP.
-
-#### void painlessMesh::setDebugMsgTypes( uint16_t types )
+// Debug configuration
+mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+```
 
-Change the internal log level. List of types defined in Logger.hpp:
-ERROR | MESH_STATUS | CONNECTION | SYNC | COMMUNICATION | GENERAL | MSG_TYPES | REMOTE
+**For complete API documentation, see [USER_GUIDE.md](USER_GUIDE.md#api-reference) or [online docs](https://alteriom.github.io/painlessMesh/#/api/core-api).**
 
 # Funding
 

package/docs/README.md

@@ -115,7 +115,7 @@ Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh
 ## Quick Links
 
 - **[GitHub Repository](https://github.com/Alteriom/painlessMesh)**
-- **[API Documentation](http://painlessmesh.gitlab.io/painlessMesh/index.html)**
+- **[API Documentation](https://alteriom.github.io/painlessMesh/#/api/doxygen)**
 - **[Community Forum](https://groups.google.com/forum/#!forum/painlessmesh-user)**
 - **[Issue Tracker](https://github.com/Alteriom/painlessMesh/issues)**
 

package/docs/troubleshooting/common-issues.md

@@ -60,6 +60,32 @@ For Arduino IDE, download and install manually from: https://github.com/ESP32Asy
 
 ## Connection Issues
 
+### External Devices Cannot Connect to Mesh AP
+
+**Symptoms:**
+- Phone or computer can't see the mesh WiFi network
+- Can see network but can't connect
+- Connected but no IP address assigned
+- Connection drops frequently
+
+**Solution:**
+
+See the dedicated guide for connecting external devices:
+
+📖 **[Connecting External Devices Guide](external-device-connection.md)**
+
+**Quick Summary:**
+
+External devices (phones, computers, test equipment) can connect to the bridge node's WiFi AP for debugging:
+- **SSID**: Your MESH_PREFIX value
+- **Password**: Your MESH_PASSWORD value  
+- **IP Range**: 10.x.x.x/24 (DHCP automatic)
+- **Limits**: ESP32 supports 10 devices, ESP8266 supports 4
+
+Common issues are DHCP timing, channel changes, and connection limits.
+
+---
+
 ### Nodes Not Connecting
 
 **Symptoms:**
@@ -149,6 +175,81 @@ void checkMemory() {
 }
 ```
 
+### TCP Connection Error -14 (ERR_CONN)
+
+**Symptoms:**
+- Serial output shows: `tcp_err(): error trying to connect -14`
+- Nodes get an IP address but fail to establish mesh connection
+- Connection attempts keep failing and retrying
+
+**Cause:**
+
+The error -14 (ERR_CONN in LwIP) indicates a TCP connection failure. This typically occurs when:
+1. The TCP server on the target node is not ready when the connection is attempted
+2. There's a timing issue between WiFi association and TCP readiness
+3. Network stack hasn't fully stabilized after IP acquisition
+4. The target node is overloaded or has resource constraints
+
+**Solutions:**
+
+#### 1. Update AsyncTCP Library (Most Common Fix)
+The error often occurs with older AsyncTCP versions that don't have proper thread safety for ESP32 Arduino Core 3.x:
+
+For PlatformIO:
+```ini
+lib_deps =
+    esp32async/AsyncTCP @ ^3.4.7
+```
+
+For Arduino IDE, install manually from: https://github.com/ESP32Async/AsyncTCP
+
+#### 2. Built-in Retry Mechanism
+painlessMesh now includes automatic TCP connection retry with the following behavior:
+- Up to 3 retry attempts with 500ms delay between each
+- 100ms stabilization delay after IP acquisition before first connection attempt
+- Full WiFi reconnection only triggered after all retries are exhausted
+
+This helps handle transient timing issues automatically.
+
+#### 3. Check Node Resource Usage
+Monitor memory and ensure nodes aren't overloaded:
+
+```cpp
+void loop() {
+    mesh.update();
+    
+    // Monitor health periodically
+    static unsigned long lastCheck = 0;
+    if (millis() - lastCheck > 10000) {
+        lastCheck = millis();
+        Serial.printf("Free heap: %d, WiFi RSSI: %d\n", 
+                      ESP.getFreeHeap(), WiFi.RSSI());
+    }
+}
+```
+
+#### 4. Ensure Proper Initialization Order
+Make sure the mesh is properly initialized before connections are attempted:
+
+```cpp
+void setup() {
+    Serial.begin(115200);
+    delay(100);  // Let serial initialize
+    
+    mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+    mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
+    // Add callbacks after init
+    mesh.onReceive(&receivedCallback);
+    mesh.onNewConnection(&newConnectionCallback);
+}
+```
+
+#### 5. Check WiFi Signal Strength
+Poor signal can cause connection timing issues:
+- Ensure nodes are within good WiFi range
+- Check for interference from other 2.4GHz devices
+- Monitor RSSI values (should be above -80 dBm for reliable connections)
+
 ## Message Delivery Issues
 
 ### Messages Not Being Received