@alteriom/painlessmesh 1.7.2 → 1.7.3

package/CHANGELOG.md

@@ -19,6 +19,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - TBD
 
+## [1.7.3] - 2025-10-16
+
+### Fixed
+
+- **Router Memory Safety**: Replaced dangerous escalating memory allocation workaround with safe pre-calculated capacity
+  - Removed static `baseCapacity` variable that grew indefinitely (512B → 20KB)
+  - Implemented single-allocation strategy with pre-calculated capacity based on message size and nesting depth
+  - Added 8KB safety cap to protect ESP8266 devices from OOM crashes
+  - Support for both ArduinoJson v6 and v7 with version-aware capacity calculation
+
+### Performance
+
+- **Small messages (50B)**: +512B predictable overhead (vs. variable 512B-20KB in v1.7.0)
+- **Medium messages (500B)**: -3596B saved by eliminating retry allocations
+- **Large messages (2KB)**: -17KB saved by preventing escalation to 20KB
+
+### Added
+
+- **Tests**: New comprehensive memory safety test suite (`test/catch/catch_router_memory.cpp`)
+  - Simple message parsing tests
+  - Deeply nested JSON structure tests (10+ levels)
+  - Oversized message handling tests
+  - Predictable capacity allocation verification
+  - 14 new assertions, all passing
+
+### Documentation
+
+- **CODE_REFACTORING_RECOMMENDATIONS.md**: Comprehensive code analysis document with 8 prioritized refactoring recommendations (P0-P3)
+- **PATCH_v1.7.3.md**: Complete release notes with before/after comparison, performance metrics, and migration guide
+
+### Technical Details
+
+- Fixes issue #521: ArduinoJson copy constructor segmentation fault workaround
+- All 710+ test assertions passing across 18 test suites
+- Docker-based testing on Linux x86_64 with CMake + Ninja
+
 ## [1.7.2] - 2025-10-15
 
 ### Fixed
@@ -26,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **NPM Configuration**: Updated `.npmrc` to use public NPM registry instead of GitHub Packages
 - **Dependencies**: Moved `@alteriom/mqtt-schema` back to `devDependencies` now that it's publicly available
 - **Automated Releases**: Fixed npm install failures during automated release workflow
-- **Package Availability**: Package now accessible at https://www.npmjs.com/package/@alteriom/mqtt-schema
+- **Package Availability**: Package now accessible at <https://www.npmjs.com/package/@alteriom/mqtt-schema>
 
 ## [1.7.1] - 2025-10-15
 
@@ -52,6 +88,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### Phase 2: Broadcast OTA & MQTT Status Bridge
 
 **Broadcast OTA Distribution**
+
 - ✨ **Broadcast Mode OTA**: True mesh-wide firmware distribution with ~98% network traffic reduction for 50+ node meshes
 - 📡 **Parallel Updates**: All nodes receive firmware chunks simultaneously instead of sequential unicast
 - ⚡ **Performance**: ~50x faster for 50-node mesh, ~100x faster for 100-node mesh
@@ -60,6 +97,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 📊 **Scalability**: Efficiently handles 50-100+ node meshes with minimal overhead
 
 **MQTT Status Bridge**
+
 - 🌉 **Professional Monitoring**: Complete MQTT bridge for publishing mesh status to monitoring tools
 - 📈 **Multiple Topics**: Publishes topology, metrics, alerts, and per-node status
 - 🔗 **Tool Integration**: Ready for Grafana, InfluxDB, Prometheus, Home Assistant, Node-RED
@@ -157,14 +195,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### ⚙️ Configuration Changes
 
 **library.json**
+
 - Added `"srcDir": "src"` for explicit source directory
 - Added `"includeDir": "src"` for explicit include directory
 - Removed conflicting `"export": {"include": "src"}` section
 
 **library.properties**
+
 - Updated `includes=painlessMesh.h` (was AlteriomPainlessMesh.h)
 
 **package.json**
+
 - Renamed `build` → `dev:build` (prevents auto-execution)
 - Renamed `prebuild` → `dev:prebuild` (prevents auto-execution)
 - Updated to @alteriom/mqtt-schema v0.5.0
