/*
 * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
 *
 * SPDX-License-Identifier: MIT
 */

#include "esp_check.h"
#include "relay_chn_core.h"
#include "relay_chn_output.h"
#include "relay_chn_run_info.h"
#include "relay_chn_tilt.h"

#if CONFIG_RELAY_CHN_ENABLE_NVS
#include "relay_chn_nvs.h"

#define RELAY_CHN_TILT_FLUSH_DEBOUNCE_MS 3000
#endif


static const char *TAG = "RELAY_CHN_TILT";

/**@{*/
/*
 * Tilt Pattern Timing Definitions
 * 
 * The min and max timing definitions as well as the default timing definitions.
 * These definitions are used to define and adjust the tilt sensitivity.
 */
#define RELAY_CHN_TILT_RUN_MIN_MS 50
#define RELAY_CHN_TILT_RUN_MAX_MS 10
#define RELAY_CHN_TILT_PAUSE_MIN_MS 450
#define RELAY_CHN_TILT_PAUSE_MAX_MS 90

#define RELAY_CHN_TILT_DEFAULT_RUN_MS 15
#define RELAY_CHN_TILT_DEFAULT_PAUSE_MS 150

#define RELAY_CHN_TILT_DEFAULT_SENSITIVITY \
    ( (RELAY_CHN_TILT_DEFAULT_RUN_MS - RELAY_CHN_TILT_RUN_MIN_MS) \
    * 100 / (RELAY_CHN_TILT_RUN_MAX_MS - RELAY_CHN_TILT_RUN_MIN_MS) )
/**@}*/

#define ADJUST_TILT_SENS_BOUNDARIES(sens) if (sens > 100) sens = 100

/// @brief Tilt steps.
typedef enum {
    RELAY_CHN_TILT_STEP_NONE,       /*!< No step */
    RELAY_CHN_TILT_STEP_PENDING,    /*!< Pending step */
    RELAY_CHN_TILT_STEP_MOVE,       /*!< Move step. Tilt is driving either for forward or reverse */
    RELAY_CHN_TILT_STEP_PAUSE       /*!< Pause step. Tilt is paused */
} relay_chn_tilt_step_t;

/// @brief Tilt timing structure to manage tilt pattern timing.
typedef struct {
    uint8_t sensitivity;    /*!< Tilt sensitivity in percentage (%) */
    uint32_t move_time_ms;  /*!< Move time in milliseconds */
    uint32_t pause_time_ms; /*!< Pause time in milliseconds */
} relay_chn_tilt_timing_t;

/// @brief Tilt control structure to manage tilt operations.
typedef struct relay_chn_tilt_ctl {
    relay_chn_ctl_t *chn_ctl;               /*!< The relay channel control structure */
    relay_chn_tilt_cmd_t cmd;               /*!< The tilt command in process */
    relay_chn_tilt_step_t step;             /*!< Current tilt step */
    relay_chn_tilt_timing_t tilt_timing;    /*!< Tilt timing structure */
    uint16_t tilt_count;                    /*!< Tilt count to manage forward and reverse tilts */
    esp_timer_handle_t tilt_timer;          /*!< Tilt timer handle */
#if CONFIG_RELAY_CHN_ENABLE_NVS
    esp_timer_handle_t flush_timer;         /*!< Flush timer to avoid frequent write of tilt counters */
#endif
} relay_chn_tilt_ctl_t;


#if CONFIG_RELAY_CHN_COUNT > 1
static relay_chn_tilt_ctl_t tilt_ctls[CONFIG_RELAY_CHN_COUNT];
#else
static relay_chn_tilt_ctl_t tilt_ctl;
#endif


// Returns the required timing before tilting depending on the last run.
static uint32_t relay_chn_tilt_get_required_timing_before_tilting(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_tilt_cmd_t cmd)
{
    relay_chn_cmd_t last_run_cmd = relay_chn_run_info_get_last_run_cmd(tilt_ctl->chn_ctl->run_info);
    if (cmd == RELAY_CHN_TILT_CMD_FORWARD && last_run_cmd == RELAY_CHN_CMD_REVERSE)
        return 0;
    else if (cmd == RELAY_CHN_TILT_CMD_REVERSE && last_run_cmd == RELAY_CHN_CMD_FORWARD)
        return 0;
    
    uint32_t last_run_cmd_time_ms = relay_chn_run_info_get_last_run_cmd_time_ms(tilt_ctl->chn_ctl->run_info);
    uint32_t inertia_time_passed_ms = (uint32_t) (esp_timer_get_time() / 1000) - last_run_cmd_time_ms;
    return CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS - inertia_time_passed_ms;
}

