538 lines
18 KiB
C
538 lines
18 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2025 Kozmotronik Tech
|
|
*
|
|
* SPDX-License-Identifier: MIT
|
|
*
|
|
* One relay channel consists of 2 output relays, hence 2 GPIO pins are required for each relay channel.
|
|
* This module provides an API to control the relay channels, specifically to drive bipolar motors.
|
|
* It also provides APIs to control the direction of the relay channel, bipolar motors in mind.
|
|
* To prevent mechanical strain on the motor, the component automatically manages direction changes
|
|
* with a configurable inertia delay, protecting it from abrupt reversals.
|
|
* The STOP command overrides any other command and clears the pending command if any.
|
|
*/
|
|
|
|
#pragma once
|
|
|
|
#include "esp_err.h"
|
|
#include "relay_chn_types.h"
|
|
#include "relay_chn_adapter.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Create and initialize relay channels.
|
|
*
|
|
* This function initializes the relay channels based on the provided GPIO map.
|
|
*
|
|
* @param gpio_map Pointer to an array of GPIO numbers that correspond to the relay channels.
|
|
* @param gpio_count The number of GPIOs in the gpio_map array.
|
|
*
|
|
* @return
|
|
* - ESP_OK: Success
|
|
* - ESP_ERR_INVALID_ARG: Invalid argument
|
|
* - ESP_FAIL: General failure
|
|
*/
|
|
esp_err_t relay_chn_create(const uint8_t* gpio_map, uint8_t gpio_count);
|
|
|
|
/**
|
|
* @brief Destroy the relay channels and free resources.
|
|
*
|
|
* This function cleans up the relay channels and releases any resources allocated during their creation.
|
|
*/
|
|
void relay_chn_destroy(void);
|
|
|
|
/**
|
|
* @brief Register a channel state change listener.
|
|
*
|
|
* @param listener A function that implements relay_chn_state_listener_t interface.
|
|
*
|
|
* @return
|
|
* - ESP_OK: Success
|
|
* - ESP_ERR_INVALID_ARG: Invalid argument
|
|
* - ESP_ERR_NO_MEM: No enough memory
|
|
* - ESP_FAIL: General failure
|
|
*/
|
|
esp_err_t relay_chn_register_listener(relay_chn_state_listener_t listener);
|
|
|
|
/**
|
|
* @brief Unregister a channel state change listener.
|
|
*
|
|
* @param listener A function that implements relay_chn_state_listener_t interface.
|
|
*/
|
|
void relay_chn_unregister_listener(relay_chn_state_listener_t listener);
|
|
|
|
#if CONFIG_RELAY_CHN_COUNT > 1
|
|
/**
|
|
* @brief Get the state of the specified relay channel.
|
|
*
|
|
* This function retrieves the current state of the relay channel identified by the given channel ID.
|
|
*
|
|
* @param chn_id The ID of the relay channel whose state is to be retrieved.
|
|
* @return The current state of the specified relay channel.
|
|
*/
|
|
relay_chn_state_t relay_chn_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.
|
|
*/
|
|
esp_err_t relay_chn_ctl_get_state_all(relay_chn_state_t *states);
|
|
|
|
/**
|
|
* @brief Get the state string of the specified relay channel.
|
|
*
|
|
* This function returns a string representation of the state of the relay
|
|
* channel identified by the given channel ID.
|
|
*
|
|
* @param chn_id The ID of the relay channel whose state is to be retrieved.
|
|
* The valid range of channel IDs depends on the specific hardware
|
|
* and implementation.
|
|
*
|
|
* @return A pointer to a string representing the state of the specified relay
|
|
* channel. The returned string is managed internally and should not be
|
|
* modified or freed by the caller.
|
|
*/
|
|
char *relay_chn_get_state_str(uint8_t chn_id);
|
|
|
|
/**
|
|
* @brief Runs the relay channel in the forward direction.
|
|
*
|
|
* This function activates the specified relay channel to run in the forward direction.
|
|
*
|
|
* @param chn_id The ID of the relay channel to be activated.
|
|
*/
|
|
void relay_chn_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.
|
|
*/
|
|
void relay_chn_ctl_run_forward_all(void);
|
|
|
|
/**
|
|
* @brief Runs the relay channel in reverse.
|
|
*
|
|
* This function activates the specified relay channel to run in reverse.
|
|
*
|
|
* @param chn_id The ID of the relay channel to be reversed.
|
|
*/
|
|
void relay_chn_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.
|
|
*/
|
|
void relay_chn_ctl_run_reverse_all(void);
|
|
|
|
/**
|
|
* @brief Stops the relay channel specified by the channel ID.
|
|
*
|
|
* This function stops the operation of the relay channel identified by the
|
|
* provided channel ID. It is typically used to turn off or disable the relay
|
|
* channel.
|
|
*
|
|
* @param chn_id The ID of the relay channel to stop.
|
|
*/
|
|
void relay_chn_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.
|
|
*/
|
|
void relay_chn_ctl_stop_all(void);
|
|
|
|
/**
|
|
* @brief Flips the direction of the specified relay channel.
|
|
*
|
|
* This function toggles the direction of the relay channel identified by the
|
|
* given channel ID.
|
|
*
|
|
* @param chn_id The ID of the relay channel to flip. This should be a valid
|
|
* channel ID within the range of available relay channels.
|
|
*/
|
|
void relay_chn_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.
|
|
*/
|
|
void relay_chn_ctl_flip_direction_all(void);
|
|
|
|
/**
|
|
* @brief Get the direction of the specified relay channel.
|
|
*
|
|
* This function retrieves the direction configuration of a relay channel
|
|
* identified by the given channel ID.
|
|
*
|
|
* @param chn_id The ID of the relay channel to query.
|
|
* @return The direction of the specified relay channel as a value of type
|
|
* relay_chn_direction_t.
|
|
*/
|
|
relay_chn_direction_t relay_chn_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);
|
|
|
|
#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.
|
|
*/
|
|
uint16_t relay_chn_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
|
|
*
|
|
* Sets the time limit in seconds for the specified channel. It will not proceed
|
|
* if the channel ID is invalid.
|
|
* If the limit_sec value is lesser than the CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC,
|
|
* the value will be set to CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC.
|
|
* If the limit_sec value is greater than the CONFIG_RELAY_CHN_RUN_LIMIT_MAX_SEC,
|
|
* the value will be set to CONFIG_RELAY_CHN_RUN_LIMIT_MAX_SEC.
|
|
*
|
|
* @param chn_id The ID of the relay channel to query.
|
|
* @param limit_sec The run limit time in seconds.
|
|
*/
|
|
void relay_chn_set_run_limit(uint8_t chn_id, uint16_t limit_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);
|
|
#endif // CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT == 1
|
|
|
|
|
|
#if CONFIG_RELAY_CHN_ENABLE_TILTING
|
|
|
|
/**
|
|
* @brief Enables automatic tilting for the specified relay channel.
|
|
*
|
|
* This function enables automatic tilting mode for the given relay channel.
|
|
* The channel will automatically switch between forward and reverse tilting
|
|
* based on the last movement of the channel
|
|
*
|
|
* @param chn_id The ID of the relay channel to enable automatic tilting.
|
|
*/
|
|
void relay_chn_tilt_auto(uint8_t chn_id);
|
|
|
|
/**
|
|
* @brief Initiates an automatic tilt operation for all configured relay channels.
|
|
*
|
|
* This function iterates through all configured relay channels and initiates an
|
|
* automatic tilt operation for each, based on their individual last run commands.
|
|
*/
|
|
void relay_chn_tilt_auto_all(void);
|
|
|
|
/**
|
|
* @brief Tilts the specified relay channel forward.
|
|
*
|
|
* This function initiates a forward tilting action for the specified relay channel.
|
|
*
|
|
* @param chn_id The ID of the relay channel to tilt forward.
|
|
*/
|
|
void relay_chn_tilt_forward(uint8_t chn_id);
|
|
|
|
/**
|
|
* @brief Initiates a forward tilt operation for all configured relay channels.
|
|
*/
|
|
void relay_chn_tilt_forward_all(void);
|
|
|
|
/**
|
|
* @brief Tilts the specified relay channel reverse.
|
|
*
|
|
* This function initiates a reverse tilting action for the specified relay channel.
|
|
*
|
|
* @param chn_id The ID of the relay channel to tilt reverse.
|
|
*/
|
|
void relay_chn_tilt_reverse(uint8_t chn_id);
|
|
|
|
/**
|
|
* @brief Initiates a reverse tilt operation for all configured relay channels.
|
|
*/
|
|
void relay_chn_tilt_reverse_all(void);
|
|
|
|
/**
|
|
* @brief Stops the tilting action on the specified relay channel.
|
|
*
|
|
* This function stops any ongoing tilting action (automatic or manual) on the specified relay channel.
|
|
*
|
|
* @param chn_id The ID of the relay channel to stop tilting.
|
|
*/
|
|
void relay_chn_tilt_stop(uint8_t chn_id);
|
|
|
|
/**
|
|
* @brief Stops any ongoing tilt operation for all configured relay channels.
|
|
*/
|
|
void relay_chn_tilt_stop_all(void);
|
|
|
|
/**
|
|
* @brief Sets the tilting sensitivity for the specified relay channel.
|
|
*
|
|
* This function sets the sensitivity for the automatic tilting mechanism. A higher sensitivity value
|
|
* typically means the channel will react more readily to tilting events.
|
|
*
|
|
* @param chn_id The ID of the relay channel to set the sensitivity for.
|
|
* @param sensitivity The sensitivity in percentage: 0 - 100%.
|
|
*/
|
|
void relay_chn_tilt_set_sensitivity(uint8_t chn_id, uint8_t sensitivity);
|
|
|
|
/**
|
|
* @brief Sets the tilt sensitivity for all configured relay channels.
|
|
*
|
|
* This function sets the tilt sensitivity for each channel based on the values
|
|
* provided in the `sensitivities` array. Each sensitivity value (0-100%)
|
|
* determines the `move_time_ms` and `pause_time_ms` for tilt operations.
|
|
* The new sensitivities are persisted in NVS if enabled.
|
|
*
|
|
* @param sensitivities Pointer to an array containing the desired tilt sensitivities.
|
|
*
|
|
* @return
|
|
* - ESP_OK: Success
|
|
* - ESP_ERR_INVALID_ARG: When sensitivities parameter is NULL
|
|
*/
|
|
esp_err_t relay_chn_tilt_set_sensitivity_all(uint8_t *sensitivities);
|
|
|
|
/**
|
|
* @brief Sets a single tilt sensitivity value for all configured relay channels.
|
|
*
|
|
* This function sets the same `sensitivity` value for all configured relay channels.
|
|
* The sensitivity value (0-100%) determines the `move_time_ms` and `pause_time_ms`
|
|
* for tilt operations. The new sensitivities are persisted in NVS if enabled.
|
|
*
|
|
* @param sensitivity The desired tilt sensitivity in percentage (0-100) to apply to all channels.
|
|
*/
|
|
void relay_chn_tilt_set_sensitivity_all_with(uint8_t sensitivity);
|
|
|
|
/**
|
|
* @brief Gets the tilting sensitivity for the specified relay channel.
|
|
*
|
|
* This function retrieves the currently set sensitivity for the specified relay channel's automatic
|
|
* tilting mechanism.
|
|
*
|
|
* @param chn_id The ID of the relay channel to get the sensitivity for.
|
|
* @param sensitivity The pointer to the memory in to which the sensitivity values will be copied.
|
|
* @param length The length of the sensitvity memory.
|
|
* @return
|
|
* - ESP_OK: Success
|
|
* - ESP_ERR_INVALID_ARG: Invalid argument
|
|
*/
|
|
uint8_t relay_chn_tilt_get_sensitivity(uint8_t chn_id);
|
|
|
|
/**
|
|
* @brief Gets the current tilt sensitivities for all configured relay channels.
|
|
*
|
|
* This function populates an array with the current tilt sensitivities (0-100%)
|
|
* of all configured relay channels. The caller must ensure the `sensitivity` array
|
|
* is large enough to hold `CONFIG_RELAY_CHN_COUNT` elements.
|
|
*
|
|
* @param sensitivity Pointer to an array where the sensitivities will be stored.
|
|
* @return ESP_OK on success, ESP_ERR_INVALID_ARG if `sensitivity` is NULL.
|
|
*/
|
|
esp_err_t relay_chn_tilt_get_sensitivity_all(uint8_t *sensitivities);
|
|
|
|
#endif // CONFIG_RELAY_CHN_ENABLE_TILTING
|
|
|
|
#else // CONFIG_RELAY_CHN_COUNT > 1
|
|
|
|
/**
|
|
* @brief Get the state of the relay channel.
|
|
*
|
|
* This function retrieves the current state of the relay channel.
|
|
*
|
|
* @return The current state of the relay channel.
|
|
*/
|
|
relay_chn_state_t relay_chn_get_state(void);
|
|
|
|
/**
|
|
* @brief Get the state string of the relay channel.
|
|
*
|
|
* This function returns a string representation of the state of the relay channel.
|
|
*
|
|
* @return A pointer to a string representing the state of the relay
|
|
* channel. The returned string is managed internally and should not be
|
|
* modified or freed by the caller.
|
|
*/
|
|
char *relay_chn_get_state_str(void);
|
|
|
|
/**
|
|
* @brief Runs the relay channel in the forward direction.
|
|
*
|
|
* This function activates the relay channel to run in the forward direction.
|
|
*/
|
|
void relay_chn_run_forward(void);
|
|
|
|
/**
|
|
* @brief Runs the relay channel in reverse.
|
|
*
|
|
* This function activates the relay channel to run in reverse.
|
|
*/
|
|
void relay_chn_run_reverse(void);
|
|
|
|
/**
|
|
* @brief Stops the relay channel.
|
|
*
|
|
* This function stops the operation of the relay channel.
|
|
*/
|
|
void relay_chn_stop(void);
|
|
|
|
/**
|
|
* @brief Flips the direction of the relay channel.
|
|
*
|
|
* This function toggles the direction of the relay channel.
|
|
*/
|
|
void relay_chn_flip_direction(void);
|
|
|
|
/**
|
|
* @brief Get the direction of the relay channel.
|
|
*
|
|
* This function retrieves the direction configuration of a relay channel.
|
|
*
|
|
* @return The direction of the relay channel as a value of type
|
|
* relay_chn_direction_t.
|
|
*/
|
|
relay_chn_direction_t relay_chn_get_direction(void);
|
|
|
|
#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
|
|
/**
|
|
* @brief Get the run limit for the channel
|
|
*
|
|
* @return The run limit value for the channel.
|
|
*/
|
|
uint16_t relay_chn_get_run_limit(void);
|
|
|
|
/**
|
|
* @brief Set the run limit for the channel
|
|
*
|
|
* Sets the time limit in seconds for the channel. It will not proceed
|
|
* if the channel ID is invalid.
|
|
* If the limit_sec value is lesser than the CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC,
|
|
* the value will be set to CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC.
|
|
* If the limit_sec value is greater than the CONFIG_RELAY_CHN_RUN_LIMIT_MAX_SEC,
|
|
* the value will be set to CONFIG_RELAY_CHN_RUN_LIMIT_MAX_SEC.
|
|
*
|
|
* @param limit_sec The run limit time in seconds.
|
|
*/
|
|
void relay_chn_set_run_limit(uint16_t limit_sec);
|
|
#endif // CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT == 1
|
|
|
|
|
|
#if CONFIG_RELAY_CHN_ENABLE_TILTING
|
|
|
|
/**
|
|
* @brief Enables automatic tilting for the relay channel.
|
|
*
|
|
* This function enables automatic tilting mode for the given relay channel.
|
|
* The channel will automatically switch between forward and reverse tilting
|
|
* based on the last movement of the channel
|
|
*/
|
|
void relay_chn_tilt_auto(void);
|
|
|
|
/**
|
|
* @brief Tilts the relay channel forward.
|
|
*
|
|
* This function initiates a forward tilting action for the relay channel.
|
|
*/
|
|
void relay_chn_tilt_forward(void);
|
|
|
|
/**
|
|
* @brief Tilts the relay channel reverse.
|
|
*
|
|
* This function initiates a reverse tilting action for the relay channel.
|
|
*/
|
|
void relay_chn_tilt_reverse(void);
|
|
|
|
/**
|
|
* @brief Stops the tilting action on the relay channel.
|
|
*
|
|
* This function stops any ongoing tilting action (automatic or manual) on the relay channel.
|
|
*/
|
|
void relay_chn_tilt_stop(void);
|
|
|
|
/**
|
|
* @brief Sets the tilting sensitivity for the relay channel.
|
|
*
|
|
* This function sets the sensitivity for the automatic tilting mechanism. A higher sensitivity value
|
|
* typically means the channel will react more readily to tilting events.
|
|
*
|
|
* @param sensitivity The sensitivity in percentage: 0 - 100%.
|
|
*/
|
|
void relay_chn_tilt_set_sensitivity(uint8_t sensitivity);
|
|
|
|
/**
|
|
* @brief Gets the tilting sensitivity for the relay channel.
|
|
*
|
|
* This function retrieves the currently set sensitivity for the relay channel's automatic
|
|
* tilting mechanism.
|
|
*
|
|
* @return Sensitivity value in percentage: 0 - 100%.
|
|
*/
|
|
uint8_t relay_chn_tilt_get_sensitivity(void);
|
|
|
|
#endif // CONFIG_RELAY_CHN_ENABLE_TILTING
|
|
|
|
#endif // CONFIG_RELAY_CHN_COUNT > 1
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif |