Esp32Dimmer/FUTURE_ENHANCEMENTS.md

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:

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:

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:

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