static void relay_chn_tilt_execute_stop(relay_chn_tilt_ctl_t *tilt_ctl);

static void relay_chn_tilt_start_timer_or_stop(relay_chn_tilt_ctl_t *tilt_ctl, esp_timer_handle_t timer, uint32_t time_ms, const char* timer_name)
{
    if (relay_chn_start_esp_timer_once(timer, time_ms) != ESP_OK) {
        ESP_LOGE(TAG, "Failed to start %s timer for ch %d", timer_name, tilt_ctl->chn_ctl->id);
        // Attempt to go to a safe state for tilt.
        // relay_chn_tilt_execute_stop is safe to call, it stops timers and sets state.
        relay_chn_tilt_execute_stop(tilt_ctl);
    }
}

// Issue a tilt command to a specific relay channel.
static void relay_chn_tilt_issue_cmd(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_tilt_cmd_t cmd)
{
    // TILT_STOP is safe and high priority
    if (cmd == RELAY_CHN_TILT_CMD_STOP) {
        if (tilt_ctl->chn_ctl->state == RELAY_CHN_STATE_STOPPED) {
            return; // Do nothing if already stopped
        }
        // If the command is TILT_STOP, issue it immediately
        relay_chn_tilt_dispatch_cmd(tilt_ctl, cmd);
        return;
    }
    
    if (relay_chn_run_info_get_last_run_cmd(tilt_ctl->chn_ctl->run_info) == RELAY_CHN_CMD_NONE) {
        // Do not tilt if the channel hasn't been run before
        ESP_LOGD(TAG, "relay_chn_tilt_issue_cmd: Tilt will not be executed since the channel hasn't been run yet");
        return;
    }
    
    if (tilt_ctl->cmd == cmd) {
        ESP_LOGD(TAG, "relay_chn_tilt_issue_cmd: There is already a tilt command in progress!");
        return;
    }

    // Set the command that will be processed
    tilt_ctl->cmd = cmd;
    switch (tilt_ctl->chn_ctl->state) {
        case RELAY_CHN_STATE_IDLE:
            // Relay channel is free, tilt can be issued immediately
            relay_chn_tilt_dispatch_cmd(tilt_ctl, cmd);
            break;
        
        case RELAY_CHN_STATE_FORWARD_PENDING:
        case RELAY_CHN_STATE_REVERSE_PENDING:
            // Issue a stop command first so that the timer and pending cmd get cleared
            relay_chn_dispatch_cmd(tilt_ctl->chn_ctl, RELAY_CHN_CMD_STOP);
            // FALLTHRU
        case RELAY_CHN_STATE_STOPPED: {
            // Check if channel needs timing before tilting
            uint32_t req_timing_ms = relay_chn_tilt_get_required_timing_before_tilting(tilt_ctl, cmd);
            if (req_timing_ms == 0) {
                relay_chn_tilt_dispatch_cmd(tilt_ctl, cmd);
            } else {
                // Channel needs timing before running tilting action, schedule it
                tilt_ctl->step = RELAY_CHN_TILT_STEP_PENDING;
                relay_chn_tilt_start_timer_or_stop(tilt_ctl, tilt_ctl->tilt_timer, req_timing_ms, "pending tilt");
            }
            break;
        }

        case RELAY_CHN_STATE_FORWARD:
            if (cmd == RELAY_CHN_TILT_CMD_FORWARD) {
                // Stop the running channel first
                relay_chn_dispatch_cmd(tilt_ctl->chn_ctl, RELAY_CHN_CMD_STOP);
                // Schedule for tilting
                tilt_ctl->step = RELAY_CHN_TILT_STEP_PENDING;
                relay_chn_tilt_start_timer_or_stop(tilt_ctl, tilt_ctl->tilt_timer, CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS, "tilt inertia");
            } else if (cmd == RELAY_CHN_TILT_CMD_REVERSE) {
                // Stop the running channel first
                relay_chn_dispatch_cmd(tilt_ctl->chn_ctl, RELAY_CHN_CMD_STOP);
                // If the tilt cmd is TILT_REVERSE then dispatch it immediately
                relay_chn_tilt_dispatch_cmd(tilt_ctl, cmd);
            }
            break;

        case RELAY_CHN_STATE_REVERSE:
            if (cmd == RELAY_CHN_TILT_CMD_REVERSE) {
                // Stop the running channel first
                relay_chn_dispatch_cmd(tilt_ctl->chn_ctl, RELAY_CHN_CMD_STOP);
                // Schedule for tilting
                tilt_ctl->step = RELAY_CHN_TILT_STEP_PENDING;
                relay_chn_tilt_start_timer_or_stop(tilt_ctl, tilt_ctl->tilt_timer, CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS, "tilt inertia");
            } else if (cmd == RELAY_CHN_TILT_CMD_FORWARD) {
                // Stop the running channel first
                relay_chn_dispatch_cmd(tilt_ctl->chn_ctl, RELAY_CHN_CMD_STOP);
                // If the tilt cmd is TILT_FORWARD then dispatch it immediately
                relay_chn_tilt_dispatch_cmd(tilt_ctl, cmd);
            }
            break;

        default:
            ESP_LOGD(TAG, "relay_chn_tilt_issue_cmd: Unexpected relay channel state: %s!", relay_chn_state_str(tilt_ctl->chn_ctl->state));
    }
}

