Add single channel mode feature.

The addition of a single-channel mode implied further modularisation of the component. This commit has broken the component down into the following modules to avoid a huge single source file and to make unit testing easier.

The modules:

- Separation of public and private code
- *types and *defs
- public relay_chn API
- *adapter
- *output
- *run_info
- *core
- *ctl (control)
- *tilt

Closes #957.

private_include/relay_chn_core.h

@@ -0,0 +1,114 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_event_base.h"
+#include "esp_event.h"
+#include "esp_timer.h"
+#include "relay_chn_defs.h"
+#include "relay_chn_types.h"
+#include "relay_chn_priv_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Event base used by *_core, *_ctl, and *_tilt modules.
+ESP_EVENT_DECLARE_BASE(RELAY_CHN_CMD_EVENT);
+
+/**
+ * @brief Initializes the relay channel timer.
+ * 
+ * This function creates a timer for the relay channel to handle direction change inertia.
+ * Required by *_ctl_* module.
+ * 
+ * @param chn_ctl Pointer to the relay channel control structure.
+ * @return esp_err_t ESP_OK on success, or an error code on failure.
+ */
+esp_err_t relay_chn_init_timer(relay_chn_ctl_t *chn_ctl);
+
+/**
+ * @brief Issues a command to the relay channel.
+ * 
+ * Evaluates the current state of the relay channel and issues the command accordingly.
+ * Required by *_core, *_ctl_* and *_tilt modules.
+ * 
+ * @param chn_ctl Pointer to the relay channel control structure.
+ * @param cmd The command to issue.
+ */
+void relay_chn_issue_cmd(relay_chn_ctl_t* chn_ctl, relay_chn_cmd_t cmd);
+
+/**
+ * @brief Dispatches a relay channel command to the event loop.
+ * 
+ * @param chn_ctl Pointer to the relay channel control structure.
+ * @param cmd The command to dispatch.
+ */
+void relay_chn_dispatch_cmd(relay_chn_ctl_t *chn_ctl, 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.
+ */
+char *relay_chn_cmd_str(relay_chn_cmd_t cmd);
+
+/**
+ * @brief Starts the ESP timer once with the specified time in milliseconds.
+ * 
+ * Starts the ESP timer to run once after the specified time.
+ * If the timer is already running, it stops it first and then starts it again.
+ * Required by *_ctl_* and *_tilt modules.
+ * 
+ * @param esp_timer The ESP timer handle.
+ * @param time_ms The time in milliseconds to wait before the timer expires.
+ * @return esp_err_t ESP_OK on success, or an error code on failure.
+ */
+esp_err_t relay_chn_start_esp_timer_once(esp_timer_handle_t esp_timer, uint32_t time_ms);
+
+/**
+ * @brief Updates the state of the relay channel and notifies listeners.
+ * 
+ * This function updates the state of the relay channel and notifies all registered listeners
+ * about the state change.
+ * Required by *_ctl_* and *_tilt modules.
+ * 
+ * @param chn_ctl Pointer to the relay channel control structure.
+ * @param new_state The new state to set for the relay channel.
+ */
+void relay_chn_update_state(relay_chn_ctl_t *chn_ctl, relay_chn_state_t new_state);
+
+/**
+ * @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);
+
+#if RELAY_CHN_COUNT > 1
+/**
+ * @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.
+ */
+bool relay_chn_is_channel_id_valid(uint8_t chn_id);
+#endif // RELAY_CHN_COUNT > 1
+
+#if RELAY_CHN_ENABLE_TILTING == 1
+/// Relay channel event loop handle declaration for *_tilt module.
+extern esp_event_loop_handle_t relay_chn_event_loop;
+#endif // RELAY_CHN_ENABLE_TILTING
+
+#ifdef __cplusplus
+}
+#endif

private_include/relay_chn_ctl.h

@@ -0,0 +1,56 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech developer@kozmotronik.com.tr
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Expose the *_ctl functions required by *_core.c file.
+ */
+
+#pragma once
+
+#include "relay_chn_priv_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Initialize the relay channel control.
+ * 
+ * @param output Pointer to the output object(s).
+ * @param run_info Pointer to the runtime information object(s).
+ * 
+ * @return esp_err_t Returns ESP_OK on success, or an error code on failure.
+ */
+esp_err_t relay_chn_ctl_init(relay_chn_output_t *output, relay_chn_run_info_t *run_info);
+
+/**
+ * @brief Deinitialize the relay channel control.
+ * 
+ * This function cleans up resources used by the relay channel control.
+ */
+void relay_chn_ctl_deinit(void);
+
+#if RELAY_CHN_COUNT > 1
+/**
+ * @brief Get the control structure for a specific relay channel.
+ * 
+ * @param chn_id The ID of the relay channel to retrieve.
+ * 
+ * @return relay_chn_ctl_t* Pointer to the control structure for the specified channel, or NULL if not found.
+ */
+relay_chn_ctl_t *relay_chn_ctl_get(uint8_t chn_id);
+
+/**
+ * @brief Get the control structures for all relay channels.
+ * 
+ * @return relay_chn_ctl_t* Pointer to the array of control structures for all channels.
+ */
+relay_chn_ctl_t *relay_chn_ctl_get_all(void);
+#else
+relay_chn_ctl_t *relay_chn_ctl_get(void);
+#endif // RELAY_CHN_COUNT > 1
+
+#ifdef __cplusplus
+}
+#endif

