@alteriom/painlessmesh 1.8.15 → 1.9.0

package/docs/releases/RELEASE_SUMMARY_v1.7.8.md

@@ -1,523 +0,0 @@
-# painlessMesh v1.7.8 Release Summary
-
-**Release Date:** November 5, 2025  
-**Version:** 1.7.8  
-**Type:** Feature Release + Bug Fixes  
-**Compatibility:** 100% backward compatible with v1.7.7
-
-## 🎯 Executive Summary
-
-Version 1.7.8 introduces MQTT Schema v0.7.3 compliance with `message_type` fields for 90% faster message classification, comprehensive documentation for bridging mesh networks to the Internet, and enhanced StatusPackage with organization and sensor configuration fields. This release also includes critical bug fixes for CI/CD pipelines, ArduinoJson API updates, and ESP8266 compatibility improvements.
-
-## 🚀 What's New
-
-### MQTT Schema v0.7.3 Compliance
-
-**Upgraded from v0.7.2 to v0.7.3** - Added `message_type` field to key packages for dramatic performance improvement:
-
-- **SensorPackage (Type 200)** - Now includes `message_type` field
-- **StatusPackage (Type 202)** - Now includes `message_type` field  
-- **CommandPackage (Type 400)** - Now includes `message_type` field
-- **Performance**: 90% faster message classification by avoiding JSON parsing
-- **Full alignment** with @alteriom/mqtt-schema v0.7.3 specification
-
-**Why This Matters:**
-- Previous versions required parsing entire JSON to determine message type
-- Now type can be read from a single field at the envelope level
-- Dramatically reduces CPU overhead on gateway/bridge nodes
-- Enables faster routing and processing in large mesh networks
-
-### BRIDGE_TO_INTERNET.md Documentation
-
-**New comprehensive guide** for bridging mesh networks to the Internet via WiFi router:
-
-**What's Covered:**
-- Complete code examples with AP+STA mode configuration
-- WiFi channel matching requirements and best practices
-- Links to working bridge examples:
-  - Basic bridge implementation
-  - MQTT bridge
-  - Web server bridge
-  - Enhanced MQTT bridge
-- Architecture diagrams and forwarding patterns
-- Troubleshooting common issues
-- Additional resources and references
-
-**Use Cases:**
-- Connect isolated mesh network to the Internet
-- Enable remote monitoring and control
-- Bridge mesh data to cloud services
-- Integrate with existing infrastructure
-
-### Enhanced StatusPackage
-
-**New organization fields** for enterprise deployments:
-- `organizationId` - Unique identifier for the organization
-- `organizationName` - Human-readable organization name
-- `organizationDomain` - DNS domain for the organization
-
-**New sensor configuration fields:**
-- `sensorTypes` - Array of sensor types available on this node
-- `sensorConfig` - JSON configuration for sensors
-- `sensorInventory` - Array of sensor identifiers
-
-**Improved JSON Structure:**
-- Sensor data uses `sensors` key (array of readings)
-- Sensor configuration uses separate keys (no key collisions)
-- CamelCase field naming convention for consistency
-- Unconditional serialization for predictable JSON structure
-
-**Benefits:**
-- Better multi-tenant support
-- Clear separation of runtime data vs configuration
-- Easier inventory management
-- Improved dashboard integration
-
-### API Design Guidelines
-
-**New documentation file:** `docs/API_DESIGN_GUIDELINES.md`
-
-**Contents:**
-- Field naming conventions (camelCase, units in field names)
-- Boolean naming patterns (`is`, `has`, `should`, `can` prefixes)
-- Time field naming with units (`_ms`, `_s`, `_us` suffixes)
-- Serialization patterns and consistency rules
-- Comprehensive validation tests
-
-**Impact:**
-- Standardizes API across all packages
-- Prevents naming inconsistencies
-- Improves developer experience
-- Facilitates code reviews
-
-### Manual Publishing Workflow
-
-**New workflow file:** `.github/workflows/manual-publish.yml`
-
-**Purpose:**
-- On-demand NPM and GitHub Packages publishing
-- Fixes cases where automated release doesn't trigger package publication
-- Configurable options for selective publishing
-
-**When to Use:**
-- Automated release workflow fails
-- Need to republish existing version
-- Testing publication process
-- Emergency package updates
-
-## 🔄 Breaking Changes
-
-### Time Field Naming Convention
-
-**BREAKING CHANGE** - Consistent unit suffixes across all packages:
-
-**Changed Fields:**
-- `collectionTimestamp` → `collectionTimestamp_ms` (milliseconds)
-- `avgResponseTime` → `avgResponseTime_us` (microseconds)
-- `estimatedTimeToFailure` → `estimatedTimeToFailure_s` (seconds)
-
-**Documentation:** See `docs/architecture/TIME_FIELD_NAMING.md` for complete details
-
-**Migration Required:**
-- Update field names in your code
-- Update JSON parsing logic
-- Update database schemas if applicable
-- Update monitoring dashboards
-
-**Why This Change:**
-- Eliminates ambiguity about time units
-- Prevents conversion errors
-- Follows industry best practices
-- Improves API clarity
-
-### StatusPackage JSON Structure
-
-**CHANGED** - Improved field organization to prevent key collisions:
-
-**Before (v1.7.7):**
-```json
-{
-  "sensors": [...],  // Runtime data
-  "sensors": {...}   // Configuration - COLLISION!
-}
-```
-
-**After (v1.7.8):**
-```json
-{
-  "sensors": [...],           // Runtime data array
-  "sensorTypes": [...],       // Configuration array
-  "sensorConfig": {...},      // Configuration object
-  "sensorInventory": [...]    // Inventory array
-}
-```
-
-**Migration Impact:**
-- Update JSON parsing code
-- No data loss - all information preserved
-- Clearer separation of concerns
-- Easier to work with
-
-## 🐛 Bug Fixes
-
-### CI Pipeline Improvements
-
-**Fixed validate-release dependency** - Made validate-release depend on CI completion:
-- Prevents release validation from running before tests complete
-- Ensures all tests pass before release can proceed
-- Improves release reliability
-
-**Impact:**
-- Fewer failed releases
-- Better CI/CD reliability
-- Catch issues earlier
-
-### ArduinoJson API Updates
-
-**Fixed deprecated API usage** throughout codebase:
-- Fixed deprecated `JsonVariant::is<JsonObject>()` calls
-- Updated to ArduinoJson 7.x compatible patterns
-- Code formatting improvements
-
-**Files Updated:**
-- Multiple package implementations
-- Bridge examples
-- Test files
-
-**Benefits:**
-- Future-proof code
-- Eliminates compiler warnings
-- Better performance with ArduinoJson 7.x
-
-### ESP8266 Compatibility
-
-**Fixed `getDeviceId()` function** in mqttTopologyTest:
-- Added proper ESP8266 implementation
-- Platform-specific device ID retrieval
-- Uses `ESP.getChipId()` for ESP8266
-- Uses `ESP.getEfuseMac()` for ESP32
-
-**Impact:**
-- mqttTopologyTest now works on ESP8266
-- Proper device identification
-- Cross-platform compatibility
-
-### MQTT Retry Logic
-
-**Fixed serialization** to include all retry fields:
-- Proper condition for including retry configuration
-- Epsilon comparison for floating-point backoff multiplier
-- Prevents missing retry configuration in JSON
-
-**Benefits:**
-- Reliable MQTT retry behavior
-- Better error handling
-- Predictable retry logic
-
-### Documentation Fixes
-
-**Multiple improvements:**
-- Fixed v1.7.7 release date in documentation
-- Added comprehensive mqtt-schema v0.7.2+ message type codes table
-- Corrected CommandPackage type number (400, not 201)
-- Enhanced Alteriom Extensions section in README
-- Added GitHub Packages authentication for npm install
-
-**Impact:**
-- Clearer documentation
-- Easier onboarding
-- Fewer support questions
-
-## 📊 Performance Impact
-
-### Memory Usage
-- **Enhanced StatusPackage:** +100-200 bytes per message (organization + sensor config fields)
-- **message_type field:** +1 byte per message (negligible)
-- **Total Overhead:** Minimal, <1% increase
-
-### Network Bandwidth
-- **Additional fields:** ~150 bytes per status message (only when used)
-- **message_type field:** +1 byte per message
-- **Impact:** Negligible for typical mesh networks
-
-### CPU Performance
-- **Message classification:** 90% faster with `message_type` field
-- **JSON parsing:** Reduced load on bridge/gateway nodes
-- **Routing:** Faster message type determination
-- **Overall:** Significant improvement for high-traffic meshes
-
-### Scalability
-- **Large Meshes (50+ nodes):** Better performance with fast message classification
-- **Gateway Nodes:** Reduced CPU load
-- **Bridge Nodes:** More efficient message routing
-- **Monitoring Systems:** Faster data processing
-
-## 📚 Documentation & Examples
-
-### New Documentation Files
-
-1. **`BRIDGE_TO_INTERNET.md`** (comprehensive guide)
-   - AP+STA mode configuration
-   - WiFi channel matching
-   - Architecture patterns
-   - Working examples
-   - Troubleshooting guide
-
-2. **`docs/API_DESIGN_GUIDELINES.md`** (API standards)
-   - Naming conventions
-   - Field patterns
-   - Serialization rules
-   - Validation tests
-
-3. **`docs/architecture/TIME_FIELD_NAMING.md`** (time field standards)
-   - Unit suffix conventions
-   - Migration guide
-   - Complete field list
-
-### Updated Documentation
-
-1. **`README.md`**
-   - Updated package descriptions
-   - Added v1.7.8 features
-   - GitHub Packages authentication
-   - Enhanced Alteriom Extensions section
-
-2. **`CHANGELOG.md`**
-   - Detailed v1.7.8 changes
-   - Migration notes
-   - Breaking changes highlighted
-
-### New Workflow Files
-
-1. **`.github/workflows/manual-publish.yml`**
-   - On-demand publishing
-   - NPM and GitHub Packages
-   - Configurable options
-
-## 🔄 Migration Guide
-
-### From v1.7.7 to v1.7.8
-
-**BREAKING CHANGES require code updates:**
-
-#### 1. Update Time Field Names
-
-**Before (v1.7.7):**
-```cpp
-MetricsPackage metrics;
-metrics.collectionTimestamp = millis();
-metrics.avgResponseTime = 150;
-```
-
-**After (v1.7.8):**
-```cpp
-MetricsPackage metrics;
-metrics.collectionTimestamp_ms = millis();  // Note: _ms suffix
-metrics.avgResponseTime_us = 150;           // Note: _us suffix
-```
-
-#### 2. Update StatusPackage JSON Parsing
-
-**Before (v1.7.7):**
-```cpp
-// Parse sensors array
-JsonArray sensorsArray = obj["sensors"];
-```
-
-**After (v1.7.8):**
-```cpp
-// Parse sensors array (unchanged)
-JsonArray sensorsArray = obj["sensors"];
-
-// Parse sensor configuration (new)
-JsonArray sensorTypes = obj["sensorTypes"];
-JsonObject sensorConfig = obj["sensorConfig"];
-JsonArray sensorInventory = obj["sensorInventory"];
-```
-
-#### 3. Optional: Add message_type to Custom Packages
-
-**Recommended for performance:**
-```cpp
-class MyPackage : public painlessmesh::plugin::BroadcastPackage {
-public:
-    uint16_t message_type = 300;  // Add this field
-    
-    MyPackage() : BroadcastPackage(300) {
-        message_type = 300;  // Set in constructor
-    }
-    
-    JsonObject addTo(JsonObject&& jsonObj) const {
-        jsonObj = BroadcastPackage::addTo(std::move(jsonObj));
-        jsonObj["message_type"] = message_type;  // Serialize it
-        return jsonObj;
-    }
-};
-```
-
-#### 4. No Changes Required For
-
-- ✅ Basic mesh networking
-- ✅ Existing custom packages (still work, just not optimized)
-- ✅ MQTT bridges (backward compatible)
-- ✅ Examples (all updated)
-
-### Database Schema Updates
-
-If you're storing package data in a database:
-
-```sql
--- Add new time field columns
-ALTER TABLE metrics ADD COLUMN collectionTimestamp_ms BIGINT;
-ALTER TABLE metrics ADD COLUMN avgResponseTime_us INTEGER;
-
--- Add new StatusPackage columns
-ALTER TABLE status ADD COLUMN organizationId VARCHAR(50);
-ALTER TABLE status ADD COLUMN organizationName VARCHAR(100);
-ALTER TABLE status ADD COLUMN organizationDomain VARCHAR(100);
-ALTER TABLE status ADD COLUMN sensorTypes JSON;
-ALTER TABLE status ADD COLUMN sensorConfig JSON;
-
--- Migrate data from old columns (if needed)
-UPDATE metrics SET collectionTimestamp_ms = collectionTimestamp;
-UPDATE metrics SET avgResponseTime_us = avgResponseTime;
-
--- Drop old columns (after migration confirmed)
--- ALTER TABLE metrics DROP COLUMN collectionTimestamp;
--- ALTER TABLE metrics DROP COLUMN avgResponseTime;
-```
-
-### Monitoring Dashboard Updates
-
-Update Grafana/InfluxDB queries:
-
-**Before:**
-```
-SELECT avgResponseTime FROM metrics
-```
-
-**After:**
-```
-SELECT avgResponseTime_us FROM metrics
-```
-
-## 🎯 Use Cases
-
-### Enterprise Deployments
-- Multi-tenant mesh networks with organizationId
-- Centralized monitoring with fast message classification
-- Cloud integration via Internet bridge
-- Professional dashboards with clear time units
-
-### IoT Sensor Networks
-- Efficient sensor data collection
-- Clear sensor configuration management
-- Inventory tracking
-- Performance monitoring
-
-### Development & Testing
-- Consistent API naming
-- Easier debugging with explicit time units
-- Better documentation
-- Improved code quality
-
-## 📋 Testing
-
-### Existing Tests
-- ✅ All 710+ existing tests pass
-- ✅ No regressions introduced
-- ✅ Backward compatibility verified
-
-### New Tests
-- ✅ Time field naming validation
-- ✅ StatusPackage JSON structure tests
-- ✅ message_type field tests
-- ✅ ESP8266 compatibility tests
-
-### Platform Compatibility
-- ✅ ESP32: Compiles and runs successfully
-- ✅ ESP8266: Compiles and runs successfully
-- ✅ Desktop (unit tests): All tests pass
-
-## 🔍 Comparison with v1.7.7
-
-| Feature | v1.7.7 | v1.7.8 |
-|---------|--------|--------|
-| MQTT Schema | v0.7.2 | v0.7.3 |
-| message_type field | No | Yes (3 packages) |
-| Message classification | Parse JSON | Read field (90% faster) |
-| Time field naming | Inconsistent | Consistent with units |
-| StatusPackage fields | 15 | 21 (+organization, sensor config) |
-| Internet bridge docs | No | Yes (comprehensive) |
-| API guidelines | No | Yes (detailed) |
-| Manual publish workflow | No | Yes |
-
-## ⚠️ Important Notes
-
-### Breaking Changes Impact
-
-**Low Impact for Most Users:**
-- Time field changes only affect code that directly accesses these fields
-- StatusPackage changes only affect code parsing JSON directly
-- Most users use helper methods that are already updated
-
-**Medium Impact for:**
-- Custom dashboards
-- Database integrations
-- External monitoring systems
-
-**High Impact for:**
-- Systems with hardcoded field names
-- Custom JSON parsing code
-- Database schemas
-
-### Recommendations
-
-1. **Test Thoroughly** - Validate in development environment first
-2. **Update Gradually** - Migrate one system at a time
-3. **Monitor Closely** - Watch for parsing errors
-4. **Keep Old Fields** - Maintain backward compatibility during migration
-5. **Update Documentation** - Document your specific migration process
-
-### Known Limitations
-
-- **Database Migration** - Requires manual schema updates
-- **Dashboard Updates** - May need to recreate queries
-- **API Documentation** - External API docs need updating
-- **Third-party Integrations** - May need coordination
-
-## 📞 Support & Resources
-
-### Documentation
-- **Full CHANGELOG:** `CHANGELOG.md`
-- **API Guidelines:** `docs/API_DESIGN_GUIDELINES.md`
-- **Time Fields:** `docs/architecture/TIME_FIELD_NAMING.md`
-- **Bridge Guide:** `BRIDGE_TO_INTERNET.md`
-- **Website:** https://alteriom.github.io/painlessMesh/
-
-### Community
-- **GitHub Issues:** https://github.com/Alteriom/painlessMesh/issues
-- **Discussions:** https://github.com/Alteriom/painlessMesh/discussions
-
-### Getting Help
-
-1. Review migration guide above
-2. Check API design guidelines
-3. Search existing issues
-4. Test with provided examples
-5. Report issues with logs and configuration
-
-## 🎉 Credits
-
-**Contributors:**
-- Alteriom Team - Package enhancements and documentation
-- painlessMesh Community - Testing and feedback
-- GitHub Copilot - Development assistance
-
-## 📄 License
-
-LGPL-3.0 - Same as painlessMesh
-
----
-
-**Ready to Upgrade?** Follow the migration guide above and review the breaking changes carefully. Test in a development environment before deploying to production.