static void relay_chn_tilt_issue_auto(relay_chn_tilt_ctl_t *tilt_ctl)
{
    relay_chn_cmd_t last_run_cmd = relay_chn_run_info_get_last_run_cmd(tilt_ctl->chn_ctl->run_info);
    if (last_run_cmd == RELAY_CHN_CMD_FORWARD || tilt_ctl->chn_ctl->state == RELAY_CHN_STATE_FORWARD) {
        relay_chn_tilt_issue_cmd(tilt_ctl, RELAY_CHN_TILT_CMD_FORWARD);
    }
    else if (last_run_cmd == RELAY_CHN_CMD_REVERSE || tilt_ctl->chn_ctl->state == RELAY_CHN_STATE_REVERSE) {
        relay_chn_tilt_issue_cmd(tilt_ctl, RELAY_CHN_TILT_CMD_REVERSE);
    }
}


#if CONFIG_RELAY_CHN_COUNT > 1
static void relay_chn_tilt_issue_cmd_on_all_channels(relay_chn_tilt_cmd_t cmd)
{
    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
        relay_chn_tilt_ctl_t* tilt_ctl = &tilt_ctls[i];
        relay_chn_tilt_issue_cmd(tilt_ctl, cmd);
    }
}

void relay_chn_tilt_auto(uint8_t chn_id)
{
    if (relay_chn_is_channel_id_valid(chn_id)) {
        relay_chn_tilt_issue_auto(&tilt_ctls[chn_id]);
    }
}

void relay_chn_tilt_auto_all()
{
    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
        relay_chn_tilt_issue_auto(&tilt_ctls[i]);
    }
}

void relay_chn_tilt_forward(uint8_t chn_id)
{
    if (relay_chn_is_channel_id_valid(chn_id)) {
        relay_chn_tilt_issue_cmd(&tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_FORWARD);
    }
}

void relay_chn_tilt_forward_all()
{
    relay_chn_tilt_issue_cmd_on_all_channels(RELAY_CHN_TILT_CMD_FORWARD);
}

void relay_chn_tilt_reverse(uint8_t chn_id)
{
    if (relay_chn_is_channel_id_valid(chn_id)) {
        relay_chn_tilt_issue_cmd(&tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_REVERSE);
    }
}

void relay_chn_tilt_reverse_all()
{
    relay_chn_tilt_issue_cmd_on_all_channels(RELAY_CHN_TILT_CMD_REVERSE);
}

void relay_chn_tilt_stop(uint8_t chn_id)
{
    if (!relay_chn_is_channel_id_valid(chn_id)) {
        relay_chn_tilt_dispatch_cmd(&tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_STOP);
    }
}

void relay_chn_tilt_stop_all()
{
    relay_chn_tilt_issue_cmd_on_all_channels(RELAY_CHN_TILT_CMD_STOP);
}

#else // CONFIG_RELAY_CHN_COUNT > 1

void relay_chn_tilt_auto()
{
    relay_chn_tilt_issue_auto(&tilt_ctl);
}

void relay_chn_tilt_forward()
{
    relay_chn_tilt_issue_cmd(&tilt_ctl, RELAY_CHN_TILT_CMD_FORWARD);
}

void relay_chn_tilt_reverse()
{
    relay_chn_tilt_issue_cmd(&tilt_ctl, RELAY_CHN_TILT_CMD_REVERSE);
}

void relay_chn_tilt_stop()
{
    relay_chn_tilt_dispatch_cmd(&tilt_ctl, RELAY_CHN_TILT_CMD_STOP);
}
#endif // CONFIG_RELAY_CHN_COUNT > 1