private_include/relay_chn_output.h

@@ -0,0 +1,113 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Abstraction layer for controlling relay channel outputs. This is the layer
+ * that interacts with the GPIO pins to control the relay channels.
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "esp_err.h"
+#include "relay_chn_priv_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Initialize relay channel outputs.
+ *
+ * Maps relay channels to GPIO pins and prepares them for operation.
+ *
+ * @param[in] gpio_map Array of GPIO pin numbers for each relay channel.
+ * @param[in] gpio_count Number of GPIO pins (relay channels).
+ * 
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t relay_chn_output_init(const uint8_t* gpio_map, uint8_t gpio_count);
+
+/**
+ * @brief Deinitialize relay channel outputs.
+ *
+ * Releases resources and resets GPIO pins used for relay channels.
+ */
+void relay_chn_output_deinit(void);
+
+#if RELAY_CHN_COUNT > 1
+/**
+ * @brief Get the relay channel output object for a specific channel.
+ *
+ * @param[in] chn_id Channel ID.
+ * 
+ * @return Pointer to relay channel output object, or NULL if invalid.
+ */
+relay_chn_output_t *relay_chn_output_get(uint8_t chn_id);
+
+/**
+ * @brief Get all relay channel output objects.
+ *
+ * @return Pointer to array of relay channel output objects.
+ */
+relay_chn_output_t *relay_chn_output_get_all(void);
+#else
+/**
+ * @brief Get the relay channel output object.
+ *
+ * @return Pointer to relay channel output object.
+ */
+relay_chn_output_t *relay_chn_output_get(void);
+#endif // RELAY_CHN_COUNT > 1
+
+/**
+ * @brief Stop the relay channel output.
+ *
+ * Sets the relay channel to the stop state.
+ *
+ * @param[in] output Pointer to relay channel output object.
+ * 
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t relay_chn_output_stop(relay_chn_output_t *output);
+
+/**
+ * @brief Set relay channel output to forward direction.
+ *
+ * @param[in] output Pointer to relay channel output object.
+ * 
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t relay_chn_output_forward(relay_chn_output_t *output);
+
+/**
+ * @brief Set relay channel output to reverse direction.
+ *
+ * @param[in] output Pointer to relay channel output object.
+ * 
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t relay_chn_output_reverse(relay_chn_output_t *output);
+
+/**
+ * @brief Flip the direction of the relay channel output.
+ *
+ * Changes the direction from forward to reverse or vice versa.
+ *
+ * @param[in] output Pointer to relay channel output object.
+ */
+void relay_chn_output_flip(relay_chn_output_t *output);
+
+/**
+ * @brief Get the current direction of the relay channel output.
+ *
+ * @param[in] output Pointer to relay channel output object.
+ * 
+ * @return Current direction of the relay channel.
+ */
+relay_chn_direction_t relay_chn_output_get_direction(relay_chn_output_t *output);
+
+#ifdef __cplusplus
+}
+#endif

private_include/relay_chn_priv_types.h

