Merge pull request 'hotfix-v0.1.0' (#8) from hotfix-v0.1.0 into v0.1

Reviewed-on: https://kozmotronik.nohost.me/gitea/KozmotronikTech/relay_chn/pulls/8

.gitignore

@@ -100,3 +100,8 @@ CTestTestfile.cmake
 _deps
 CMakeUserPresets.json
 
+# Build directory
+build
+
+# unity-app directory
+unity-app

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "files.associations": {
+        "relay_chn.h": "c"
+    }
+}

CMakeLists.txt

@@ -0,0 +1,4 @@
+idf_component_register(SRCS "src/relay_chn.c"
+                    INCLUDE_DIRS include
+                    REQUIRES driver
+                    PRIV_REQUIRES esp_timer esp_event)

Kconfig

@@ -0,0 +1,20 @@
+menu "Relay Channel Driver Configuration"
+
+    config RELAY_CHN_OPPOSITE_INERTIA_MS
+        int "Inertia time before it runs opposite direction (ms)"
+        range 200 1500
+        default 800
+        help
+            Time to wait after changing the direction of the output before
+            starting the output. This is useful for the motors or some other
+            mechanical actuators to allow them to stop and settle before
+            changing the direction.
+    
+    config RELAY_CHN_COUNT
+        int "Number of relay channels"
+        range 1 8
+        default 1
+        help
+            Number of relay channels between 1 and 8.
+    
+endmenu

README.md

@@ -1,3 +1,82 @@
-# relay_chn
+# relay_chn - Relay Channel Controller
 
-A custom ESP-IDF component for controlling a relay channel
+An ESP-IDF component for controlling relay channels, specifically designed for driving bipolar motors through relay pairs.
+
+## Features
+
+- Controls multiple relay channel pairs (up to 8 channels)
+- Built-in direction change inertia protection
+- Automatic command sequencing and timing
+- Event-driven architecture for reliable operation
+- Forward/Reverse direction control
+- Direction flipping capability
+- State monitoring and reporting
+
+## Description
+
+Each relay channel consists of 2 output relays controlled by 2 GPIO pins. The component provides APIs to control these relay pairs while ensuring safe operation, particularly for driving bipolar motors. It prevents short-circuits by automatically managing direction changes with configurable inertia timing.
+
+## Configuration
+
+Configure the component through menuconfig under "Relay Channel Driver Configuration":
+
+- `CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS`: Time to wait before changing direction (200-1500ms, default: 800ms)
+- `CONFIG_RELAY_CHN_COUNT`: Number of relay channels (1-8, default: 1)
+
+## Installation
+
+1. Copy the component to your project's components directory
+2. Add dependency to your project's `idf_component.yml`:
+
+```yaml
+dependencies:
+  relay_chn:
+    version: "^0.1.0"
+```
+
+## Usage
+
+### 1. Initialize relay channels
+
+```c
+// Define GPIO pins for relay channels
+const gpio_num_t gpio_map[] = {GPIO_NUM_4, GPIO_NUM_5};  // One channel example
+const uint8_t gpio_count = sizeof(gpio_map) / sizeof(gpio_map[0]);
+
+// Create and initialize relay channels
+esp_err_t ret = relay_chn_create(gpio_map, gpio_count);
+if (ret != ESP_OK) {
+    // Handle error
+}
+```
+
+### 2. Control relay channels
+
+```c
+// Run channel 0 forward
+relay_chn_run_forward(0);
+
+// Run channel 0 reverse
+relay_chn_run_reverse(0);
+
+// Stop channel 0
+relay_chn_stop(0);
+
+// Flip direction of channel 0
+relay_chn_flip_direction(0);
+```
+
+### 3. Monitor channel state
+
+```c
+// Get channel state
+relay_chn_state_t state = relay_chn_get_state(0);
+char *state_str = relay_chn_get_state_str(0);
+
+// Get channel direction
+relay_chn_direction_t direction = relay_chn_get_direction(0);
+```
+
+## License
+
+[MIT License](LICENSE) - Copyright (c) 2025 kozmotronik.

idf_component.yml

@@ -0,0 +1,7 @@
+name: relay_chn
+version: 0.1.0
+description: Custom component for relay channel control
+dependencies:
+  idf:
+    version: ">=4.0"
+# TODO: Repo ve belgelendirme bağlantılarını ekle.

include/relay_chn.h

