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.

include/relay_chn_adapter.h

@@ -0,0 +1,186 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ * 
+ * An adapter header to expose the appropriate API functions to the public API
+ * depending on the RELAY_CHN_COUNT value which determines single or multi mode.
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if RELAY_CHN_COUNT > 1
+/**
+ * @brief Get the current state of a relay channel.
+ *
+ * @param[in] chn_id Channel ID to get state for.
+ * @return Current state of the specified channel, or RELAY_CHN_STATE_UNDEFINED if invalid.
+ */
+extern relay_chn_state_t relay_chn_ctl_get_state(uint8_t chn_id);
+
+/**
+ * @brief Get string representation of a relay channel's state.
+ *
+ * @param[in] chn_id Channel ID to get state string for.
+ * @return String representation of channel state, or "UNDEFINED" if invalid.
+ */
+extern char *relay_chn_ctl_get_state_str(uint8_t chn_id);
+
+/**
+ * @brief Run a relay channel in forward direction.
+ *
+ * @param[in] chn_id Channel ID to run forward, or RELAY_CHN_ID_ALL for all channels.
+ */
+extern void relay_chn_ctl_run_forward(uint8_t chn_id);
+
+/**
+ * @brief Run a relay channel in reverse direction.
+ *
+ * @param[in] chn_id Channel ID to run reverse, or RELAY_CHN_ID_ALL for all channels.
+ */
+extern void relay_chn_ctl_run_reverse(uint8_t chn_id);
+
+/**
+ * @brief Stop a relay channel.
+ *
+ * @param[in] chn_id Channel ID to stop, or RELAY_CHN_ID_ALL for all channels.
+ */
+extern void relay_chn_ctl_stop(uint8_t chn_id);
+
+/**
+ * @brief Flip the running direction of a relay channel.
+ *
+ * @param[in] chn_id Channel ID to flip direction for, or RELAY_CHN_ID_ALL for all channels.
+ */
+extern void relay_chn_ctl_flip_direction(uint8_t chn_id);
+
+/**
+ * @brief Get the current direction of a relay channel.
+ *
+ * @param[in] chn_id Channel ID to get direction for.
+ * @return Current direction of the specified channel, or RELAY_CHN_DIRECTION_DEFAULT if invalid.
+ */
+extern relay_chn_direction_t relay_chn_ctl_get_direction(uint8_t chn_id);
+
+static inline relay_chn_state_t relay_chn_get_state(uint8_t chn_id)
+{
+    return relay_chn_ctl_get_state(chn_id);
+}
+
+static inline char *relay_chn_get_state_str(uint8_t chn_id)
+{
+    return relay_chn_ctl_get_state_str(chn_id);
+}
+
+static inline void relay_chn_run_forward(uint8_t chn_id)
+{
+    relay_chn_ctl_run_forward(chn_id);
+}
+
+static inline void relay_chn_run_reverse(uint8_t chn_id)
+{
+    relay_chn_ctl_run_reverse(chn_id);
+}
+
+static inline void relay_chn_stop(uint8_t chn_id)
+{
+    relay_chn_ctl_stop(chn_id);
+}
+
+static inline void relay_chn_flip_direction(uint8_t chn_id)
+{
+    relay_chn_ctl_flip_direction(chn_id);
+}
+
+static inline relay_chn_direction_t relay_chn_get_direction(uint8_t chn_id)
+{
+    return relay_chn_ctl_get_direction(chn_id);
+}
+
+#else
+
+/**
+ * @brief Get the current state of the relay channel.
+ *
+ * @return Current state of the channel.
+ */
+extern relay_chn_state_t relay_chn_ctl_get_state(void);
+
+/**
+ * @brief Get string representation of the relay channel's state.
+ *
+ * @return String representation of channel state.
+ */
+extern char *relay_chn_ctl_get_state_str(void);
+
+/**
+ * @brief Run the relay channel in forward direction.
+ */
+extern void relay_chn_ctl_run_forward(void);
+
+/**
+ * @brief Run the relay channel in reverse direction.
+ */
+extern void relay_chn_ctl_run_reverse(void);
+
+/**
+ * @brief Stop the relay channel.
+ */
+extern void relay_chn_ctl_stop(void);
+
+/**
+ * @brief Flip the running direction of the relay channel.
+ */
+extern void relay_chn_ctl_flip_direction(void);
+
+/**
+ * @brief Get the current direction of the relay channel.
+ *
+ * @return Current direction of the channel.
+ */
+extern relay_chn_direction_t relay_chn_ctl_get_direction(void);
+
+static inline relay_chn_state_t relay_chn_get_state(void)
+{
+    return relay_chn_ctl_get_state();
+}
+
+static inline char *relay_chn_get_state_str(void)
+{
+    return relay_chn_ctl_get_state_str();
+}
+
+static inline void relay_chn_run_forward(void)
+{
+    relay_chn_ctl_run_forward();
+}
+
+static inline void relay_chn_run_reverse(void)
+{
+    relay_chn_ctl_run_reverse();
+}
+
+static inline void relay_chn_stop(void)
+{
+    relay_chn_ctl_stop();
+}
+
+static inline void relay_chn_flip_direction(void)
+{
+    relay_chn_ctl_flip_direction();
+}
+
+static inline relay_chn_direction_t relay_chn_get_direction(void)
+{
+    return relay_chn_ctl_get_direction();
+}
+
+#endif // RELAY_CHN_COUNT > 1
+
+#ifdef __cplusplus
+}
+#endif

include/relay_chn_defs.h

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+ #pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Config defines for covenient writing */
+#define RELAY_CHN_OPPOSITE_INERTIA_MS CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS
+#define RELAY_CHN_COUNT CONFIG_RELAY_CHN_COUNT
+#define RELAY_CHN_ENABLE_TILTING CONFIG_RELAY_CHN_ENABLE_TILTING
+
+#if RELAY_CHN_COUNT > 1
+#define RELAY_CHN_ID_ALL RELAY_CHN_COUNT /*!< Special ID to address all channels */
+#endif
+
+#ifdef __cplusplus
+}
+#endif

include/relay_chn_types.h

@@ -0,0 +1,58 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include "relay_chn_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Enumeration for relay channel direction.
+ */
+typedef 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 */
+} relay_chn_direction_t;
+
+
+/**
+ * @brief Enums that represent the state of a relay channel.
+ */
+typedef enum relay_chn_state_enum {
+    RELAY_CHN_STATE_UNDEFINED,          /*!< The relay channel state is undefined */
+    RELAY_CHN_STATE_IDLE,               /*!< 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
+} 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);
+
+#ifdef __cplusplus
+}
+#endif