ismail
7a0f9b1420
It turned out that esp_event was adding extra complexity to the code base and it was completely unnecessary. So it has been removed from the component completely. The actions are now executed directly in the `relay_chn_distpacth_cmd()` and `relay_chn_tilt_dispatch_cmd()` functions. This change has simplified the component as well as reduced the memory footprint. Fixes #1084, refs #1083
384 lines
12 KiB
C
384 lines
12 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_defs.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 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 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 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 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 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 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);
|
|
|
|
#if RELAY_CHN_ENABLE_RUN_LIMIT == 1
|
|
/**
|
|
* @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 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 time_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 time_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 time_sec The run limit time in seconds.
|
|
*/
|
|
void relay_chn_set_run_limit(uint8_t chn_id, uint16_t time_sec);
|
|
#endif // RELAY_CHN_ENABLE_RUN_LIMIT == 1
|
|
|
|
|
|
#if CONFIG_RELAY_CHN_ENABLE_TILTING == 1
|
|
|
|
/**
|
|
* @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 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 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 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 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 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
|
|
*/
|
|
esp_err_t relay_chn_tilt_get_sensitivity(uint8_t chn_id, uint8_t *sensitivity, size_t length);
|
|
|
|
#endif // CONFIG_RELAY_CHN_ENABLE_TILTING
|
|
|
|
#else // 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 RELAY_CHN_ENABLE_RUN_LIMIT == 1
|
|
/**
|
|
* @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 time_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 time_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 time_sec The run limit time in seconds.
|
|
*/
|
|
void relay_chn_set_run_limit(uint16_t time_sec);
|
|
#endif // RELAY_CHN_ENABLE_RUN_LIMIT == 1
|
|
|
|
|
|
#if CONFIG_RELAY_CHN_ENABLE_TILTING == 1
|
|
|
|
/**
|
|
* @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 // RELAY_CHN_COUNT > 1
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif |