@alteriom/painlessmesh 1.9.6 → 1.9.8

package/CHANGELOG.md

@@ -5,6 +5,61 @@ 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.8] - 2025-12-14
+
+### Fixed
+
+- **Heap Corruption on TCP Connection Errors** (#254) - Fixed ESP32 heap corruption crashes during AsyncClient deletion
+  - **Root Cause**: AsyncClient objects were being deleted synchronously from within their own error callback handlers, causing heap corruption and use-after-free crashes
+  - **Symptom**: ESP32 devices crash with "CORRUPT HEAP: Bad head at 0x4083a398. Expected 0xabba1234 got 0xfefefefe" during TCP connection error handling
+  - **Solution**: Deferred AsyncClient deletion using task scheduler to execute after error handler completes
+    - Changed from synchronous `delete client` to deferred deletion via `mesh.addTask([client]() { delete client; }, 0)`
+    - Deletion now occurs microseconds after error handler returns, preventing use-after-free
+    - Added logging for cleanup operations to aid debugging
+  - **Impact**: Eliminates heap corruption crashes on ESP32 during TCP connection retries and error conditions
+  - **Files Modified**: `src/painlessmesh/tcp.hpp` (lines 138, 149)
+
+### Changed
+
+- **README Version Reference** - Updated version banner to 1.9.7 for consistency with release history
+
+## [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

package/README.md

@@ -4,7 +4,7 @@
 
 <div align="center">
 
-**Version 1.9.6** - Latest release with TCP connection improvements and documentation updates
+**Version 1.9.8** - Latest release with ESP32 heap corruption fix and improved TCP error handling
 
 [![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)
@@ -647,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
+## 📚 Documentation
 
-> **� [Visit the Full Documentation Website](https://alteriom.github.io/painlessMesh/)**
+### 📖 Essential Guides
 
-### 🚀 Getting Started
+| 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 |
 
-**New to AlteriomPainlessMesh?** Start with these essential guides:
+### 🚀 Quick Links
 
-| 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) |
+**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
 
-### 📖 API Documentation
+**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
 
-**Complete reference for all classes, functions, and features:**
+**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
 
-| 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
-
-**Bookmark these for daily development:**
-
-- **[📋 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
-
-**📖 Examples:**
-
-- **[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
-
-**📋 Complete Documentation Index:** [docs/README.md](docs/README.md)
-
-## painlessMesh API Summary
-
-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` = 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.
 
-#### void painlessMesh::onChangedConnections( &amp;changedConnectionsCallback )
+// Initialize mesh
+mesh.init(MESH_PREFIX, MESH_PASSWORD, &userScheduler, MESH_PORT);
 
-This fires every time there is a change in mesh topology. Callback has the following structure.
+// Main loop - call this in loop()
+mesh.update();
 
-`void onChangedConnections()`
+// Send messages
+mesh.sendBroadcast("Hello everyone!");
+mesh.sendSingle(nodeId, "Hello specific node");
 
-There are no parameters passed. This is a signal only.
+// Get information
+uint32_t myId = mesh.getNodeId();
+std::list<uint32_t> nodes = mesh.getNodeList();
 
-#### bool painlessMesh::isConnected( nodeId )
+// Register callbacks
+mesh.onReceive(&receivedCallback);
+mesh.onNewConnection(&newConnectionCallback);
+mesh.onChangedConnections(&changedConnectionCallback);
 
-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
-
-#### 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/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:**

package/docs/troubleshooting/external-device-connection.md

@@ -0,0 +1,283 @@
+# Connecting External Devices to painlessMesh Bridge
+
+This guide explains how to connect external devices (phones, computers, test equipment) to a painlessMesh bridge node's WiFi Access Point for debugging and testing purposes.
+
+## Overview
+
+Each painlessMesh node operates in AP+STA mode, broadcasting a WiFi Access Point (AP) with the mesh SSID. External devices can connect to this AP, though they typically don't get internet access (unless using shared gateway mode).
+
+## When to Connect External Devices
+
+You might want to connect external devices to the mesh AP when:
+- Debugging mesh connectivity issues
+- Running diagnostic tools (ping, network scanners)
+- Testing DHCP configuration
+- Monitoring mesh traffic
+- Developing custom mesh applications
+
+## Connection Details
+
+### Basic Information
+
+| Setting | Value |
+|---------|-------|
+| **SSID** | Your `MESH_PREFIX` value (e.g., "FishFarmMesh", "whateverYouLike") |
+| **Password** | Your `MESH_PASSWORD` value (e.g., "securepass", "somethingSneaky") |
+| **Security** | WPA2-PSK |
+| **IP Range** | 10.x.x.x/24 (automatically assigned via DHCP) |
+| **Gateway** | 10.x.x.1 (the bridge node itself) |
+| **DNS** | 10.x.x.1 (the bridge node) |
+
+### Node-Specific IP Addressing
+
+Each mesh node gets a unique IP address based on its Node ID:
+```
+IP = 10.(NodeID >> 8).(NodeID & 0xFF).1
+```
+
+Example: If Node ID is `0x1A2B`, the AP IP would be `10.26.43.1`
+
+Connected clients receive IPs in the same subnet, typically starting from `.2`
+
+## Connection Limits
+
+The number of devices that can connect simultaneously depends on the platform:
+
+| Platform | Max Connections | Notes |
+|----------|----------------|-------|
+| **ESP32** | 10 (default) | Configurable via `MAX_CONN` |
+| **ESP8266** | 4 (default) | Configurable via `MAX_CONN` |
+
+**Important**: Mesh nodes also count toward this limit! If 3 mesh nodes are connected to a bridge, only 7 slots remain for external devices on ESP32 (or 1 on ESP8266).
+
+## Step-by-Step Connection Guide
+
+### 1. Verify Bridge is Running
+
+Check the serial output for these messages:
+```
+init(): Mesh channel set to X
+apInit(): AP configured - SSID: YourMeshName, Channel: X, IP: 10.x.x.1
+apInit(): AP active - Max connections: 10
+```
+
+### 2. Connect Your Device
+
+#### On Android:
+1. Open WiFi settings
+2. Look for network with your MESH_PREFIX name
+3. Enter your MESH_PASSWORD
+4. Wait for connection (may take 5-10 seconds)
+5. Check IP address (should be 10.x.x.x)
+
+#### On Windows 11:
+1. Click WiFi icon in system tray
+2. Find network with your MESH_PREFIX name
+3. Click "Connect"
+4. Enter your MESH_PASSWORD
+5. Open Command Prompt and run `ipconfig` to verify IP
+
+#### On macOS:
+1. Click WiFi icon in menu bar
+2. Select network with your MESH_PREFIX name
+3. Enter your MESH_PASSWORD
+4. Open Terminal and run `ifconfig` to verify IP
+
+#### On Linux:
+1. Use NetworkManager GUI or command line:
+   ```bash
+   nmcli device wifi connect "FishFarmMesh" password "securepass"
+   ```
+2. Verify connection:
+   ```bash
+   ip addr show
+   ```
+
+### 3. Test Connectivity
+
+Once connected, test basic connectivity:
+
+```bash
+# Ping the bridge/gateway
+ping 10.x.x.1
+
+# Check if you got an IP via DHCP
+# Windows: ipconfig
+# Linux/Mac: ifconfig or ip addr
+
+# Try to reach other mesh nodes (if you know their IPs)
+ping 10.y.y.1
+```
+
+## Troubleshooting
+
+### Can't See the SSID
+
+**Possible Causes:**
+1. Bridge hasn't finished initializing (wait 10-15 seconds after boot)
+2. Channel conflict with nearby WiFi networks
+3. WiFi range issue
+4. AP not properly started
+
+**Solutions:**
+1. Check serial output for "AP configured" message
+2. Ensure `CONNECTION` debug level is enabled:
+   ```cpp
+   mesh.setDebugMsgTypes(ERROR | STARTUP | CONNECTION);
+   ```
+3. Try power cycling the bridge
+4. Check if the AP is hidden:
+   ```cpp
+   // In your sketch, ensure:
+   mesh.init(MESH_PREFIX, MESH_PASSWORD, &scheduler, MESH_PORT, 
+             WIFI_AP_STA, channel, 0);  // 0 = not hidden
+   ```
+
+### Can Connect But Don't Get IP Address
+
+**Possible Causes:**
+1. DHCP server not initialized
+2. Too many devices connected (limit reached)
+3. IP conflict
+4. WiFi stack timing issue
+
+**Solutions:**
+1. Disconnect and reconnect after 10 seconds
+2. Check serial output for connection count
+3. Try rebooting the bridge node
+4. Ensure you're using the latest painlessMesh version with DHCP fixes
+
+### Connection Drops Frequently
+
+**Possible Causes:**
+1. Channel change during mesh discovery
+2. Weak signal strength
+3. Network congestion
+4. Too many mesh topology changes
+
+**Solutions:**
+1. This is normal during initial mesh formation when channels are being discovered
+2. After 30-60 seconds, the mesh should stabilize on one channel
+3. Move closer to the bridge node
+4. Use a fixed channel if you know your router's channel:
+   ```cpp
+   mesh.init(MESH_PREFIX, MESH_PASSWORD, &scheduler, MESH_PORT, 
+             WIFI_AP_STA, 6);  // Force channel 6
+   ```
+
+### Can't Access Internet
+
+**This is expected behavior!** Regular mesh nodes don't provide internet routing by default.
+
+**Options for Internet Access:**
+
+1. **Use Shared Gateway Mode**: All nodes connect to router
+   ```cpp
+   mesh.initAsSharedGateway(MESH_PREFIX, MESH_PASSWORD,
+                            ROUTER_SSID, ROUTER_PASSWORD,
+                            &scheduler, MESH_PORT);
+   ```
+
+2. **Connect to the Router**: Connect your device to the router WiFi instead, then communicate with mesh nodes via the bridge
+
+3. **Custom Routing**: Implement custom NAT/routing on the bridge (advanced)
+
+## Advanced: Using with Test Tools
+
+### ESPping or Similar Tools
+
+If you're using tools like ESPping (https://github.com/dvarrel/ESPping) to debug mesh connectivity:
+
+1. Connect the test device to the mesh AP
+2. You'll get an IP in the 10.x.x.x range
+3. You can now ping mesh nodes directly:
+   ```bash
+   ping 10.x.x.1  # The bridge you're connected to
+   ```
+4. To find other mesh nodes, check the bridge's serial output for their IPs
+
+### Network Scanners
+
+Tools like `nmap`, `arp-scan`, or Android apps like "Network Analyzer" can help:
+
+```bash
+# Scan the mesh network
+sudo nmap -sn 10.x.x.0/24
+
+# Or use arp-scan
+sudo arp-scan --interface=wlan0 10.x.x.0/24
+```
+
+### Packet Analysis
+
+If you need to capture mesh traffic:
+
+1. Connect your computer to the mesh AP
+2. Use Wireshark or tcpdump to capture packets
+3. Filter for TCP port 5555 (default mesh port)
+   ```
+   tcp.port == 5555
+   ```
+
+## Example Debug Session
+
+Here's a complete example of connecting and debugging:
+
+```bash
+# 1. Connect to mesh AP
+nmcli device wifi connect "FishFarmMesh" password "securepass"
+
+# 2. Check your IP
+ip addr show wlan0
+# Should show: inet 10.26.43.2/24
+
+# 3. Ping the gateway (bridge)
+ping -c 3 10.26.43.1
+# Should get replies
+
+# 4. Check DHCP lease
+cat /var/lib/NetworkManager/dhclient-*.lease
+# Shows lease details from 10.26.43.1
+
+# 5. Scan for other mesh nodes
+sudo nmap -sn 10.0.0.0/8 --exclude 10.26.43.2
+# May find other nodes on 10.x.x.1 addresses
+
+# 6. Try connecting to mesh TCP port
+nc -v 10.26.43.1 5555
+# Should connect if node is accepting connections
+```
+
+## Security Considerations
+
+### Important Warnings
+
+1. **Don't use weak passwords**: The mesh password protects your entire network
+2. **Change default credentials**: Always change from example values like "whateverYouLike"
+3. **No internet isolation**: External devices on mesh AP can potentially communicate with all mesh nodes
+4. **Production vs. Debug**: Consider disabling external connections in production:
+   ```cpp
+   // Limit max connections to only mesh nodes
+   mesh.init(MESH_PREFIX, MESH_PASSWORD, &scheduler, MESH_PORT, 
+             WIFI_AP_STA, channel, 0, 4);  // Max 4 on ESP8266
+   ```
+
+### Best Practices
+
+1. **Use strong passwords**: At least 8 characters, mixed case, numbers
+2. **Monitor connections**: Log when devices connect/disconnect
+3. **Implement timeouts**: Automatically disconnect idle external devices
+4. **Network segmentation**: Use VLANs if possible for mesh vs. debug traffic
+
+## Related Documentation
+
+- [Bridge Setup Guide](../BRIDGE_TO_INTERNET.md)
+- [Shared Gateway Mode](../api/shared-gateway.md)
+- [Common Issues](common-issues.md)
+- [ESP32-C6 Compatibility](ESP32_C6_COMPATIBILITY.md)
+
+## Changelog
+
+- **Unreleased**: Initial documentation for external device connections
+- Added DHCP server initialization fixes for ESP32
+- Improved AP restart timing for channel changes

package/examples/bridge/bridge.ino

@@ -16,6 +16,29 @@
 //   - Enables nodes to implement failover and queueing logic
 //
 // For more details, see BRIDGE_TO_INTERNET.md
+//
+// EXTERNAL DEVICE CONNECTIONS:
+// ----------------------------
+// External devices (phones, computers) can connect to the bridge's WiFi
+// AP for debugging and testing purposes. The AP will broadcast the mesh
+// SSID (e.g., "whateverYouLike") with the configured password.
+//
+// Connection details:
+// - SSID: Your MESH_PREFIX value
+// - Password: Your MESH_PASSWORD value
+// - IP Range: 10.x.x.x (automatically assigned via DHCP)
+// - Gateway: 10.x.x.1 (the bridge node itself)
+//
+// Note: ESP32 AP mode supports up to 10 concurrent connections by default,
+// ESP8266 supports up to 4. If mesh nodes are already connected, fewer
+// slots will be available for external devices.
+//
+// Troubleshooting external connections:
+// 1. Ensure the bridge has successfully initialized (check serial output)
+// 2. Wait a few seconds after boot for the AP to fully start
+// 3. Check for channel conflicts with other WiFi networks
+// 4. Try forgetting the network on your device and reconnecting
+// 5. Monitor serial output with CONNECTION debug level enabled
 //************************************************************
 #include "painlessMesh.h"