@@ -172,6 +213,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 📊 Performance Improvements
 
 **Broadcast OTA Performance**
+
 - **Network Traffic**: 90% reduction (10 nodes), 98% reduction (50 nodes), 99% reduction (100 nodes)
 - **Update Speed**: ~N times faster (parallel vs sequential)
 - **Example**: 150-chunk firmware to 50 nodes
@@ -180,6 +222,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - **Savings: 98% (7,350 transmissions)**
 
 **Memory Impact**
+
 - Broadcast OTA: +2-5KB per node (chunk tracking)
 - MQTT Bridge: +5-8KB (root node only)
 - Minimal overhead for ESP32, acceptable for ESP8266
@@ -205,6 +248,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 **No migration required** for existing code. To adopt new features:
 
 **Enable Broadcast OTA:**
+
 ```cpp
 // Before (v1.6.x)
 mesh.offerOTA(role, hw, md5, parts, false, false, true);
@@ -215,6 +259,7 @@ mesh.offerOTA(role, hw, md5, parts, false, true, true);
 ```
 
 **Add MQTT Status Bridge:**
+
 ```cpp
 #include "examples/bridge/mqtt_status_bridge.hpp"
 
@@ -277,8 +322,8 @@ This release includes contributions from Phase 2 implementation, bug fixes disco
   - Release validation with multi-file version consistency
 - **Arduino IDE Support**: Added keywords.txt for syntax highlighting
 - **Distribution Documentation**: Complete guides for all publication channels
-  - RELEASE_SUMMARY.md template for release notes
-  - TRIGGER_RELEASE.md for step-by-step release instructions
+  - docs/archive/RELEASE_SUMMARY.md template for release notes (archived)
+  - docs/archive/TRIGGER_RELEASE.md for step-by-step release instructions (archived, see RELEASE_GUIDE.md)
   - Enhanced RELEASE_GUIDE.md with comprehensive publication workflow
 - **Version Management**: Enhanced bump-version script
   - Updates all three version files simultaneously (library.properties, library.json, package.json)
@@ -286,6 +331,7 @@ This release includes contributions from Phase 2 implementation, bug fixes disco
   - Clear instructions for NPM and GitHub Packages publication
 
 ### Changed  
+
 - **Library Name**: Updated from "Painless Mesh" to "Alteriom PainlessMesh" for Arduino Library Manager
 - **Release Process**: Streamlined to support multiple package managers
   - Single commit with "release:" prefix triggers full publication pipeline
@@ -301,6 +347,7 @@ This release includes contributions from Phase 2 implementation, bug fixes disco
   - Troubleshooting guides for each distribution channel
 
 ### Fixed
+
 - **NPM Publishing**: Fixed registry configuration issues that prevented NPM publication
 - **GitHub Pages**: Improved workflow to handle cases where Pages is not configured
 - **PlatformIO Build**: Fixed include paths in improved_sensor_node.ino example
@@ -311,6 +358,7 @@ This release includes contributions from Phase 2 implementation, bug fixes disco
 ## [1.6.0] - 2025-09-29
 
 ### Added
+
 - Enhanced Alteriom-specific package documentation and examples
 - Updated repository URLs and metadata for Alteriom fork
 - Improved release process documentation
@@ -319,11 +367,13 @@ This release includes contributions from Phase 2 implementation, bug fixes disco
 - Comprehensive Alteriom package documentation and quick start guide
 
 ### Changed  
+
 - Migrated from deprecated `actions/create-release@v1` to GitHub CLI for releases
 - Updated library.properties and library.json to reflect Alteriom ownership
 - Enhanced package descriptions to highlight Alteriom extensions
 
 ### Fixed
+
 - Fixed deprecated GitHub Actions in release workflow  
 - Corrected undefined variable references in upload workflow steps
 - Updated repository URLs from GitLab to GitHub in library files
@@ -331,6 +381,7 @@ This release includes contributions from Phase 2 implementation, bug fixes disco
 ## [1.5.6] - Current Release
 
 ### Features
+
 - painlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices
 - Automatic routing and network management
 - JSON-based messaging system
@@ -339,16 +390,19 @@ This release includes contributions from Phase 2 implementation, bug fixes disco
 - Sensor network patterns for IoT applications
 
 ### Platforms Supported
+
 - ESP32 (espressif32)
 - ESP8266 (espressif8266)
 
 ### Dependencies
+
 - ArduinoJson ^7.4.2
 - TaskScheduler ^3.8.5
 - AsyncTCP ^3.4.7 (ESP32)
 - ESPAsyncTCP ^2.0.0 (ESP8266)
 
 ### Alteriom Extensions
+
 - SensorPackage for environmental monitoring
 - CommandPackage for device control
 - StatusPackage for health monitoring
@@ -378,4 +432,4 @@ This project follows [Semantic Versioning](https://semver.org/):
 - **MINOR** version when you add functionality in a backwards compatible manner  
 - **PATCH** version when you make backwards compatible bug fixes
 
-Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.
+Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

package/README.md

@@ -7,7 +7,8 @@
 [![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)
 [![Release](https://github.com/Alteriom/painlessMesh/actions/workflows/release.yml/badge.svg)](https://github.com/Alteriom/painlessMesh/actions/workflows/release.yml)
-[![GitHub release](https://img.shields.io/github/release/Alteriom/painlessMesh.svg)](https://github.com/Alteriom/painlessMesh/releases)
+[![GitHub release](https://img.shields.io/github/v/release/Alteriom/painlessMesh?label=version)](https://github.com/Alteriom/painlessMesh/releases)
+[![NPM Version](https://img.shields.io/npm/v/@alteriom/painlessmesh?label=npm)](https://www.npmjs.com/package/@alteriom/painlessmesh)
 [![PlatformIO Registry](https://badges.registry.platformio.org/packages/alteriom/library/painlessMesh.svg)](https://registry.platformio.org/libraries/alteriom/painlessMesh)
 [![Arduino Library Manager](https://img.shields.io/badge/Arduino-Library%20Manager-blue.svg)](https://www.arduino.cc/reference/en/libraries/alteriompainlessmesh/)
 
@@ -33,12 +34,14 @@ All packages provide type-safe serialization, automatic JSON conversion, and mes
 #### 🚀 Phase 2 Features (v1.7.0+)
 
 **Broadcast OTA Distribution**
+
 - 📡 **98% Network Traffic Reduction** for 50+ node meshes
 - ⚡ **Parallel Firmware Updates** - All nodes receive simultaneously
 - 🔄 **Backward Compatible** - Single parameter enables broadcast mode
 - 📊 **Scales to 100+ Nodes** efficiently
 
 **MQTT Status Bridge**
+
 - 🌉 **Professional Monitoring** - Grafana, InfluxDB, Prometheus integration
 - 📈 **Real-Time Topology** - Complete mesh visualization over MQTT
 - 🎯 **Production Ready** - Enterprise IoT and commercial deployments
@@ -56,10 +59,12 @@ The MQTT bridge enables bidirectional communication between MQTT brokers and mes
 - **Event Notifications** - Track node connections, disconnections, and mesh topology changes
 
 **Documentation:**
+
 - 📖 [MQTT Bridge Commands Reference](docs/MQTT_BRIDGE_COMMANDS.md) - Complete command API documentation
 - 🔧 [OTA Commands Reference](docs/OTA_COMMANDS_REFERENCE.md) - Over-the-air firmware updates
 
 **Examples:**
+
 - 🌉 [MQTT Command Bridge](examples/mqttCommandBridge/mqttCommandBridge.ino) - Gateway bridge with bidirectional MQTT-mesh routing
 - 📡 [Mesh Command Node](examples/alteriom/mesh_command_node.ino) - Node that receives and handles MQTT commands
 
@@ -178,6 +183,7 @@ void receivedCallback(uint32_t from, String& msg) {
 ## Key Features
 
 ### Core Features
+
 - **🔄 Automatic Mesh Formation** - Nodes discover and connect automatically
 - **📡 Self-Healing Network** - Adapts when nodes join/leave
 - **⏰ Time Synchronization** - Coordinated actions across all nodes  
@@ -187,6 +193,7 @@ void receivedCallback(uint32_t from, String& msg) {
 - **🛡️ Memory Efficient** - Optimized for resource-constrained devices
 
 ### Advanced Features (v1.7.0+)
+
 - **📡 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
@@ -210,6 +217,7 @@ void receivedCallback(uint32_t from, String& msg) {
 ## Development
 
 ### Building from Source
+
 ```bash
 git clone https://github.com/Alteriom/painlessMesh.git
 cd painlessMesh
