KozmotronikTech/relay_chn
3
0
Fork 0
Code Issues Pull Requests Actions Packages Releases 10 Wiki Activity

Refactor and update the relay_chn component.

Browse Source 
Refactor relay channel component to support single and multi-channel modes; update CMake configuration and enhance API documentation.
This commit is contained in:
Ismail Sahillioglu
2025-08-13 17:55:07 +03:00
parent 61f8ed440e
commit 9f1134763e
3 changed files with 278 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
include/relay_chn.h
View File

@@ -1,16 +1,8 @@
#ifndef RELAY_CHN_H
#define RELAY_CHN_H
/**
* @file relay_chn.h
*
* @author
* Ismail Sahillioglu <ismailsahillioglu@gmail.com>
/*
* SPDX-FileCopyrightText: 2025 Kozmotronik Tech
*
* SPDX-License-Identifier: MIT
*
* @date 2025.02.08
*
* @defgroup relay_chn Relay Channel Controller
* @ingroup components
* @{
* 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.
@@ -22,66 +14,17 @@
* reliability and prevent conflict operations. Also, the esp timer is used to manage the direction change inertia.
*/
#pragma once
#include "esp_err.h"
#include "driver/gpio.h"
#include <stdint.h>
#include "relay_chn_defs.h"
#include "relay_chn_types.h"
#include "relay_chn_adapter.h"
#ifdef __cplusplus
extern "C" {
#endif
#define RELAY_CHN_ID_ALL CONFIG_RELAY_CHN_COUNT ///< Special ID to address all channels
/**
* @brief Enumeration for relay channel direction.
*/
enum relay_chn_direction_enum {
RELAY_CHN_DIRECTION_DEFAULT, ///< Default direction of the relay channel.
RELAY_CHN_DIRECTION_FLIPPED ///< Flipped direction of the relay channel.
};
/**
* @brief Alias for the enum type relay_chn_direction_enum.
*/
typedef enum relay_chn_direction_enum relay_chn_direction_t;
/**
* @brief Enums that represent the state of a relay channel.
*/
enum relay_chn_state_enum {
RELAY_CHN_STATE_UNDEFINED, ///< The relay channel state is undefined.
RELAY_CHN_STATE_FREE, ///< The relay channel is free to run or execute commands.
RELAY_CHN_STATE_STOPPED, ///< The relay channel is stopped and not running.
RELAY_CHN_STATE_FORWARD, ///< The relay channel is running in the forward direction.
RELAY_CHN_STATE_REVERSE, ///< The relay channel is running in the reverse direction.
RELAY_CHN_STATE_FORWARD_PENDING, ///< The relay channel is pending to run in the forward direction.
RELAY_CHN_STATE_REVERSE_PENDING, ///< The relay channel is pending to run in the reverse direction.
#if CONFIG_RELAY_CHN_ENABLE_TILTING == 1
RELAY_CHN_STATE_TILT_FORWARD, ///< The relay channel is tilting for forward.
RELAY_CHN_STATE_TILT_REVERSE, ///< The relay channel is tilting for reverse.
#endif
};
/**
* @brief Alias for the enum type relay_chn_state_enum.
*/
typedef enum relay_chn_state_enum relay_chn_state_t;
/**
* @brief Relay channel state change listener.
*
* An optional interface to listen to the channel state change events.
* The listeners SHOULD be implemented as light functions and SHOULD NOT contain
* any blocking calls. Otherwise the relay_chn module would not function properly
* since it is designed as event driven.
*
* @param chn_id The ID of the channel whose state has changed.
* @param old_state The old state of the channel.
* @param new_state The new state of the channel.
*/
typedef void (*relay_chn_state_listener_t)(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state);
/**
* @brief Create and initialize relay channels.
*
@@ -95,7 +38,7 @@ typedef void (*relay_chn_state_listener_t)(uint8_t chn_id, relay_chn_state_t old
* - ESP_ERR_INVALID_ARG: Invalid argument
* - ESP_FAIL: General failure
*/
esp_err_t relay_chn_create(const gpio_num_t* gpio_map, uint8_t gpio_count);
esp_err_t relay_chn_create(const uint8_t* gpio_map, uint8_t gpio_count);
/**
* @brief Destroy the relay channels and free resources.
@@ -124,6 +67,7 @@ esp_err_t relay_chn_register_listener(relay_chn_state_listener_t listener);
*/
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.
*
@@ -150,14 +94,6 @@ relay_chn_state_t relay_chn_get_state(uint8_t chn_id);
*/
char *relay_chn_get_state_str(uint8_t chn_id);
/**
* @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);
/**
* @brief Runs the relay channel in the forward direction.
*
@@ -191,8 +127,7 @@ 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. It is typically used to change the state of the relay
* from its current direction to the opposite direction.
* 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.
@@ -217,9 +152,9 @@ relay_chn_direction_t relay_chn_get_direction(uint8_t chn_id);
/**
* @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 some internal sensing mechanism (not detailed here).
* Requires appropriate hardware support and configuration.
* 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.
*/
@@ -228,8 +163,7 @@ 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. This is a manual tilting
* operation, unlike `relay_chn_tilt_auto()`.
* This function initiates a forward tilting action for the specified relay channel.
*
* @param chn_id The ID of the relay channel to tilt forward.
*/
@@ -238,8 +172,7 @@ 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. This is a manual tilting
* operation, unlike `relay_chn_tilt_auto()`.
* This function initiates a reverse tilting action for the specified relay channel.
*
* @param chn_id The ID of the relay channel to tilt reverse.
*/
@@ -263,7 +196,7 @@ void relay_chn_tilt_stop(uint8_t chn_id);
* @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_sensitivity_set(uint8_t chn_id, uint8_t sensitivity);
void relay_chn_tilt_set_sensitivity(uint8_t chn_id, uint8_t sensitivity);
/**
* @brief Gets the tilting sensitivity for the specified relay channel.
@@ -278,14 +211,127 @@ void relay_chn_tilt_sensitivity_set(uint8_t chn_id, uint8_t sensitivity);
* - ESP_OK: Success
* - ESP_ERR_INVALID_ARG: Invalid argument
*/
esp_err_t relay_chn_tilt_sensitivity_get(uint8_t chn_id, uint8_t *sensitivity, size_t length);
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 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
/// @}
#endif // RELAY_CHN_H
#endif