@@ -0,0 +1,207 @@
+#ifndef RELAY_CHN_H
+#define RELAY_CHN_H
+/**
+ * @file relay_chn.h
+ * 
+ * @author
+ * Ismail Sahillioglu <ismailsahillioglu@gmail.com>
+ *
+ * @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.
+ * The module also automatically manages the direction change inertia to prevent short-circuiting the motor.
+ * The STOP command overrides any other command and clears the pending command if any.
+ * 
+ * The module internally uses a custom esp event loop to handle relay commands serially to ensure
+ * reliability and prevent conflict operations. Also, the esp timer is used to manage the direction change inertia.
+ */
+
+#include "esp_err.h"
+#include "driver/gpio.h"
+#include <stdint.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_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.
+};
+
+/**
+ * @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.
+ *
+ * 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 gpio_num_t* gpio_map, uint8_t gpio_count);
+
+/**
+ * @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);
+
+/**
+ * @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 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.
+ *
+ * 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. It is typically used to change the state of the relay
+ * from its current direction to the opposite direction.
+ *
+ * @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);
+
+#ifdef __cplusplus
+}
+#endif
+
+/// @}
+
+#endif // RELAY_CHN_H

src/relay_chn.c

@@ -0,0 +1,725 @@
+/**
+ * @file relay_chn.c
+ * 
+ * @author
+ * Ismail Sahillioglu <ismailsahillioglu@gmail.com>
+ *
+ * @date 2025.02.08
+ * 
+ * @ingroup relay_chn
+ * 
+ * @brief This file contains the implementation of the relay channel component.
+ * @{
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_task.h"
+#include "driver/gpio.h"
+#include "esp_timer.h"
+#include "esp_event_base.h"
+#include "esp_event.h"
+#include "relay_chn.h"
+#include "sdkconfig.h"
+
+
+#define RELAY_CHN_OPPOSITE_INERTIA_MS CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS
+#define RELAY_CHN_COUNT CONFIG_RELAY_CHN_COUNT
+
+static const char *TAG = "relay_chn";
+
+ESP_EVENT_DEFINE_BASE(RELAY_CHN_CMD_EVENT);
+
+
+/**
+ * @brief Enumeration for relay channel commands.
+ */
+enum relay_chn_cmd_enum {
+    RELAY_CHN_CMD_NONE,     ///< No command.
+    RELAY_CHN_CMD_STOP,     ///< Stop the relay channel.
+    RELAY_CHN_CMD_FORWARD,  ///< Run the relay channel in the forward direction.
+    RELAY_CHN_CMD_REVERSE,  ///< Run the relay channel in the reverse direction.
+    RELAY_CHN_CMD_FLIP,     ///< Flip the direction of the relay channel.
+    RELAY_CHN_CMD_FREE      ///< Free the relay channel.
+};
+
+/// @brief Alias for the enum type relay_chn_cmd_enum.
+typedef enum relay_chn_cmd_enum relay_chn_cmd_t;
+
+/**
+ * @brief Structure to hold runtime information for a relay channel.
+ */
+typedef struct relay_chn_run_info_type {
+    relay_chn_cmd_t last_run_cmd;   ///< The last run command issued on the relay channel; forward or reverse.
+    uint32_t last_run_cmd_time_ms;  ///< The time in milliseconds when the last run command was issued.
+} relay_chn_run_info_t;
+
+/**
+ * @brief Structure to hold the output configuration of a relay channel.
+ */
+typedef struct relay_chn_output_type {
+    gpio_num_t forward_pin; ///< GPIO pin number for the forward direction.
+    gpio_num_t reverse_pin; ///< GPIO pin number for the reverse direction.
+    relay_chn_direction_t direction; ///< The current direction of the relay channel.
+} relay_chn_output_t;
+
+typedef struct relay_chn_type relay_chn_t; // Forward declaration
+
+/**
+ * @brief Function pointer type for relay channel command execution functions.
+ * @param relay_chn Pointer to the relay channel to execute the command on.
+ */
+typedef void(*relay_chn_cmd_fn_t)(relay_chn_t*);
+
+/**
+ * @brief Structure to hold the state and configuration of a relay channel.
+ */
+typedef struct relay_chn_type {
+    uint8_t id; ///< The ID of the relay channel.
+    relay_chn_state_t state;        ///< The current state of the relay channel.
+    relay_chn_run_info_t run_info;  ///< Runtime information of the relay channel.
+    relay_chn_output_t output;      ///< Output configuration of the relay channel.
+    relay_chn_cmd_t pending_cmd;    ///< The command that is pending to be issued
+    esp_timer_handle_t inertia_timer;       ///< Timer to handle the opposite direction inertia time.
+} relay_chn_t;
+
+/**
+ * @brief Structure to manage the state change listeners. 
+ */
+struct relay_chn_state_listener_manager_type {
+    uint8_t listener_count;                 ///< The number of registered listeners.
+    relay_chn_state_listener_t *listeners;  ///< The list that holds references to the registered listeners.
+} relay_chn_state_listener_manager;
+
+
+static relay_chn_t relay_channels[RELAY_CHN_COUNT];
+static esp_event_loop_handle_t relay_chn_event_loop;
+
+
+// Private function declarations
+// Event handler for the relay channel command event
+static void relay_chn_event_handler(void* handler_arg, esp_event_base_t event_base, int32_t event_id, void* event_data);
+
+/**
+ * @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.
+ */
+static bool relay_chn_is_channel_id_valid(uint8_t chn_id);
+
+/**
+ * @brief Dispatches a relay channel command to the event loop.
+ * 
+ * @param relay_chn The relay channel.
+ * @param cmd The command to dispatch.
+ */
+static void relay_chn_dispatch_cmd(relay_chn_t *relay_chn, 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.
+ */
+static char *relay_chn_cmd_str(relay_chn_cmd_t cmd);
+
+/**
+ * @brief Timer callback function for relay channel direction change inertia.
+ * 
+ * This function is called when the opposite direction inertia timer expires. It checks if the channel
+ * has a pending command and dispatches it if there is one.
+ * 
+ * @param arg The channel ID of the relay channel.
+ */
+static void relay_chn_timer_cb(void* arg)
+{
+    uint8_t chn_id = *(uint8_t*) arg;
+    if (!relay_chn_is_channel_id_valid(chn_id)) {
+        ESP_LOGE(TAG, "relay_chn_timer_cb: Invalid relay channel ID!");
+        return;
+    }
+    relay_chn_t* relay_chn = &relay_channels[chn_id];
+    // Does channel have a pending command?
+    if (relay_chn->pending_cmd != RELAY_CHN_CMD_NONE) {
+        relay_chn_dispatch_cmd(relay_chn, relay_chn->pending_cmd);
+        relay_chn->pending_cmd = RELAY_CHN_CMD_NONE;
+    }
+    else {
+        ESP_LOGE(TAG, "relay_chn_timer_cb: No pending cmd for relay channel %d!", chn_id);
+    }
+}
+
+static esp_err_t relay_chn_init_timer(relay_chn_t *relay_chn)
+{
+    char timer_name[32];
+    snprintf(timer_name, sizeof(timer_name), "relay_chn_%d_timer", relay_chn->id);
+    esp_timer_create_args_t timer_args = {
+        .callback = relay_chn_timer_cb,
+        .arg = &relay_chn->id,
+        .name = timer_name
+    };
+    return esp_timer_create(&timer_args, &relay_chn->inertia_timer);
+}
+
+/**
+ * @brief Check if the provided GPIO pin number is valid for the current device.
+ * 
+ * @param gpio The GPIO pin number to check.
+ * @return true GPIO pin number is valid.
+ * @return false GPIO pin number is invalid.
+ */
+static bool relay_chn_is_gpio_valid(gpio_num_t gpio)
+{
+    return gpio >= 0 && gpio < GPIO_PIN_COUNT;
+}
+
+static esp_err_t relay_chn_create_event_loop()
+{
+    esp_event_loop_args_t loop_args = {
+        .queue_size = RELAY_CHN_COUNT * 8,
+        .task_name = "relay_chn_event_loop",
+        .task_priority = ESP_TASKD_EVENT_PRIO - 1,
+        .task_stack_size = 2048,
+        .task_core_id = tskNO_AFFINITY
+    };
+    esp_err_t ret = esp_event_loop_create(&loop_args, &relay_chn_event_loop);
+    ret |= esp_event_handler_register_with(relay_chn_event_loop,
+                                            RELAY_CHN_CMD_EVENT,
+                                            ESP_EVENT_ANY_ID,
+                                            relay_chn_event_handler, NULL);
+    return ret;
+}
+
+esp_err_t relay_chn_create(const gpio_num_t* gpio_map, uint8_t gpio_count)
+{
+    // Check if the device's GPIOs are enough for the number of channels
+    if (RELAY_CHN_COUNT > (GPIO_PIN_COUNT / 2)) {
+        ESP_LOGE(TAG, "Not enough GPIOs for the number of channels!");
+        ESP_LOGE(TAG, "Max available num of channels: %d, requested channels: %d", GPIO_PIN_COUNT / 2, RELAY_CHN_COUNT);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    // Check if the provided GPIOs correspond to the number of channels
+    if (gpio_count != RELAY_CHN_COUNT * 2) {
+        ESP_LOGE(TAG, "Invalid number of GPIOs provided: %d", gpio_count);
+        ESP_LOGE(TAG, "Expected number of GPIOs: %d", RELAY_CHN_COUNT * 2);
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    esp_err_t ret;
+    for (int i = 0; i < RELAY_CHN_COUNT; i++) {
+        int gpio_index = i << 1; // gpio_index = i * 2
+        gpio_num_t forward_pin = gpio_map[gpio_index];
+        gpio_num_t reverse_pin = gpio_map[gpio_index + 1];
+        // Check if the GPIOs are valid
+        if (!relay_chn_is_gpio_valid(forward_pin)) {
+            ESP_LOGE(TAG, "Invalid GPIO pin number: %d", forward_pin);
+            return ESP_ERR_INVALID_ARG;
+        }
+        if (!relay_chn_is_gpio_valid(reverse_pin)) {
+            ESP_LOGE(TAG, "Invalid GPIO pin number: %d", reverse_pin);
+            return ESP_ERR_INVALID_ARG;
+        }
+        // Check if the GPIOs are valid
+
+        // Initialize the GPIOs
+        ret = gpio_reset_pin(forward_pin);
+        ret |= gpio_set_direction(forward_pin, GPIO_MODE_OUTPUT);
+        
+        ret |= gpio_reset_pin(reverse_pin);
+        ret |= gpio_set_direction(reverse_pin, GPIO_MODE_OUTPUT);
+        if (ret != ESP_OK) {
+            ESP_LOGE(TAG, "Failed to initialize GPIOs relay channel %d!", i);
+            return ret;
+        }
+        // Initialize the GPIOs
+
+        // Initialize the relay channel
+        relay_chn_t* relay_chn = &relay_channels[i];
+        relay_chn->id = i;
+        relay_chn->output.forward_pin = forward_pin;
+        relay_chn->output.reverse_pin = reverse_pin;
+        relay_chn->output.direction = RELAY_CHN_DIRECTION_DEFAULT;
+        relay_chn->state = RELAY_CHN_STATE_FREE;
+        relay_chn->pending_cmd = RELAY_CHN_CMD_NONE;
+        relay_chn->run_info.last_run_cmd = RELAY_CHN_CMD_NONE;
+        ret |= relay_chn_init_timer(relay_chn);// Create direction change inertia timer
+        if (ret != ESP_OK) {
+            ESP_LOGE(TAG, "Failed to initialize relay channel %d!", i);
+            return ret;
+        }
+    }
+
+    // Create relay channel command event loop
+    ret |= relay_chn_create_event_loop();
+
+    // Init the state listener manager
+    relay_chn_state_listener_manager.listeners = malloc(sizeof(relay_chn_state_listener_t*));
+    if (relay_chn_state_listener_manager.listeners == NULL) {
+        ESP_LOGE(TAG, "Failed to initialize memory for the listeners!");
+        ret = ESP_ERR_NO_MEM;
+    }
+
+    return ret;
+}
+
+static int relay_chn_listener_index(relay_chn_state_listener_t listener)
+{
+    for (int i = 0; i < relay_chn_state_listener_manager.listener_count; i++) {
+        if (relay_chn_state_listener_manager.listeners[i] == listener) {
+            // This is the listener to unregister. Check if it is in the middle
+            ESP_LOGD(TAG, "relay_chn_listener_index: Listener %p; found at index %d.", listener, i);
+            return i;
+        }
+    }
+    return -1;
+}
+
+esp_err_t relay_chn_register_listener(relay_chn_state_listener_t listener)
+{
+    if (listener == NULL) {
+        ESP_LOGE(TAG, "relay_chn_register_listener: A NULL listener given.");
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    if (relay_chn_listener_index(listener) > -1) {
+        ESP_LOGD(TAG, "relay_chn_register_listener: The listener %p is already registered.", listener);
+        return ESP_OK;
+    }
+
+    ESP_LOGD(TAG, "relay_chn_register_listener: Register listener: %p", listener);
+    relay_chn_state_listener_manager.listeners[relay_chn_state_listener_manager.listener_count] = listener;
+    // Update listener count
+    relay_chn_state_listener_manager.listener_count++;
+
+    return ESP_OK;
+}
+
+void relay_chn_unregister_listener(relay_chn_state_listener_t listener)
+{
+    if (listener == NULL) {
+        ESP_LOGD(TAG, "relay_chn_unregister_listener: A NULL listener given, nothing to do.");
+        return;
+    }
+    // Search the listener in the listeners list and get its index if exists
+    int i = relay_chn_listener_index(listener);
+    if (i == -1) {
+        ESP_LOGD(TAG, "relay_chn_unregister_listener: %p is not registered already.", listener);
+        return;
+    }
+
+    uint8_t max_index = relay_chn_state_listener_manager.listener_count - 1;
+    // Check whether the listener's index is in the middle
+    if (i == max_index) {
+        // free(&relay_chn_state_listener_manager.listeners[i]);
+        relay_chn_state_listener_manager.listeners[i] = NULL;
+    }
+    else {
+        // It is in the middle, so align the next elements in the list and then free the last empty pointer
+        // Align the next elements
+        uint8_t num_of_elements = max_index - i;
+        relay_chn_state_listener_t *pnext = NULL;
+        // (i + j): current index; (i + j + 1): next index
+        for (uint8_t j = 0; j < num_of_elements; j++) {
+            uint8_t current_index = i + j;
+            uint8_t next_index = current_index + 1;
+            pnext = &relay_chn_state_listener_manager.listeners[next_index];
+            relay_chn_state_listener_manager.listeners[current_index] = *pnext;
+        }
+        // free(&relay_chn_state_listener_manager.listeners[max_index]); // Free the last element
+        relay_chn_state_listener_manager.listeners[max_index] = NULL; // Free the last element
+    }
+    // Decrease listener count
+    relay_chn_state_listener_manager.listener_count--;
+}
+
+/**
+ * @brief Check channel ID validity
+ * 
+ * @param chn_id Channel ID to check
+ * @return true If channel is valid
+ * @return false If channel is invalid
+ */
+static bool relay_chn_is_channel_id_valid(uint8_t chn_id)
+{
+    bool valid = (chn_id < RELAY_CHN_COUNT) || chn_id == RELAY_CHN_ID_ALL;
+    if (!valid) {
+        ESP_LOGE(TAG, "Invalid channel ID: %d", chn_id);
+    }
+    return valid;
+}
+
+
+// Dispatch relay channel command to its event loop
+static void relay_chn_dispatch_cmd(relay_chn_t *relay_chn, relay_chn_cmd_t cmd) {
+    if (cmd == RELAY_CHN_CMD_NONE) {
+        return;
+    }
+    esp_event_post_to(relay_chn_event_loop,
+                        RELAY_CHN_CMD_EVENT,
+                        cmd,
+                        &relay_chn->id,
+                        sizeof(relay_chn->id), portMAX_DELAY);
+}
+
+
+static esp_err_t relay_chn_start_esp_timer_once(esp_timer_handle_t esp_timer, uint32_t time_ms)
+{
+    // Invalidate the channel's timer if it is active
+    esp_err_t ret = esp_timer_start_once(esp_timer, time_ms * 1000);
+    if (ret == ESP_ERR_INVALID_STATE) {
+        // This timer is already running, stop the timer first
+        ret = esp_timer_stop(esp_timer);
+        if (ret != ESP_OK && ret != ESP_ERR_INVALID_STATE) {
+            return ret;
+        }
+        ret = esp_timer_start_once(esp_timer, time_ms * 1000);
+    }
+    return ESP_OK;
+}
+
+static void relay_chn_update_state(relay_chn_t *relay_chn, relay_chn_state_t new_state)
+{
+    relay_chn_state_t old = relay_chn->state;
+    relay_chn->state = new_state;
+    for (uint8_t i = 0; i < relay_chn_state_listener_manager.listener_count; i++) {
+        relay_chn_state_listener_t listener = relay_chn_state_listener_manager.listeners[i];
+        if (listener == NULL) {
+            relay_chn_state_listener_manager.listener_count -= 1;
+            ESP_LOGD(TAG, "relay_chn_update_state: A listener is NULL at index: %u", i);
+        }
+        // Emit the state change to the listeners
+        listener(relay_chn->id, old, new_state);
+    }
+}
+
+/**
+ * @brief The command issuer function.
+ * 
+ * This function is the deciding logic for issuing a command to a relay channel. It evaluates 
+ * the current state of the channel before issuing the command. Then it decides whether to run
+ * the command immediately or wait for the opposite inertia time.
+ * 
+ * The STOP command is an exception, it is always run immediately since it is safe in any case.
+ * 
+ * Another special consideration is the FLIP command. If the channel is running, the FLIP command
+ * is issued after the channel is stopped. If the channel is stopped, the FLIP command is issued
+ * immediately.
+ * 
+ * @param relay_chn The relay channel to issue the command to.
+ * @param cmd The command to issue.
+ */
+static void relay_chn_issue_cmd(relay_chn_t* relay_chn, relay_chn_cmd_t cmd)
+{
+    if (cmd == RELAY_CHN_CMD_NONE) {
+        return;
+    }
+    
+    if (cmd == RELAY_CHN_CMD_STOP) {
+        if (relay_chn->state == RELAY_CHN_STATE_STOPPED) {
+            return; // Do nothing if already stopped
+        }
+        // If the command is STOP, issue it immediately
+        relay_chn_dispatch_cmd(relay_chn, cmd);
+        return;
+    }
+
+    // Evaluate the channel's next move depending on its status
+    switch (relay_chn->state)
+    {
+        case RELAY_CHN_STATE_FREE:
+            // If the channel is free, run the command immediately
+            relay_chn_dispatch_cmd(relay_chn, cmd);
+            break;
+        
+        case RELAY_CHN_STATE_FORWARD_PENDING:
+        case RELAY_CHN_STATE_REVERSE_PENDING:
+            // The channel is already waiting for the opposite inertia time,
+            // so do nothing unless the command is STOP
+            if (cmd == RELAY_CHN_CMD_STOP) {
+                relay_chn_dispatch_cmd(relay_chn, cmd);
+            }
+            break;
+        
+        case RELAY_CHN_STATE_STOPPED:
+            if (relay_chn->run_info.last_run_cmd == cmd || relay_chn->run_info.last_run_cmd == RELAY_CHN_CMD_NONE) {
+                // Since the state is STOPPED, the inertia timer should be running and must be invalidated
+                // with the pending FREE command
+                esp_timer_stop(relay_chn->inertia_timer);
+                relay_chn->pending_cmd = RELAY_CHN_CMD_NONE;
+                                
+                // If this is the first run or the last run command is the same as the current command,
+                // run the command immediately
+                relay_chn_dispatch_cmd(relay_chn, cmd);
+            }
+            else {
+                // If the last run command is different from the current command, calculate the time passed 
+                // since the last run command stopped and decide whether to run the command immediately or wait
+                uint32_t inertia_time_passed_ms = (uint32_t) (esp_timer_get_time() / 1000) - relay_chn->run_info.last_run_cmd_time_ms;
+                uint32_t inertia_time_ms = RELAY_CHN_OPPOSITE_INERTIA_MS - inertia_time_passed_ms;
+                if (inertia_time_ms > 0) {
+                    relay_chn->pending_cmd = cmd;
+                    relay_chn_state_t new_state = cmd == RELAY_CHN_CMD_FORWARD 
+                            ? RELAY_CHN_STATE_FORWARD_PENDING : RELAY_CHN_STATE_REVERSE_PENDING;
+                    relay_chn_update_state(relay_chn, new_state);
+                    // If the time passed is less than the opposite inertia time, wait for the remaining time
+                    relay_chn_start_esp_timer_once(relay_chn->inertia_timer, inertia_time_ms);
+                }
+                else {
+                    // If the time passed is more than the opposite inertia time, run the command immediately
+                    relay_chn_dispatch_cmd(relay_chn, cmd);
+                }
+            }
+            break;
+        
+        case RELAY_CHN_STATE_FORWARD:
+        case RELAY_CHN_STATE_REVERSE:
+            if (cmd == RELAY_CHN_CMD_FLIP) {
+                // If the command is FLIP, stop the running channel first, then issue the FLIP command
+                relay_chn_dispatch_cmd(relay_chn, RELAY_CHN_CMD_STOP);
+                relay_chn_dispatch_cmd(relay_chn, cmd);
+                return;
+            }
+            
+            if (relay_chn->run_info.last_run_cmd == cmd) {
+                // If the last run command is the same as the current command, do nothing
+                return;
+            }
+            
+            // Stop the channel first before the schedule
+            relay_chn_dispatch_cmd(relay_chn, RELAY_CHN_CMD_STOP);
+
+            // If the last run command is different from the current command, wait for the opposite inertia time
+            relay_chn->pending_cmd = cmd;
+            relay_chn_state_t new_state = cmd == RELAY_CHN_CMD_FORWARD 
+                    ? RELAY_CHN_STATE_FORWARD_PENDING : RELAY_CHN_STATE_REVERSE_PENDING;
+            relay_chn_update_state(relay_chn, new_state);
+            relay_chn_start_esp_timer_once(relay_chn->inertia_timer, RELAY_CHN_OPPOSITE_INERTIA_MS);
+            break;
+
+        default: ESP_LOGD(TAG, "relay_chn_evaluate: Unknown relay channel state!");
+    }
+}
+
+/* relay_chn APIs */
+relay_chn_state_t relay_chn_get_state(uint8_t chn_id)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) {
+        return RELAY_CHN_STATE_STOPPED;
+    }
+    return relay_channels[chn_id].state;
+}
+
+char *relay_chn_get_state_str(uint8_t chn_id)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) {
+        return "INVALID";
+    }
+    return relay_chn_state_str(relay_channels[chn_id].state);
+}
+
+static void relay_chn_issue_cmd_on_all_channels(relay_chn_cmd_t cmd)
+{
+    for (int i = 0; i < RELAY_CHN_COUNT; i++) {
+        relay_chn_issue_cmd(&relay_channels[i], cmd);
+    }
+}
+
+void relay_chn_run_forward(uint8_t chn_id)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) return;
+
+    if (chn_id == RELAY_CHN_ID_ALL) {
+        relay_chn_issue_cmd_on_all_channels(RELAY_CHN_CMD_FORWARD);
+        return;
+    }
+
+    relay_chn_t* relay_chn = &relay_channels[chn_id];
+    relay_chn_issue_cmd(relay_chn, RELAY_CHN_CMD_FORWARD);
+}
+
+void relay_chn_run_reverse(uint8_t chn_id)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) return;
+
+    if (chn_id == RELAY_CHN_ID_ALL) {
+        relay_chn_issue_cmd_on_all_channels(RELAY_CHN_CMD_REVERSE);
+        return;
+    }
+
+    relay_chn_t* relay_chn = &relay_channels[chn_id];
+    relay_chn_issue_cmd(relay_chn, RELAY_CHN_CMD_REVERSE);
+}
+
+void relay_chn_stop(uint8_t chn_id)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) return;
+
+    if (chn_id == RELAY_CHN_ID_ALL) {
+        relay_chn_issue_cmd_on_all_channels(RELAY_CHN_CMD_STOP);
+        return;
+    }
+
+    relay_chn_t* relay_chn = &relay_channels[chn_id];
+    relay_chn_issue_cmd(relay_chn, RELAY_CHN_CMD_STOP);
+}
+
+void relay_chn_flip_direction(uint8_t chn_id)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) return;
+
+    if (chn_id == RELAY_CHN_ID_ALL) {
+        relay_chn_issue_cmd_on_all_channels(RELAY_CHN_CMD_FLIP);
+        return;
+    }
+
+    relay_chn_t* relay_chn = &relay_channels[chn_id];
+    relay_chn_issue_cmd(relay_chn, RELAY_CHN_CMD_FLIP);    
+}
+
+relay_chn_direction_t relay_chn_get_direction(uint8_t chn_id)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) {
+        return RELAY_CHN_DIRECTION_DEFAULT;
+    }
+    return relay_channels[chn_id].output.direction;
+}
+/* relay_chn APIs */
+
+
+static void relay_chn_execute_stop(relay_chn_t *relay_chn)
+{
+    gpio_set_level(relay_chn->output.forward_pin, 0);
+    gpio_set_level(relay_chn->output.reverse_pin, 0);
+    relay_chn_update_state(relay_chn, RELAY_CHN_STATE_STOPPED);
+    
+    // If there is any pending command, cancel it since the STOP command is issued right after it
+    relay_chn->pending_cmd = RELAY_CHN_CMD_NONE;
+    // Invalidate the channel's timer if it is active
+    esp_timer_stop(relay_chn->inertia_timer);
+
+    // If the channel was running, schedule a free command for the channel
+    relay_chn_cmd_t last_run_cmd = relay_chn->run_info.last_run_cmd;
+    if (last_run_cmd == RELAY_CHN_CMD_FORWARD || last_run_cmd == RELAY_CHN_CMD_REVERSE) {
+        // Record the command's last run time
+        relay_chn->run_info.last_run_cmd_time_ms = esp_timer_get_time() / 1000;
+        // Schedule a free command for the channel
+        relay_chn->pending_cmd = RELAY_CHN_CMD_FREE;
+        relay_chn_start_esp_timer_once(relay_chn->inertia_timer, RELAY_CHN_OPPOSITE_INERTIA_MS);
+    } else {
+        // If the channel was not running, issue a free command immediately
+        relay_chn_dispatch_cmd(relay_chn, RELAY_CHN_CMD_FREE);
+    }
+}
+
+static void relay_chn_execute_forward(relay_chn_t *relay_chn)
+{
+    gpio_set_level(relay_chn->output.reverse_pin, 0);
+    gpio_set_level(relay_chn->output.forward_pin, 1);
+    relay_chn->run_info.last_run_cmd = RELAY_CHN_CMD_FORWARD;
+    relay_chn_update_state(relay_chn, RELAY_CHN_STATE_FORWARD);
+}
+
+static void relay_chn_execute_reverse(relay_chn_t *relay_chn)
+{
+    gpio_set_level(relay_chn->output.forward_pin, 0);
+    gpio_set_level(relay_chn->output.reverse_pin, 1);
+    relay_chn->run_info.last_run_cmd = RELAY_CHN_CMD_REVERSE;
+    relay_chn_update_state(relay_chn, RELAY_CHN_STATE_REVERSE);
+}
+
+static void relay_chn_execute_flip(relay_chn_t *relay_chn)
+{
+    // Flip the output GPIO pins
+    gpio_num_t temp = relay_chn->output.forward_pin;
+    relay_chn->output.forward_pin = relay_chn->output.reverse_pin;
+    relay_chn->output.reverse_pin = temp;
+    // Flip the direction
+    relay_chn->output.direction = (relay_chn->output.direction == RELAY_CHN_DIRECTION_DEFAULT) 
+                                    ? RELAY_CHN_DIRECTION_FLIPPED 
+                                    : RELAY_CHN_DIRECTION_DEFAULT;
+    // Set an inertia on the channel to prevent any immediate movement
+    relay_chn->pending_cmd = RELAY_CHN_CMD_FREE;
+    relay_chn_start_esp_timer_once(relay_chn->inertia_timer, RELAY_CHN_OPPOSITE_INERTIA_MS);
+}
+
+void relay_chn_execute_free(relay_chn_t *relay_chn)
+{
+    relay_chn->pending_cmd = RELAY_CHN_CMD_NONE;
+    // Invalidate the channel's timer if it is active
+    esp_timer_stop(relay_chn->inertia_timer);
+    relay_chn_update_state(relay_chn, RELAY_CHN_STATE_FREE);
+}
+
+static void relay_chn_event_handler(void* handler_arg, esp_event_base_t event_base, int32_t event_id, void* event_data)
+{
+    uint8_t chn_id = *(uint8_t*) event_data;
+    if (!relay_chn_is_channel_id_valid(chn_id)) {
+        return;
+    }
+    relay_chn_t* relay_chn = &relay_channels[chn_id];
+    ESP_LOGD(TAG, "relay_chn_event_handler: Channel %d, Command: %s", relay_chn->id, relay_chn_cmd_str(event_id));
+    switch (event_id) {
+        case RELAY_CHN_CMD_STOP:
+            relay_chn_execute_stop(relay_chn);
+            break;
+        case RELAY_CHN_CMD_FORWARD:
+            relay_chn_execute_forward(relay_chn);
+            break;
+        case RELAY_CHN_CMD_REVERSE:
+            relay_chn_execute_reverse(relay_chn);
+            break;
+        case RELAY_CHN_CMD_FLIP:
+            relay_chn_execute_flip(relay_chn);
+            break;
+        case RELAY_CHN_CMD_FREE:
+            relay_chn_execute_free(relay_chn);
+            break;
+        default:
+            ESP_LOGD(TAG, "Unknown relay channel command!");
+    }
+}
+
+static char *relay_chn_cmd_str(relay_chn_cmd_t cmd)
+{
+    switch (cmd) {
+        case RELAY_CHN_CMD_STOP:
+            return "STOP";
+        case RELAY_CHN_CMD_FORWARD:
+            return "FORWARD";
+        case RELAY_CHN_CMD_REVERSE:
+            return "REVERSE";
+        case RELAY_CHN_CMD_FLIP:
+            return "FLIP";
+        case RELAY_CHN_CMD_FREE:
+            return "FREE";
+        default:
+            return "UNKNOWN";
+    }
+}
+
+char *relay_chn_state_str(relay_chn_state_t state)
+{
+    switch (state) {
+        case RELAY_CHN_STATE_FREE:
+            return "FREE";
+        case RELAY_CHN_STATE_STOPPED:
+            return "STOPPED";
+        case RELAY_CHN_STATE_FORWARD:
+            return "FORWARD";
+        case RELAY_CHN_STATE_REVERSE:
+            return "REVERSE";
+        case RELAY_CHN_STATE_FORWARD_PENDING:
+            return "FORWARD_PENDING";
+        case RELAY_CHN_STATE_REVERSE_PENDING:
+            return "REVERSE_PENDING";
+        default:
+            return "UNKNOWN";
+    }
+}
+
+/// @}

