MycilaDimmer.h

// SPDX-License-Identifier: MIT
/*
 * Copyright (C) 2023-2025 Mathieu Carbou
 */
#pragma once
 
#define MYCILA_DIMMER_VERSION          "2.2.1"
#define MYCILA_DIMMER_VERSION_MAJOR    2
#define MYCILA_DIMMER_VERSION_MINOR    2
#define MYCILA_DIMMER_VERSION_REVISION 0
 
#ifdef MYCILA_JSON_SUPPORT
  #include <ArduinoJson.h>
#endif
 
#include <assert.h>
#include <esp32-hal-gpio.h>
 
#include <cstdio>
 
namespace Mycila {
  class Dimmer {
    public:
      typedef struct {
          // Output voltage (dimmed)
          float voltage = 0.0f;
          float current = 0.0f;
          float power = 0.0f;
          float apparentPower = 0.0f;
          float powerFactor = NAN;
          float thdi = NAN;
      } Metrics;
 
    public:
      virtual ~Dimmer() {};
 
      virtual void begin() { _enabled = true; };
      virtual void end() { _enabled = false; };
      virtual const char* type() const { return "virtual"; }

      // DIMMER CONFIG //

      void setDutyCycleLimit(float limit) {
        _dutyCycleLimit = _contrain(limit, 0, 1);
        if (_dutyCycle > _dutyCycleLimit)
          setDutyCycle(_dutyCycleLimit);
      }

      void setDutyCycleMin(float min) {
        _dutyCycleMin = _contrain(min, 0, _dutyCycleMax);
        setDutyCycle(_dutyCycle);
      }

      void setDutyCycleMax(float max) {
        _dutyCycleMax = _contrain(max, _dutyCycleMin, 1);
        setDutyCycle(_dutyCycle);
      }

      float getDutyCycleLimit() const { return _dutyCycleLimit; }

      float getDutyCycleMin() const { return _dutyCycleMin; }

      float getDutyCycleMax() const { return _dutyCycleMax; }

      // POWER LUT //

      void enablePowerLUT(bool enable, uint16_t semiPeriod = 0) {
        if (!enable) {
          _powerLUTEnabled = false;
          return;
        }
        // Enabling the LUT
        if (semiPeriod > 0) {
          // A semi-period is provided, use it
          _semiPeriod = semiPeriod;
        } else {
          // semiPeriod == 0, use already set semi-period, must be >0
          if (_semiPeriod == 0) {
            ESP_LOGE("MycilaDimmer", "enablePowerLUT: semiPeriod must be provided or must be already set when enabling power LUT");
          }
          assert(_semiPeriod > 0);
        }
        _powerLUTEnabled = true;
      }

      bool isPowerLUTEnabled() const { return _powerLUTEnabled; }

      uint16_t getPowerLUTSemiPeriod() const { return _powerLUTEnabled ? _semiPeriod : 0; }

      // DIMMER STATES //

      bool isEnabled() const { return _enabled; }

      bool isOnline() const { return _enabled && _online; }

      void setOnline(bool online) {
        _online = online;
        if (!_online) {
          _dutyCycleFire = 0.0f;
          if (_enabled)
            _apply();
        } else {
          setDutyCycle(_dutyCycle);
        }
      }

      // DIMMER CONTROL //

      void on() { setDutyCycle(1); }

      void off() { setDutyCycle(0); }

      bool isOff() const { return !isOn(); }

      bool isOn() const { return isOnline() && _dutyCycle; }

      bool isOnAtFullPower() const { return _dutyCycle >= _dutyCycleMax; }

      bool setDutyCycle(float dutyCycle) {
        // Apply limit and save the wanted duty cycle.
        // It will only be applied when dimmer will be on.
        _dutyCycle = _contrain(dutyCycle, 0, _dutyCycleLimit);
 
        const float mapped = getDutyCycleMapped();
 
        if (_powerLUTEnabled) {
          if (mapped == 0) {
            _dutyCycleFire = 0.0f;
          } else if (mapped == 1) {
            _dutyCycleFire = 1.0f;
          } else {
            _dutyCycleFire = 1.0f - static_cast<float>(_lookupFiringDelay(mapped, _semiPeriod)) / static_cast<float>(_semiPeriod);
          }
        } else {
          _dutyCycleFire = mapped;
        }
 
        return isOnline() && _apply();
      }

      // DUTY CYCLE //

      float getDutyCycle() const { return _dutyCycle; }

      float getDutyCycleMapped() const { return _dutyCycleMin + _dutyCycle * (_dutyCycleMax - _dutyCycleMin); }

      float getDutyCycleFire() const { return isOnline() ? _dutyCycleFire : 0.0f; }

      // METRICS //
 
      // Calculate harmonics based on dimmer firing angle for resistive loads
      // array[0] = H1 (fundamental), array[1] = H3, array[2] = H5, array[3] = H7, etc.
      // Only odd harmonics are calculated (even harmonics are negligible for symmetric dimmers)
      // Returns true if harmonics were calculated, false if dimmer is not active
      bool calculateHarmonics(float* array, size_t n) const {
        if (array == nullptr || n == 0)
          return false;
 
        // Check if dimmer is active and routing
        if (!isOnline() || _dutyCycleFire <= 0.0f) {
          for (size_t i = 0; i < n; i++) {
            array[i] = 0.0f; // No power, no harmonics
          }
          return true;
        }
 
        if (_dutyCycleFire >= 1.0f) {
          array[0] = 100.0f; // H1 (fundamental) = 100% reference
          for (size_t i = 1; i < n; i++) {
            array[i] = 0.0f; // No harmonics at full power
          }
          return true;
        }
 
        // Initialize all values to NAN
        for (size_t i = 0; i < n; i++) {
          array[i] = NAN;
        }
 
        return _calculateHarmonics(array, n);
      }
 
      virtual bool calculateMetrics(Metrics& metrics, float gridVoltage, float loadResistance) const { return false; }
 
#ifdef MYCILA_JSON_SUPPORT
      virtual void toJson(const JsonObject& root) const {
        root["type"] = type();
        root["enabled"] = _enabled;
        root["online"] = _online;
        root["state"] = isOn() ? "on" : "off";
        root["duty_cycle"] = _dutyCycle;
        root["duty_cycle_mapped"] = getDutyCycleMapped();
        root["duty_cycle_fire"] = _dutyCycleFire;
        root["duty_cycle_limit"] = _dutyCycleLimit;
        root["duty_cycle_min"] = _dutyCycleMin;
        root["duty_cycle_max"] = _dutyCycleMax;
        root["power_lut"] = _powerLUTEnabled;
        root["power_lut_semi_period"] = _semiPeriod;
        JsonObject harmonics = root["harmonics"].to<JsonObject>();
        float output[11]; // H1 to H21
        if (calculateHarmonics(output, 11)) {
          for (size_t i = 0; i < 11; i++) {
            if (!std::isnan(output[i])) {
              char key[8];
              snprintf(key, sizeof(key), "H%d", static_cast<int>(2 * i + 1));
              harmonics[key] = output[i];
            }
          }
        }
      }
#endif
 
    protected:
      bool _enabled = false;
      bool _online = false;
 
      float _dutyCycle = 0.0f;
      float _dutyCycleFire = 0.0f;
      float _dutyCycleLimit = 1.0f;
      float _dutyCycleMin = 0.0f;
      float _dutyCycleMax = 1.0f;
 
      bool _powerLUTEnabled = false;
      uint16_t _semiPeriod = 0;
 
      virtual bool _apply() { return _enabled; }
      virtual bool _calculateHarmonics(float* array, size_t n) const {
        for (size_t i = 0; i < n; i++) {
          array[i] = 0.0f; // No harmonics for virtual dimmer
        }
        return true;
      }

