relay_chn/include/relay_chn_adapter.h

/*
 * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
 *
 * SPDX-License-Identifier: MIT
 * 
 * An adapter header to expose the appropriate API functions to the public API
 * depending on the CONFIG_RELAY_CHN_COUNT value which determines single or multi mode.
 */

#pragma once

#ifdef __cplusplus
extern "C" {
#endif

#if CONFIG_RELAY_CHN_COUNT > 1
/**
 * @brief Get the current state of a relay channel.
 *
 * @param[in] chn_id Channel ID to get state for.
 * @return Current state of the specified channel, or RELAY_CHN_STATE_UNDEFINED if invalid.
 */
extern relay_chn_state_t relay_chn_ctl_get_state(uint8_t chn_id);

/**
 * @brief Gets the current state of all relay channels.
 *
 * This function populates an array with the current states of all configured
 * relay channels. The caller must ensure the `states` array is large enough
 * to hold `CONFIG_RELAY_CHN_COUNT` elements.
 *
 * @param states Pointer to an array where the states will be stored.
 * 
 * @return ESP_OK on success, ESP_ERR_INVALID_ARG if `states` is NULL.
 */
extern esp_err_t relay_chn_ctl_get_state_all(relay_chn_state_t *states);

/**
 * @brief Get string representation of a relay channel's state.
 *
 * @param[in] chn_id Channel ID to get state string for.
 * @return String representation of channel state, or "UNDEFINED" if invalid.
 */
extern char *relay_chn_ctl_get_state_str(uint8_t chn_id);

/**
 * @brief Run a relay channel in forward direction.
 *
 * @param[in] chn_id Channel ID to run forward.
 */
extern void relay_chn_ctl_run_forward(uint8_t chn_id);

/**
 * @brief Commands all configured relay channels to run in the forward direction.
 *
 * This function iterates through all configured relay channels and issues a command
 * to each to move in the forward direction.
 */
extern void relay_chn_ctl_run_forward_all(void);

/**
 * @brief Run a relay channel in reverse direction.
 *
 * @param[in] chn_id Channel ID to run reverse.
 */
extern void relay_chn_ctl_run_reverse(uint8_t chn_id);

/**
 * @brief Commands all configured relay channels to run in the reverse direction.
 *
 * This function iterates through all configured relay channels and issues a command
 * to each to move in the reverse direction.
 */
extern void relay_chn_ctl_run_reverse_all(void);

/**
 * @brief Stop a relay channel.
 *
 * @param[in] chn_id Channel ID to stop.
 */
extern void relay_chn_ctl_stop(uint8_t chn_id);

/**
 * @brief Commands all configured relay channels to stop.
 *
 * This function iterates through all configured relay channels and issues a command to each to stop any ongoing movement.
 */
extern void relay_chn_ctl_stop_all(void);

/**
 * @brief Flip the running direction of a relay channel.
 *
 * @param[in] chn_id Channel ID to flip direction for.
 */
extern void relay_chn_ctl_flip_direction(uint8_t chn_id);

/**
 * @brief Flips the logical direction of all configured relay channels.
 *
 * This function iterates through all configured relay channels and swaps the 
 * physical GPIO pins assigned to the forward and reverse directions for each.
 */
extern void relay_chn_ctl_flip_direction_all(void);

/**
 * @brief Get the current direction of a relay channel.
 *
 * @param[in] chn_id Channel ID to get direction for.
 * @return Current direction of the specified channel, or RELAY_CHN_DIRECTION_DEFAULT if invalid.
 */
extern relay_chn_direction_t relay_chn_ctl_get_direction(uint8_t chn_id);

/**
 * @brief Gets the current logical direction of all configured relay channels.
 *
 * This function populates an array with the current logical directions of all
 * configured relay channels. The caller must ensure the `directions` array is
 * large enough to hold `CONFIG_RELAY_CHN_COUNT` elements.
 *
 * @param directions Pointer to an array where the directions will be stored.
 * @return ESP_OK on success, ESP_ERR_INVALID_ARG if `directions` is NULL.
 */
esp_err_t relay_chn_ctl_get_direction_all(relay_chn_direction_t *directions);

static inline relay_chn_state_t relay_chn_get_state(uint8_t chn_id)
{
    return relay_chn_ctl_get_state(chn_id);
}

static inline esp_err_t relay_chn_get_state_all(relay_chn_state_t *states)
{
    return relay_chn_ctl_get_state_all(states);
}

static inline char *relay_chn_get_state_str(uint8_t chn_id)
{
    return relay_chn_ctl_get_state_str(chn_id);
}

static inline void relay_chn_run_forward(uint8_t chn_id)
{
    relay_chn_ctl_run_forward(chn_id);
}

static inline void relay_chn_run_forward_all(void)
{
    relay_chn_ctl_run_forward_all();
}

static inline void relay_chn_run_reverse(uint8_t chn_id)
{
    relay_chn_ctl_run_reverse(chn_id);
}

static inline void relay_chn_run_reverse_all(void)
{
    relay_chn_ctl_run_reverse_all();
}

static inline void relay_chn_stop(uint8_t chn_id)
{
    relay_chn_ctl_stop(chn_id);
}

static inline void relay_chn_stop_all(void)
{
    relay_chn_ctl_stop_all();
}

static inline void relay_chn_flip_direction(uint8_t chn_id)
{
    relay_chn_ctl_flip_direction(chn_id);
}

static inline void relay_chn_flip_direction_all(void)
{
    relay_chn_ctl_flip_direction_all();
}

static inline relay_chn_direction_t relay_chn_get_direction(uint8_t chn_id)
{
    return relay_chn_ctl_get_direction(chn_id);
}

static inline esp_err_t relay_chn_get_direction_all(relay_chn_direction_t *directions)
{
    return relay_chn_ctl_get_direction_all(directions);
}

#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
/**
 * @brief Get the run limit for the specified channel
 *
 * @param chn_id The ID of the relay channel to query.
 * 
 * @return The run limit value for the relevant channel if the channel ID is valid.
 *         0 if the channel ID is invalid.
 */
extern uint16_t relay_chn_ctl_get_run_limit(uint8_t chn_id);

/**
 * @brief Gets the configured run limits for all configured relay channels.
 *
 * This function populates an array with the run limits (in seconds) of all
 * configured relay channels. The caller must ensure the `limits_sec` array is
 * large enough to hold `CONFIG_RELAY_CHN_COUNT` elements.
 *
 * @param limits_sec Pointer to an array where the run limits will be stored.
 * @return ESP_OK on success, ESP_ERR_INVALID_ARG if `limits_sec` is NULL.
 */
esp_err_t relay_chn_ctl_get_run_limit_all(uint16_t *limits_sec);

/**
 * @brief Set the run limit for the specified channel
 *
 * @param chn_id The ID of the relay channel to query.
 * @param time_sec The run limit time in seconds.
 */
extern void relay_chn_ctl_set_run_limit(uint8_t chn_id, uint16_t time_sec);

/**
 * @brief Sets the run limits for all configured relay channels.
 *
 * This function iterates through all configured relay channels and sets their
 * run limits based on the values provided in the `limits_sec` array. Each value
 * will be clamped within the configured `RELAY_CHN_RUN_LIMIT_MIN_SEC` and
 * `RELAY_CHN_RUN_LIMIT_MAX_SEC` boundaries. The new run limits are persisted
 * in NVS if enabled.
 *
 * @param limits_sec Pointer to an array containing the desired run limits in seconds.
 * @return ESP_OK on success, ESP_ERR_INVALID_ARG if `limits_sec` is NULL.
 */
esp_err_t relay_chn_ctl_set_run_limit_all(uint16_t *limits_sec);

/**
 * @brief Sets a single run limit value for all configured relay channels.
 *
 * This function sets the same `limit_sec` value for all configured relay channels.
 * The value will be clamped within the configured `RELAY_CHN_RUN_LIMIT_MIN_SEC`
 * and `RELAY_CHN_RUN_LIMIT_MAX_SEC` boundaries.
 * @param limit_sec The desired run limit in seconds to apply to all channels.
 * @return ESP_OK on success.
 */
esp_err_t relay_chn_ctl_set_run_limit_all_with(uint16_t limit_sec);

static inline uint16_t relay_chn_get_run_limit(uint8_t chn_id)
{
    return relay_chn_ctl_get_run_limit(chn_id);
}

static inline esp_err_t relay_chn_get_run_limit_all(uint16_t *limits_sec)
{
    return relay_chn_ctl_get_run_limit_all(limits_sec);
}

static inline void relay_chn_set_run_limit(uint8_t chn_id, uint16_t time_sec)
{
    relay_chn_ctl_set_run_limit(chn_id, time_sec);
}

static inline esp_err_t relay_chn_set_run_limit_all(uint16_t *limits_sec)
{
    return relay_chn_ctl_set_run_limit_all(limits_sec);
}

static inline esp_err_t relay_chn_set_run_limit_all_with(uint16_t limit_sec)
{
    return relay_chn_ctl_set_run_limit_all_with(limit_sec);
}
#endif // CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT == 1

#else

/**
 * @brief Get the current state of the relay channel.
 *
 * @return Current state of the channel.
 */
extern relay_chn_state_t relay_chn_ctl_get_state(void);

/**
 * @brief Get string representation of the relay channel's state.
 *
 * @return String representation of channel state.
 */
extern char *relay_chn_ctl_get_state_str(void);

/**
 * @brief Run the relay channel in forward direction.
 */
extern void relay_chn_ctl_run_forward(void);

/**
 * @brief Run the relay channel in reverse direction.
 */
extern void relay_chn_ctl_run_reverse(void);

/**
 * @brief Stop the relay channel.
 */
extern void relay_chn_ctl_stop(void);

/**
 * @brief Flip the running direction of the relay channel.
 */
extern void relay_chn_ctl_flip_direction(void);

/**
 * @brief Get the current direction of the relay channel.
 *
 * @return Current direction of the channel.
 */
extern relay_chn_direction_t relay_chn_ctl_get_direction(void);

static inline relay_chn_state_t relay_chn_get_state(void)
{
    return relay_chn_ctl_get_state();
}

static inline char *relay_chn_get_state_str(void)
{
    return relay_chn_ctl_get_state_str();
}

static inline void relay_chn_run_forward(void)
{
    relay_chn_ctl_run_forward();
}

static inline void relay_chn_run_reverse(void)
{
    relay_chn_ctl_run_reverse();
}

static inline void relay_chn_stop(void)
{
    relay_chn_ctl_stop();
}

static inline void relay_chn_flip_direction(void)
{
    relay_chn_ctl_flip_direction();
}

static inline relay_chn_direction_t relay_chn_get_direction(void)
{
    return relay_chn_ctl_get_direction();
}

#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
/**
 * @brief Get the run limit for the channel
 * 
 * @return The run limit value for the channel.
 */
extern uint16_t relay_chn_ctl_get_run_limit(void);

/**
 * @brief Set the run limit for the channel
 *
 * @param time_sec The run limit time in seconds.
 */
extern void relay_chn_ctl_set_run_limit(uint16_t time_sec);

static inline uint16_t relay_chn_get_run_limit(void)
{
    return relay_chn_ctl_get_run_limit();
}

static inline void relay_chn_set_run_limit(uint16_t time_sec)
{
    relay_chn_ctl_set_run_limit(time_sec);
}
#endif // CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT == 1

#endif // CONFIG_RELAY_CHN_COUNT > 1

#ifdef __cplusplus
}
#endif