test/CMakeLists.txt

@@ -0,0 +1,8 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(EXTRA_COMPONENT_DIRS "$ENV{IDF_PATH}/tools/unit-test-app/components"
+                         "../../relay_chn")
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(relay_chn_test)

test/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(SRCS_DIRS "."
+                    PRIV_INCLUDE_DIRS "."
+                    PRIV_REQUIRES unity test_utils relay_chn)

test/main/test_relay_chn.c

@@ -0,0 +1,95 @@
+#include "driver/gpio.h"
+#include "unity.h"
+#include "unity_test_utils.h"
+#include "relay_chn.h"
+
+
+const gpio_num_t gpio_map[] = {GPIO_NUM_4, GPIO_NUM_5, GPIO_NUM_18, GPIO_NUM_19};
+const uint8_t gpio_count = sizeof(gpio_map) / sizeof(gpio_map[0]);
+const uint8_t relay_chn_count = gpio_count / 2;
+
+TEST_CASE("relay chn inits correctly", "[relay_chn]")
+{
+    TEST_ESP_OK(relay_chn_create(gpio_map, gpio_count));
+}
+
+TEST_CASE("Relay channels run forward and update state", "[relay_chn][forward]")
+{
+    TEST_ESP_OK(relay_chn_create(gpio_map, gpio_count));
+    // Test forward run on all channels
+    for (uint8_t i = 0; i < relay_chn_count; i++) {
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
+        relay_chn_run_forward(i); // Run the channel forward
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, relay_chn_get_state(i));
+        relay_chn_stop(i); // Stop the channel
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
+        
+        relay_chn_flip_direction(i); // Flip the direction
+        TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_FLIPPED, relay_chn_get_direction(i));
+        relay_chn_run_forward(i); // Run the channel forward
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, relay_chn_get_state(i));
+        relay_chn_stop(i); // Stop the channel
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
+    }
+}
+
+TEST_CASE("Relay channels run reverse and update state", "[relay_chn][reverse]")
+{
+    TEST_ESP_OK(relay_chn_create(gpio_map, gpio_count));
+    // Test reverse run on all channels
+    for (uint8_t i = 0; i < relay_chn_count; i++) {
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
+        relay_chn_run_reverse(i); // Run the channel reverse
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state(i));
+        relay_chn_stop(i); // Stop the channel
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
+        
+        relay_chn_flip_direction(i); // Flip the direction
+        TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_FLIPPED, relay_chn_get_direction(i));
+        relay_chn_run_reverse(i); // Run the channel forward
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state(i));
+        relay_chn_stop(i); // Stop the channel
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
+    }
+}
+
+static void check_channels_state_unchanged(void)
+{
+    for (uint8_t i = 0; i < relay_chn_count; i++) {
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
+        TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, relay_chn_get_direction(i));
+    }
+}
+
+TEST_CASE("Relay channels do not change state for invalid channel", "[relay_chn][invalid]")
+{
+    TEST_ESP_OK(relay_chn_create(gpio_map, gpio_count));
+    // Test invalid channel run
+    relay_chn_run_forward(relay_chn_count + 1); // Run the channel forward
+    check_channels_state_unchanged();
+    relay_chn_run_reverse(relay_chn_count + 1); // Run the channel reverse
+    check_channels_state_unchanged();
+    relay_chn_stop(relay_chn_count + 1); // Stop the channel
+    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(relay_chn_count + 1));
+    check_channels_state_unchanged();
+    relay_chn_flip_direction(relay_chn_count + 1); // Flip the direction
+    check_channels_state_unchanged();
+}
+
+
+void setUp(void)
+{
+    // Run before each test
+}
+
+void tearDown(void)
+{
+    // Run after each test
+}
+
+// Test app entry point
+void app_main(void) 
+{
+    // Run the Unity tests menu
+    unity_run_menu();
+}

test/sdkconfig.defaults

@@ -0,0 +1,5 @@
+# For IDF 5.0
+CONFIG_ESP_TASK_WDT_EN=n
+
+# For IDF4.4
+CONFIG_ESP_TASK_WDT=n