static void relay_chn_tilt_set_timing_values(relay_chn_tilt_timing_t *tilt_timing,
                                             uint8_t sensitivity,
                                             uint32_t run_time_ms,
                                             uint32_t pause_time_ms)
{
    tilt_timing->sensitivity = sensitivity;
    tilt_timing->move_time_ms = run_time_ms;
    tilt_timing->pause_time_ms = pause_time_ms;
}

static void relay_chn_tilt_compute_set_sensitivity(relay_chn_tilt_ctl_t *tilt_ctl, uint8_t sensitivity)
{
    if (sensitivity >= 100) {
        relay_chn_tilt_set_timing_values(&tilt_ctl->tilt_timing,
                                         100,
                                         RELAY_CHN_TILT_RUN_MAX_MS,
                                         RELAY_CHN_TILT_PAUSE_MAX_MS);
    }
    else if (sensitivity == 0) {
        relay_chn_tilt_set_timing_values(&tilt_ctl->tilt_timing,
                                         0,
                                         RELAY_CHN_TILT_RUN_MIN_MS,
                                         RELAY_CHN_TILT_PAUSE_MIN_MS);
    }
    else if (sensitivity == RELAY_CHN_TILT_DEFAULT_SENSITIVITY) {
        relay_chn_tilt_set_timing_values(&tilt_ctl->tilt_timing,
                                         sensitivity,
                                         RELAY_CHN_TILT_DEFAULT_RUN_MS,
                                         RELAY_CHN_TILT_DEFAULT_PAUSE_MS);
    }
    else {
        // Compute the new timing values from the sensitivity percent value by using linear interpolation
        uint32_t tilt_run_time_ms = 0, tilt_pause_time_ms = 0;
        tilt_run_time_ms = RELAY_CHN_TILT_RUN_MIN_MS + (sensitivity * (RELAY_CHN_TILT_RUN_MAX_MS - RELAY_CHN_TILT_RUN_MIN_MS) / 100);
        tilt_pause_time_ms = RELAY_CHN_TILT_PAUSE_MIN_MS + (sensitivity * (RELAY_CHN_TILT_PAUSE_MAX_MS - RELAY_CHN_TILT_PAUSE_MIN_MS) / 100);
        
        relay_chn_tilt_set_timing_values(&tilt_ctl->tilt_timing,
                                         sensitivity,
                                         tilt_run_time_ms,
                                         tilt_pause_time_ms);
    }
}

#if CONFIG_RELAY_CHN_COUNT > 1
void relay_chn_tilt_set_sensitivity(uint8_t chn_id, uint8_t sensitivity)
{
    if (relay_chn_is_channel_id_valid(chn_id)) {
        ADJUST_TILT_SENS_BOUNDARIES(sensitivity);
        relay_chn_tilt_compute_set_sensitivity(&tilt_ctls[chn_id], sensitivity);
        
#if CONFIG_RELAY_CHN_ENABLE_NVS
        relay_chn_nvs_set_tilt_sensitivity(chn_id, sensitivity);
#endif // CONFIG_RELAY_CHN_ENABLE_NVS
    }
}

esp_err_t relay_chn_tilt_set_sensitivity_all(uint8_t *sensitivities)
{
    ESP_RETURN_ON_FALSE(sensitivities != NULL, ESP_ERR_INVALID_ARG, TAG, "set_sensitivity_all: sensitivities is NULL");
    
    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
        uint8_t *src_sensitivity = &sensitivities[i];
        if (src_sensitivity == NULL) {
            ESP_LOGW(TAG, "set_sensitivity_all: Run limits have been set until channel %d since sensitivities[%d] is NULL", i, i);
            break;
        }
        ADJUST_TILT_SENS_BOUNDARIES(*src_sensitivity);
        relay_chn_tilt_compute_set_sensitivity(&tilt_ctls[i], *src_sensitivity);
#if CONFIG_RELAY_CHN_ENABLE_NVS
        relay_chn_nvs_set_tilt_sensitivity(i, *src_sensitivity);
#endif // CONFIG_RELAY_CHN_ENABLE_NVS
    }
    return ESP_OK;
}

void relay_chn_tilt_set_sensitivity_all_with(uint8_t sensitivity)
{
    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
        ADJUST_TILT_SENS_BOUNDARIES(sensitivity);
        relay_chn_tilt_compute_set_sensitivity(&tilt_ctls[i], sensitivity);
#if CONFIG_RELAY_CHN_ENABLE_NVS
        relay_chn_nvs_set_tilt_sensitivity(i, sensitivity);
#endif // CONFIG_RELAY_CHN_ENABLE_NVS
    }
}