      // STATIC HELPERS //
 
      static uint16_t _lookupFiringDelay(float dutyCycle, uint16_t semiPeriod);
 
      static inline float _contrain(float amt, float low, float high) {
        return (amt < low) ? low : ((amt > high) ? high : amt);
      }
 
      static bool _calculatePhaseControlHarmonics(float dutyCycleFire, float* array, size_t n) {
        // getDutyCycleFire() returns the conduction angle normalized (0-1)
        // Convert to firing angle: α = π × (1 - conduction)
        // At 50% power: α ≈ 90° (π/2), which gives maximum harmonics
        const float firingAngle = M_PI * (1.0f - dutyCycleFire);
 
        // Calculate RMS of fundamental component (reference)
        // Formula from Thierry Lequeu: I1_rms = (1/π) × √[2(π - α + ½sin(2α))]
        const float sin_2a = sinf(2.0f * firingAngle);
        const float i1_rms = sqrtf((2.0f / M_PI) * (M_PI - firingAngle + 0.5f * sin_2a));
 
        if (i1_rms <= 0.001f)
          return false;
 
        array[0] = 100.0f; // H1 (fundamental) = 100% reference
 
        // Pre-compute scale factor for efficiency
        const float scale_factor = (2.0f / M_PI) * 0.70710678f * 100.0f / i1_rms;
 
        // Calculate odd harmonics (H3, H5, H7, ...)
        // Formula for phase-controlled resistive loads (IEEE standard):
        // Hn = (2/π√2) × |cos((n-1)α)/(n-1) - cos((n+1)α)/(n+1)| / I1_rms × 100%
        // This gives the correct harmonic magnitudes relative to the fundamental
        for (size_t i = 1; i < n; i++) {
          const float n_f = static_cast<float>(2 * i + 1); // 3, 5, 7, 9, ...
          const float n_minus_1 = n_f - 1.0f;
          const float n_plus_1 = n_f + 1.0f;
 
          // Compute Fourier coefficient
          const float coeff = cosf(n_minus_1 * firingAngle) / n_minus_1 -
                              cosf(n_plus_1 * firingAngle) / n_plus_1;
 
          // Convert to percentage of fundamental
          array[i] = fabsf(coeff) * scale_factor;
        }
 
        return true;
      }
 
      static bool _calculatePhaseControlMetrics(Metrics& metrics, float dutyCycleFire, float gridVoltage, float loadResistance) {
        if (loadResistance > 0 && gridVoltage > 0) {
          if (dutyCycleFire > 0) {
            const float nominalPower = gridVoltage * gridVoltage / loadResistance;
            if (dutyCycleFire >= 1.0f) {
              // full power
              metrics.powerFactor = 1.0f;
              metrics.thdi = 0.0f;
              metrics.power = nominalPower;
              metrics.voltage = gridVoltage;
              metrics.current = gridVoltage / loadResistance;
              metrics.apparentPower = nominalPower;
              return true;
            } else {
              // partial power
              metrics.powerFactor = std::sqrt(dutyCycleFire);
              metrics.thdi = 100.0f * std::sqrt(1 / dutyCycleFire - 1);
              metrics.power = dutyCycleFire * nominalPower;
              metrics.voltage = metrics.powerFactor * gridVoltage;
              metrics.current = metrics.voltage / loadResistance;
              metrics.apparentPower = gridVoltage * metrics.current;
              return true;
            }
          } else {
            // no power
            metrics.voltage = 0.0f;
            metrics.current = 0.0f;
            metrics.power = 0.0f;
            metrics.apparentPower = 0.0f;
            metrics.powerFactor = NAN;
            metrics.thdi = NAN;
            return true;
          }
        } else {
          return false;
        }
      }
  };
} // namespace Mycila
 
#include "MycilaDimmerDFRobot.h"
#include "MycilaDimmerPWM.h"
#include "MycilaDimmerThyristor.h"