@alteriom/painlessmesh 1.8.14 → 1.9.0

package/docs/ARDUINO_LIBRARY_MANAGER_SUBMISSION.md

@@ -1,331 +0,0 @@
-# Arduino Library Manager Submission Guide
-
-## Overview
-
-This document explains the Arduino Library Manager indexing issue and provides the solution to restore automatic version updates.
-
-## Current Status
-
-**Status**: ✅ **Already registered** in Arduino Library Manager  
-**Issue**: New releases (v1.7.0 - v1.8.2) not being indexed  
-**Last Indexed Version**: 1.6.1  
-**Repository**: https://github.com/Alteriom/painlessMesh
-
-## Problem Statement
-
-Users report that the Arduino IDE:
-- Shows old version (1.6.1) instead of current version (1.8.2)
-- Does not detect new releases (v1.7.0 through v1.8.2)
-- Cannot update to newer versions via Library Manager
-- Has issues when trying to add the library as a ZIP file
-
-## Root Cause **[RESOLVED]**
-
-The library name in `library.properties` was changed between v1.6.1 and v1.7.0:
-
-- **v1.6.1**: `name=Alteriom PainlessMesh` (with space)
-- **v1.7.0+**: `name=AlteriomPainlessMesh` (no space)
-
-**Arduino Library Manager requires the library name to remain consistent.** When the name changed, the indexer treated it as a completely different library and stopped indexing new releases under the original name.
-
-The library IS registered at: https://github.com/arduino/library-registry (entry: `https://github.com/Alteriom/painlessMesh`)
-
-## Solution **[IMPLEMENTED]**
-
-Revert the library name in `library.properties` back to the original format with a space:
-
-```properties
-name=Alteriom PainlessMesh
-```
-
-This will allow Arduino Library Manager to resume indexing new releases as updates to the existing library entry.
-
-## Solution: Submit to Arduino Library Registry
-
-### Prerequisites Check ✅
-
-Before submission, verify that the library meets all Arduino Library Manager requirements.
-
-**Automated Validation**:
-
-Run the validation script to check all requirements:
-
-```bash
-./scripts/validate-arduino-compliance.sh
-```
-
-This script verifies:
-
-- ✅ **library.properties file**: Present and properly formatted
-- ✅ **Version field**: Set to 1.8.2
-- ✅ **src/ directory**: Contains all library source code
-- ✅ **examples/ directory**: Contains working example sketches (29+ examples)
-- ✅ **Valid license**: LGPL-3.0 (open source)
-- ✅ **README.md**: Comprehensive documentation
-- ✅ **Git tags**: Releases are properly tagged (v1.8.2, etc.)
-- ✅ **GitHub repository**: Public and accessible
-- ✅ **Library name**: Unique (AlteriomPainlessMesh)
-- ✅ **Version consistency**: All package files have matching versions
-- ✅ **Header files**: Present in src/ directory
-- ✅ **keywords.txt**: Present (optional but recommended)
-
-**Current Status**: ✅ All checks passing
-
-### library.properties Validation
-
-Current library.properties contents:
-
-```properties
-name=AlteriomPainlessMesh
-version=1.8.2
-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
-paragraph=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.
-category=Communication
-url=https://github.com/Alteriom/painlessMesh
-architectures=esp8266,esp32
-includes=painlessMesh.h
-depends=ArduinoJson, TaskScheduler
-```
-
-**Status**: ✅ All required fields present and properly formatted
-
-### Submission Process
-
-#### Step 1: Prepare Submission Information
-
-Gather the following information for the submission:
-
-```
-Repository URL: https://github.com/Alteriom/painlessMesh
-Library Name: AlteriomPainlessMesh
-Current Version: 1.8.2
-Latest Release Tag: v1.8.2
-Category: Communication
-Architectures: ESP8266, ESP32
-Dependencies: ArduinoJson, TaskScheduler
-License: LGPL-3.0
-```
-
-#### Step 2: Create Submission Issue
-
-1. Go to: https://github.com/arduino/library-registry
-2. Click on "Issues" tab
-3. Click "New Issue"
-4. Use the template below:
-
-```markdown
-## Add AlteriomPainlessMesh to Arduino Library Manager
-
-**Repository URL**: https://github.com/Alteriom/painlessMesh
-
-**Library Name**: AlteriomPainlessMesh
-
-**Current Version**: 1.8.2
-
-**Release Tag**: v1.8.2
-
-**Description**: 
-AlteriomPainlessMesh is a user-friendly library for creating mesh networks with ESP8266 and ESP32 devices. This is an enhanced fork of the original painlessMesh library with additional features:
-
-- **SensorPackage** (Type 200): Environmental data collection with temperature, humidity, pressure monitoring
-- **StatusPackage** (Type 202): Device health monitoring with memory, uptime, and WiFi metrics
-- **CommandPackage** (Type 400): Remote device control and automation
-- **MetricsPackage** (Type 204): Comprehensive performance metrics for dashboards
-- **HealthCheckPackage** (Type 605): Proactive problem detection and predictive maintenance
-- **Bridge Coordination** (Type 613): Multi-bridge support for high availability
-- **Message Queue**: Offline message queuing for critical sensor data
-
-The library handles mesh routing and network management automatically, uses JSON-based messaging, and syncs time across all nodes. Ideal for IoT sensor networks, smart agriculture, home automation, and industrial monitoring.
-
-**Category**: Communication
-
-**Architectures**: esp8266, esp32
-
-**Dependencies**: 
-- ArduinoJson (^7.4.2)
-- TaskScheduler (^4.0.0)
-
-**License**: LGPL-3.0
-
-**Documentation**: https://alteriom.github.io/painlessMesh/
-
-**Maintainer**: Alteriom (https://github.com/Alteriom)
-
-**Additional Information**:
-- Comprehensive CI/CD with automated testing
-- 19+ working examples included
-- 710+ unit tests passing
-- Active maintenance and regular releases
-- PlatformIO Registry: https://registry.platformio.org/libraries/sparck75/AlteriomPainlessMesh
-- NPM Package: https://www.npmjs.com/package/@alteriom/painlessmesh
-
-This library is ready for Arduino Library Manager indexing. All requirements are met:
-- ✅ Valid library.properties file
-- ✅ Proper directory structure (src/, examples/)
-- ✅ Semantic versioning with git tags
-- ✅ Open source license
-- ✅ Examples compile successfully
-- ✅ Comprehensive documentation
-```
-
-#### Step 3: Wait for Review
-
-The Arduino team will review the submission:
-
-1. **Automated checks**: The Arduino bot will validate the repository structure
-2. **Manual review**: Arduino team will verify library quality
-3. **Approval**: If everything is correct, the library will be added to `repositories.txt`
-4. **Indexing**: The Arduino Library Manager will start indexing new releases
-
-**Expected Timeline**: 1-2 weeks (can be longer depending on queue)
-
-#### Step 4: Verify Registration
-
-Once approved, verify the library is accessible:
-
-1. Open Arduino IDE
-2. Go to: Sketch → Include Library → Manage Libraries
-3. Search for "AlteriomPainlessMesh"
-4. Verify version 1.8.2 (or latest) appears
-5. Test installation
-
-### Alternative: Direct Pull Request (Advanced)
-
-If you prefer to submit via pull request:
-
-1. Fork: https://github.com/arduino/library-registry
-2. Edit `repositories.txt`
-3. Add line: `https://github.com/Alteriom/painlessMesh`
-4. Create pull request with description
-5. Wait for review and merge
-
-**Note**: The issue submission method is recommended for first-time submissions.
-
-## Post-Registration
-
-### Automatic Updates
-
-Once registered, future releases will be automatically indexed:
-
-1. Create new release on GitHub with semantic version tag (e.g., v1.8.3)
-2. Update `library.properties`, `library.json`, `package.json` versions
-3. Arduino Library Manager automatically detects new releases
-4. Users can update via Library Manager
-
-**Update Frequency**: Arduino Library Manager checks for updates every 24-48 hours
-
-### Maintenance
-
-To ensure continued compatibility:
-
-- Keep `library.properties` version in sync with git tags
-- Follow semantic versioning (MAJOR.MINOR.PATCH)
-- Test examples before each release
-- Update CHANGELOG.md with changes
-- Maintain backward compatibility when possible
-
-## Testing Library Manager Installation
-
-Once registered, test the installation process:
-
-### Test 1: Fresh Installation
-
-```
-1. Open Arduino IDE
-2. Sketch → Include Library → Manage Libraries
-3. Search: "AlteriomPainlessMesh"
-4. Click "Install"
-5. Verify installation completes
-6. Check: Tools → Manage Libraries → Installed
-```
-
-### Test 2: Example Compilation
-
-```
-1. File → Examples → AlteriomPainlessMesh → basic
-2. Select board: ESP32 Dev Module or ESP8266 board
-3. Verify/Compile sketch
-4. Confirm compilation succeeds
-```
-
-### Test 3: Update Detection
-
-```
-1. Release new version (e.g., v1.8.3)
-2. Wait 24-48 hours for indexing
-3. Open Library Manager
-4. Search: "AlteriomPainlessMesh"
-5. Verify "Update" button appears
-6. Click Update and verify installation
-```
-
-## Troubleshooting
-
-### Library Not Appearing in Manager
-
-**Cause**: Not yet indexed or submission not approved
-**Solution**: 
-- Check submission issue status
-- Wait 24-48 hours after approval
-- Verify `library.properties` has correct format
-
-### Version Not Updating
-
-**Cause**: Git tag doesn't match library.properties version
-**Solution**:
-- Ensure version in library.properties matches git tag
-- Example: library.properties has `version=1.8.2` → git tag must be `v1.8.2`
-- Push corrected tag to GitHub
-
-### Compilation Errors in Library Manager
-
-**Cause**: Missing dependencies or platform-specific issues
-**Solution**:
-- Verify `depends=` field in library.properties lists all dependencies
-- Test compilation on target platforms before release
-- Check Arduino forum for reported issues
-
-### Old Version Showing (1.6.1 Issue)
-
-**Cause**: Library not properly registered or name conflict
-**Solution**:
-- Complete Arduino Library Manager registration
-- Verify library name is unique
-- Check if old library version exists under different name
-
-## Reference Links
-
-- **Arduino Library Manager**: https://www.arduino.cc/reference/en/libraries/
-- **Library Registry**: https://github.com/arduino/library-registry
-- **Submission Guide**: https://support.arduino.cc/hc/en-us/articles/360012175419
-- **Library Specification**: https://arduino.github.io/arduino-cli/latest/library-specification/
-- **Library Manager FAQ**: https://support.arduino.cc/hc/en-us/articles/360016077340
-
-## Support
-
-If you encounter issues with the Arduino Library Manager submission:
-
-1. **Check Documentation**: Review Arduino's official library submission guide
-2. **Search Issues**: Look for similar submissions in arduino/library-registry issues
-3. **Ask Arduino Forum**: Post questions in Arduino's library development forum
-4. **Contact Maintainer**: Open issue in this repository for help
-
-## Summary
-
-**Action Required**: Submit the library to Arduino Library Manager registry
-
-**Method**: Create issue at https://github.com/arduino/library-registry
-
-**Expected Result**: Library becomes installable via Arduino IDE's Library Manager
-
-**Timeline**: 1-2 weeks for review and approval
-
-**Maintenance**: Future releases automatically indexed every 24-48 hours
-
-Once registered, users will be able to:
-- ✅ Search for "AlteriomPainlessMesh" in Arduino IDE
-- ✅ Install with one click
-- ✅ Update to latest versions automatically
-- ✅ Access library documentation and examples