uint8_t relay_chn_tilt_get_sensitivity(uint8_t chn_id)
{
    return relay_chn_is_channel_id_valid(chn_id) ?
           tilt_ctls[chn_id].tilt_timing.sensitivity : 0;
}

esp_err_t relay_chn_tilt_get_sensitivity_all(uint8_t *sensitivities)
{
    ESP_RETURN_ON_FALSE(sensitivities != NULL, ESP_ERR_INVALID_ARG, TAG, "get_sensitivity_all: sensitivities is NULL");
    
    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
        uint8_t *dest_sensitivity = &sensitivities[i];
        if (dest_sensitivity == NULL) {
            ESP_LOGW(TAG, "get_sensitivity_all: Sensitivites have been copied until channel %d since sensitivities[%d] is NULL", i, i);
            break;
        }
        *dest_sensitivity = tilt_ctls[i].tilt_timing.sensitivity;
    }
    return ESP_OK;
}

#else

void relay_chn_tilt_set_sensitivity(uint8_t sensitivity)
{
    ADJUST_TILT_SENS_BOUNDARIES(sensitivity);
    relay_chn_tilt_compute_set_sensitivity(&tilt_ctl, sensitivity);
    
#if CONFIG_RELAY_CHN_ENABLE_NVS
    relay_chn_nvs_set_tilt_sensitivity(0, sensitivity);
#endif // CONFIG_RELAY_CHN_ENABLE_NVS
}

uint8_t relay_chn_tilt_get_sensitivity()
{
    return tilt_ctl.tilt_timing.sensitivity;
}
#endif // CONFIG_RELAY_CHN_COUNT > 1

void relay_chn_tilt_reset_count(relay_chn_tilt_ctl_t *tilt_ctl)
{
    tilt_ctl->tilt_count = 0;

#if CONFIG_RELAY_CHN_ENABLE_NVS
    esp_timer_stop(tilt_ctl->flush_timer);
#endif
}

/**
 * @brief Update tilt count automatically and return the current value.
 * 
 * This helper function updates the relevant tilt count depending on the
 * last run info and helps the tilt module in deciding whether the requested
 * tilt should execute or not.
 * 
 * This is useful to control reverse tilting for the same direction particularly.
 * For example:
 *   - If the channel's last run was FORWARD and a TILT_FORWARD is requested,
 *     then the tilt count will count up on the relay_chn_tilt_ctl_t::tilt_count 
 *     and the function will return the actual count.
 *   - If the channel's last run was FORWARD and a TILT_REVERSE is requested,
 *     then the relay_chn_tilt_ctl_t::tilt_count will be checked against zero first, 
 *     and then it will count down and return the actual count if it is greater 
 *     than 0, else the function will return 0.
 *   - If the tilt command is irrelevant then the function will return 0.
 *   - If the last run is irrelevant then the function will return 0.
 * 
 * @param tilt_ctl The relay channel handle.
 * 
 * @return The actual value of the relevant count.
 * @return 1 if the last tilt_count was 1 and decremented to 0.
 * @return 0 if:
 *           - related count is already 0.
 *           - tilt command is irrelevant.
 *           - last run info is irrelevant.
 */
static uint16_t relay_chn_tilt_count_update(relay_chn_tilt_ctl_t *tilt_ctl)
{
    relay_chn_cmd_t last_run_cmd = relay_chn_run_info_get_last_run_cmd(tilt_ctl->chn_ctl->run_info);
    if (last_run_cmd == RELAY_CHN_CMD_FORWARD) {
        if (tilt_ctl->cmd == RELAY_CHN_TILT_CMD_FORWARD) {
            return ++tilt_ctl->tilt_count;
        }
        else if (tilt_ctl->cmd == RELAY_CHN_TILT_CMD_REVERSE) {
            if (tilt_ctl->tilt_count > 0) {
                --tilt_ctl->tilt_count;
                // Still should do one more move, return non-zero value
                return 1;
            }
            else
                return 0;
        }
    }
    else if (last_run_cmd == RELAY_CHN_CMD_REVERSE) {
        if (tilt_ctl->cmd == RELAY_CHN_TILT_CMD_REVERSE) {
            return ++tilt_ctl->tilt_count;
        }
        else if (tilt_ctl->cmd == RELAY_CHN_TILT_CMD_FORWARD) {
            if (tilt_ctl->tilt_count > 0) {
                --tilt_ctl->tilt_count;
                // Still should do one more move, return non-zero value
                return 1;
            }
            else
                return 0;
        }
    }

    // Irrelevant case -> reset
    tilt_ctl->tilt_count = 0;
    return 0;
}

