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

#pragma once

#include "esp_err.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "relay_chn_defs.h"
#include "relay_chn_types.h"
#include "relay_chn_priv_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Initializes the relay channel timer.
 * 
 * This function creates a timer for the relay channel to handle direction change inertia.
 * Required by *_ctl_* module.
 * 
 * @param chn_ctl Pointer to the relay channel control structure.
 * @return esp_err_t ESP_OK on success, or an error code on failure.
 */
esp_err_t relay_chn_init_timer(relay_chn_ctl_t *chn_ctl);

#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
/**
 * @brief Initializes the relay channel run limit timer.
 * 
 * This function creates a timer for the relay channel to handle run time limit.
 * Required by *_ctl_* module.
 * 
 * @param chn_ctl Pointer to the relay channel control structure.
 * 
 * @return esp_err_t ESP_OK on success, or an error code on failure.
 */
esp_err_t relay_chn_init_run_limit_timer(relay_chn_ctl_t *chn_ctl);
#endif // CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT

/**
 * @brief Issues a command to the relay channel.
 * 
 * Evaluates the current state of the relay channel and issues the command accordingly.
 * Required by *_core, *_ctl_* and *_tilt modules.
 * 
 * @param chn_ctl Pointer to the relay channel control structure.
 * @param cmd The command to issue.
 */
void relay_chn_issue_cmd(relay_chn_ctl_t* chn_ctl, relay_chn_cmd_t cmd);

/**
 * @brief Dispatches a relay channel command.
 * 
 * @param chn_ctl Pointer to the relay channel control structure.
 * @param cmd The command to dispatch.
 */
void relay_chn_dispatch_cmd(relay_chn_ctl_t *chn_ctl, relay_chn_cmd_t cmd);

/**
 * @brief Returns the string representation of a relay channel command.
 * 
 * @param cmd The relay channel command.
 * @return char* The string representation of the command.
 */
char *relay_chn_cmd_str(relay_chn_cmd_t cmd);

/**
 * @brief Starts the ESP timer once with the specified time in milliseconds.
 * 
 * Starts the ESP timer to run once after the specified time.
 * If the timer is already running, it stops it first and then starts it again.
 * Required by *_ctl_* and *_tilt modules.
 * 
 * @param esp_timer The ESP timer handle.
 * @param time_ms The time in milliseconds to wait before the timer expires.
 * @return esp_err_t ESP_OK on success, or an error code on failure.
 */
esp_err_t relay_chn_start_esp_timer_once(esp_timer_handle_t esp_timer, uint32_t time_ms);

/**
 * @brief Updates the state of the relay channel and notifies listeners.
 * 
 * This function updates the state of the relay channel and notifies all registered listeners
 * about the state change.
 * Required by *_ctl_* and *_tilt modules.
 * 
 * @param chn_ctl Pointer to the relay channel control structure.
 * @param new_state The new state to set for the relay channel.
 */
void relay_chn_update_state(relay_chn_ctl_t *chn_ctl, relay_chn_state_t new_state);

/**
 * @brief Return the text presentation of an state.
 * 
 * @param state A state with type of relay_chn_state_t.
 * @return char* The text presentation of the state. "UNKNOWN" if the state is not known.
 */
char *relay_chn_state_str(relay_chn_state_t state);

#if CONFIG_RELAY_CHN_COUNT > 1
/**
 * @brief Check if the provided channel ID is valid.
 * 
 * @param chn_id Channel ID to check.
 * @return true Channel ID is valid.
 * @return false Channel ID is invalid.
 */
bool relay_chn_is_channel_id_valid(uint8_t chn_id);
#endif // CONFIG_RELAY_CHN_COUNT > 1

#ifdef __cplusplus
}
#endif