Remove legacy code and implement pure event-driven architecture

Co-authored-by: pmarchini <49943249+pmarchini@users.noreply.github.com>

FUTURE_ENHANCEMENTS.md

@@ -0,0 +1,206 @@
+# Future Enhancements
+
+This document tracks features that need to be implemented before future releases.
+
+## Release 1.1.0 Requirements
+
+### Toggle Mode Implementation
+
+**Status**: Not Yet Implemented  
+**Priority**: Must-have for 1.1.0  
+**Reason**: Backward compatibility with existing applications
+
+#### Overview
+
+Toggle mode allows a dimmer to automatically ramp up and down between a minimum and maximum power level, creating a fading effect. This feature exists in the legacy implementation but has been temporarily removed from the event-driven architecture.
+
+#### Current State
+
+- API function `toggleSettings()` exists but only logs a warning
+- `TOGGLE_MODE` enum value exists in header
+- Toggle-related global variables (`togMin`, `togMax`, `togDir`) are declared but unused
+
+#### Implementation Approach
+
+**Option 1: FreeRTOS Task (Recommended)**
+
+Create a separate FreeRTOS task that handles toggle mode updates:
+
+```c
+static void toggle_task(void *arg)
+{
+    while (1)
+    {
+        for (int i = 0; i < current_dim; i++)
+        {
+            if (dimMode[i] == TOGGLE_MODE)
+            {
+                // Update dimPulseBegin based on toggle direction
+                if (dimPulseBegin[i] >= togMax[i])
+                    togDir[i] = false;
+                if (dimPulseBegin[i] <= togMin[i])
+                    togDir[i] = true;
+                    
+                if (togDir[i])
+                    dimPulseBegin[i]++;
+                else
+                    dimPulseBegin[i]--;
+            }
+        }
+        vTaskDelay(pdMS_TO_TICKS(50)); // Adjust for desired toggle speed
+    }
+}
+```
+
+**Benefits:**
+- Clean separation of concerns
+- Doesn't burden ISR with toggle logic
+- Easy to adjust toggle speed
+- Can be paused/resumed
+
+**Implementation Steps:**
+
+1. Create toggle task in `begin()` function (only once, shared by all dimmers)
+2. Task scans all dimmers for `TOGGLE_MODE`
+3. Updates `dimPulseBegin[]` values periodically
+4. Zero-crossing ISR reads updated values and schedules events accordingly
+
+**Option 2: Timer-based Updates**
+
+Use a separate software timer to update toggle values:
+
+```c
+static void toggle_timer_callback(void *arg)
+{
+    for (int i = 0; i < current_dim; i++)
+    {
+        if (dimMode[i] == TOGGLE_MODE)
+        {
+            // Same logic as Option 1
+        }
+    }
+}
+```
+
+**Benefits:**
+- Lighter weight than FreeRTOS task
+- Precise timing control
+
+**Drawbacks:**
+- More complex timer management
+- Another ISR to manage
+
+#### Testing Requirements
+
+Before 1.1.0 release, toggle mode must be tested for:
+
+- [ ] Single dimmer in toggle mode
+- [ ] Multiple dimmers in toggle mode with different ranges
+- [ ] Switching between NORMAL_MODE and TOGGLE_MODE
+- [ ] Toggle speed consistency
+- [ ] No interference with normal mode dimmers
+- [ ] Memory usage and CPU overhead acceptable
+
+#### API Changes
+
+No API changes needed - `toggleSettings()` signature remains the same:
+
+```c
+void toggleSettings(dimmertyp *ptr, int minValue, int maxValue);
+```
+
+#### Documentation Updates Needed
+
+- Update README.md with toggle mode examples
+- Update TRIAC_CYCLE.md with toggle mode timing diagrams
+- Update IMPLEMENTATION_SUMMARY.md to remove "Not Yet Implemented" note
+- Add toggle mode examples to examples directory
+
+---
+
+## Release 2.0.0 - Full Optimization
+
+These enhancements can wait for a major release but would provide significant performance improvements.
+
+### One-Shot Timer Mode
+
+**Status**: Design Complete, Not Implemented  
+**Priority**: Nice-to-have  
+**Benefit**: 94-98% reduction in ISR invocations
+
+Currently, the timer still runs in periodic mode at 100μs intervals. The event queue is processed on every tick even when there are no events to process.
+
+#### Implementation Approach
+
+1. Switch timer to one-shot mode: `auto_reload_on_alarm = false`
+2. After processing an event, schedule the next alarm for the next event's timestamp
+3. If no events are pending, timer remains idle until next zero-crossing
+
+#### Challenges
+
+- More complex timer management
+- Need to handle case when events are scheduled while timer is idle
+- Require mutex or critical section for event queue access
+
+### Priority Queue for Event Management
+
+**Status**: Not Started  
+**Priority**: Optimization  
+**Benefit**: O(log n) instead of O(n) event processing
+
+Current implementation uses linear search to find and process events. For small event counts (< 10), this is acceptable. For high dimmer counts or rapid updates, a priority queue would be more efficient.
+
+#### Implementation Options
+
+1. Min-heap implementation
+2. Binary search tree
+3. Third-party priority queue library
+
+### Multi-Phase AC Support
+
+**Status**: Design Concept Only  
+**Priority**: Feature Request Dependent
+
+Extend system to support 3-phase AC systems:
+- Track phase relationships
+- Independent zero-crossing detection per phase
+- Phase-aware power distribution
+
+### Power Factor Correction
+
+**Status**: Research Phase  
+**Priority**: Advanced Feature
+
+Implement leading/trailing edge control for improved power factor.
+
+### Energy Monitoring
+
+**Status**: Concept  
+**Priority**: Feature Request Dependent
+
+Add real-time power consumption tracking:
+- Integrate with current sensing
+- Calculate RMS power
+- Expose power data via API
+
+---
+
+## How to Update This Document
+
+When implementing features:
+
+1. Move feature from "Future" to "In Progress"
+2. Update status and add implementation details
+3. Link to relevant pull requests
+4. After completion, move to "Completed" section with version number
+
+When adding new features:
+
+1. Add to appropriate release section
+2. Include: Status, Priority, Overview, Implementation Approach
+3. Note any API changes or breaking changes
+
+---
+
+**Last Updated**: 2026-01-25  
+**Maintainer**: ESP32 Triac Dimmer Driver Team