#if CONFIG_RELAY_CHN_ENABLE_NVS
static esp_err_t relay_chn_tilt_save_tilt_count(relay_chn_tilt_ctl_t *tilt_ctl)
{
     // Save the tilt count to NVS storage
    esp_err_t ret = relay_chn_nvs_set_tilt_count(tilt_ctl->chn_ctl->id, tilt_ctl->tilt_count);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "relay_chn_tilt_execute_stop: Failed to save tilt count for channel #%d: %s", tilt_ctl->chn_ctl->id, esp_err_to_name(ret));
    }
    return ESP_OK;
}

static void relay_chn_tilt_flush_timer_cb(void *arg)
{
    relay_chn_tilt_ctl_t* tilt_ctl = (relay_chn_tilt_ctl_t*) arg;
    ESP_RETURN_VOID_ON_FALSE(tilt_ctl != NULL, TAG, "relay_chn_tilt_flush_timer_cb: timer arg is NULL");
    // Save the tilt count to storage
    esp_err_t ret = relay_chn_tilt_save_tilt_count(tilt_ctl);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "relay_chn_tilt_execute_stop: Failed to save tilt count for channel #%d: %s", tilt_ctl->chn_ctl->id, esp_err_to_name(ret));
    }
}
#endif

static void relay_chn_tilt_execute_stop(relay_chn_tilt_ctl_t *tilt_ctl)
{
    // Stop the channel's timer if active
    esp_timer_stop(tilt_ctl->tilt_timer);
    // Invalidate tilt cmd and step
    tilt_ctl->cmd = RELAY_CHN_TILT_CMD_NONE;
    tilt_ctl->step = RELAY_CHN_TILT_STEP_NONE;
    // Stop the channel
    if (relay_chn_output_stop(tilt_ctl->chn_ctl->output) != ESP_OK) {
        ESP_LOGE(TAG, "relay_chn_tilt_execute_stop: Failed to output stop for relay channel #%d!", tilt_ctl->chn_ctl->id);
    }
    relay_chn_dispatch_cmd(tilt_ctl->chn_ctl, RELAY_CHN_CMD_IDLE);

#if CONFIG_RELAY_CHN_ENABLE_NVS
    // Start the flush debounce timer
    if (relay_chn_start_esp_timer_once(tilt_ctl->flush_timer, RELAY_CHN_TILT_FLUSH_DEBOUNCE_MS) != ESP_OK) {
        ESP_LOGE(TAG, "Failed to start tilt flush timer for ch %d", tilt_ctl->chn_ctl->id);
        // This is not a critical failure, just log it. The count will be saved on next stop.
    }
#endif
}

static void relay_chn_tilt_execute_forward(relay_chn_tilt_ctl_t *tilt_ctl)
{
    if (relay_chn_output_reverse(tilt_ctl->chn_ctl->output) != ESP_OK) {
        ESP_LOGE(TAG, "relay_chn_tilt_execute_forward: Failed to output reverse for relay channel #%d!", tilt_ctl->chn_ctl->id);
        // Stop tilting because of the error
        relay_chn_tilt_execute_stop(tilt_ctl);
        return;
    }
    // Set the move time timer
    relay_chn_tilt_start_timer_or_stop(tilt_ctl, tilt_ctl->tilt_timer, tilt_ctl->tilt_timing.move_time_ms, "tilt move");
    // Set to pause step
    tilt_ctl->step = RELAY_CHN_TILT_STEP_PAUSE;
}

static void relay_chn_tilt_execute_reverse(relay_chn_tilt_ctl_t *tilt_ctl)
{
    if (relay_chn_output_forward(tilt_ctl->chn_ctl->output) != ESP_OK) {
        ESP_LOGE(TAG, "relay_chn_tilt_execute_reverse: Failed to output forward for relay channel #%d!", tilt_ctl->chn_ctl->id);
        // Stop tilting because of the error
        relay_chn_tilt_execute_stop(tilt_ctl);
        return;
    }
    // Set the move time timer
    relay_chn_tilt_start_timer_or_stop(tilt_ctl, tilt_ctl->tilt_timer, tilt_ctl->tilt_timing.move_time_ms, "tilt move");
    // Set to pause step
    tilt_ctl->step = RELAY_CHN_TILT_STEP_PAUSE;
}

