style: minor changes

README.md

@@ -1,22 +1,12 @@
-# ESP32 ESP-IDF component for AC dimmer for 115V/400Hz
+# ESP32 ESP-IDF component for AC dimmer
 
 ## Features
 
-1. Zero-crossing detection via GPIO interrupt for precise phase-angle control.
+1. Zero-crossing detection via GPIO interrupt on both edges (`GPIO_INTR_ANYEDGE`), with edge polarity determined from the current GPIO level and duplicate/glitch edge rejection. Spurious-interrupt filtering: the interval between rising edges must be within the half-cycle range derived from the frequency 30 - 500 Hz (shorter intervals are ignored, longer ones reset the timing and calibration state).
-2. TRIAC gate control through ESP-IDF gptimer with configurable dimming level (0–100%).
+2. Measured zero-crossing half-period is low-pass filtered and used to calculate the TRIAC firing delay, so the dimmer adapts to the actual mains frequency.
-3. IRAM-safe ISR and callback functions for reliable operation.
+3. TRIAC gate control through ESP-IDF gptimer (1 MHz resolution) with configurable dimming level (0–100%): 0 keeps the load off, 100 fires the TRIAC immediately. The firing delay is clamped to leave a guard band (period / 20, at least 5 us) before the end of the half-cycle.
-4. Thread-safe start/stop/set/get API.
+4. Automatic runtime calibration of the hardware base offset: on each falling edge the width of the zero-crossing pulse is measured and fed into an EMA (`pulse_width / 2`), compensating for the zero-crossing detector advance relative to the physical mains zero crossing.
-
+5. Handle-based API: init/deinit (with full GPIO, ISR and timer cleanup), start/stop, set/get dimming level.
-## Note
-
-Enable the following settings in menuconfig:
-
-```text
-GPIO_CTRL_FUNC_IN_IRAM
-CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM
-CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM
-CONFIG_GPTIMER_ISR_CACHE_SAFE
-```
 
 ## Using
 

idf_component.yml

@@ -1,6 +1,6 @@
-description: ESP32 ESP-IDF component for AC dimmer control
+description: ESP32 ESP-IDF component for AC dimmer
 url: https://github.com/aZholtikov/zh_ac_dimmer
-version: "3.0.0"
+version: "3.1.0"
 license: "Apache-2.0"
 maintainers:
   - "Alexey Zholtikov <alexey.zholtikov@yandex.ru>"

include/zh_ac_dimmer.h

@@ -5,17 +5,20 @@
  *
  * This module provides an interface for controlling AC power via phase-angle
  * dimming using ESP-IDF gptimer and GPIO peripherals. It detects the AC
- * mains zero-crossing point and fires the TRIAC with a programmable delay
+ * mains zero-crossing point, measures the zero-crossing period, and fires the
- * to regulate the average power delivered to the load.
+ * TRIAC with a programmable delay to regulate the average power delivered to
+ * the load.
  *
  * Key features:
- * - Zero-crossing detection via GPIO interrupt
+ * - Zero-crossing detection via GPIO interrupt with period measurement
  * - TRIAC gate control through ESP-IDF gptimer
  * - Configurable dimming level (0–100 %)
- * - Thread-safe start/stop/set/get API
+ * - Automatic runtime calibration of the hardware base offset
+ * - Start/stop/set/get API
  *
- * @note The driver assumes a 400 Hz AC mains frequency (1250 µs period).
+ * @note The supported mains frequency range is defined by
- *       Adjust the timing constants in `zh_ac_dimmer.c` for other frequencies.
+ *       `ZH_AC_DIMMER_FREQ_MIN_HZ` and `ZH_AC_DIMMER_FREQ_MAX_HZ`. The measured
+ *       zero-crossing period is filtered and used to calculate the firing delay.
  * @warning This module interacts with mains voltage. Incorrect wiring or
  *          insufficient isolation can cause electric shock or hardware damage.
  *          Ensure proper opto-isolation and safety compliance before deployment.
@@ -23,6 +26,8 @@
 
 #pragma once
 
+#include "stdint.h"
+#include "esp_heap_caps.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "driver/gptimer.h"
@@ -30,6 +35,9 @@
 #include "esp_log.h"
 #include "driver/gpio.h"
 