@@ -0,0 +1,78 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "driver/gpio.h"
+#include "esp_timer.h"
+#include "relay_chn_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Enumeration for relay channel commands.
+ */
+typedef 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_IDLE      /*!< Free the relay channel */
+} relay_chn_cmd_t;
+
+
+/**
+ * @brief Structure to hold the output configuration of a relay channel.
+ */
+typedef struct {
+    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;
+
+/**
+ * @brief Structure to hold runtime information for a relay channel.
+ */
+typedef struct {
+    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;
+
+#if RELAY_CHN_ENABLE_TILTING == 1
+/// @brief Tilt commands.
+typedef enum {
+    RELAY_CHN_TILT_CMD_NONE,    /*!< No command */
+    RELAY_CHN_TILT_CMD_STOP,    /*!< Tilt command stop */
+    RELAY_CHN_TILT_CMD_FORWARD, /*!< Tilt command for forward */
+    RELAY_CHN_TILT_CMD_REVERSE  /*!< Tilt command for reverse */
+} relay_chn_tilt_cmd_t;
+
+/// Forward declaration for relay_chn_tilt_ctl
+typedef struct relay_chn_tilt_ctl relay_chn_tilt_ctl_t;
+#endif
+
+/**
+ * @brief Structure to hold the state and configuration of a relay channel.
+ */
+typedef struct {
+    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 */
+#if RELAY_CHN_ENABLE_TILTING == 1
+    relay_chn_tilt_ctl_t *tilt_ctl;     /*!< Pointer to the tilt control structure if tilting is enabled */
+#endif
+} relay_chn_ctl_t;
+
+#ifdef __cplusplus
+}
+#endif

private_include/relay_chn_run_info.h

@@ -0,0 +1,84 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * This is for managing the run information of relay channels.
+ */
+
+#pragma once
+
+#include "relay_chn_priv_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Initialize relay channel run information.
+ *
+ * Initializes the run information for all relay channels with default values.
+ */
+void relay_chn_run_info_init(void);
+
+#if RELAY_CHN_COUNT > 1
+/**
+ * @brief Get run information object for a specific relay channel.
+ *
+ * @param[in] chn_id Channel ID to get run information for.
+ * @return Pointer to run information structure, or NULL if channel ID is invalid.
+ */
+relay_chn_run_info_t *relay_chn_run_info_get(uint8_t chn_id);
+
+/**
+ * @brief Get run information objects for all relay channels.
+ *
+ * @return Pointer to array of run information structures.
+ */
+relay_chn_run_info_t *relay_chn_run_info_get_all(void);
+#else
+/**
+ * @brief Get run information object for the single relay channel.
+ *
+ * @return Pointer to run information structure.
+ */
+relay_chn_run_info_t *relay_chn_run_info_get(void);
+#endif // RELAY_CHN_COUNT > 1
+
+/**
+ * @brief Get the last run command for a relay channel.
+ *
+ * @param[in] run_info Pointer to run information structure.
+ * 
+ * @return Last command that was executed, or RELAY_CHN_CMD_NONE if invalid.
+ */
+relay_chn_cmd_t relay_chn_run_info_get_last_run_cmd(relay_chn_run_info_t *run_info);
+
+/**
+ * @brief Set the last run command for a relay channel.
+ *
+ * @param[in] run_info Pointer to run information structure.
+ * @param[in] cmd Command to set as last run command.
+ */
+void relay_chn_run_info_set_last_run_cmd(relay_chn_run_info_t *run_info, relay_chn_cmd_t cmd);
+
+/**
+ * @brief Get the timestamp of the last run command.
+ *
+ * @param[in] run_info Pointer to run information structure.
+ * 
+ * @return Timestamp in milliseconds of last command, or 0 if invalid.
+ */
+uint32_t relay_chn_run_info_get_last_run_cmd_time_ms(relay_chn_run_info_t *run_info);
+
+/**
+ * @brief Set the timestamp for the last run command.
+ *
+ * @param[in] run_info Pointer to run information structure.
+ * @param[in] time_ms Timestamp in milliseconds to set.
+ */
+void relay_chn_run_info_set_last_run_cmd_time_ms(relay_chn_run_info_t *run_info, uint32_t time_ms);
+
+#ifdef __cplusplus
+}
+#endif

private_include/relay_chn_tilt.h

@@ -0,0 +1,58 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include "relay_chn_priv_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Initialize relay channel tilt controls.
+ *
+ * Sets up tilt functionality for relay channels including timers and event handlers.
+ * Must be called before using any other tilt functions.
+ *
+ * @param[in] chn_ctls Array of relay channel control structures.
+ * 
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t relay_chn_tilt_init(relay_chn_ctl_t *chn_ctls);
+
+/**
+ * @brief Deinitialize relay channel tilt controls.
+ *
+ * Cleans up tilt resources including timers and event handlers.
+ * Should be called when tilt functionality is no longer needed.
+ */
+void relay_chn_tilt_deinit(void);
+
+/**
+ * @brief Dispatch a tilt command to a relay channel.
+ * 
+ * Queues a tilt command for execution on the specified channel.
+ *
+ * @param[in] tilt_ctl Pointer to tilt control structure.
+ * @param[in] cmd Tilt command to execute.
+ * 
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t relay_chn_tilt_dispatch_cmd(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_tilt_cmd_t cmd);
+
+/**
+ * @brief Reset tilt counters for a relay channel.
+ *
+ * Resets both forward and reverse tilt counters to zero.
+ *
+ * @param[in] tilt_ctl Pointer to tilt control structure.
+ */
+void relay_chn_tilt_reset_count(relay_chn_tilt_ctl_t *tilt_ctl);
+
+#ifdef __cplusplus
+}
+#endif