package/docs/BOOLEAN_NAMING_CONVENTION.md

@@ -1,235 +0,0 @@
-# Boolean Field Naming Convention
-
-**Related Issue**: #27
-
-## Overview
-
-This document establishes the standard naming conventions for boolean fields in Alteriom packages, particularly in `StatusPackage`. Consistent naming patterns make the code self-documenting and help developers understand field semantics at a glance.
-
-## Three Naming Patterns
-
-### Pattern 1: `*Set` Suffix
-
-**Purpose**: Indicates that required configuration data has been provided (typically for sensitive data like passwords or secrets).
-
-**When to use**:
-- Field represents whether configuration data exists
-- Typically used for passwords, secrets, API keys, server URLs
-- Does NOT indicate if the feature is active or working
-
-**Examples**:
-```cpp
-bool deviceSecretSet = false;  // Has device secret been configured?
-bool wifiPasswordSet = false;  // Has WiFi password been provided?
-bool meshPasswordSet = false;  // Has mesh password been provided?
-bool otaServerSet = false;     // Has OTA server URL been configured?
-bool mqttBrokerSet = false;    // Has MQTT broker been configured?
-```
-
-**Semantic meaning**:
-- `true` = Configuration data has been provided
-- `false` = Configuration data is missing or not yet provided
-- Does NOT indicate the feature is enabled or currently working
-
-### Pattern 2: `*Enabled` Suffix
-
-**Purpose**: Indicates that a feature is currently active or turned on.
-
-**When to use**:
-- Field represents a feature toggle (on/off)
-- User or system can enable/disable the feature
-- Feature state is controllable and intentional
-
-**Examples**:
-```cpp
-bool displayEnabled = false;           // Is display feature enabled?
-bool deepSleepEnabled = false;         // Is deep sleep mode enabled?
-bool mqttHourlyRetryEnabled = false;   // Is hourly retry feature enabled?
-bool otaEnabled = false;               // Are OTA updates enabled?
-bool encryptionEnabled = false;        // Is data encryption enabled?
-bool encodingEnabled = false;          // Is data encoding enabled?
-bool logTimestampEnabled = false;      // Are log timestamps enabled?
-```
-
-**Semantic meaning**:
-- `true` = Feature is currently active/turned on
-- `false` = Feature is currently inactive/turned off
-- Independent of whether required configuration exists
-
-### Pattern 3: Runtime State (`is*` Prefix or `*Connected`)
-
-**Purpose**: Indicates current runtime status or operational state (not configuration).
-
-**When to use**:
-- Field represents current operational status
-- Status changes at runtime based on system behavior
-- Not directly controlled by configuration
-
-**Examples**:
-```cpp
-bool isConfigured = false;    // Has device completed configuration?
-bool mqttConnected = false;   // Currently connected to MQTT broker?
-bool meshIsRoot = false;      // Is this node currently the mesh root?
-bool isOnline = false;        // Is device currently online?
-bool wifiConnected = false;   // Currently connected to WiFi?
-```
-
-**Semantic meaning**:
-- `true` = Currently in this state
-- `false` = Not currently in this state
-- Reflects actual runtime conditions, not configuration
-
-## Combining Patterns
-
-A feature may legitimately have multiple boolean fields using different patterns:
-
-### Example: OTA (Over-The-Air) Updates
-
-```cpp
-bool otaServerSet = false;     // Has OTA server URL been configured? (*Set)
-bool otaEnabled = false;       // Are OTA updates enabled? (*Enabled)
-bool otaInProgress = false;    // Is an OTA update currently running? (is* / runtime state)
-```
-
-**Valid states**:
-- `otaServerSet=true, otaEnabled=false` → Server configured but feature disabled
-- `otaServerSet=false, otaEnabled=true` → Feature enabled but no server (invalid/warning state)
-- `otaServerSet=true, otaEnabled=true` → Fully configured and active
-- `otaServerSet=true, otaEnabled=true, otaInProgress=true` → Update in progress
-
-### Example: MQTT Connection
-
-```cpp
-bool mqttBrokerSet = false;    // Has MQTT broker been configured? (*Set)
-bool mqttEnabled = false;      // Is MQTT feature enabled? (*Enabled)
-bool mqttConnected = false;    // Currently connected to broker? (runtime state)
-```
-
-## Current StatusPackage Implementation
-
-### Existing `*Set` Fields (Build 8057)
-```cpp
-bool deviceSecretSet = false;  // Whether device secret is configured
-```
-
-**Potential additions** (if needed):
-```cpp
-bool wifiPasswordSet = false;  // Whether WiFi password is configured
-bool meshPasswordSet = false;  // Whether mesh password is configured
-bool mqttBrokerSet = false;    // Whether MQTT broker is configured
-bool otaServerSet = false;     // Whether OTA server URL is configured
-```
-
-### Existing `*Enabled` Fields
-```cpp
-bool displayEnabled = false;           // Display feature enabled
-bool deepSleepEnabled = false;         // Deep sleep feature enabled
-bool mqttHourlyRetryEnabled = false;   // Hourly retry feature enabled
-```
-
-**Potential additions** (if needed):
-```cpp
-bool meshEnabled = false;       // Is WiFi mesh feature enabled?
-bool otaEnabled = false;        // Are OTA updates enabled?
-bool encryptionEnabled = false; // Is encryption enabled?
-bool encodingEnabled = false;   // Is data encoding enabled?
-```
-
-### Potential Runtime State Fields
-Currently, StatusPackage does not have explicit runtime state fields. If needed in the future:
-
-```cpp
-bool isConfigured = false;      // Device has complete valid configuration
-bool mqttConnected = false;     // Currently connected to MQTT broker
-bool meshIsRoot = false;        // Currently acting as mesh root
-bool wifiConnected = false;     // Currently connected to WiFi
-```
-
-## Best Practices
-
-### DO ✅
-
-1. **Use `*Set` for configuration presence**
-   ```cpp
-   bool deviceSecretSet = false;  // ✅ Indicates if secret is configured
-   ```
-
-2. **Use `*Enabled` for feature toggles**
-   ```cpp
-   bool displayEnabled = false;   // ✅ Indicates if feature is on/off
-   ```
-
-3. **Use `is*` or `*Connected` for runtime state**
-   ```cpp
-   bool isConfigured = false;     // ✅ Indicates current state
-   bool mqttConnected = false;    // ✅ Indicates connection status
-   ```
-
-4. **Document field purpose clearly**
-   ```cpp
-   bool otaServerSet = false;     // Has OTA server URL been configured? (Build XXXX)
-   ```
-
-### DON'T ❌
-
-1. **Don't mix patterns without clear semantics**
-   ```cpp
-   bool wifiSet = false;          // ❌ Ambiguous - set to what? On/off or configured?
-   ```
-
-2. **Don't use generic boolean names**
-   ```cpp
-   bool wifi = false;             // ❌ Unclear meaning
-   bool display = false;          // ❌ What about display?
-   ```
-
-3. **Don't use `*Set` for feature toggles**
-   ```cpp
-   bool displaySet = false;       // ❌ Confusing - use displayEnabled instead
-   ```
-
-4. **Don't use `*Enabled` for configuration presence**
-   ```cpp
-   bool deviceSecretEnabled = false;  // ❌ Confusing - use deviceSecretSet instead
-   ```
-
-## Validation
-
-When adding new boolean fields, ask these questions:
-
-1. **Does this field indicate configuration presence?**
-   - YES → Use `*Set` suffix
-   - Example: `mqttBrokerSet`, `deviceSecretSet`
-
-2. **Does this field toggle a feature on/off?**
-   - YES → Use `*Enabled` suffix
-   - Example: `displayEnabled`, `otaEnabled`
-
-3. **Does this field reflect current runtime state?**
-   - YES → Use `is*` prefix or `*Connected` suffix
-   - Example: `isConfigured`, `mqttConnected`
-
-4. **Does this field fit multiple categories?**
-   - Consider creating separate fields for each semantic meaning
-   - Example: `otaServerSet` AND `otaEnabled` AND `otaInProgress`
-
-## Benefits
-
-1. **Self-Documenting Code**: Field names clearly indicate semantic meaning
-2. **Reduced Confusion**: Developers immediately understand what each boolean represents
-3. **Better API Design**: Consistent patterns across entire codebase
-4. **Easier Onboarding**: New developers can infer meaning from field names
-5. **Fewer Bugs**: Clear semantics reduce misunderstandings and implementation errors
-
-## References
-
-- StatusPackage implementation: `examples/alteriom/alteriom_sensor_package.hpp`
-- Test validation: `test/catch/catch_alteriom_packages.cpp`
-- Time field conventions: See header documentation in `alteriom_sensor_package.hpp`
-
----
-
-**Document Version**: 1.0  
-**Last Updated**: 2025-11-04  
-**Status**: Active  
-**Applies To**: StatusPackage, EnhancedStatusPackage, and all future Alteriom packages