@alteriom/painlessmesh 1.9.5 → 1.9.7

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"
 

package/examples/bridge_failover/bridge_failover.ino

@@ -5,6 +5,30 @@
 // When the primary bridge loses Internet connectivity, nodes automatically
 // hold an election to select a new bridge based on router signal strength.
 //
+// EXTERNAL DEVICE CONNECTIONS FOR DEBUGGING:
+// -------------------------------------------
+// You can connect phones, computers, or test devices to the mesh network
+// for debugging purposes. The bridge node broadcasts the mesh SSID as a
+// WiFi Access Point.
+//
+// Connection details:
+// - SSID: "FishFarmMesh" (or your MESH_PREFIX value)
+// - Password: "securepass" (or your MESH_PASSWORD value)
+// - IP Range: 10.x.x.x/24 (automatically assigned via DHCP)
+// - Gateway: 10.x.x.1 (the bridge node itself)
+//
+// Important notes:
+// 1. ESP32 supports up to 10 concurrent AP connections (ESP8266: 4)
+// 2. Each mesh node connection uses one slot, leaving fewer for external devices
+// 3. After boot, wait 5-10 seconds for the AP to fully initialize
+// 4. If you can't connect, try these troubleshooting steps:
+//    - Check serial output for "AP configured" message
+//    - Verify the channel matches (bridge auto-detects router's channel)
+//    - Forget the network on your device and reconnect
+//    - Check for WiFi channel conflicts with other networks
+// 5. External devices get DHCP but have no internet routing by default
+//    (they can only communicate with the mesh network itself)
+//
 // IMPORTANT - UNDERSTANDING INTERNET CONNECTIVITY:
 // ================================================
 // The mesh.hasInternetConnection() method checks if a GATEWAY (bridge) node
@@ -15,6 +39,9 @@
 //
 // To send data to the Internet from a regular node:
 //   1. Use mesh.sendToInternet() to route through a gateway
+//      - Call mesh.enableSendToInternet() on the sending node after mesh.init()
+//      - Bridge nodes (this example) do NOT need enableSendToInternet() - they route automatically
+//      - See examples/sendToInternet/sendToInternet.ino for complete usage
 //   2. Use initAsSharedGateway() so all nodes have router access
 //      NOTE: initAsSharedGateway() requires ROUTER credentials:
 //      mesh.initAsSharedGateway(MESH_PREFIX, MESH_PASSWORD,

package/examples/sendToInternet/sendToInternet.ino

@@ -24,9 +24,27 @@
 // - Smart home sensors reporting to home automation servers
 //
 // Prerequisites:
-// - At least one node must be a bridge/gateway with Internet access
-// - OR use initAsSharedGateway() so all nodes have Internet
-// - Enable sendToInternet() after mesh.init(): mesh.enableSendToInternet()
+//
+// 1. GATEWAY SETUP (Choose one approach):
+//
+//    Option A - Dedicated Bridge (Recommended):
+//    - Use initAsBridge() on ONE node (see examples/bridge/bridge.ino)
+//    - The bridge node automatically handles Internet routing
+//
+//    Option B - Shared Gateway (All nodes have router access):
+//    - Use initAsSharedGateway() on ALL nodes (see examples/sharedGateway/sharedGateway.ino)
+//    - Requires ROUTER_SSID and ROUTER_PASSWORD on every node
+//    - All nodes connect directly to the router for Internet access
+//
+//    Option C - Failover Bridge (High Availability):
+//    - Use bridge_failover example unchanged (see examples/bridge_failover/bridge_failover.ino)
+//    - Automatically elects backup bridges if primary fails
+//    - Works as-is without any modifications needed!
+//
+// 2. SENDING NODE SETUP:
+//    - Call mesh.enableSendToInternet() AFTER mesh.init() on nodes that will SEND requests
+//    - Bridge nodes do NOT need to call enableSendToInternet() - they route automatically
+//    - This example shows how to enable it in the setup() function below
 //
 // For Callmebot WhatsApp API:
 // - Get your API key from https://www.callmebot.com/blog/free-api-whatsapp-messages/

package/library.json

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

package/library.properties

@@ -1,5 +1,5 @@
 name=Alteriom PainlessMesh
-version=1.9.5
+version=1.9.7
 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.5",
+  "version": "1.9.7",
   "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",
@@ -39,11 +39,11 @@
     "url": "https://github.com/Alteriom/painlessMesh/issues"
   },
   "devDependencies": {
-    "@alteriom/mqtt-schema": "^0.7.3",
-    "@eslint/js": "^9.0.0",
+    "@alteriom/mqtt-schema": "^0.8.0",
+    "@eslint/js": "^9.39.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "prettier": "^3.0.0"
+    "prettier": "^3.7.4"
   },
   "scripts": {
     "test": "run-parts --regex catch_ bin/ || echo 'Tests completed'",

package/src/AlteriomPainlessMesh.h

@@ -29,10 +29,10 @@
 /**
  * @brief AlteriomPainlessMesh library version information
  */
-#define ALTERIOM_PAINLESS_MESH_VERSION "1.8.13"
+#define ALTERIOM_PAINLESS_MESH_VERSION "1.9.7"
 #define ALTERIOM_PAINLESS_MESH_VERSION_MAJOR 1
-#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 8
-#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 13
+#define ALTERIOM_PAINLESS_MESH_VERSION_MINOR 9
+#define ALTERIOM_PAINLESS_MESH_VERSION_PATCH 7
 
 /**
  * @brief Library description and usage information