+#define ZH_AC_DIMMER_FREQ_MIN_HZ 30
+#define ZH_AC_DIMMER_FREQ_MAX_HZ 500
+
 #define ZH_AC_DIMMER_INIT_CONFIG_DEFAULT() \
     {                                      \
         .zero_cross_gpio = GPIO_NUM_MAX,   \
@@ -53,6 +61,9 @@ extern "C"
      *
      * Specifies the GPIO pins used for zero-crossing detection and TRIAC
      * gate control. Both pins must be valid and different from each other.
+     *
+     * @note The firing-delay offset is calibrated automatically at runtime and
+     *       is not part of the configuration.
      */
     typedef struct
     {
@@ -65,33 +76,36 @@ extern "C"
      *
      * Allocates memory for the dimmer handle, validates the configuration,
      * initializes GPIO pins (TRIAC as output, zero-crossing as input with
-     * positive-edge interrupt), installs the ISR service, and creates the
+     * both-edge interrupt), installs the ISR service, and creates the gptimer.
-     * gptimer instance.
      *
-     * @param[in] config Pointer to the initialization configuration structure.
+     * @param[in] config Pointer to the initialization configuration structure (may point to a
-     *                   May point to a temporary variable (not stored internally)
+     *            temporary variable, not stored internally)
-     * @param[out] handle Pointer to receive the created dimmer handle (must be NULL)
+     * @param[out] handle Pointer to receive the created dimmer handle (must not be NULL and must point to NULL)
      *
      * @return ESP_OK on success
-     * @return ESP_ERR_INVALID_ARG if handle is NULL or GPIO pins are invalid
+     * @return ESP_ERR_INVALID_ARG if config or handle is NULL
-     * @return ESP_ERR_INVALID_STATE if a dimmer instance is already initialized
+     * @return ESP_ERR_INVALID_STATE if the handle pointer already points to an initialized instance
      * @return ESP_ERR_NO_MEM if memory allocation failed
-     * @return ESP_FAIL if GPIO, ISR service, or timer initialization failed
+     * @return ESP_FAIL if configuration validation, GPIO, ISR service, or timer initialization failed
+     *
+     * @note The driver supports only one instance per zero-crossing GPIO pin. Initializing a
+     *       second instance on the same pin replaces the ISR handler of the first one, so each
+     *       pin must be claimed by a single dimmer instance.
      */
     esp_err_t zh_ac_dimmer_init(const zh_ac_dimmer_init_config_t *config, zh_ac_dimmer_handle_t **handle);
 
     /**
      * @brief Deinitialize the AC dimmer driver.
      *
-     * Stops and deletes the gptimer, removes the GPIO ISR handler, resets
+     * Disables TRIAC firing, removes the GPIO ISR handler, resets the GPIO
-     * the GPIO pins to input mode, frees the dimmer handle, and sets the
+     * pins, stops, disables and deletes the gptimer, frees the dimmer handle
-     * output handle to NULL.
+     * and sets the output handle to NULL. Cleanup steps are executed
+     * unconditionally and their failures are only logged.
      *
-     * @param[in,out] handle Pointer to the dimmer handle (must not be NULL)
+     * @param[in,out] handle Pointer to the dimmer handle, set to NULL on return (must not be NULL)
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle or *handle is NULL
-     * @return ESP_FAIL if timer or GPIO cleanup failed
      *
      * @warning After calling this function, the handle is invalid and must not
      *          be used. Call `zh_ac_dimmer_init()` again to reinitialize.
@@ -104,7 +118,7 @@ extern "C"
      * Enables the dimmer so that zero-crossing events trigger TRIAC firing
      * according to the current dimming value.
      *
-     * @param[in,out] handle Pointer to the dimmer handle (must not be NULL)
+     * @param[in] handle Pointer to the dimmer handle (must not be NULL)
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle or *handle is NULL
@@ -115,9 +129,10 @@ extern "C"
      * @brief Stop the AC dimmer.
      *
      * Disables TRIAC firing on zero-crossing events. The dimmer can be
-     * restarted with `zh_ac_dimmer_start()`.
+     * restarted with `zh_ac_dimmer_start()`. The TRIAC gate stays in the
+     * state left by the last half-cycle until the next zero-crossing event.
      *
-     * @param[in,out] handle Pointer to the dimmer handle (must not be NULL)
+     * @param[in] handle Pointer to the dimmer handle (must not be NULL)
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle or *handle is NULL
@@ -131,7 +146,7 @@ extern "C"
      * zero-crossing event.
      *
      * @param[in] handle Pointer to the dimmer handle (must not be NULL)
-     * @param[in] value Dimming level from 0 (off) to 100 (full brightness)
+     * @param[in] value Dimming level in percent, where 0 keeps the load off and 100 fires the TRIAC immediately (must be <= 100)
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle, *handle, or value is invalid
@@ -142,7 +157,7 @@ extern "C"
      * @brief Get the current AC dimmer brightness level.
      *
      * @param[in] handle Pointer to the dimmer handle (must not be NULL)
-     * @param[out] value Pointer to receive the current dimming level (0–100) (must not be NULL)
+     * @param[out] value Pointer to receive the current dimming level in percent (must not be NULL)
      *
      * @return ESP_OK on success
      * @return ESP_ERR_INVALID_ARG if handle, *handle, or value is NULL

version.txt

@@ -1 +1 @@
-3.0.0
+3.1.0

zh_ac_dimmer.c

@@ -13,32 +13,44 @@ static const char *TAG = "zh_ac_dimmer";
         return err;                                  \
     }
 
+#define ZH_ERROR_CHECK_CONT(cond, cleanup, msg, ...) \
+    if (!(cond))                                     \
+    {                                                \
+        ZH_LOGE(msg, ESP_FAIL, ##__VA_ARGS__);       \
+        cleanup;                                     \
+    }
+
 /**
  * @brief Internal handle for AC dimmer instance.
  *
- * Stores GPIO pin assignments, gptimer handle, timing state,
+ * Stores GPIO pin assignments, gptimer handle, zero-crossing timing state,
- * current dimming level, and running state.
+ * auto-calibrated base offset, current dimming level, and running state.
  */
 struct _zh_ac_dimmer_handle_t
 {
     gpio_num_t zero_cross_gpio;           /*!< GPIO pin for zero-crossing detection input */
     gpio_num_t triac_gpio;                /*!< GPIO pin for TRIAC gate control output */
     gptimer_handle_t dimmer_timer_handle; /*!< gptimer instance used for TRIAC firing delay */
-    uint64_t prev_zero_crossing_us;       /*!< Timestamp of the last zero-crossing event (µs) */
+    uint64_t prev_zero_crossing_us;       /*!< Timestamp of the previous rising edge (us) */
-    uint8_t dimmer_value;                 /*!< Current dimming level (0 = off, 100 = full) */
+    uint64_t pulse_start_us;              /*!< Timestamp of the current rising edge, used to measure pulse width (us) */
-    bool is_dimmer_work;                  /*!< `true` when the dimmer is actively running */
+    uint32_t period_us;                   /*!< Filtered zero-crossing half-period in microseconds (0 until measured) */
+    volatile uint32_t base_offset_us;     /*!< Auto-calibrated advance of the zero-cross ISR relative to T0 (us) */
+    volatile uint32_t auto_base_samples;  /*!< Number of valid pulse-width measurements used for calibration */
+    volatile uint8_t dimmer_value;        /*!< Current dimming level, 0 off .. 100 full */
+    volatile bool is_dimmer_work;         /*!< Set when the dimmer is actively running */
+    bool last_edge_was_rising;            /*!< Tracks edge polarity to reject duplicate/glitch edges */
 };
 
 /**
  * @brief Validate the AC dimmer initialization configuration.
  *
- * Checks that both GPIO pins are valid (not `GPIO_NUM_MAX`),
+ * Checks that both GPIO pins are valid (less than `GPIO_NUM_MAX`) and are not
- * are within the acceptable range, and are not the same pin.
+ * the same pin.
  *
  * @param config Pointer to the initialization configuration structure
  *
  * @return ESP_OK if the configuration is valid
- * @return ESP_ERR_INVALID_ARG if any GPIO pin is invalid or both pins are the same
+ * @return ESP_ERR_INVALID_ARG if any GPIO pin is invalid, or both pins are the same
  */
 static esp_err_t _zh_ac_dimmer_validate_config(const zh_ac_dimmer_init_config_t *config);
 
@@ -46,7 +58,7 @@ static esp_err_t _zh_ac_dimmer_validate_config(const zh_ac_dimmer_init_config_t
  * @brief Initialize GPIO pins for TRIAC control and zero-crossing detection.
  *
  * Configures the TRIAC GPIO as an output (pulled low) and the zero-crossing
- * GPIO as an input with pull-down and positive-edge interrupt. Installs the
+ * GPIO as an input with pull-down and both-edge interrupt. Installs the
  * ESP-IDF ISR service (if not already installed) and registers the ISR
  * handler for the zero-crossing pin.
  *
@@ -65,9 +77,11 @@ static esp_err_t _zh_ac_dimmer_gpio_init(const zh_ac_dimmer_init_config_t *confi
 /**
  * @brief Initialize the gptimer used for TRIAC firing delay.
  *
- * Creates a new gptimer with a 1 MHz resolution (1 µs steps), registers
+ * Creates a new gptimer with a 1 MHz resolution (1 us steps), registers the
- * the alarm callback that fires the TRIAC, enables the timer, and starts
+ * alarm callback that fires the TRIAC, and enables the timer.
- * it in auto-reload mode.
+ * The timer is enabled but not started. It is stopped, reset and armed from
+ * the rising-edge branch of the zero-crossing ISR, then started when a delay
+ * is required.
  *
  * @param handle Pointer to the dimmer handle (timer handle stored here)
  *
@@ -79,13 +93,39 @@ static esp_err_t _zh_ac_dimmer_timer_init(zh_ac_dimmer_handle_t *handle);
 /**
  * @brief ISR handler for zero-crossing detection.
  *
- * Executed on every positive edge of the zero-crossing signal. Resets the
+ * Executed on both edges of the zero-crossing signal. The edge polarity is
- * TRIAC gate low, updates the last zero-crossing timestamp, and schedules
+ * determined from the current GPIO level:
- * a gptimer alarm to fire the TRIAC at the appropriate phase angle.
  *
- * - At dimming = 0: TRIAC stays off (gate held low).
+ * - On a falling edge (falling edge follows a rising edge of the same pulse),
- * - At dimming = 100: TRIAC fires immediately (gate set high).
+ *   the width of the zero-crossing pulse is measured and fed into the
- * - At dimming 1–99: gptimer alarm fires after a calculated delay.
+ *   auto-calibration EMA for `base_offset_us`. The value represents the
+ *   advance of the rising edge relative to the physical mains zero crossing
+ *   and is computed as `pulse_width / 2` (valid for a symmetric AC-input
+ *   optocoupler). No TRIAC action is taken on falling edges.
+ *
+ * - On a rising edge, the interval since the previous rising edge is compared
+ *   against the half-cycle range derived from `ZH_AC_DIMMER_FREQ_MIN_HZ` and
+ *   `ZH_AC_DIMMER_FREQ_MAX_HZ`:
+ *
+ *   - An interval shorter than the minimum is treated as spurious and ignored.
+ *   - An interval longer than the maximum resets the timing state: the period
+ *     filter and the calibration sample counter are cleared, the TRIAC gate is
+ *     set low, and only the timestamp is kept.
+ *   - The first rising edge only stores its timestamp and sets the TRIAC gate low.
+ *
+ *   Each accepted rising edge updates the low-pass filtered half-period and
+ *   resets the TRIAC gate low, then behaves according to the running state and
+ *   the dimming level:
+ *
+ *   - When not running or at dimming = 0: the timer is stopped and reset, and
+ *     the gate stays low.
+ *   - When the computed delay is not positive: the TRIAC fires immediately
+ *     (gate set high).
+ *   - Otherwise: the gptimer alarm fires after a delay calculated from the
+ *     filtered period, the dimming value and the auto-calibrated base offset,
+ *     clamped to leave a guard band (period / 20, at least 5 us) before the
+ *     end of the half-cycle. The delay decreases as the dimming value
+ *     increases, so the TRIAC fires earlier and the load receives more power.
  *
  * @param arg Pointer to the dimmer handle (passed from GPIO ISR)
  */
@@ -94,31 +134,32 @@ static void _zh_ac_dimmer_isr_handler(void *arg);
 /**
  * @brief gptimer alarm callback that fires the TRIAC.
  *
- * Sets the TRIAC gate high to trigger conduction, then stops and resets
+ * Stops the timer and clears its count, then sets the TRIAC gate high to
- * the timer for the next half-cycle.
+ * trigger conduction, but only while the dimmer is running and the dimming
+ * level is above zero. Otherwise the gate is left unchanged until the next
+ * zero-crossing event.
  *
  * @param timer Handle to the gptimer that triggered the alarm
  * @param edata Event data (unused)
  * @param user_ctx Pointer to the dimmer handle
  *
- * @return `false` to indicate that the timer should not auto-restart
+ * @return false to indicate that no higher-priority task needs to be woken
  */
 static bool _zh_ac_dimmer_timer_on_alarm_cb(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx);
 
 esp_err_t zh_ac_dimmer_init(const zh_ac_dimmer_init_config_t *config, zh_ac_dimmer_handle_t **handle)
 {
     ZH_LOGI("AC dimmer initialization started.");
-
     ZH_ERROR_CHECK(config != NULL && handle != NULL, ESP_ERR_INVALID_ARG, NULL, "AC dimmer initialization failed. Invalid argument.");
     ZH_ERROR_CHECK(*handle == NULL, ESP_ERR_INVALID_STATE, NULL, "AC dimmer initialization failed. AC dimmer is already initialized.");
     *handle = heap_caps_calloc(1, sizeof(zh_ac_dimmer_handle_t), MALLOC_CAP_8BIT);
-    ZH_ERROR_CHECK(*handle != NULL, ESP_ERR_NO_MEM, NULL, "AC dimmer initialization failed. Failed to allocate 160X handle.");
+    ZH_ERROR_CHECK(*handle != NULL, ESP_ERR_NO_MEM, NULL, "AC dimmer initialization failed. Failed to allocate handle.");
     ZH_ERROR_CHECK(_zh_ac_dimmer_validate_config(config) == ESP_OK, ESP_FAIL, heap_caps_free(*handle); *handle = NULL, "AC dimmer initialization failed. Initial configuration check failed.");
     ZH_ERROR_CHECK(_zh_ac_dimmer_gpio_init(config, *handle) == ESP_OK, ESP_FAIL, heap_caps_free(*handle); *handle = NULL, "AC dimmer initialization failed. GPIO initialization failed.");
     ZH_ERROR_CHECK(_zh_ac_dimmer_timer_init(*handle) == ESP_OK, ESP_FAIL,
-                   {ZH_ERROR_CHECK(gpio_isr_handler_remove(config->zero_cross_gpio) == ESP_OK, ESP_FAIL, NULL, "Remove GPIO isr handler failed.")};
+                   {ZH_ERROR_CHECK_CONT(gpio_isr_handler_remove(config->zero_cross_gpio) == ESP_OK, NULL, "Remove GPIO isr handler failed.")};
-                   {ZH_ERROR_CHECK(gpio_reset_pin(config->triac_gpio) == ESP_OK, ESP_FAIL, NULL, "Reset GPIO failed.")};
+                   {ZH_ERROR_CHECK_CONT(gpio_reset_pin(config->triac_gpio) == ESP_OK, NULL, "Reset GPIO failed.")};
-                   {ZH_ERROR_CHECK(gpio_reset_pin(config->zero_cross_gpio) == ESP_OK, ESP_FAIL, NULL, "Reset GPIO failed.")};
+                   {ZH_ERROR_CHECK_CONT(gpio_reset_pin(config->zero_cross_gpio) == ESP_OK, NULL, "Reset GPIO failed.")};
                    heap_caps_free(*handle); *handle = NULL, "AC dimmer initialization failed. Timer initialization failed.");
     ZH_LOGI("AC dimmer initialization completed successfully.");
     return ESP_OK;
@@ -128,12 +169,13 @@ esp_err_t zh_ac_dimmer_deinit(zh_ac_dimmer_handle_t **handle)
 {
     ZH_LOGI("AC dimmer deinitialization started.");
     ZH_ERROR_CHECK(handle != NULL && *handle != NULL, ESP_ERR_INVALID_ARG, NULL, "AC dimmer deinitialization failed. Invalid argument.");
-    ZH_ERROR_CHECK(gptimer_stop((*handle)->dimmer_timer_handle) == ESP_OK, ESP_FAIL, NULL, "AC dimmer deinitialization failed. Timer stop fail.");
+    (*handle)->is_dimmer_work = false;
-    ZH_ERROR_CHECK(gptimer_disable((*handle)->dimmer_timer_handle) == ESP_OK, ESP_FAIL, NULL, "AC dimmer deinitialization failed. Timer disable fail.");
+    ZH_ERROR_CHECK_CONT(gpio_isr_handler_remove((*handle)->zero_cross_gpio) == ESP_OK, NULL, "AC dimmer deinitialization failed. Remove GPIO isr handler failed.");
-    ZH_ERROR_CHECK(gptimer_del_timer((*handle)->dimmer_timer_handle) == ESP_OK, ESP_FAIL, NULL, "AC dimmer deinitialization failed. Timer delete fail.");
+    ZH_ERROR_CHECK_CONT(gpio_reset_pin((*handle)->triac_gpio) == ESP_OK, NULL, "AC dimmer deinitialization failed. Reset GPIO failed.");
-    ZH_ERROR_CHECK(gpio_isr_handler_remove((*handle)->zero_cross_gpio) == ESP_OK, ESP_FAIL, NULL, "AC dimmer deinitialization failed. Remove GPIO isr handler failed.");
+    ZH_ERROR_CHECK_CONT(gpio_reset_pin((*handle)->zero_cross_gpio) == ESP_OK, NULL, "AC dimmer deinitialization failed. Reset GPIO failed.");
-    ZH_ERROR_CHECK(gpio_reset_pin((*handle)->triac_gpio) == ESP_OK, ESP_FAIL, NULL, "AC dimmer deinitialization failed. Reset GPIO failed.");
+    ZH_ERROR_CHECK_CONT(gptimer_stop((*handle)->dimmer_timer_handle) == ESP_OK, NULL, "AC dimmer deinitialization failed. Timer stop fail.");
-    ZH_ERROR_CHECK(gpio_reset_pin((*handle)->zero_cross_gpio) == ESP_OK, ESP_FAIL, NULL, "AC dimmer deinitialization failed. Reset GPIO failed.");
+    ZH_ERROR_CHECK_CONT(gptimer_disable((*handle)->dimmer_timer_handle) == ESP_OK, NULL, "AC dimmer deinitialization failed. Timer disable fail.");
+    ZH_ERROR_CHECK_CONT(gptimer_del_timer((*handle)->dimmer_timer_handle) == ESP_OK, NULL, "AC dimmer deinitialization failed. Timer delete fail.");
     heap_caps_free(*handle);
     *handle = NULL;
     ZH_LOGI("AC dimmer deinitialization completed successfully.");
@@ -197,23 +239,23 @@ static esp_err_t _zh_ac_dimmer_gpio_init(const zh_ac_dimmer_init_config_t *confi
     ZH_ERROR_CHECK(gpio_config(&triac_gpio_config) == ESP_OK, ESP_FAIL, NULL, "Triac GPIO configuration failed.");
     ZH_ERROR_CHECK(gpio_set_level(config->triac_gpio, 0) == ESP_OK, ESP_FAIL, NULL, "Triac GPIO set failed.");
     gpio_config_t zero_cross_gpio_config = {
-        .intr_type = GPIO_INTR_POSEDGE,
+        .intr_type = GPIO_INTR_ANYEDGE,
         .mode = GPIO_MODE_INPUT,
         .pin_bit_mask = (1ULL << config->zero_cross_gpio),
         .pull_down_en = GPIO_PULLDOWN_ENABLE,
         .pull_up_en = GPIO_PULLUP_DISABLE,
     };
     ZH_ERROR_CHECK(gpio_config(&zero_cross_gpio_config) == ESP_OK, ESP_FAIL,
-                   {ZH_ERROR_CHECK(gpio_reset_pin(config->triac_gpio) == ESP_OK, ESP_FAIL, NULL, "Reset GPIO failed.")}, "Zero cross GPIO configuration failed.");
+                   {ZH_ERROR_CHECK_CONT(gpio_reset_pin(config->triac_gpio) == ESP_OK, NULL, "Reset GPIO failed.")}, "Zero cross GPIO configuration failed.");
     esp_err_t err = gpio_install_isr_service(ESP_INTR_FLAG_LOWMED);
     ZH_ERROR_CHECK(err == ESP_OK || err == ESP_ERR_INVALID_STATE, ESP_FAIL,
-                   {ZH_ERROR_CHECK(gpio_reset_pin(config->triac_gpio) == ESP_OK, ESP_FAIL, NULL, "Reset GPIO failed.")};
+                   {ZH_ERROR_CHECK_CONT(gpio_reset_pin(config->triac_gpio) == ESP_OK, NULL, "Reset GPIO failed.")};
-                   {ZH_ERROR_CHECK(gpio_reset_pin(config->zero_cross_gpio) == ESP_OK, ESP_FAIL, NULL, "Reset GPIO failed.")}, "Failed install isr service.")
+                   {ZH_ERROR_CHECK_CONT(gpio_reset_pin(config->zero_cross_gpio) == ESP_OK, NULL, "Reset GPIO failed.")}, "Failed install isr service.")
-    ZH_ERROR_CHECK(gpio_isr_handler_add(config->zero_cross_gpio, _zh_ac_dimmer_isr_handler, handle) == ESP_OK, ESP_FAIL,
-                   {ZH_ERROR_CHECK(gpio_reset_pin(config->triac_gpio) == ESP_OK, ESP_FAIL, NULL, "Reset GPIO failed.")};
-                   {ZH_ERROR_CHECK(gpio_reset_pin(config->zero_cross_gpio) == ESP_OK, ESP_FAIL, NULL, "Reset GPIO failed.")}, "Failed add isr handler.");
     handle->triac_gpio = config->triac_gpio;
     handle->zero_cross_gpio = config->zero_cross_gpio;
+    ZH_ERROR_CHECK(gpio_isr_handler_add(config->zero_cross_gpio, _zh_ac_dimmer_isr_handler, handle) == ESP_OK, ESP_FAIL,
+                   {ZH_ERROR_CHECK_CONT(gpio_reset_pin(config->triac_gpio) == ESP_OK, NULL, "Reset GPIO failed.")};
+                   {ZH_ERROR_CHECK_CONT(gpio_reset_pin(config->zero_cross_gpio) == ESP_OK, NULL, "Reset GPIO failed.")}, "Failed add isr handler.");
     return ESP_OK;
 }
 
@@ -222,55 +264,129 @@ static esp_err_t _zh_ac_dimmer_timer_init(zh_ac_dimmer_handle_t *handle)
     gptimer_config_t timer_config = {
         .clk_src = GPTIMER_CLK_SRC_DEFAULT,
         .direction = GPTIMER_COUNT_UP,
-        .resolution_hz = 1 * 1000 * 1000,
+        .resolution_hz = 1000000,
     };
     ZH_ERROR_CHECK(gptimer_new_timer(&timer_config, &handle->dimmer_timer_handle) == ESP_OK, ESP_FAIL, NULL, "Failed create dimmer timer.");
     gptimer_event_callbacks_t cbs = {
         .on_alarm = _zh_ac_dimmer_timer_on_alarm_cb,
     };
     ZH_ERROR_CHECK(gptimer_register_event_callbacks(handle->dimmer_timer_handle, &cbs, handle) == ESP_OK, ESP_FAIL,
-                   {ZH_ERROR_CHECK(gptimer_del_timer(handle->dimmer_timer_handle) == ESP_OK, ESP_FAIL, NULL, "Timer delete fail.")}, "Failed register dimmer timer event callbacks.");
+                   {ZH_ERROR_CHECK_CONT(gptimer_del_timer(handle->dimmer_timer_handle) == ESP_OK, NULL, "Timer delete fail.")}, "Failed register dimmer timer event callbacks.");
     ZH_ERROR_CHECK(gptimer_enable(handle->dimmer_timer_handle) == ESP_OK, ESP_FAIL,
-                   {ZH_ERROR_CHECK(gptimer_del_timer(handle->dimmer_timer_handle) == ESP_OK, ESP_FAIL, NULL, "Timer delete fail.")}, "Failed enable dimmer timer.");
+                   {ZH_ERROR_CHECK_CONT(gptimer_del_timer(handle->dimmer_timer_handle) == ESP_OK, NULL, "Timer delete fail.")}, "Failed enable dimmer timer.");
     return ESP_OK;
 }
 
-static void IRAM_ATTR _zh_ac_dimmer_isr_handler(void *arg)
+static void _zh_ac_dimmer_isr_handler(void *arg)
 {
     zh_ac_dimmer_handle_t *handle = (zh_ac_dimmer_handle_t *)arg;
-    uint64_t _current_us = esp_timer_get_time();
+    uint64_t now_us = esp_timer_get_time();
-    // Ignore spurious interrupts that arrive too soon after the previous one.
+    if (gpio_get_level(handle->zero_cross_gpio) == 0)
-    if (_current_us - handle->prev_zero_crossing_us > (1250 * 0.9)) // 90% of zero-crossing period (1250 µs) at 400 Hz.
     {
-        gpio_set_level(handle->triac_gpio, 0);
+        if (handle->last_edge_was_rising == true)
-        handle->prev_zero_crossing_us = _current_us;
-        if (handle->is_dimmer_work == true)
         {
-            if (handle->dimmer_value != 0)
+            uint64_t pulse_width = now_us - handle->pulse_start_us;
+            const uint64_t pulse_min_us = 4;
+            const uint64_t pulse_max_us = (handle->period_us > 0) ? (handle->period_us / 4) : 2000;
+            if (pulse_width >= pulse_min_us && pulse_width <= pulse_max_us)
             {
-                if (handle->dimmer_value == 100)
+                uint32_t measured_adv = (uint32_t)(pulse_width / 2);
+                if (handle->auto_base_samples == 0)
                 {
-                    gpio_set_level(handle->triac_gpio, 1);
+                    handle->base_offset_us = measured_adv;
-                    return;
+                }
+                else
+                {
+                    handle->base_offset_us = (handle->base_offset_us * 15 + measured_adv) / 16;
+                }
+                if (handle->auto_base_samples < UINT32_MAX)
+                {
+                    ++handle->auto_base_samples;
                 }
-                gptimer_alarm_config_t _alarm_config = {0};
-                // Calculate alarm delay: maps dimming (1–99) to a µs value.
-                // 330 µs is the base offset (50% of zero-crossing period, measured with a logic analyzer).
-                _alarm_config.alarm_count = (uint64_t)((((1250 - 330) / 100) * (100 - handle->dimmer_value)) + 330);
-                _alarm_config.flags.auto_reload_on_alarm = false;
-                gptimer_set_alarm_action(handle->dimmer_timer_handle, &_alarm_config);
-                gptimer_start(handle->dimmer_timer_handle);
             }
         }
+        handle->last_edge_was_rising = false;
+        return;
     }
+    handle->last_edge_was_rising = true;
+    handle->pulse_start_us = now_us;
+    if (handle->prev_zero_crossing_us == 0)
+    {
+        handle->prev_zero_crossing_us = now_us;
+        gpio_set_level(handle->triac_gpio, 0);
+        return;
+    }
+    uint64_t delta_us = now_us - handle->prev_zero_crossing_us;
+    const uint64_t period_min_us = 1000000 / (2 * ZH_AC_DIMMER_FREQ_MAX_HZ);
+    const uint64_t period_max_us = 1000000 / (2 * ZH_AC_DIMMER_FREQ_MIN_HZ);
+    if (delta_us < period_min_us)
+    {
+        return;
+    }
+    if (delta_us > period_max_us)
+    {
+        handle->prev_zero_crossing_us = now_us;
+        handle->period_us = 0;
+        handle->auto_base_samples = 0;
+        gpio_set_level(handle->triac_gpio, 0);
+        return;
+    }
+    if (handle->period_us == 0)
+    {
+        handle->period_us = (uint32_t)delta_us;
+    }
+    else
+    {
+        handle->period_us = (handle->period_us * 7 + (uint32_t)delta_us) / 8;
+    }
+    handle->prev_zero_crossing_us = now_us;
+    gpio_set_level(handle->triac_gpio, 0);
+    if (handle->is_dimmer_work == false || handle->dimmer_value == 0)
+    {
+        gptimer_stop(handle->dimmer_timer_handle);
+        gptimer_set_raw_count(handle->dimmer_timer_handle, 0);
+        return;
+    }
+    uint32_t period = handle->period_us;
+    uint32_t base = handle->base_offset_us;
+    if (base >= period)
+    {
+        base = period;
+    }
+    int32_t t_fire = (int32_t)(((uint64_t)period * (100 - handle->dimmer_value)) / 100);
+    int32_t delay_us = t_fire + (int32_t)base;
+    if (delay_us <= 0)
+    {
+        gpio_set_level(handle->triac_gpio, 1);
+        return;
+    }
+    int32_t guard_us = (int32_t)(period / 20);
+    if (guard_us < 5)
+    {
+        guard_us = 5;
+    }
+    if (delay_us > (int32_t)period - guard_us)
+    {
+        delay_us = (int32_t)period - guard_us;
+    }
+    gptimer_stop(handle->dimmer_timer_handle);
+    gptimer_set_raw_count(handle->dimmer_timer_handle, 0);
+    gptimer_alarm_config_t alarm_config = {0};
+    alarm_config.alarm_count = (uint32_t)delay_us;
+    alarm_config.flags.auto_reload_on_alarm = false;
+    gptimer_set_alarm_action(handle->dimmer_timer_handle, &alarm_config);
+    gptimer_start(handle->dimmer_timer_handle);
 }
 
-static bool IRAM_ATTR _zh_ac_dimmer_timer_on_alarm_cb(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx)
+static bool _zh_ac_dimmer_timer_on_alarm_cb(gptimer_handle_t timer, const gptimer_alarm_event_data_t *edata, void *user_ctx)
 {
     (void)edata;
     zh_ac_dimmer_handle_t *handle = (zh_ac_dimmer_handle_t *)user_ctx;
-    gpio_set_level(handle->triac_gpio, 1);
     gptimer_stop(timer);
     gptimer_set_raw_count(timer, 0);
+    if (handle->is_dimmer_work && handle->dimmer_value > 0)
+    {
+        gpio_set_level(handle->triac_gpio, 1);
+    }
     return false;
 }