static void relay_chn_tilt_execute_pause(relay_chn_tilt_ctl_t *tilt_ctl)
{
    // Pause the channel
    if (relay_chn_output_stop(tilt_ctl->chn_ctl->output) != ESP_OK) {
        ESP_LOGE(TAG, "relay_chn_tilt_execute_pause: Failed to output stop for relay channel #%d!", tilt_ctl->chn_ctl->id);
        // Stop tilting because of the error
        relay_chn_tilt_execute_stop(tilt_ctl);
        return;
    }

    // Update the tilt count before the next move and expect the return value to be greater than 0
    if (relay_chn_tilt_count_update(tilt_ctl) == 0) {
        ESP_LOGD(TAG, "relay_chn_tilt_execute_pause: Relay channel cannot tilt anymore");
        // Stop tilting since the tilting limit has been reached
        relay_chn_tilt_execute_stop(tilt_ctl);
        return;
    }

    // Set the pause time timer
    relay_chn_tilt_start_timer_or_stop(tilt_ctl, tilt_ctl->tilt_timer, tilt_ctl->tilt_timing.pause_time_ms, "tilt pause");
    // Set to move step
    tilt_ctl->step = RELAY_CHN_TILT_STEP_MOVE;
}

esp_err_t relay_chn_tilt_dispatch_cmd(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_tilt_cmd_t cmd)
{
    ESP_LOGD(TAG, "relay_chn_tilt_dispatch_cmd: Command: %d", cmd);

    switch(cmd) {
        case RELAY_CHN_TILT_CMD_STOP:
            relay_chn_tilt_execute_stop(tilt_ctl);
            break;
        case RELAY_CHN_TILT_CMD_FORWARD:
            relay_chn_tilt_execute_forward(tilt_ctl);
            // Update channel state
            relay_chn_update_state(tilt_ctl->chn_ctl, RELAY_CHN_STATE_TILT_FORWARD);
            break;
        case RELAY_CHN_TILT_CMD_REVERSE:
            relay_chn_tilt_execute_reverse(tilt_ctl);
            // Update channel state
            relay_chn_update_state(tilt_ctl->chn_ctl, RELAY_CHN_STATE_TILT_REVERSE);
            break;
        default:
            ESP_LOGW(TAG, "Unexpected relay channel tilt command: %d!", cmd);
    }
    return ESP_OK;
}

// Timer callback for the relay_chn_tilt_control_t::tilt_timer
static void relay_chn_tilt_timer_cb(void *arg)
{
    relay_chn_tilt_ctl_t* tilt_ctl = (relay_chn_tilt_ctl_t*) arg;
    ESP_RETURN_VOID_ON_FALSE(tilt_ctl != NULL, TAG, "relay_chn_tilt_timer_cb: timer arg is NULL");
    
    switch (tilt_ctl->step)
    {
        case RELAY_CHN_TILT_STEP_MOVE:
            if (tilt_ctl->cmd == RELAY_CHN_TILT_CMD_FORWARD) {
                relay_chn_tilt_execute_forward(tilt_ctl);
            }
            else if (tilt_ctl->cmd == RELAY_CHN_TILT_CMD_REVERSE) {
                relay_chn_tilt_execute_reverse(tilt_ctl);
            }
            break;

        case RELAY_CHN_TILT_STEP_PAUSE:
            relay_chn_tilt_execute_pause(tilt_ctl);
            break;

        case RELAY_CHN_TILT_STEP_PENDING:
            // Just dispatch the pending tilt command
            relay_chn_tilt_dispatch_cmd(tilt_ctl, tilt_ctl->cmd);
            break;
        
        default:
            break;
    }
}

#if CONFIG_RELAY_CHN_ENABLE_NVS
static esp_err_t relay_chn_tilt_load_sensitivity(uint8_t ch, uint8_t *sensitivity)
{
    esp_err_t ret = relay_chn_nvs_get_tilt_sensitivity(ch, sensitivity);
    if (ret == ESP_ERR_NVS_NOT_FOUND) {
        *sensitivity = RELAY_CHN_TILT_DEFAULT_SENSITIVITY;
        return ESP_OK;
    }
    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt sensitivity for channel %d", ch);
    return ESP_OK;
}

static esp_err_t relay_chn_tilt_load_tilt_count(uint8_t ch, uint16_t *tilt_count)
{
    esp_err_t ret = relay_chn_nvs_get_tilt_count(ch, tilt_count);
    if (ret == ESP_ERR_NVS_NOT_FOUND) {
        ESP_LOGD(TAG, "relay_chn_tilt_load_tilt_count: No tilt count found in NVS for channel %d, initializing to zero", ch);
        tilt_count = 0;
        return ESP_OK;
    }
    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt counters for channel %d", ch);
    return ESP_OK;
}
#endif // CONFIG_RELAY_CHN_ENABLE_NVS