@@ -220,6 +228,7 @@ run-parts --regex catch_ bin/  # Run tests
 ```
 
 ### Requirements
+
 - **ESP32/ESP8266**: Arduino Core 2.0.0+
 - **Dependencies**: ArduinoJson 6.x, TaskScheduler 3.x  
 - **Development**: CMake, Ninja, Boost (for desktop testing)
@@ -229,12 +238,14 @@ run-parts --regex catch_ bin/  # Run tests
 painlessMesh features a state-of-the-art automated CI/CD pipeline:
 
 **🔄 Continuous Integration:**
+
 - Automated builds on gcc/clang with strict warnings
 - Cross-platform testing (Arduino CLI, PlatformIO)
 - Code quality and formatting validation
 - Comprehensive test suite execution
 
 **🚀 Automated Releases:**
+
 - Semantic versioning with automated tagging
 - GitHub Releases with changelog generation
 - Library package distribution
@@ -242,6 +253,7 @@ painlessMesh features a state-of-the-art automated CI/CD pipeline:
 - Arduino Library Manager & PlatformIO Registry integration
 
 **📋 Release Management:**
+
 ```bash
 # Bump version and prepare release
 ./scripts/bump-version.sh patch  # or minor, major
@@ -321,16 +333,19 @@ You can tip me using ko-fi:
 - **[❓ FAQ](https://alteriom.github.io/painlessMesh/#/troubleshooting/faq)** - Frequently asked questions
 
 **📖 Tutorials & Examples:**
+
 - **[Basic Examples](docs/tutorials/basic-examples.md)** - Essential patterns and techniques
 - **[Custom Packages](docs/tutorials/custom-packages.md)** - Type-safe message handling
 - **[Sensor Networks](docs/tutorials/sensor-networks.md)** - IoT sensor network patterns
 
 **🚀 Alteriom Extensions:**
+
 - **[Alteriom Overview](docs/alteriom/overview.md)** - Production-ready IoT packages
 - **[Sensor Packages](docs/alteriom/sensor-packages.md)** - Environmental monitoring
 - **[Command System](docs/alteriom/command-system.md)** - Device control and automation
 
 **🔧 Troubleshooting:**
+
 - **[Common Issues](docs/troubleshooting/common-issues.md)** - Solutions to frequent problems
 - **[FAQ](docs/troubleshooting/faq.md)** - Frequently asked questions
 - **[Debugging Guide](docs/troubleshooting/debugging.md)** - Tools and techniques
@@ -467,8 +482,7 @@ Note: The mesh must be on the same WiFi channel as the AP.
 Change the internal log level. List of types defined in Logger.hpp:
 ERROR | MESH_STATUS | CONNECTION | SYNC | COMMUNICATION | GENERAL | MSG_TYPES | REMOTE
 
-
-# Funding 
+# Funding
 
 Most development of painlessMesh has been done as a hobby, but some specific features have been funded by the companies listed below:
 

package/docs/README.md

@@ -1,62 +1,114 @@
-# painlessMesh Documentation
+# 📚 AlteriomPainlessMesh Documentation
 
-Welcome to the comprehensive documentation for painlessMesh - a user-friendly ESP8266/ESP32 mesh networking library that automatically handles routing and network management.
+Welcome to the comprehensive documentation for the Alteriom fork of painlessMesh - a user-friendly ESP8266/ESP32 mesh networking library with advanced OTA updates, MQTT integration, and structured IoT packages.
 
-## Documentation Structure
+## 🌟 What's New in Alteriom Fork
+
+- **Broadcast OTA Distribution** - 98% network traffic reduction for large meshes
+- **MQTT Status Bridge** - Enterprise monitoring integration (Grafana, InfluxDB)
+- **Structured Packages** - SensorPackage, CommandPackage, StatusPackage
+- **Enhanced CI/CD** - Automated releases to NPM, PlatformIO, Arduino Library Manager
+
+## 📖 Documentation Structure
 
 ### Getting Started
+
 - [Quick Start Guide](getting-started/quickstart.md) - Get up and running in minutes
 - [Installation](getting-started/installation.md) - Detailed installation instructions
 - [First Mesh Network](getting-started/first-mesh.md) - Your first working mesh
 
 ### Architecture & Design  
+
 - [Mesh Architecture](architecture/mesh-architecture.md) - How painlessMesh works internally
 - [Plugin System](architecture/plugin-system.md) - Understanding the plugin architecture
 - [Message Routing](architecture/routing.md) - Message routing algorithms and strategies
 - [Time Synchronization](architecture/time-sync.md) - Mesh-wide time synchronization
 
 ### API Reference
+
 - [Core API](api/core-api.md) - Main painlessMesh class methods
 - [Plugin API](api/plugin-api.md) - Creating custom packages and plugins
 - [Configuration](api/configuration.md) - Configuration options and constants
 - [Callbacks](api/callbacks.md) - Event handling and callbacks
 
 ### Tutorials & Examples
+
 - [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
 
 ### Alteriom Extensions
+
 - [Alteriom Overview](alteriom/overview.md) - Alteriom-specific functionality
 - [Sensor Packages](alteriom/sensor-packages.md) - Environmental sensor data handling
 - [Command System](alteriom/command-system.md) - Device command and control
 - [Status Monitoring](alteriom/status-monitoring.md) - Device health and diagnostics
 
+### 📡 MQTT Integration
+
+- **[MQTT Bridge Commands](MQTT_BRIDGE_COMMANDS.md)** - Complete MQTT command API
+- **[MQTT Bridge Implementation](MQTT_BRIDGE_IMPLEMENTATION_SUMMARY.md)** - Implementation details
+- **[MQTT Schema Compliance](MQTT_SCHEMA_COMPLIANCE.md)** - Schema validation
+- **[OTA Commands Reference](OTA_COMMANDS_REFERENCE.md)** - OTA update commands
+- **[Mesh Topology Guide](MESH_TOPOLOGY_GUIDE.md)** - Topology reporting over MQTT
+
 ### Advanced Topics
+
 - [Performance Optimization](advanced/performance.md) - Optimizing mesh performance
 - [Memory Management](advanced/memory.md) - Managing ESP8266/ESP32 memory constraints
 - [Security Considerations](advanced/security.md) - Securing your mesh network
 - [OTA Updates](advanced/ota.md) - Over-the-air firmware updates in mesh
 
 ### Troubleshooting
+
 - [Common Issues](troubleshooting/common-issues.md) - Solutions to frequent problems
 - [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
 
 ### Development
+
 - [Contributing](development/contributing.md) - How to contribute to painlessMesh
 - [Building & Testing](development/building.md) - Development environment setup
 - [Documentation](development/documentation.md) - Contributing to documentation
 - [Release Process](development/releases.md) - Understanding releases and versioning
+- **[Docker Testing](development/DOCKER_TESTING.md)** - Containerized testing environment
+- **[Testing Summary](development/TESTING_SUMMARY.md)** - Complete test suite overview
+- **[Arduino Compliance](development/ARDUINO_COMPLIANCE_SUMMARY.md)** - Arduino Library Manager standards
+- **[PlatformIO Usage](development/PLATFORMIO_USAGE.md)** - PlatformIO integration guide
+
+### 📦 Releases & Changelogs
+
+- **[Feature History](releases/FEATURE_HISTORY.md)** - ⭐ Consolidated Phase 1 & 2 development history
+- **[Release Notes v1.7.0](releases/RELEASE_NOTES_1.7.0.md)** - Detailed v1.7.0 release notes
+- **[CHANGELOG](../CHANGELOG.md)** - Complete version history
+- **[RELEASE_GUIDE](../RELEASE_GUIDE.md)** - Maintainer release process
+- [Phase 1 Details](releases/PHASE1_SUMMARY.md) - v1.6.x detailed summary (archived)
+- [Phase 2 Details](releases/PHASE2_SUMMARY.md) - v1.7.x detailed summary (archived)
+
+### 🗂️ Core Documentation (Root)
+
+- **[Main README](../README.md)** - Project overview and quick start
+- **[CONTRIBUTING](../CONTRIBUTING.md)** - Contribution guidelines
+- **[LICENSE](../LICENSE)** - LGPL-3.0 license terms
+
+### 🗃️ Historical & Archive
+
+- **[Archive](archive/)** - Historical bug fixes and obsolete documentation
+  - Bug fix documentation (SCONS, VECTOR, LIBRARY fixes)
+  - Legacy deployment guides
+  - Superseded release documentation
+
+### 🚀 Improvements & Enhancements
 
-### Improvements & Proposals
-- [Library Improvements](improvements/README.md) - Overview of performance and security enhancements
-- **[Feature Proposals: OTA & Status](improvements/FEATURE_PROPOSALS.md)** 🆕 - Comprehensive proposals for OTA distribution and mesh status monitoring
-  - [Full Analysis](improvements/ota-and-status-enhancements.md) - Detailed exploration of 10+ enhancement options
-  - [Quick Reference](improvements/ota-status-quick-reference.md) - TL;DR with decision guides
-  - [Architecture Diagrams](improvements/ota-status-architecture-diagrams.md) - Visual diagrams of each option
+- **[Improvements Overview](improvements/README.md)** - Complete guide to library enhancements
+- **[OTA & Status Enhancements](improvements/OTA_STATUS_ENHANCEMENTS.md)** 📋 - Complete reference for all options
+  - ✅ Phase 1 (v1.6.x): Compressed OTA + Enhanced Status
+  - ✅ Phase 2 (v1.7.0): Broadcast OTA + MQTT Bridge
+  - 📋 Phase 3 (Future): Progressive rollout, P2P distribution, real-time telemetry
+- **[Implementation History](improvements/IMPLEMENTATION_HISTORY.md)** 🔧 - Technical details for Phases 1-2
+- **[Future Proposals](improvements/FUTURE_PROPOSALS.md)** 🚀 - Phase 3+ roadmap and specifications
 
 ## Quick Links
 
@@ -75,4 +127,4 @@ Welcome to the comprehensive documentation for painlessMesh - a user-friendly ES
 
 ---
 
-This documentation is maintained by the painlessMesh community. Contributions are welcome! See our [Documentation Contributing Guide](development/documentation.md) to get started.
+This documentation is maintained by the painlessMesh community. Contributions are welcome! See our [Documentation Contributing Guide](development/documentation.md) to get started.

package/docs/archive/DOCUSAURUS_DEPLOYMENT.md

@@ -0,0 +1,166 @@
+# GitHub Pages Deployment Guide
+
+This guide explains how to deploy the Docusaurus documentation site to GitHub Pages.
+
+## 🚀 Deployment Steps
+
+### 1. Enable GitHub Pages
+
+1. Go to your repository on GitHub: `https://github.com/Alteriom/painlessMesh`
+2. Click **Settings** tab
+3. Scroll down to **Pages** section
+4. Under **Source**, select **GitHub Actions**
+5. Save the changes
+
+### 2. Commit and Push Changes
+
+```bash
+# Add all changes
+git add .
+
+# Commit the Docusaurus setup
+git commit -m "feat: Add Docusaurus documentation site
+
+- Replace basic HTML generation with modern Docusaurus
+- Add GitHub Actions workflow for automated deployment
+- Include Alteriom package documentation
+- Integrate Doxygen API docs with user guides
+- Enable responsive design and built-in search
+
+Closes: Documentation modernization initiative"
+
+# Push to trigger deployment
+git push origin main
+```
+
+### 3. Monitor Deployment
+
+1. Go to **Actions** tab in your repository
+2. Watch the **Documentation** workflow run
+3. When complete, your site will be available at:
+   - **URL**: `https://alteriom.github.io/painlessMesh/`
+
+## 🛠️ Local Development
+
+### Start Development Server
+
+```bash
+cd website
+npm start
+```
+
+Visit: `http://localhost:3000/painlessMesh/`
+
+### Build for Production
+
+```bash
+cd website
+npm run build
+```
+
+### Test Production Build
+
+```bash
+cd website
+npm run serve
+```
+
+## 📁 Documentation Structure
+
+```
+website/
+├── docs/                          # Main documentation
+│   ├── intro.md                   # Homepage content
+│   ├── getting-started/           # Installation & quickstart
+│   ├── api/                       # API reference
+│   ├── alteriom/                  # Alteriom extensions
+│   ├── tutorials/                 # Usage examples
+│   ├── architecture/              # Technical details
+│   ├── advanced/                  # Advanced topics
+│   └── troubleshooting/           # Help & FAQ
+├── static/                        # Static assets
+│   └── api/                       # Doxygen API docs (auto-generated)
+├── docusaurus.config.ts          # Main configuration
+└── sidebars.ts                   # Navigation structure
+```
+
+## 🔄 Workflow Overview
+
+The GitHub Actions workflow:
+
+1. **Checkout** repository code
+2. **Setup Node.js** for Docusaurus
+3. **Install Doxygen** for API documentation
+4. **Generate API docs** using existing Doxygen config
+5. **Install dependencies** for Docusaurus
+6. **Integrate Doxygen** output with Docusaurus
+7. **Build site** for production
+8. **Deploy** to GitHub Pages
+
+## 🎯 Benefits Over Previous System
+
+| Feature | Old System | **New Docusaurus** |
+|---------|------------|-------------------|
+| **Search** | ❌ None | ✅ Built-in Algolia search |
+| **Mobile** | ❌ Poor responsive | ✅ Perfect mobile experience |
+| **Navigation** | ❌ Manual links | ✅ Auto-generated sidebar |
+| **Performance** | ❌ Slow page loads | ✅ Single-page app speed |
+| **Maintenance** | ❌ Manual HTML generation | ✅ Pure Markdown workflow |
+| **Link validation** | ❌ Broken links undetected | ✅ Automatic validation |
+| **Versioning** | ❌ Not supported | ✅ Multiple library versions |
+| **API integration** | ❌ Separate Doxygen site | ✅ Seamless integration |
+
+## 🔧 Customization
+
+### Adding New Pages
+
+1. Create `.md` files in appropriate `docs/` subdirectory
+2. Update `sidebars.ts` to include in navigation
+3. Commit and push - automatic deployment
+
+### Modifying Branding
+
+Edit `docusaurus.config.ts`:
+- `title`: Site title
+- `tagline`: Site description  
+- `favicon`: Icon file
+- `themeConfig.navbar`: Navigation menu
+- `themeConfig.footer`: Footer content
+
+### Custom Styling
+
+Edit `src/css/custom.css` for custom styles and branding.
+
+## 🚨 Troubleshooting
+
+### Build Fails
+
+1. Check **Actions** tab for error details
+2. Verify all referenced files exist in sidebars
+3. Ensure Markdown syntax is valid
+
+### Pages Not Deploying
+
+1. Verify **GitHub Pages** is set to **GitHub Actions**
+2. Check repository permissions
+3. Ensure workflow has **Pages write** permission
+
+### Links Broken
+
+1. Use relative paths: `../other-page`
+2. Verify file extensions: `.md` files become `.html`
+3. Check sidebar configuration matches file structure
+
+## 📞 Support
+
+For issues with:
+- **Docusaurus**: See [Docusaurus docs](https://docusaurus.io/)
+- **GitHub Actions**: Check workflow logs in Actions tab
+- **Content**: Create issues in repository
+
+## 🎉 Next Steps
+
+1. **Enable search**: Configure Algolia search index
+2. **Add analytics**: Integrate Google Analytics
+3. **Custom domain**: Set up custom domain if desired
+4. **Content migration**: Move remaining docs from `/docs` folder