static esp_err_t relay_chn_tilt_ctl_init(relay_chn_tilt_ctl_t *tilt_ctl,
                                         relay_chn_ctl_t *chn_ctl,
                                         uint16_t tilt_count ,
                                         uint8_t sensitivity)
{
    tilt_ctl->cmd = RELAY_CHN_TILT_CMD_NONE;
    tilt_ctl->step = RELAY_CHN_TILT_STEP_NONE;
    relay_chn_tilt_compute_set_sensitivity(tilt_ctl, sensitivity);
    tilt_ctl->tilt_count = tilt_count;

    tilt_ctl->chn_ctl = chn_ctl;
    tilt_ctl->chn_ctl->tilt_ctl = tilt_ctl;
    
    // Create tilt timer for the channel
    char timer_name[32];
    snprintf(timer_name, sizeof(timer_name), "relay_chn_%2d_tilt_timer", chn_ctl->id);
    esp_timer_create_args_t timer_args = {
        .callback = relay_chn_tilt_timer_cb,
        .arg = tilt_ctl,
        .name = timer_name
    };
    esp_err_t ret = esp_timer_create(&timer_args, &tilt_ctl->tilt_timer);
    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create tilt timer for channel %d", chn_ctl->id);

#if CONFIG_RELAY_CHN_ENABLE_NVS
    // Create flush timer for the tilt counters
    snprintf(timer_name, sizeof(timer_name), "relay_chn_%2d_tilt_flush_timer", chn_ctl->id);
    timer_args.callback = relay_chn_tilt_flush_timer_cb;
    timer_args.name = timer_name;
    ret = esp_timer_create(&timer_args, &tilt_ctl->flush_timer);
    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create tilt flush timer for channel %d", chn_ctl->id);
#endif
    return ESP_OK;
}

esp_err_t relay_chn_tilt_init(relay_chn_ctl_t *chn_ctls)
{
    uint8_t sensitivity;
    uint16_t tilt_count;
    
#if CONFIG_RELAY_CHN_COUNT > 1
    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
        esp_err_t ret;
#if CONFIG_RELAY_CHN_ENABLE_NVS
        ret = relay_chn_tilt_load_sensitivity(i, &sensitivity);
        ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt sensitivity for channel %d", i);
        ret = relay_chn_tilt_load_tilt_count(i, &tilt_count);
        ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt count for channel %d", i);
#else
        sensitivity = RELAY_CHN_TILT_DEFAULT_SENSITIVITY;
        tilt_count = 0;
#endif // CONFIG_RELAY_CHN_ENABLE_NVS == 1
        ret = relay_chn_tilt_ctl_init(&tilt_ctls[i], &chn_ctls[i], tilt_count, sensitivity);
        ESP_RETURN_ON_ERROR(ret, TAG, "Failed to init tilt control for channel %d", i);
    }
    return ESP_OK;
#else
    sensitivity = RELAY_CHN_TILT_DEFAULT_SENSITIVITY;
    tilt_count = 0;
#if CONFIG_RELAY_CHN_ENABLE_NVS
    esp_err_t ret = relay_chn_tilt_load_sensitivity(0, &sensitivity);
    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt sensitivity for channel %d", 0);
    ret = relay_chn_tilt_load_tilt_count(0, &tilt_count);
    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt count for channel %d", 0);
#endif // CONFIG_RELAY_CHN_ENABLE_NVS == 1
    return relay_chn_tilt_ctl_init(&tilt_ctl, chn_ctls, tilt_count, sensitivity);
#endif // CONFIG_RELAY_CHN_COUNT > 1
}

void relay_chn_tilt_ctl_deinit(relay_chn_tilt_ctl_t *tilt_ctl)
{
    if (tilt_ctl->tilt_timer != NULL) {
        esp_timer_delete(tilt_ctl->tilt_timer);
        tilt_ctl->tilt_timer = NULL;
    }
#if CONFIG_RELAY_CHN_ENABLE_NVS
    if (tilt_ctl->flush_timer != NULL) {
        esp_timer_delete(tilt_ctl->flush_timer);
        tilt_ctl->flush_timer = NULL;
    }
#endif // CONFIG_RELAY_CHN_ENABLE_NVS == 1
}

void relay_chn_tilt_deinit()
{
#if CONFIG_RELAY_CHN_COUNT > 1
    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
        relay_chn_tilt_ctl_deinit(&tilt_ctls[i]);
    }
#else
    relay_chn_tilt_ctl_deinit(&tilt_ctl);
#endif // CONFIG_RELAY_CHN_COUNT > 1
}