Merge pull request 'release-1.0.0' (!39) from release-1.0.0 into main

Reviewed-on: #39

.gitignore

@@ -56,6 +56,11 @@ tools/test_apps/**/build_*_*/
 tools/test_apps/**/sdkconfig
 tools/test_apps/**/sdkconfig.old
 
+# autogenerated config files
+sdkconfig
+test_apps/sdkconfig
+test_apps/sdkconfig.old
+
 TEST_LOGS/
 build_summary_*.xml
 
@@ -69,6 +74,7 @@ test_multi_heap_host
 
 # VS Code Settings
 # .vscode/
+settings.json
 
 # VIM files
 *.swp

.vscode/settings.json

@@ -1,3 +0,0 @@
-{
-    "C_Cpp.intelliSenseEngine": "default"
-}

CMakeLists.txt

@@ -3,7 +3,8 @@ set(priv_include_dirs "private_include")
 
 set(srcs "src/relay_chn_core.c"
          "src/relay_chn_output.c"
-         "src/relay_chn_run_info.c")
+         "src/relay_chn_run_info.c"
+         "src/relay_chn_notify.c")
 
 if(CONFIG_RELAY_CHN_ENABLE_TILTING)
     list(APPEND srcs "src/relay_chn_tilt.c")
@@ -15,7 +16,7 @@ else()
     list(APPEND srcs "src/relay_chn_ctl_single.c")
 endif()
 
-if(CONFIG_RELAY_CHN_NVS)
+if(CONFIG_RELAY_CHN_ENABLE_NVS)
     list(APPEND srcs "src/relay_chn_nvs.c")
 endif()
 

README.md

@@ -31,6 +31,16 @@ Another optional feature is NVS storage, which saves the configuration permanent
 - Tilt sensitivity
 - Last tilt position
 
+### NVS Operation Details
+When NVS storage is enabled (CONFIG_RELAY_CHN_ENABLE_NVS=y), the component creates a dedicated background task to manage all NVS write operations. This design has important implications for how you use the NVS-related functions:
+- **Asynchronous Writes:** All `set` operations (e.g., `relay_chn_flip_direction()`, `relay_chn_set_run_limit()`) are asynchronous. They add the write request to a queue and return immediately, preventing the calling task from being blocked.
+- **Synchronous Reads:** All get operations (e.g., `relay_chn_get_direction()`) are synchronous. They read the value directly from the NVS storage and will block the calling task until the read is complete.
+- **Batched Commits:** To optimize performance and minimize flash wear, the NVS task uses a batching mechanism for writes. It collects multiple write requests and commits them to the NVS flash in a single operation after a short period of inactivity (typically 200ms).
+
+> [!IMPORTANT]
+> Due to the asynchronous and batched nature of write operations, a call to a get function may not immediately reflect a value that was just written by a set function. Your application should account for this small delay.
+
+
 ## Configuration
 
 Configure the component through menuconfig under "Relay Channel Driver Configuration":
@@ -120,7 +130,7 @@ dependencies:
   # Add as a custom component from git repository
   relay_chn:
     git: https://git.kozmotronik.com.tr/KozmotronikTech/relay_chn.git
-    version: '>=0.5.0'
+    version: '>=1.0.0'
 ```
 
 ## Usage
@@ -200,6 +210,9 @@ relay_chn_flip_direction_all();
 
 ### 3. Monitor channel state
 
+> [!WARNING]
+> Listener callbacks are executed from the context of the notification dispatcher task. To ensure system responsiveness and prevent event loss, callbacks must be lightweight and non-blocking. Avoid any long-running operations or functions that may block, such as `vTaskDelay()` or semaphore takes with long timeouts, inside the callback.
+
 For single mode:
 
 ```c

examples/relay_chn_multi/.gitignore

@@ -0,0 +1,6 @@
+build/
+sdkconfig
+sdkconfig.old
+
+# Exclude auto-populated settings file
+settings.json

examples/relay_chn_multi/.vscode/c_cpp_properties.json

@@ -0,0 +1,23 @@
+{
+  "configurations": [
+    {
+      "name": "ESP-IDF",
+      "compilerPath": "${config:idf.toolsPath}/tools/riscv32-esp-elf/esp-14.2.0_20241119/riscv32-esp-elf/bin/riscv32-esp-elf-gcc",
+      "compileCommands": "/disk/Projeler/ESP-Components/relay_chn/examples/relay_chn_single/build/compile_commands.json",
+      "includePath": [
+        "${config:idf.espIdfPath}/components/**",
+        "${config:idf.espIdfPathWin}/components/**",
+        "${workspaceFolder}/**"
+      ],
+      "browse": {
+        "path": [
+          "${config:idf.espIdfPath}/components",
+          "${config:idf.espIdfPathWin}/components",
+          "${workspaceFolder}"
+        ],
+        "limitSymbolsToIncludedHeaders": true
+      }
+    }
+  ],
+  "version": 4
+}

examples/relay_chn_multi/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "gdbtarget",
+      "request": "attach",
+      "name": "Eclipse CDT GDB Adapter"
+    },
+    {
+      "type": "espidf",
+      "name": "Launch",
+      "request": "launch"
+    }
+  ]
+}

examples/relay_chn_multi/CMakeLists.txt

@@ -0,0 +1,10 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five 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(COMPONENTS main)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(relay_chn_single)

examples/relay_chn_multi/README.md

@@ -0,0 +1,176 @@
+# Relay Channel Multi Example
+
+## Introduction
+
+This example demonstrates how to use the relay channel component to control a 3-channel setup with button inputs and LED status indication. It showcases:
+
+- Basic relay channel operations (forward/reverse running, stopping)
+- Secondary operations (tilting, direction flipping)
+- State change event handling with a listener
+- Relay channel run limit
+- Button event handling using esp-iot-solution's button component
+- Visual feedback using esp-iot-solution's LED indicator component
+
+## How to Use Example
+
+This example has been tested on an `ESP32-C3-DevKitM-1U` board. However, it can be adapted to any ESP32-based board with at least six available GPIO pins by adjusting the configuration options.
+
+### Hardware Required
+
+* An ESP32-based development board
+* 2 relays connected to GPIO pins (default: GPIO4, GPIO5)
+* 3 buttons connected to GPIO pins:
+  - UP button (default: GPIO0)
+  - DOWN button (default: GPIO1) 
+  - STOP button (default: GPIO2)
+  - SELECT button (default: GPIO3)
+* LED indicators for status indication of each channel (default: GPIO4, GPIO10 and GPIO9 respectively)
+
+#### Hardware Schematic
+
+Relay blocks are ommitted for simplicity. You can refer to schematic of the [Single-channel example](/examples/relay_chn_single/README.md) for a fully implemented relay block.
+
+> [!NOTE]
+> A single relay channel consists of two relay block and two GPIO pins.
+
+![Hardware Schematic](example_schematic.png)
+
+### Configuration
+
+The example can be configured through `menuconfig` under "Relay Channel Multi Example Configuration":
+
+1. Button active level (`EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL`)
+   - Select between active LOW or HIGH logic level for buttons
+   
+2. GPIO assignments:
+   - UP button pin (`EXAMPLE_RLCHN_BTN_UP_IO_NUM`, default: 0)
+   - DOWN button pin (`EXAMPLE_RLCHN_BTN_DOWN_IO_NUM`, default: 1)
+   - STOP button pin (`EXAMPLE_RLCHN_BTN_STOP_IO_NUM`, default: 2)
+   - SELECT button pin (`EXAMPLE_RLCHN_BTN_SELECT_IO_NUM`, default: 3)
+   - LED indicator pin (`EXAMPLE_RLCHN_LED_INDICATOR1_IO_NUM`, default: 4)
+   - LED indicator pin (`EXAMPLE_RLCHN_LED_INDICATOR2_IO_NUM`, default: 10)
+   - LED indicator pin (`EXAMPLE_RLCHN_LED_INDICATOR3_IO_NUM`, default: 9)
+
+3. Long press timing:
+   - `EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS`: Duration for long press actions (1500-3000ms, default: 2000ms)
+
+### Button Operations
+
+The example uses esp-iot-solution's `button` component to handle the following operations:
+
+- **UP button**:
+  * Short press: Start forward movement
+  * Long press: Start forward tilt (stops on release)
+
+- **DOWN button**: 
+  * Short press: Start reverse movement
+  * Long press: Start reverse tilt (stops on release)
+
+- **STOP button**:
+  * Short press: Stop movement
+  * Long press: Flip movement direction
+
+- **SELECT button**:
+  * Short press: Selects a channel to operate
+  * Long press: Selects all channels to operate in batch
+
+### LED Indicator States
+
+The example uses esp-iot-solution's `led_indicator` component to show different states:
+
+- **Running**: LED blinks at 300ms on, 100ms off
+- **Tilting**: Fast blink at 100ms on, 50ms off
+- **Operation Success**: Two quick blinks
+- **Operation Fail**: One long blink
+
+### Dependencies
+
+This example requires:
+- ESP-IDF v4.1 or later
+- esp-iot-solution components:
+  * button v4.1.1 or later
+  * led_indicator v1.1.1 or later
+- relay_chn component
+
+## Example Output
+
+When the application boots, it will wait for a button event. Then ta state listener will print state changes.
+
+```log
+I (269) main_task: Calling app_main()
+I (269) RELAY_CHN_MULTI_EXAMPLE: Initializing relay channel
+I (279) gpio: GPIO[18]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (279) gpio: GPIO[19]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (289) gpio: GPIO[5]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (299) gpio: GPIO[6]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (309) gpio: GPIO[7]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (319) gpio: GPIO[8]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (329) RELAY_CHN_MULTI_EXAMPLE: Initializing buttons
+I (329) RELAY_CHN_MULTI_EXAMPLE: Initializing buttons with active level: 0
+I (339) gpio: GPIO[0]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (339) button: IoT Button Version: 4.1.3
+I (349) gpio: GPIO[1]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (359) gpio: GPIO[2]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (359) gpio: GPIO[3]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (369) RELAY_CHN_MULTI_EXAMPLE: Setting up button callbacks. Configured long press time: 2000 ms
+I (379) RELAY_CHN_MULTI_EXAMPLE: Initializing LED indicator
+I (389) gpio: GPIO[4]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (389) led_indicator: LED Indicator Version: 1.1.1
+I (399) gpio: GPIO[4]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
+I (409) led_indicator: Indicator create successfully. type:GPIO mode, hardware_data:0x3fc96498, blink_lists:custom
+I (419) gpio: GPIO[10]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (429) led_indicator: LED Indicator Version: 1.1.1
+I (429) gpio: GPIO[10]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
+I (439) led_indicator: Indicator create successfully. type:GPIO mode, hardware_data:0x3fc965a4, blink_lists:custom
+I (449) gpio: GPIO[9]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (459) led_indicator: LED Indicator Version: 1.1.1
+I (459) gpio: GPIO[9]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
+I (469) led_indicator: Indicator create successfully. type:GPIO mode, hardware_data:0x3fc966b0, blink_lists:custom
+I (479) RELAY_CHN_MULTI_EXAMPLE: Relay Channel Multi Example is ready to operate
+I (489) main_task: Returned from app_main()
+I (3759) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from IDLE to FORWARD
+I (6639) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from FORWARD to STOPPED
+I (7439) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from STOPPED to IDLE
+I (7439) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from IDLE to TILT_FORWARD
+I (8119) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from TILT_FORWARD to IDLE
+I (13579) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from IDLE to TILT_REVERSE
+I (14419) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from TILT_REVERSE to IDLE
+I (20319) RELAY_CHN_MULTI_EXAMPLE: Selected channel: 1
+I (21479) RELAY_CHN_MULTI_EXAMPLE: Selected channel: 2
+I (22229) RELAY_CHN_MULTI_EXAMPLE: Selected channel: 0
+I (23169) RELAY_CHN_MULTI_EXAMPLE: Selected channel: 1
+I (29039) RELAY_CHN_MULTI_EXAMPLE: Selected all channels
+I (35419) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from IDLE to FORWARD
+I (35419) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from IDLE to FORWARD
+I (35419) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from IDLE to FORWARD
+I (39349) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from FORWARD to STOPPED
+I (39349) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from FORWARD to STOPPED
+I (39359) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from FORWARD to STOPPED
+I (40149) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from STOPPED to IDLE
+I (40149) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from IDLE to TILT_FORWARD
+I (40159) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from STOPPED to IDLE
+I (40169) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from IDLE to TILT_FORWARD
+I (40179) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from STOPPED to IDLE
+I (40189) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from IDLE to TILT_FORWARD
+I (41699) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from TILT_FORWARD to IDLE
+I (41699) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from TILT_FORWARD to IDLE
+I (41709) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from TILT_FORWARD to IDLE
+I (64129) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from IDLE to TILT_REVERSE
+I (64129) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from IDLE to TILT_REVERSE
+I (64139) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from IDLE to TILT_REVERSE
+I (68929) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from TILT_REVERSE to IDLE
+I (68929) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from TILT_REVERSE to IDLE
+I (68939) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from TILT_REVERSE to IDLE
+I (280109) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from IDLE to FORWARD
+I (280109) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from IDLE to FORWARD
+I (280109) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from IDLE to FORWARD
+I (283219) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from FORWARD to STOPPED
+I (283219) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from STOPPED to REVERSE_PENDING
+I (283229) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from FORWARD to STOPPED
+I (283239) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from STOPPED to REVERSE_PENDING
+I (283249) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from FORWARD to STOPPED
+I (283259) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from STOPPED to REVERSE_PENDING
+I (284019) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #0, from REVERSE_PENDING to REVERSE
+I (284019) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #1, from REVERSE_PENDING to REVERSE
+I (284029) RELAY_CHN_MULTI_EXAMPLE: example_event_listener: State change for #2, from REVERSE_PENDING to REVERSE
+```

examples/relay_chn_multi/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "relay_chn_multi_main.c"
+                       PRIV_REQUIRES button led_indicator relay_chn)

examples/relay_chn_multi/main/Kconfig.projbuild

@@ -0,0 +1,52 @@
+menu "Relay Channel Multi Example Configuration"
+    
+    choice EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL
+        prompt "Choose an active level for buttons"
+        default EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_LOW
+        help
+            Specify the active level for buttons.
+        
+        config EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_LOW
+            bool "Active level LOW"
+
+        config EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_HIGH
+            bool "Active level HIGH"
+    endchoice
+    
+    config EXAMPLE_RLCHN_BTN_UP_IO_NUM
+        int "GPIO number for UP button"
+        default 0
+    
+    config EXAMPLE_RLCHN_BTN_DOWN_IO_NUM
+        int "GPIO number for DOWN button"
+        default 1
+    
+    config EXAMPLE_RLCHN_BTN_STOP_IO_NUM
+        int "GPIO number for STOP button"
+        default 2
+    
+    config EXAMPLE_RLCHN_BTN_SELECT_IO_NUM
+        int "GPIO number for STOP button"
+        default 3
+    
+    config EXAMPLE_RLCHN_LED_INDICATOR1_IO_NUM
+        int "GPIO number for LED indicator output for channel 1"
+        default 4
+    
+    config EXAMPLE_RLCHN_LED_INDICATOR2_IO_NUM
+        int "GPIO number for LED indicator output for channel 2"
+        default 10
+    
+    config EXAMPLE_RLCHN_LED_INDICATOR3_IO_NUM
+        int "GPIO number for LED indicator output for channel 3"
+        default 9
+    
+    config EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS
+        int "Long press time in ms to start secondary actions"
+        range 1500 3000
+        default 2000
+        help
+            Long press time in milliseconds is required to start secondary actions 
+            like tilting and flipping.
+
+endmenu

examples/relay_chn_multi/main/idf_component.yml

@@ -0,0 +1,8 @@
+dependencies:
+  idf:
+    version: '>=4.1.0'
+  espressif/button: ^4.1.1
+  espressif/led_indicator: ^1.1.1
+  relay_chn:
+    version: '*'
+    override_path: ../../../

examples/relay_chn_multi/main/relay_chn_multi_main.c

@@ -0,0 +1,427 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <stdio.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_check.h"
+#include "driver/gpio.h"
+#include "nvs.h"
+#include "nvs_flash.h"
+#include "esp_timer.h"
+#include "button_gpio.h"
+#include "iot_button.h"
+#include "led_indicator.h"
+#include "relay_chn.h"
+
+static const char *TAG = "RELAY_CHN_MULTI_EXAMPLE";
+
+#define EXAMPLE_CHN_INDICATOR_ON_TIME_MS 3000
+#define EXAMPLE_ALL_CHANNELS CONFIG_RELAY_CHN_COUNT
+
+
+/**
+ * @brief LED indicator modes for different states.
+ */
+typedef enum {
+    INDICATOR_MODE_SELECT,      /*!< Channel select indication */
+    INDICATOR_MODE_OK,          /*!< OK/Success indication */
+    INDICATOR_MODE_FAIL,        /*!< Fail/Error indication */
+    INDICATOR_MODE_TILTING,     /*!< Tilting operation in progress */
+    INDICATOR_MODE_RUNNING,     /*!< Full run operation in progress */
+    INDICATOR_MODE_MAX          /*!< Maximum number of indicator modes */
+} indicator_mode_t;
+
+/** @brief Blink pattern for channel select indication. */
+static const blink_step_t indc_mode_select[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, EXAMPLE_CHN_INDICATOR_ON_TIME_MS},    // step1: turn on LED 3000 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 10},     // step2: turn off LED 500 ms
+    {LED_BLINK_STOP, 0, 0},                  // step4: stop blink (off)
+};
+
+/** @brief Blink pattern for OK/Success indication. */
+static const blink_step_t indc_mode_ok[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 100},    // step1: turn on LED 100 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 50},    // step2: turn off LED 50 ms
+    {LED_BLINK_HOLD, LED_STATE_ON, 100},    // step3: turn on LED 100 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 50},    // step4: turn off LED 50 ms
+    {LED_BLINK_STOP, 0, 0},                 // step5: stop blink (off)
+};
+
+/** @brief Blink pattern for Fail/Error indication. */
+static const blink_step_t indc_mode_fail[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 1000},    // step1: turn on LED 1000 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 500},    // step2: turn off LED 500 ms
+    {LED_BLINK_STOP, 0, 0},                  // step4: stop blink (off)
+};
+
+/** @brief Blink pattern for full run operation. */
+static const blink_step_t indc_mode_running[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 300},    // step1: turn on LED 300 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 100},   // step2: turn off LED 100 ms
+    {LED_BLINK_LOOP, 0, 0},                 // step3: loop from step1
+};
+
+/** @brief Blink pattern for tilting operation. */
+static const blink_step_t indc_mode_tilting[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 100},    // step1: turn on LED 100 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 50},    // step2: turn off LED 50 ms
+    {LED_BLINK_LOOP, 0, 0},                 // step3: loop from step1
+};
+
+/** @brief Array of LED indicator blink patterns. */
+blink_step_t const *led_indicator_modes[] = {
+    [INDICATOR_MODE_SELECT]     = indc_mode_select,
+    [INDICATOR_MODE_OK]         = indc_mode_ok,
+    [INDICATOR_MODE_FAIL]       = indc_mode_fail,
+    [INDICATOR_MODE_RUNNING]    = indc_mode_running,
+    [INDICATOR_MODE_TILTING]    = indc_mode_tilting,
+    [INDICATOR_MODE_MAX]        = NULL,
+};
+
+/** @brief Handle for the LED indicator. */
+static led_indicator_handle_t indicators[CONFIG_RELAY_CHN_COUNT];
+static uint8_t selected_channel = 0; /*!< Currently selected channel */
+static uint8_t selected_channel_backup = 0; /*!< Backup for last selected channel */
+static int64_t last_indc_update_us = 0; /*!< Timestamp of the last channel selection */
+
+
+/**
+ * @brief Initializes the buttons for user interaction.
+ *
+ * This function configures and creates GPIO buttons for UP, DOWN, and STOP
+ * operations. It also registers callbacks for single-click and long-press
+ * events to control the relay channel.
+ *
+ * @return esp_err_t
+ *      - ESP_OK: Success
+ *      - Others: Fail
+ */
+static esp_err_t init_buttons(void);
+
+/**
+ * @brief Initializes the LED indicator.
+ *
+ * This function configures and creates the LED indicator used to provide
+ * visual feedback on the relay channel's status.
+ *
+ * @return esp_err_t
+ *      - ESP_OK: Success
+ *      - ESP_FAIL: Fail
+ */
+static esp_err_t init_led_indicators(void);
+
+/**
+ * @brief Starts all indicators with the specified mode.
+ * 
+ * @param mode One of the indicator modes defined with indicator_mode_t.
+ */
+static void start_all_indicators_for_mode(indicator_mode_t mode);
+
+/**
+ * @brief Stops all indicators with the specified mode.
+ * 
+ * @param mode One of the indicator modes defined with indicator_mode_t.
+ */
+static void stop_all_indicators_for_mode(indicator_mode_t mode);
+
+/**
+ * @brief Event listener for relay channel state changes to log the state transition.
+ */
+static void example_event_listener(uint8_t ch, relay_chn_state_t old_state, relay_chn_state_t new_state);
+
+void app_main(void)
+{
+    const uint8_t gpio_map[] = { 18, 19, 5, 6, 7, 8 };
+    const uint8_t gpio_count = sizeof(gpio_map) / sizeof(gpio_map[0]);
+
+    ESP_LOGI(TAG, "Initializing relay channel");
+    ESP_ERROR_CHECK(relay_chn_create(gpio_map, gpio_count));
+    ESP_ERROR_CHECK(relay_chn_register_listener(example_event_listener));
+
+    ESP_LOGI(TAG, "Initializing buttons");
+    ESP_ERROR_CHECK(init_buttons());
+    ESP_LOGI(TAG, "Initializing LED indicator");
+    ESP_ERROR_CHECK(init_led_indicators());
+
+    ESP_LOGI(TAG, "Relay Channel Multi Example is ready to operate");
+
+    // Indicate init was successful
+    start_all_indicators_for_mode(INDICATOR_MODE_OK);
+}
+
+static void on_click_up(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        relay_chn_run_forward_all();
+    } else {
+        relay_chn_run_forward(selected_channel);
+    }
+}
+
+static void on_click_down(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        relay_chn_run_reverse_all();
+    } else {
+        relay_chn_run_reverse(selected_channel);
+    }
+}
+
+static void on_click_stop(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        relay_chn_stop_all();
+    } else {
+        relay_chn_stop(selected_channel);
+    }
+}
+
+static void on_click_flip(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        relay_chn_flip_direction_all();
+        start_all_indicators_for_mode(INDICATOR_MODE_OK);
+    } else {
+        relay_chn_flip_direction(selected_channel);
+        led_indicator_start(indicators[selected_channel], INDICATOR_MODE_OK);
+    }
+}
+
+static void on_click_tilt_up(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        relay_chn_tilt_forward_all();
+    } else {
+        relay_chn_tilt_forward(selected_channel);
+    }
+}
+
+static void on_click_tilt_down(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        relay_chn_tilt_reverse_all();
+    } else {
+        relay_chn_tilt_reverse(selected_channel);
+    }
+}
+
+static void on_release_tilt(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        relay_chn_tilt_stop_all();
+    } else {
+        relay_chn_tilt_stop(selected_channel);
+    }
+}
+
+static void on_click_select(void *arg, void *data)
+{
+    int64_t now_us = esp_timer_get_time();
+    uint32_t delta_ms = (now_us - last_indc_update_us) / 1000;
+    if (delta_ms >= EXAMPLE_CHN_INDICATOR_ON_TIME_MS) {
+        // Channel indicator was off, turn it on first
+        if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+            start_all_indicators_for_mode(INDICATOR_MODE_SELECT);
+        } else {
+            led_indicator_start(indicators[selected_channel], INDICATOR_MODE_SELECT);
+        }
+        last_indc_update_us = esp_timer_get_time(); // Save last selection time
+        return;
+    }
+
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        // All channels selected previously, restore the selected channel
+        selected_channel = selected_channel_backup;
+        ESP_LOGI(TAG, "Restored selected channel: %d", selected_channel);
+        stop_all_indicators_for_mode(INDICATOR_MODE_SELECT);
+        led_indicator_start(indicators[selected_channel], INDICATOR_MODE_SELECT);
+        return;
+    }
+
+    // Channel indicator is turned on, select the next channel
+    selected_channel = ((selected_channel + 1) % CONFIG_RELAY_CHN_COUNT);
+    ESP_LOGI(TAG, "Selected channel: %d", selected_channel);
+    // Update the indicator
+    stop_all_indicators_for_mode(INDICATOR_MODE_SELECT);
+    led_indicator_start(indicators[selected_channel], INDICATOR_MODE_SELECT);
+    last_indc_update_us = esp_timer_get_time(); // Save last selection time
+}
+
+static void on_click_select_all(void *arg, void *data)
+{
+    if (selected_channel == EXAMPLE_ALL_CHANNELS) {
+        ESP_LOGI(TAG, "All channels are selected already");
+        int64_t now_us = esp_timer_get_time();
+        uint32_t delta_ms = (now_us - last_indc_update_us) / 1000;
+        // If the indicators in sleep, wake up
+        if (delta_ms >= EXAMPLE_CHN_INDICATOR_ON_TIME_MS) {
+            start_all_indicators_for_mode(INDICATOR_MODE_SELECT);
+        }
+        return;
+    }
+
+    selected_channel_backup = selected_channel;
+    selected_channel = EXAMPLE_ALL_CHANNELS;
+    ESP_LOGI(TAG, "Selected all channels");
+    start_all_indicators_for_mode(INDICATOR_MODE_SELECT);
+    last_indc_update_us = esp_timer_get_time(); // Save last selection time
+}
+
+static void start_all_indicators_for_mode(indicator_mode_t mode)
+{
+    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        led_indicator_start(indicators[i], mode);
+    }
+}
+
+static void stop_all_indicators_for_mode(indicator_mode_t mode)
+{
+    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        led_indicator_stop(indicators[i], mode);
+        led_indicator_set_on_off(indicators[i], false);
+    }
+}
+
+static void example_event_listener(uint8_t ch, relay_chn_state_t old_state, relay_chn_state_t new_state)
+{
+    ESP_LOGI(TAG, "example_event_listener: State change for #%d, from %s to %s",
+                ch, relay_chn_state_to_str(old_state), relay_chn_state_to_str(new_state));
+    switch (new_state) {
+        case RELAY_CHN_STATE_FORWARD:
+        case RELAY_CHN_STATE_REVERSE:
+            led_indicator_start(indicators[ch], INDICATOR_MODE_RUNNING);
+            break;
+
+        case RELAY_CHN_STATE_STOPPED:
+        case RELAY_CHN_STATE_IDLE:
+            if (old_state == RELAY_CHN_STATE_FORWARD || old_state == RELAY_CHN_STATE_REVERSE) {
+                led_indicator_stop(indicators[ch], INDICATOR_MODE_RUNNING);
+                // Make sure the indicator turned off
+                led_indicator_set_on_off(indicators[ch], false);
+            }
+            else if (old_state == RELAY_CHN_STATE_TILT_FORWARD || old_state == RELAY_CHN_STATE_TILT_REVERSE) {
+                led_indicator_stop(indicators[ch], INDICATOR_MODE_TILTING);
+                // Make sure the indicator turned off
+                led_indicator_set_on_off(indicators[ch], false);
+            }
+            break;
+
+        case RELAY_CHN_STATE_TILT_FORWARD:
+        case RELAY_CHN_STATE_TILT_REVERSE:
+            led_indicator_start(indicators[ch], INDICATOR_MODE_TILTING);
+            break;
+
+        default: // No-op
+    }
+}
+
+static esp_err_t init_buttons()
+{
+    esp_err_t ret;
+    button_config_t btn_cfg = {0};
+
+    uint8_t active_level = CONFIG_EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_LOW ? 0 : 1;
+
+    button_gpio_config_t btn_gpio_ccfg = {
+        .gpio_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_BTN_UP_IO_NUM,
+        .active_level = active_level
+    };
+
+    ESP_LOGI(TAG, "Initializing buttons with active level: %u", active_level);
+    button_handle_t btn_up = NULL, btn_down = NULL, btn_stop = NULL, btn_select = NULL;
+    // --- Create buttons ---
+    ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_ccfg, &btn_up);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create UP button");
+    ESP_RETURN_ON_FALSE(btn_up != NULL, ret, TAG, "Failed to create UP button");
+
+    btn_gpio_ccfg.gpio_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_BTN_DOWN_IO_NUM;
+    ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_ccfg, &btn_down);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create DOWN button");
+    ESP_RETURN_ON_FALSE(btn_down != NULL, ret, TAG, "Failed to create DOWN button");
+    
+    btn_gpio_ccfg.gpio_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_BTN_STOP_IO_NUM;
+    ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_ccfg, &btn_stop);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create STOP button");
+    ESP_RETURN_ON_FALSE(btn_stop != NULL, ret, TAG, "Failed to create STOP button");
+    
+    btn_gpio_ccfg.gpio_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_BTN_SELECT_IO_NUM;
+    ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_ccfg, &btn_select);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create SELECT button");
+    ESP_RETURN_ON_FALSE(btn_select != NULL, ret, TAG, "Failed to create SELECT button");
+    // --- Create buttons ---
+
+    // --- Register button callbacks ---
+    ESP_LOGI(TAG, "Setting up button callbacks. Configured long press time: %d ms", CONFIG_EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS);
+    button_event_args_t btn_event_args = {
+        .long_press.press_time = CONFIG_EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS
+    };
+    // --- Register UP and TILT_UP operations on UP button ---
+    ret = iot_button_register_cb(btn_up, BUTTON_SINGLE_CLICK, NULL, on_click_up, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register UP button click callback");
+    ret = iot_button_register_cb(btn_up, BUTTON_LONG_PRESS_START, &btn_event_args, on_click_tilt_up, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_UP button press callback");
+    ret = iot_button_register_cb(btn_up, BUTTON_LONG_PRESS_UP, NULL, on_release_tilt, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_UP button release callback");
+    
+    // --- Register DOWN and TILT_DOWN operations on DOWN button ---
+    ret = iot_button_register_cb(btn_down, BUTTON_SINGLE_CLICK, NULL, on_click_down, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register DOWN button click callback");
+    ret = iot_button_register_cb(btn_down, BUTTON_LONG_PRESS_START, &btn_event_args, on_click_tilt_down, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_DOWN button press callback");
+    ret = iot_button_register_cb(btn_down, BUTTON_LONG_PRESS_UP, NULL, on_release_tilt, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_DOWN button release callback");
+    
+    // --- Register STOP and FLIP operations on STOP ---
+    ret = iot_button_register_cb(btn_stop, BUTTON_SINGLE_CLICK, NULL, on_click_stop, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register STOP button click callback");
+    ret = iot_button_register_cb(btn_stop, BUTTON_LONG_PRESS_START, &btn_event_args, on_click_flip, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register FLIP button press callback");
+    
+    // --- Register channel SELECT and SELECT_ALL ---
+    ret = iot_button_register_cb(btn_select, BUTTON_SINGLE_CLICK, NULL, on_click_select, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register SELECT button click callback");
+    ret = iot_button_register_cb(btn_select, BUTTON_LONG_PRESS_START, &btn_event_args, on_click_select_all, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register SELECT_ALL press callback");
+
+    return ESP_OK;
+}
+
+static esp_err_t init_led_indicators()
+{
+    const int indicator_io_nums[CONFIG_RELAY_CHN_COUNT] = {
+        CONFIG_EXAMPLE_RLCHN_LED_INDICATOR1_IO_NUM,
+        CONFIG_EXAMPLE_RLCHN_LED_INDICATOR2_IO_NUM,
+        CONFIG_EXAMPLE_RLCHN_LED_INDICATOR3_IO_NUM
+    };
+    
+    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        gpio_num_t indicator_io_num = (gpio_num_t) indicator_io_nums[i];
+        gpio_reset_pin(indicator_io_num); // Clear the output buffers
+    
+        led_indicator_gpio_config_t led_indicator_gpio_cfg = {
+            .gpio_num = indicator_io_num,
+            .is_active_level_high = true
+        };
+    
+        led_indicator_config_t led_indicator_cfg = {
+            .mode = LED_GPIO_MODE,
+            .led_indicator_gpio_config = &led_indicator_gpio_cfg,
+            .blink_lists = led_indicator_modes,
+            .blink_list_num = INDICATOR_MODE_MAX
+        };
+        
+        indicators[i] = led_indicator_create(&led_indicator_cfg);
+        if (!indicators[i]) {
+            ESP_LOGE(TAG, "Failed to create LED indicator");
+            return ESP_FAIL;
+        }
+    }
+
+    return ESP_OK;
+}

examples/relay_chn_multi/sdkconfig.defaults

@@ -0,0 +1,10 @@
+# Halt on panic
+CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT=y
+
+# Relay Channel Configs
+CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT=y
+CONFIG_RELAY_CHN_COUNT=3
+# Keep this as short as possible for example purposes
+CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC=5
+CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC=20
+CONFIG_RELAY_CHN_ENABLE_TILTING=y

examples/relay_chn_single/.gitignore

@@ -0,0 +1,6 @@
+build/
+sdkconfig
+sdkconfig.old
+
+# Exclude auto-populated settings file
+settings.json

examples/relay_chn_single/.vscode/c_cpp_properties.json

@@ -0,0 +1,23 @@
+{
+  "configurations": [
+    {
+      "name": "ESP-IDF",
+      "compilerPath": "${config:idf.toolsPath}/tools/riscv32-esp-elf/esp-14.2.0_20241119/riscv32-esp-elf/bin/riscv32-esp-elf-gcc",
+      "compileCommands": "/disk/Projeler/ESP-Components/relay_chn/examples/relay_chn_single/build/compile_commands.json",
+      "includePath": [
+        "${config:idf.espIdfPath}/components/**",
+        "${config:idf.espIdfPathWin}/components/**",
+        "${workspaceFolder}/**"
+      ],
+      "browse": {
+        "path": [
+          "${config:idf.espIdfPath}/components",
+          "${config:idf.espIdfPathWin}/components",
+          "${workspaceFolder}"
+        ],
+        "limitSymbolsToIncludedHeaders": true
+      }
+    }
+  ],
+  "version": 4
+}

examples/relay_chn_single/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "gdbtarget",
+      "request": "attach",
+      "name": "Eclipse CDT GDB Adapter"
+    },
+    {
+      "type": "espidf",
+      "name": "Launch",
+      "request": "launch"
+    }
+  ]
+}

examples/relay_chn_single/CMakeLists.txt

@@ -0,0 +1,10 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five 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(COMPONENTS main)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(relay_chn_single)

examples/relay_chn_single/README.md

@@ -0,0 +1,126 @@
+# Relay Channel Single Example
+
+## Introduction
+
+This example demonstrates how to use the relay channel component to control a 2-relay setup with button inputs and LED status indication. It showcases:
+
+- Basic relay channel operations (forward/reverse running, stopping)
+- Secondary operations (tilting, direction flipping)
+- State change event handling with multiple listeners
+- Relay channel run limit
+- Button event handling using esp-iot-solution's button component
+- Visual feedback using esp-iot-solution's LED indicator component
+
+## How to Use Example
+
+This example has been tested on an `ESP32-C3-DevKitM-1U` board. However, it can be adapted to any ESP32-based board with at least six available GPIO pins by adjusting the configuration options.
+
+### Hardware Required
+
+* An ESP32-based development board
+* 2 relays connected to GPIO pins (default: GPIO4, GPIO5)
+* 3 buttons connected to GPIO pins:
+  - UP button (default: GPIO0)
+  - DOWN button (default: GPIO1) 
+  - STOP button (default: GPIO2)
+* 1 LED for status indication (default: GPIO3)
+
+#### Hardware Schematic
+
+![Hardware Schematic](example_schematic.png)
+
+### Configuration
+
+The example can be configured through `menuconfig` under "Relay Channel Single Example Configuration":
+
+1. Button active level (`EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL`)
+   - Select between active LOW or HIGH logic level for buttons
+   
+2. GPIO assignments:
+   - UP button pin (`EXAMPLE_RLCHN_BTN_UP_IO_NUM`, default: 0)
+   - DOWN button pin (`EXAMPLE_RLCHN_BTN_DOWN_IO_NUM`, default: 1)
+   - STOP button pin (`EXAMPLE_RLCHN_BTN_STOP_IO_NUM`, default: 2)
+   - LED indicator pin (`EXAMPLE_RLCHN_LED_INDICATOR_IO_NUM`, default: 3)
+
+3. Long press timing:
+   - `EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS`: Duration for long press actions (1500-3000ms, default: 2000ms)
+
+### Button Operations
+
+The example uses esp-iot-solution's `button` component to handle the following operations:
+
+- **UP button**:
+  * Short press: Start forward movement
+  * Long press: Start forward tilt (stops on release)
+
+- **DOWN button**: 
+  * Short press: Start reverse movement
+  * Long press: Start reverse tilt (stops on release)
+
+- **STOP button**:
+  * Short press: Stop movement
+  * Long press: Flip movement direction
+
+### LED Indicator States
+
+The example uses esp-iot-solution's `led_indicator` component to show different states:
+
+- **Running**: LED blinks at 300ms on, 100ms off
+- **Tilting**: Fast blink at 100ms on, 50ms off
+- **Operation Success**: Two quick blinks
+- **Operation Fail**: One long blink
+
+### Dependencies
+
+This example requires:
+- ESP-IDF v4.1 or later
+- esp-iot-solution components:
+  * button v4.1.1 or later
+  * led_indicator v1.1.1 or later
+- relay_chn component
+
+## Example Output
+When the application boots, it will wait for a button event. Then the two state listeners will print state changes.
+
+```log
+I (273) main_task: Calling app_main()
+I (273) RELAY_CHN_SINGLE_EXAMPLE: Initializing default NVS storage
+I (283) RELAY_CHN_SINGLE_EXAMPLE: nvs_flash_init: NVS flash init return: ESP_OK
+I (283) RELAY_CHN_SINGLE_EXAMPLE: Initializing relay channel
+I (293) gpio: GPIO[4]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (303) gpio: GPIO[5]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (313) RELAY_CHN_SINGLE_EXAMPLE: Initializing buttons
+I (313) RELAY_CHN_SINGLE_EXAMPLE: Initializing buttons with active level: 0
+I (323) gpio: GPIO[0]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (323) button: IoT Button Version: 4.1.3
+I (333) gpio: GPIO[1]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (343) gpio: GPIO[2]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (343) RELAY_CHN_SINGLE_EXAMPLE: Setting up button callbacks. Configured long press time: 2000 ms
+I (353) RELAY_CHN_SINGLE_EXAMPLE: Initializing LED indicator
+I (363) gpio: GPIO[3]| InputEn: 0| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:0 
+I (373) led_indicator: LED Indicator Version: 1.1.1
+I (373) gpio: GPIO[3]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
+I (383) led_indicator: Indicator create successfully. type:GPIO mode, hardware_data:0x3fc97be4, blink_lists:custom
+I (393) RELAY_CHN_SINGLE_EXAMPLE: Relay Channel Single Example is ready to operate
+I (403) main_task: Returned from app_main()
+I (3683) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 1 to 3
+I (3683) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from IDLE to FORWARD
+I (9513) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 3 to 2
+I (9513) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from FORWARD to STOPPED
+I (9523) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 2 to 6
+I (9533) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from STOPPED to REVERSE_PENDING
+I (10313) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 6 to 4
+I (10313) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from REVERSE_PENDING to REVERSE
+I (32173) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 4 to 2
+I (32173) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from REVERSE to STOPPED
+I (32973) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 2 to 1
+I (32973) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from STOPPED to IDLE
+I (36423) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 1 to 8
+I (36423) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from IDLE to TILT_REVERSE
+I (41153) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 8 to 1
+I (41153) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from TILT_REVERSE to IDLE
+I (47113) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 1 to 7
+I (47113) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from IDLE to TILT_FORWARD
+I (51913) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_1: Defining new indicator mode for #0 and state change from 7 to 1
+I (51913) RELAY_CHN_SINGLE_EXAMPLE: example_event_listener_2: State change for #0, from TILT_FORWARD to IDLE
+```

examples/relay_chn_single/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "relay_chn_single_main.c"
+                       PRIV_REQUIRES button led_indicator relay_chn)

examples/relay_chn_single/main/Kconfig.projbuild

@@ -0,0 +1,40 @@
+menu "Relay Channel Single Example Configuration"
+    
+    choice EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL
+        prompt "Choose an active level for buttons"
+        default EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_LOW
+        help
+            Specify the active level for buttons.
+        
+        config EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_LOW
+            bool "Active level LOW"
+
+        config EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_HIGH
+            bool "Active level HIGH"
+    endchoice
+    
+    config EXAMPLE_RLCHN_BTN_UP_IO_NUM
+        int "GPIO number for UP button"
+        default 0
+    
+    config EXAMPLE_RLCHN_BTN_DOWN_IO_NUM
+        int "GPIO number for DOWN button"
+        default 1
+    
+    config EXAMPLE_RLCHN_BTN_STOP_IO_NUM
+        int "GPIO number for STOP button"
+        default 2
+    
+    config EXAMPLE_RLCHN_LED_INDICATOR_IO_NUM
+        int "GPIO number for LED indicator output"
+        default 3
+    
+    config EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS
+        int "Long press time in ms to start secondary actions"
+        range 1500 3000
+        default 2000
+        help
+            Long press time in milliseconds is required to start secondary actions 
+            like tilting and flipping.
+
+endmenu

examples/relay_chn_single/main/idf_component.yml

@@ -0,0 +1,8 @@
+dependencies:
+  idf:
+    version: '>=4.1.0'
+  espressif/button: ^4.1.1
+  espressif/led_indicator: ^1.1.1
+  relay_chn:
+    version: '*'
+    override_path: ../../../

examples/relay_chn_single/main/relay_chn_single_main.c

@@ -0,0 +1,290 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include <stdio.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_err.h"
+#include "esp_log.h"
+#include "esp_check.h"
+#include "driver/gpio.h"
+#include "nvs.h"
+#include "nvs_flash.h"
+#include "button_gpio.h"
+#include "iot_button.h"
+#include "led_indicator.h"
+#include "relay_chn.h"
+
+static const char *TAG = "RELAY_CHN_SINGLE_EXAMPLE";
+
+/**
+ * @brief LED indicator modes for different states.
+ */
+typedef enum {
+    INDICATOR_MODE_OK,          /*!< OK/Success indication */
+    INDICATOR_MODE_FAIL,        /*!< Fail/Error indication */
+    INDICATOR_MODE_TILTING,     /*!< Tilting operation in progress */
+    INDICATOR_MODE_RUNNING,     /*!< Full run operation in progress */
+    INDICATOR_MODE_MAX          /*!< Maximum number of indicator modes */
+} indicator_mode_t;
+
+/** @brief Blink pattern for OK/Success indication. */
+static const blink_step_t indc_mode_ok[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 100},    // step1: turn on LED 100 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 50},    // step2: turn off LED 50 ms
+    {LED_BLINK_HOLD, LED_STATE_ON, 100},    // step3: turn on LED 100 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 50},    // step4: turn off LED 50 ms
+    {LED_BLINK_STOP, 0, 0},                 // step5: stop blink (off)
+};
+
+/** @brief Blink pattern for Fail/Error indication. */
+static const blink_step_t indc_mode_fail[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 1000},    // step1: turn on LED 1000 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 500},    // step2: turn off LED 500 ms
+    {LED_BLINK_STOP, 0, 0},                 // step4: stop blink (off)
+};
+
+/** @brief Blink pattern for full run operation. */
+static const blink_step_t indc_mode_running[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 300},    // step1: turn on LED 300 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 100},   // step2: turn off LED 100 ms
+    {LED_BLINK_LOOP, 0, 0},                 // step3: loop from step1
+};
+
+/** @brief Blink pattern for tilting operation. */
+static const blink_step_t indc_mode_tilting[] = {
+    {LED_BLINK_HOLD, LED_STATE_ON, 100},    // step1: turn on LED 100 ms
+    {LED_BLINK_HOLD, LED_STATE_OFF, 50},    // step2: turn off LED 50 ms
+    {LED_BLINK_LOOP, 0, 0},                 // step3: loop from step1
+};
+
+/** @brief Array of LED indicator blink patterns. */
+blink_step_t const *led_indicator_modes[] = {
+    [INDICATOR_MODE_OK]         = indc_mode_ok,
+    [INDICATOR_MODE_FAIL]       = indc_mode_fail,
+    [INDICATOR_MODE_RUNNING]    = indc_mode_running,
+    [INDICATOR_MODE_TILTING]    = indc_mode_tilting,
+    [INDICATOR_MODE_MAX]        = NULL,
+};
+
+/** @brief Handle for the LED indicator. */
+static led_indicator_handle_t indicator = NULL;
+
+/**
+ * @brief Initializes the buttons for user interaction.
+ *
+ * This function configures and creates GPIO buttons for UP, DOWN, and STOP
+ * operations. It also registers callbacks for single-click and long-press
+ * events to control the relay channel.
+ *
+ * @return esp_err_t
+ *      - ESP_OK: Success
+ *      - Others: Fail
+ */
+static esp_err_t init_buttons(void);
+
+/**
+ * @brief Initializes the LED indicator.
+ *
+ * This function configures and creates the LED indicator used to provide
+ * visual feedback on the relay channel's status.
+ *
+ * @return esp_err_t
+ *      - ESP_OK: Success
+ *      - ESP_FAIL: Fail
+ */
+static esp_err_t init_led_indicator(void);
+
+/**
+ * @brief Event listener for relay channel state changes to control the LED indicator.
+ */
+static void example_event_listener_1(uint8_t ch, relay_chn_state_t old_state, relay_chn_state_t new_state);
+
+/**
+ * @brief Event listener for relay channel state changes to log the state transition.
+ */
+static void example_event_listener_2(uint8_t ch, relay_chn_state_t old_state, relay_chn_state_t new_state);
+
+void app_main(void)
+{
+    const uint8_t gpio_map[] = { 4, 5 };
+    const uint8_t gpio_count = sizeof(gpio_map) / sizeof(gpio_map[0]);
+
+    ESP_LOGI(TAG, "Initializing relay channel");
+    ESP_ERROR_CHECK(relay_chn_create(gpio_map, gpio_count));
+    ESP_ERROR_CHECK(relay_chn_register_listener(example_event_listener_1));
+    ESP_ERROR_CHECK(relay_chn_register_listener(example_event_listener_2));
+
+    ESP_LOGI(TAG, "Initializing buttons");
+    ESP_ERROR_CHECK(init_buttons());
+    ESP_LOGI(TAG, "Initializing LED indicator");
+    ESP_ERROR_CHECK(init_led_indicator());
+
+    ESP_LOGI(TAG, "Relay Channel Single Example is ready to operate");
+
+    // Indicate init was successful
+    led_indicator_start(indicator, INDICATOR_MODE_OK);
+}
+
+static void on_click_up(void *arg, void *data)
+{
+    relay_chn_run_forward();
+}
+
+static void on_click_down(void *arg, void *data)
+{
+    relay_chn_run_reverse();
+}
+
+static void on_click_stop(void *arg, void *data)
+{
+    relay_chn_stop();
+}
+
+static void on_click_flip(void *arg, void *data)
+{
+    relay_chn_flip_direction();
+    led_indicator_start(indicator, INDICATOR_MODE_OK);
+}
+
+static void on_click_tilt_up(void *arg, void *data)
+{
+    relay_chn_tilt_forward();
+}
+
+static void on_click_tilt_down(void *arg, void *data)
+{
+    relay_chn_tilt_reverse();
+}
+
+static void on_release_tilt(void *arg, void *data)
+{
+    relay_chn_tilt_stop();
+}
+
+static void example_event_listener_1(uint8_t ch, relay_chn_state_t old_state, relay_chn_state_t new_state)
+{
+    ESP_LOGI(TAG, "example_event_listener_1: Defining new indicator mode for #%d and state change from %d to %d", ch, old_state, new_state);
+    switch (new_state) {
+        case RELAY_CHN_STATE_FORWARD:
+        case RELAY_CHN_STATE_REVERSE:
+            led_indicator_start(indicator, INDICATOR_MODE_RUNNING);
+            break;
+
+        case RELAY_CHN_STATE_STOPPED:
+        case RELAY_CHN_STATE_IDLE:
+            if (old_state == RELAY_CHN_STATE_FORWARD || old_state == RELAY_CHN_STATE_REVERSE) {
+                led_indicator_stop(indicator, INDICATOR_MODE_RUNNING);
+                // Make sure the indicator turned off
+                led_indicator_set_on_off(indicator, false);
+            }
+            else if (old_state == RELAY_CHN_STATE_TILT_FORWARD || old_state == RELAY_CHN_STATE_TILT_REVERSE) {
+                led_indicator_stop(indicator, INDICATOR_MODE_TILTING);
+                // Make sure the indicator turned off
+                led_indicator_set_on_off(indicator, false);
+            }
+            break;
+
+        case RELAY_CHN_STATE_TILT_FORWARD:
+        case RELAY_CHN_STATE_TILT_REVERSE:
+            led_indicator_start(indicator, INDICATOR_MODE_TILTING);
+            break;
+
+        default: // No-op
+    }
+}
+
+static void example_event_listener_2(uint8_t ch, relay_chn_state_t old_state, relay_chn_state_t new_state)
+{
+    ESP_LOGI(TAG, "example_event_listener_2: State change for #%d, from %s to %s",
+                ch, relay_chn_state_to_str(old_state), relay_chn_state_to_str(new_state));
+}
+
+static esp_err_t init_buttons()
+{
+    esp_err_t ret;
+    button_config_t btn_cfg = {0};
+
+    uint8_t active_level = CONFIG_EXAMPLE_RLCHN_BTN_ACTIVE_LEVEL_LOW ? 0 : 1;
+
+    button_gpio_config_t btn_gpio_ccfg = {
+        .gpio_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_BTN_UP_IO_NUM,
+        .active_level = active_level
+    };
+
+    ESP_LOGI(TAG, "Initializing buttons with active level: %u", active_level);
+    button_handle_t btn_up = NULL, btn_down = NULL, btn_stop = NULL;
+    // --- Create buttons ---
+    ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_ccfg, &btn_up);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create UP button");
+    ESP_RETURN_ON_FALSE(btn_up != NULL, ret, TAG, "Failed to create UP button");
+
+    btn_gpio_ccfg.gpio_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_BTN_DOWN_IO_NUM;
+    ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_ccfg, &btn_down);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create DOWN button");
+    ESP_RETURN_ON_FALSE(btn_down != NULL, ret, TAG, "Failed to create DOWN button");
+    
+    btn_gpio_ccfg.gpio_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_BTN_STOP_IO_NUM;
+    ret = iot_button_new_gpio_device(&btn_cfg, &btn_gpio_ccfg, &btn_stop);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to create STOP button");
+    ESP_RETURN_ON_FALSE(btn_stop != NULL, ret, TAG, "Failed to create STOP button");
+    // --- Create buttons ---
+
+    // --- Register button callbacks ---
+    ESP_LOGI(TAG, "Setting up button callbacks. Configured long press time: %d ms", CONFIG_EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS);
+    button_event_args_t btn_event_args = {
+        .long_press.press_time = CONFIG_EXAMPLE_RLCHN_BTN_LONG_PRESS_TIME_MS
+    };
+    // --- Register UP and TILT_UP operations on UP button ---
+    ret = iot_button_register_cb(btn_up, BUTTON_SINGLE_CLICK, NULL, on_click_up, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register UP button click callback");
+    ret = iot_button_register_cb(btn_up, BUTTON_LONG_PRESS_START, &btn_event_args, on_click_tilt_up, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_UP button press callback");
+    ret = iot_button_register_cb(btn_up, BUTTON_LONG_PRESS_UP, NULL, on_release_tilt, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_UP button release callback");
+    
+    // --- Register DOWN and TILT_DOWN operations on DOWN button ---
+    ret = iot_button_register_cb(btn_down, BUTTON_SINGLE_CLICK, NULL, on_click_down, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register DOWN button click callback");
+    ret = iot_button_register_cb(btn_down, BUTTON_LONG_PRESS_START, &btn_event_args, on_click_tilt_down, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_DOWN button press callback");
+    ret = iot_button_register_cb(btn_down, BUTTON_LONG_PRESS_UP, NULL, on_release_tilt, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register TILT_DOWN button release callback");
+    
+    // --- Register STOP and FLIP operations on STOP ---
+    ret = iot_button_register_cb(btn_stop, BUTTON_SINGLE_CLICK, NULL, on_click_stop, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register STOP button click callback");
+    ret = iot_button_register_cb(btn_stop, BUTTON_LONG_PRESS_START, &btn_event_args, on_click_flip, NULL);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to register FLIP button press callback");
+
+    return ESP_OK;
+}
+
+static esp_err_t init_led_indicator()
+{
+    const gpio_num_t indicator_io_num = (gpio_num_t) CONFIG_EXAMPLE_RLCHN_LED_INDICATOR_IO_NUM;
+    gpio_reset_pin(indicator_io_num); // Clear the output buffers
+
+    led_indicator_gpio_config_t led_indicator_gpio_cfg = {
+        .gpio_num = indicator_io_num,
+        .is_active_level_high = true
+    };
+
+    led_indicator_config_t led_indicator_cfg = {
+        .mode = LED_GPIO_MODE,
+        .led_indicator_gpio_config = &led_indicator_gpio_cfg,
+        .blink_lists = led_indicator_modes,
+        .blink_list_num = INDICATOR_MODE_MAX
+    };
+    
+    indicator = led_indicator_create(&led_indicator_cfg);
+    if (!indicator) {
+        ESP_LOGE(TAG, "Failed to create LED indicator");
+        return ESP_FAIL;
+    }
+
+    return ESP_OK;
+}

examples/relay_chn_single/sdkconfig.defaults

@@ -0,0 +1,9 @@
+# Halt on panic
+CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT=y
+
+# Relay Channel Configs
+CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT=y
+# Keep this as short as possible for example purposes
+CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC=5
+CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC=20
+CONFIG_RELAY_CHN_ENABLE_TILTING=y

idf_component.yml

@@ -1,6 +1,12 @@
-name: relay_chn
+version: "1.0.0"
-version: "0.5.0"
+description: "Relay channel driver for bipolar motors."
-description: "Custom component for relay channel control"
 license: "MIT"
 url: "https://git.kozmotronik.com.tr/KozmotronikTech/relay_chn"
 repository: "https://git.kozmotronik.com.tr/KozmotronikTech/relay_chn.git"
+dependencies:
+  idf: ">=5.0"
+examples:
+  - path: examples/relay_chn_single
+  - path: examples/relay_chn_multi
+files:
+  use_gitignore: true

include/relay_chn.h

@@ -63,6 +63,26 @@ esp_err_t relay_chn_register_listener(relay_chn_state_listener_t listener);
  */
 void relay_chn_unregister_listener(relay_chn_state_listener_t listener);
 
+/**
+ * @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_to_str(relay_chn_state_t state);
+
+#if CONFIG_RELAY_CHN_ENABLE_TILTING
+/**
+ * @brief Get the default tilting sensitivity for the relay channel.
+ *
+ * This function retrieves the default sensitivity for the relay channel's automatic
+ * tilting mechanism.
+ *
+ * @return Sensitivity value in percentage: 0 - 100%.
+ */
+uint8_t relay_chn_tilt_get_default_sensitivity(void);
+#endif
+
 #if CONFIG_RELAY_CHN_COUNT > 1
 /**
  * @brief Get the state of the specified relay channel.

include/relay_chn_adapter.h

@@ -13,6 +13,36 @@
 extern "C" {
 #endif
 
+/**
+ * @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
+ */
+extern esp_err_t relay_chn_notify_add_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.
+ */
+extern void relay_chn_notify_remove_listener(relay_chn_state_listener_t listener);
+
+static inline esp_err_t relay_chn_register_listener(relay_chn_state_listener_t listener)
+{
+    return relay_chn_notify_add_listener(listener);
+}
+
+static inline void relay_chn_unregister_listener(relay_chn_state_listener_t listener)
+{
+    relay_chn_notify_remove_listener(listener);
+}
+
 #if CONFIG_RELAY_CHN_COUNT > 1
 /**
  * @brief Get the current state of a relay channel.

private_include/relay_chn_core.h

@@ -93,14 +93,6 @@ esp_err_t relay_chn_start_esp_timer_once(esp_timer_handle_t esp_timer, uint32_t
  */
 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 CONFIG_RELAY_CHN_COUNT > 1
 /**
  * @brief Check if the provided channel ID is valid.

private_include/relay_chn_notify.h

@@ -0,0 +1,51 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include <stdint.h>
+#include "relay_chn_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Init the notify module.
+ *
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_ERR_NO_MEM: Not enough memory to create notify queue
+ */
+esp_err_t relay_chn_notify_init(void);
+
+/**
+ * @brief Deinit the notify module.
+ *
+ * This function cleans up resources used by the notify module.
+ */
+void relay_chn_notify_deinit(void);
+
+/**
+ * @brief Notify all registered listeners about a state change.
+ *
+ * This function sends a state change event to an internal queue, which will then
+ * be processed by a dedicated task to notify all registered listeners. This
+ * function is typically called internally by the relay channel core logic.
+ *
+ * @param chn_id The ID of the relay channel whose state has changed.
+ * @param old_state The previous state of the relay channel.
+ * @param new_state The new state of the relay channel.
+ */
+esp_err_t relay_chn_notify_state_change(uint8_t chn_id,
+                                        relay_chn_state_t old_state,
+                                        relay_chn_state_t new_state);
+
+#ifdef __cplusplus
+}
+#endif
+

private_include/relay_chn_nvs.h

@@ -32,6 +32,10 @@ esp_err_t relay_chn_nvs_init(void);
  *
  * @param[in] ch Channel number.
  * @param[in] direction Direction to store.
+ *
+ * @note This operation is asynchronous. The value is queued to be written
+ *       by a background task. A subsequent `get` call may not immediately
+ *       reflect the new value.
  * @return ESP_OK on success, error code otherwise.
  */
 esp_err_t relay_chn_nvs_set_direction(uint8_t ch, relay_chn_direction_t direction);
@@ -41,16 +45,21 @@ esp_err_t relay_chn_nvs_set_direction(uint8_t ch, relay_chn_direction_t directio
  *
  * @param[in] ch Channel number.
  * @param[out] direction Pointer to store retrieved direction.
+ * @param[in] default_val Default value to use if not found in NVS.
  * @return ESP_OK on success, error code otherwise.
  */
-esp_err_t relay_chn_nvs_get_direction(uint8_t ch, relay_chn_direction_t *direction);
+esp_err_t relay_chn_nvs_get_direction(uint8_t ch, relay_chn_direction_t *direction, relay_chn_direction_t default_val);
 
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
 /**
  * @brief Store relay channel run limit in NVS.
  *
  * @param[in] ch Channel number.
- * @param[in] direction Run limit value to store.
+ * @param[in] limit_sec Run limit value to store.
+ *
+ * @note This operation is asynchronous. The value is queued to be written
+ *       by a background task. A subsequent `get` call may not immediately
+ *       reflect the new value.
  * @return ESP_OK on success, error code otherwise.
  */
 esp_err_t relay_chn_nvs_set_run_limit(uint8_t ch, uint16_t limit_sec);
@@ -59,10 +68,11 @@ esp_err_t relay_chn_nvs_set_run_limit(uint8_t ch, uint16_t limit_sec);
  * @brief Retrieve relay channel run limit from NVS.
  *
  * @param[in] ch Channel number.
- * @param[out] direction Pointer to store retrieved run limit value.
+ * @param[out] limit_sec Pointer to store retrieved run limit value.
+ * @param[in] default_val Default value to use if not found in NVS.
  * @return ESP_OK on success, error code otherwise.
  */
-esp_err_t relay_chn_nvs_get_run_limit(uint8_t ch, uint16_t *limit_sec);
+esp_err_t relay_chn_nvs_get_run_limit(uint8_t ch, uint16_t *limit_sec, uint16_t default_val);
 #endif // CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT == 1
 
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
@@ -71,6 +81,10 @@ esp_err_t relay_chn_nvs_get_run_limit(uint8_t ch, uint16_t *limit_sec);
  *
  * @param[in] ch Channel number.
  * @param[in] sensitivity Sensitivity value to store.
+ *
+ * @note This operation is asynchronous. The value is queued to be written
+ *       by a background task. A subsequent `get` call may not immediately
+ *       reflect the new value.
  * @return ESP_OK on success, error code otherwise.
  */
 esp_err_t relay_chn_nvs_set_tilt_sensitivity(uint8_t ch, uint8_t sensitivity);
@@ -80,15 +94,20 @@ esp_err_t relay_chn_nvs_set_tilt_sensitivity(uint8_t ch, uint8_t sensitivity);
  *
  * @param[in] ch Channel number.
  * @param[out] sensitivity Pointer to store retrieved sensitivity.
+ * @param[in] default_val Default value to use if not found in NVS.
  * @return ESP_OK on success, error code otherwise.
  */
-esp_err_t relay_chn_nvs_get_tilt_sensitivity(uint8_t ch, uint8_t *sensitivity);
+esp_err_t relay_chn_nvs_get_tilt_sensitivity(uint8_t ch, uint8_t *sensitivity, uint8_t default_val);
 
 /**
  * @brief Store tilt counters in NVS.
  *
  * @param[in] ch Channel number.
  * @param[in] tilt_count Tilt count value.
+ *
+ * @note This operation is asynchronous. The value is queued to be written
+ *       by a background task. A subsequent `get` call may not immediately
+ *       reflect the new value.
  * @return ESP_OK on success, error code otherwise.
  */
 esp_err_t relay_chn_nvs_set_tilt_count(uint8_t ch, uint16_t tilt_count);
@@ -98,15 +117,17 @@ esp_err_t relay_chn_nvs_set_tilt_count(uint8_t ch, uint16_t tilt_count);
  *
  * @param[in] ch Channel number.
  * @param[out] tilt_count Pointer to store tilt count.
+ * @param[in] default_val Default value to use if not found in NVS.
  * @return ESP_OK on success, error code otherwise.
  */
-esp_err_t relay_chn_nvs_get_tilt_count(uint8_t ch, uint16_t *tilt_count);
+esp_err_t relay_chn_nvs_get_tilt_count(uint8_t ch, uint16_t *tilt_count, uint16_t default_val);
 #endif // CONFIG_RELAY_CHN_ENABLE_TILTING
 
 /**
  * @brief Erase all keys in the NVS namespace.
  *
  * This function will erase all key-value pairs in the NVS namespace used by relay channels.
+ * It will also flush all pending operations in the queue.
  *
  * @return ESP_OK on success, error code otherwise.
  */
@@ -114,10 +135,8 @@ esp_err_t relay_chn_nvs_erase_all(void);
 
 /**
  * @brief Deinitialize NVS storage for relay channels.
- *
- * @return ESP_OK on success, error code otherwise.
  */
-esp_err_t relay_chn_nvs_deinit(void);
+void relay_chn_nvs_deinit(void);
 
 #ifdef __cplusplus
 }

scripts/run_tests.sh

@@ -10,7 +10,7 @@ if [[ -z "$IDF_PATH" ]]; then
 fi
 
 # ==== 2. Valid Modes and Defaults ====
-valid_test_tags=("core" "tilt" "listener" "all" "relay_chn" "nvs" "run_limit" "batch" "inertia" "direction" "auto" "sensitivity" "counter" "interrupt")
+valid_test_tags=("core" "tilt" "notify" "all" "relay_chn" "nvs" "run_limit" "batch" "inertia" "direction" "auto" "sensitivity" "counter" "interrupt")
 valid_test_profiles=("run_limit" "tilt" "nvs" "nvs_custom" "multi" "full_single" "full_multi")
 arg_tag="all" # Default to 'all' if no tag specified
 arg_profile="full_multi" # Default to 'full_multi' if no profile specified
@@ -24,7 +24,7 @@ print_help() {
     echo "This script builds and runs tests for the relay_chn component using QEMU."
     echo ""
     echo "Arguments:"
-    echo "  -t, --tag [relay_chn|core|tilt|listener|nvs|run_limit|batch|inertia|direction|auto|sensitivity|counter|interrupt|all]  Specify which test tag to run."
+    echo "  -t, --tag [relay_chn|core|tilt|notify|nvs|run_limit|batch|inertia|direction|auto|sensitivity|counter|interrupt|all]  Specify which test tag to run."
     echo ""
     echo "  If no tag is specified, it defaults to 'all'."
     echo ""
@@ -98,8 +98,7 @@ fi
 script_dir=$(dirname "$(readlink -f "$0")")
 project_root=$(dirname "$script_dir")
 
-echo "🔍 Searching for 'test_apps' directory in '$project_root'..."
+test_apps_dir="${project_root}/test_apps"
-test_apps_dir=$(find "$project_root" -type d -name "test_apps" | head -n 1)
 
 if [[ -z "$test_apps_dir" || ! -d "$test_apps_dir" ]]; then
     echo "❌ 'test_apps' directory not found within the project root: '$project_root'"
@@ -107,7 +106,7 @@ if [[ -z "$test_apps_dir" || ! -d "$test_apps_dir" ]]; then
     exit 1
 fi
 
-echo "✅ Found 'test_apps' at: $test_apps_dir"
+echo "⏳ Current time is: $(date +"%Y-%m-%d %H:%M:%S")"
 echo "🧪 Test mode: $arg_tag | Profile: $arg_profile"
 echo "🧹 Clean: $arg_clean | 📄 Log: $arg_log"
 

scripts/run_tests_all_profiles.sh

@@ -14,10 +14,15 @@ project_root=$(dirname "$script_dir")
 echo "Script dir: ${script_dir}"
 echo "Project root: ${project_root}"
 
-echo "🔍 Searching for 'test_apps' directory in '$project_root'..."
+test_apps_dir="${project_root}/test_apps"
-test_apps_dir=$(find "$project_root" -type d -name "test_apps" | head -n 1)
 echo "test_apps dir: ${test_apps_dir}"
 
+if [[ -z "$test_apps_dir" || ! -d "$test_apps_dir" ]]; then
+    echo "❌ 'test_apps' directory not found within the project root: '$project_root'"
+    echo "   Please ensure the script is in a 'scripts' directory and 'test_apps' is a sibling."
+    exit 1
+fi
+
 # Execute tests for all profiles
 mapfile -t profiles < <(find "${test_apps_dir}/profiles" -maxdepth 1 -type f)
 

src/relay_chn_core.c

@@ -11,6 +11,7 @@
 #include "relay_chn_output.h"
 #include "relay_chn_run_info.h"
 #include "relay_chn_ctl.h"
+#include "relay_chn_notify.h"
 
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
 #include "relay_chn_tilt.h"
@@ -26,15 +27,6 @@
 static const char *TAG = "RELAY_CHN_CORE";
 
 
-// Structure to hold a listener entry in the linked list.
-typedef struct relay_chn_listener_entry_type {
-    relay_chn_state_listener_t listener;  /*!< The listener function pointer */
-    ListItem_t list_item;                 /*!< FreeRTOS list item */
-} relay_chn_listener_entry_t;
-
-// The list that holds references to the registered listeners.
-static List_t relay_chn_listener_list;
-
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
 /*
  * Run limit timer callback immediately dispatches a STOP command for the
@@ -125,9 +117,9 @@ esp_err_t relay_chn_create(const uint8_t* gpio_map, uint8_t gpio_count)
     ESP_RETURN_ON_ERROR(ret, TAG, "Failed to initialize tilt feature");
 #endif
 
-    // Init the state listener list
+    // Initialize the notify feature
-    vListInitialise(&relay_chn_listener_list);
+    ret = relay_chn_notify_init();
-
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to initialize notify feature");
     return ret;
 }
 
@@ -136,96 +128,15 @@ void relay_chn_destroy(void)
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
     relay_chn_tilt_deinit();
 #endif
+    relay_chn_notify_deinit();
     relay_chn_ctl_deinit();
     relay_chn_output_deinit();
 
 #if CONFIG_RELAY_CHN_ENABLE_NVS
     relay_chn_nvs_deinit();
 #endif
-
-    // Free the listeners
-    while (listCURRENT_LIST_LENGTH(&relay_chn_listener_list) > 0) {
-        ListItem_t *pxItem = listGET_HEAD_ENTRY(&relay_chn_listener_list);
-        relay_chn_listener_entry_t *entry = listGET_LIST_ITEM_OWNER(pxItem);
-        uxListRemove(pxItem);
-        free(entry);
-    }
 }
 
-/**
- * @brief Find a listener entry in the list by its function pointer.
- *
- * This function replaces the old index-based search and is used to check
- * for the existence of a listener before registration or for finding it
- * during unregistration.
- *
- * @param listener The listener function pointer to find.
- * @return Pointer to the listener entry if found, otherwise NULL.
- */
-static relay_chn_listener_entry_t* find_listener_entry(relay_chn_state_listener_t listener)
-{
-    // Iterate through the linked list of listeners
-    for (ListItem_t *pxListItem = listGET_HEAD_ENTRY(&relay_chn_listener_list);
-         pxListItem != listGET_END_MARKER(&relay_chn_listener_list);
-         pxListItem = listGET_NEXT(pxListItem)) {
-        
-        relay_chn_listener_entry_t *entry = (relay_chn_listener_entry_t *) listGET_LIST_ITEM_OWNER(pxListItem);
-        if (entry->listener == listener) {
-            // Found the listener, return the entry
-            return entry;
-        }
-    }
-
-    // Listener was not found in the list
-    return NULL;
-}
-
-esp_err_t relay_chn_register_listener(relay_chn_state_listener_t listener)
-{
-    ESP_RETURN_ON_FALSE(listener, ESP_ERR_INVALID_ARG, TAG, "Listener cannot be NULL");
-
-    // Check for duplicates
-    if (find_listener_entry(listener) != NULL) {
-        ESP_LOGD(TAG, "Listener %p already registered", listener);
-        return ESP_OK;
-    }
-
-    // Allocate memory for the new listener entry
-    relay_chn_listener_entry_t *entry = malloc(sizeof(relay_chn_listener_entry_t));
-    ESP_RETURN_ON_FALSE(entry, ESP_ERR_NO_MEM, TAG, "Failed to allocate memory for listener");
-
-    // Initialize and insert the new listener
-    entry->listener = listener;
-    vListInitialiseItem(&(entry->list_item));
-    listSET_LIST_ITEM_OWNER(&(entry->list_item), (void *)entry);
-    vListInsertEnd(&relay_chn_listener_list, &(entry->list_item));
-
-    ESP_LOGD(TAG, "Registered listener %p", listener);
-    return ESP_OK;
-}
-
-void relay_chn_unregister_listener(relay_chn_state_listener_t listener)
-{
-    if (listener == NULL)
-    {
-        ESP_LOGD(TAG, "Cannot unregister a NULL listener.");
-        return;
-    }
-
-    // Find the listener entry in the list
-    relay_chn_listener_entry_t *entry = find_listener_entry(listener);
-
-    if (entry != NULL) {
-        // Remove the item from the list and free the allocated memory
-        uxListRemove(&(entry->list_item));
-        free(entry);
-        ESP_LOGD(TAG, "Unregistered listener %p", listener);
-    } else {
-        ESP_LOGD(TAG, "Listener %p not found for unregistration.", listener);
-    }
-}
-
-
 esp_err_t relay_chn_start_esp_timer_once(esp_timer_handle_t esp_timer, uint32_t time_ms)
 {
     esp_err_t ret = esp_timer_start_once(esp_timer, time_ms * 1000);
@@ -251,16 +162,7 @@ void relay_chn_update_state(relay_chn_ctl_t *chn_ctl, relay_chn_state_t new_stat
 
     chn_ctl->state = new_state;
 
-    // Iterate through the linked list of listeners and notify them.
+    relay_chn_notify_state_change(chn_ctl->id, old_state, new_state);
-    for (ListItem_t *pxListItem = listGET_HEAD_ENTRY(&relay_chn_listener_list);
-         pxListItem != listGET_END_MARKER(&relay_chn_listener_list);
-         pxListItem = listGET_NEXT(pxListItem)) {
-        relay_chn_listener_entry_t *entry = (relay_chn_listener_entry_t *) listGET_LIST_ITEM_OWNER(pxListItem);
-        if (entry && entry->listener) {
-            // Emit the state change to the listeners
-            entry->listener(chn_ctl->id, old_state, new_state);
-        }
-    }
 }
 
 static void relay_chn_execute_idle(relay_chn_ctl_t *chn_ctl);
@@ -314,8 +216,8 @@ void relay_chn_issue_cmd(relay_chn_ctl_t* chn_ctl, relay_chn_cmd_t cmd)
     }
 
     if (cmd == RELAY_CHN_CMD_STOP) {
-        if (chn_ctl->state == RELAY_CHN_STATE_STOPPED) {
+        if (chn_ctl->state == RELAY_CHN_STATE_STOPPED || chn_ctl->state == RELAY_CHN_STATE_IDLE) {
-            return; // Do nothing if already stopped
+            return; // Do nothing if already stopped or idle
         }
         // If the command is STOP, issue it immediately
         relay_chn_dispatch_cmd(chn_ctl, cmd);
@@ -464,9 +366,6 @@ static void relay_chn_execute_stop(relay_chn_ctl_t *chn_ctl)
 {
     relay_chn_stop_prv(chn_ctl);
 
-    // If there is any pending command, cancel it since the STOP command is issued right after it
-    // chn_ctl->pending_cmd = RELAY_CHN_CMD_NONE;
-
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
     esp_timer_stop(chn_ctl->run_limit_timer);
 #endif
@@ -480,8 +379,7 @@ static void relay_chn_execute_stop(relay_chn_ctl_t *chn_ctl)
         chn_ctl->pending_cmd = RELAY_CHN_CMD_IDLE;
         relay_chn_start_timer_or_idle(chn_ctl, chn_ctl->inertia_timer, CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS, "idle");
     } else {
-        // If the channel was not running one of the run or fwd, issue a free command immediately
+        // If the channel was not running forward or reverse, issue a free command immediately
-        // relay_chn_dispatch_cmd(chn_ctl, RELAY_CHN_CMD_IDLE);
         relay_chn_execute_idle(chn_ctl);
     }
 }
@@ -573,7 +471,7 @@ char *relay_chn_cmd_str(relay_chn_cmd_t cmd)
     }
 }
 
-char *relay_chn_state_str(relay_chn_state_t state)
+char *relay_chn_state_to_str(relay_chn_state_t state)
 {
     switch (state) {
         case RELAY_CHN_STATE_IDLE:

src/relay_chn_ctl_multi.c

@@ -5,6 +5,7 @@
  */
 
 #include "esp_check.h"
+#include "relay_chn.h"
 #include "relay_chn_priv_types.h"
 #include "relay_chn_core.h"
 #include "relay_chn_ctl.h"
@@ -16,7 +17,7 @@
 
 static const char *TAG = "RELAY_CHN_CTL";
 
-static relay_chn_ctl_t chn_ctls[CONFIG_RELAY_CHN_COUNT];
+static relay_chn_ctl_t s_chn_ctls[CONFIG_RELAY_CHN_COUNT];
 
 
 esp_err_t relay_chn_ctl_init(relay_chn_output_t *outputs, relay_chn_run_info_t *run_infos)
@@ -24,7 +25,7 @@ esp_err_t relay_chn_ctl_init(relay_chn_output_t *outputs, relay_chn_run_info_t *
     // Initialize all relay channels
     esp_err_t ret;
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_ctl_t* chn_ctl = &chn_ctls[i];
+        relay_chn_ctl_t* chn_ctl = &s_chn_ctls[i];
         relay_chn_output_t* output = &outputs[i];
         relay_chn_run_info_t* run_info = &run_infos[i];
 
@@ -38,10 +39,8 @@ esp_err_t relay_chn_ctl_init(relay_chn_output_t *outputs, relay_chn_run_info_t *
         uint16_t run_limit_sec = CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC;
 #if CONFIG_RELAY_CHN_ENABLE_NVS
         // Load run limit value from NVS
-        ret = relay_chn_nvs_get_run_limit(chn_ctl->id, &run_limit_sec);
+        ret = relay_chn_nvs_get_run_limit(chn_ctl->id, &run_limit_sec, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC);
-        if (ret != ESP_OK && ret != ESP_ERR_NVS_NOT_FOUND) {
+        ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load run limit from NVS for #%d with error: %s", i, esp_err_to_name(ret));
-            ESP_LOGE(TAG, "Failed to load run limit from NVS for channel %d with error: %s", i, esp_err_to_name(ret));
-        }
 #endif
         chn_ctl->run_limit_sec = run_limit_sec;
         ret = relay_chn_init_run_limit_timer(chn_ctl);
@@ -56,7 +55,7 @@ esp_err_t relay_chn_ctl_init(relay_chn_output_t *outputs, relay_chn_run_info_t *
 void relay_chn_ctl_deinit()
 {
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_ctl_t* chn_ctl = &chn_ctls[i];
+        relay_chn_ctl_t* chn_ctl = &s_chn_ctls[i];
         if (chn_ctl->inertia_timer != NULL) {
             esp_timer_delete(chn_ctl->inertia_timer);
             chn_ctl->inertia_timer = NULL;
@@ -73,7 +72,7 @@ void relay_chn_ctl_deinit()
 relay_chn_state_t relay_chn_ctl_get_state(uint8_t chn_id)
 {
     return relay_chn_is_channel_id_valid(chn_id) ?
-           chn_ctls[chn_id].state : RELAY_CHN_STATE_UNDEFINED;
+           s_chn_ctls[chn_id].state : RELAY_CHN_STATE_UNDEFINED;
 }
 
 esp_err_t relay_chn_ctl_get_state_all(relay_chn_state_t *states)
@@ -86,7 +85,7 @@ esp_err_t relay_chn_ctl_get_state_all(relay_chn_state_t *states)
             ESP_LOGW(TAG, "get_state_all: States have been copied until channel %d since states[%d] is NULL", i, i);
             break;
         }
-        *dest_state = chn_ctls[i].state;
+        *dest_state = s_chn_ctls[i].state;
     }
     return ESP_OK;
 }
@@ -94,22 +93,22 @@ esp_err_t relay_chn_ctl_get_state_all(relay_chn_state_t *states)
 char *relay_chn_ctl_get_state_str(uint8_t chn_id)
 {
     return relay_chn_is_channel_id_valid(chn_id)
-           ? relay_chn_state_str(chn_ctls[chn_id].state)
+           ? relay_chn_state_to_str(s_chn_ctls[chn_id].state)
-           : relay_chn_state_str(RELAY_CHN_STATE_UNDEFINED);
+           : relay_chn_state_to_str(RELAY_CHN_STATE_UNDEFINED);
 }
 
 
 static void relay_chn_ctl_issue_cmd_on_all_channels(relay_chn_cmd_t cmd)
 {
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_issue_cmd(&chn_ctls[i], cmd);
+        relay_chn_issue_cmd(&s_chn_ctls[i], cmd);
     }
 }
 
 void relay_chn_ctl_run_forward(uint8_t chn_id)
 {
     if (relay_chn_is_channel_id_valid(chn_id))
-        relay_chn_issue_cmd(&chn_ctls[chn_id], RELAY_CHN_CMD_FORWARD);
+        relay_chn_issue_cmd(&s_chn_ctls[chn_id], RELAY_CHN_CMD_FORWARD);
 }
 
 void relay_chn_ctl_run_forward_all()
@@ -120,7 +119,7 @@ void relay_chn_ctl_run_forward_all()
 void relay_chn_ctl_run_reverse(uint8_t chn_id)
 {
     if (relay_chn_is_channel_id_valid(chn_id))
-        relay_chn_issue_cmd(&chn_ctls[chn_id], RELAY_CHN_CMD_REVERSE);
+        relay_chn_issue_cmd(&s_chn_ctls[chn_id], RELAY_CHN_CMD_REVERSE);
 }
 
 void relay_chn_ctl_run_reverse_all()
@@ -131,7 +130,7 @@ void relay_chn_ctl_run_reverse_all()
 void relay_chn_ctl_stop(uint8_t chn_id)
 {
     if (relay_chn_is_channel_id_valid(chn_id))
-        relay_chn_issue_cmd(&chn_ctls[chn_id], RELAY_CHN_CMD_STOP);
+        relay_chn_issue_cmd(&s_chn_ctls[chn_id], RELAY_CHN_CMD_STOP);
 }
 
 void relay_chn_ctl_stop_all()
@@ -142,7 +141,7 @@ void relay_chn_ctl_stop_all()
 void relay_chn_ctl_flip_direction(uint8_t chn_id)
 {
     if (relay_chn_is_channel_id_valid(chn_id))
-        relay_chn_issue_cmd(&chn_ctls[chn_id], RELAY_CHN_CMD_FLIP);    
+        relay_chn_issue_cmd(&s_chn_ctls[chn_id], RELAY_CHN_CMD_FLIP);
 }
 
 void relay_chn_ctl_flip_direction_all()
@@ -153,7 +152,7 @@ void relay_chn_ctl_flip_direction_all()
 relay_chn_direction_t relay_chn_ctl_get_direction(uint8_t chn_id)
 {
     return relay_chn_is_channel_id_valid(chn_id)
-           ? relay_chn_output_get_direction(chn_ctls[chn_id].output)
+           ? relay_chn_output_get_direction(s_chn_ctls[chn_id].output)
            : RELAY_CHN_DIRECTION_DEFAULT;
 }
 
@@ -167,7 +166,7 @@ esp_err_t relay_chn_ctl_get_direction_all(relay_chn_direction_t *directions)
             ESP_LOGW(TAG, "get_direction_all: Directions have been copied until channel %d since directions[%d] is NULL", i, i);
             break;
         }
-        *dest_direction = relay_chn_output_get_direction(chn_ctls[i].output);
+        *dest_direction = relay_chn_output_get_direction(s_chn_ctls[i].output);
     }
     return ESP_OK;
 }
@@ -175,7 +174,7 @@ esp_err_t relay_chn_ctl_get_direction_all(relay_chn_direction_t *directions)
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
 uint16_t relay_chn_ctl_get_run_limit(uint8_t chn_id)
 {
-    return relay_chn_is_channel_id_valid(chn_id) ? chn_ctls[chn_id].run_limit_sec : 0;
+    return relay_chn_is_channel_id_valid(chn_id) ? s_chn_ctls[chn_id].run_limit_sec : 0;
 }
 
 esp_err_t relay_chn_ctl_get_run_limit_all(uint16_t *limits_sec)
@@ -188,7 +187,7 @@ esp_err_t relay_chn_ctl_get_run_limit_all(uint16_t *limits_sec)
             ESP_LOGW(TAG, "get_run_limit_all: Run limits have been copied until channel %d since limits_sec[%d] is NULL", i, i);
             break;
         }
-        *dest_limit_sec = chn_ctls[i].run_limit_sec;
+        *dest_limit_sec = s_chn_ctls[i].run_limit_sec;
     }
     return ESP_OK;
 }
@@ -201,7 +200,7 @@ static void relay_chn_ctl_set_run_limit_common(uint8_t chn_id, uint16_t limit_se
     else if (limit_sec < CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC)
         limit_sec = CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC;
 
-    chn_ctls[chn_id].run_limit_sec = limit_sec;
+    s_chn_ctls[chn_id].run_limit_sec = limit_sec;
 
 #if CONFIG_RELAY_CHN_ENABLE_NVS
     relay_chn_nvs_set_run_limit(chn_id, limit_sec);
@@ -243,10 +242,10 @@ esp_err_t relay_chn_ctl_set_run_limit_all_with(uint16_t limit_sec)
 
 relay_chn_ctl_t *relay_chn_ctl_get(uint8_t chn_id)
 {
-    return relay_chn_is_channel_id_valid(chn_id) ? &chn_ctls[chn_id] : NULL;
+    return relay_chn_is_channel_id_valid(chn_id) ? &s_chn_ctls[chn_id] : NULL;
 }
 
 relay_chn_ctl_t *relay_chn_ctl_get_all(void)
 {
-    return chn_ctls;
+    return s_chn_ctls;
 }

src/relay_chn_ctl_single.c

@@ -5,6 +5,7 @@
  */
 
 #include "esp_check.h"
+#include "relay_chn.h"
 #include "relay_chn_priv_types.h"
 #include "relay_chn_core.h"
 #include "relay_chn_ctl.h"
@@ -14,47 +15,45 @@
 #include "relay_chn_nvs.h"
 #endif
 
-static const char *TAG = "RELAY_CHN_CTL";
+static const char *TAG __attribute__((unused)) = "RELAY_CHN_CTL";
 
-static relay_chn_ctl_t chn_ctl;
+static relay_chn_ctl_t s_chn_ctl;
 
 
 esp_err_t relay_chn_ctl_init(relay_chn_output_t *output, relay_chn_run_info_t *run_info)
 {
     // Initialize the relay channel
-    chn_ctl.id = 0; // Single channel, so ID is 0
+    s_chn_ctl.id = 0; // Single channel, so ID is 0
-    chn_ctl.state = RELAY_CHN_STATE_IDLE;
+    s_chn_ctl.state = RELAY_CHN_STATE_IDLE;
-    chn_ctl.pending_cmd = RELAY_CHN_CMD_NONE;
+    s_chn_ctl.pending_cmd = RELAY_CHN_CMD_NONE;
-    chn_ctl.output = output;
+    s_chn_ctl.output = output;
-    chn_ctl.run_info = run_info;
+    s_chn_ctl.run_info = run_info;
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
     uint16_t run_limit_sec = CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC;
     esp_err_t ret;
 #if CONFIG_RELAY_CHN_ENABLE_NVS
     // Load run limit value from NVS
-    ret = relay_chn_nvs_get_run_limit(chn_ctl.id, &run_limit_sec);
+    ret = relay_chn_nvs_get_run_limit(s_chn_ctl.id, &run_limit_sec, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC);
-    if (ret != ESP_OK && ret != ESP_ERR_NVS_NOT_FOUND) {
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load run limit from NVS with error: %s", esp_err_to_name(ret));
-        ESP_LOGE(TAG, "Failed to load run limit from NVS with error: %s", esp_err_to_name(ret));
-    }
 #endif
-    chn_ctl.run_limit_sec = run_limit_sec;
+    s_chn_ctl.run_limit_sec = run_limit_sec;
-    ret = relay_chn_init_run_limit_timer(&chn_ctl);
+    ret = relay_chn_init_run_limit_timer(&s_chn_ctl);
     ESP_RETURN_ON_ERROR(ret, TAG, "Failed to initialize run limit timer");
 #endif
-    return relay_chn_init_timer(&chn_ctl); // Create direction change inertia timer
+    return relay_chn_init_timer(&s_chn_ctl); // Create direction change inertia timer
 }
 
 
 void relay_chn_ctl_deinit()
 {
-    if (chn_ctl.inertia_timer != NULL) {
+    if (s_chn_ctl.inertia_timer != NULL) {
-        esp_timer_delete(chn_ctl.inertia_timer);
+        esp_timer_delete(s_chn_ctl.inertia_timer);
-        chn_ctl.inertia_timer = NULL;
+        s_chn_ctl.inertia_timer = NULL;
     }
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
-    if (chn_ctl.run_limit_timer != NULL) {
+    if (s_chn_ctl.run_limit_timer != NULL) {
-        esp_timer_delete(chn_ctl.run_limit_timer);
+    esp_timer_delete(s_chn_ctl.run_limit_timer);
-        chn_ctl.run_limit_timer = NULL;
+        s_chn_ctl.run_limit_timer = NULL;
     }
 #endif
 }
@@ -62,43 +61,43 @@ void relay_chn_ctl_deinit()
 /* relay_chn APIs */
 relay_chn_state_t relay_chn_ctl_get_state()
 {
-    return chn_ctl.state;
+    return s_chn_ctl.state;
 }
 
 char *relay_chn_ctl_get_state_str()
 {
-    return relay_chn_state_str(chn_ctl.state);
+    return relay_chn_state_to_str(s_chn_ctl.state);
 }
 
 void relay_chn_ctl_run_forward()
 {
-    relay_chn_issue_cmd(&chn_ctl, RELAY_CHN_CMD_FORWARD);
+    relay_chn_issue_cmd(&s_chn_ctl, RELAY_CHN_CMD_FORWARD);
 }
 
 void relay_chn_ctl_run_reverse()
 {
-    relay_chn_issue_cmd(&chn_ctl, RELAY_CHN_CMD_REVERSE);
+    relay_chn_issue_cmd(&s_chn_ctl, RELAY_CHN_CMD_REVERSE);
 }
 
 void relay_chn_ctl_stop()
 {
-    relay_chn_issue_cmd(&chn_ctl, RELAY_CHN_CMD_STOP);
+    relay_chn_issue_cmd(&s_chn_ctl, RELAY_CHN_CMD_STOP);
 }
 
 void relay_chn_ctl_flip_direction()
 {
-    relay_chn_issue_cmd(&chn_ctl, RELAY_CHN_CMD_FLIP);    
+    relay_chn_issue_cmd(&s_chn_ctl, RELAY_CHN_CMD_FLIP);
 }
 
 relay_chn_direction_t relay_chn_ctl_get_direction()
 {
-    return relay_chn_output_get_direction(chn_ctl.output);
+    return relay_chn_output_get_direction(s_chn_ctl.output);
 }
 
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
 uint16_t relay_chn_ctl_get_run_limit()
 {
-    return chn_ctl.run_limit_sec;
+return s_chn_ctl.run_limit_sec;
 }
 
 void relay_chn_ctl_set_run_limit(uint16_t limit_sec)
@@ -109,10 +108,10 @@ void relay_chn_ctl_set_run_limit(uint16_t limit_sec)
     else if (limit_sec < CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC)
         limit_sec = CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC;
 
-    chn_ctl.run_limit_sec = limit_sec;
+    s_chn_ctl.run_limit_sec = limit_sec;
 
 #if CONFIG_RELAY_CHN_ENABLE_NVS
-    relay_chn_nvs_set_run_limit(chn_ctl.id, limit_sec);
+    relay_chn_nvs_set_run_limit(s_chn_ctl.id, limit_sec);
 #endif
 }
 #endif
@@ -120,5 +119,5 @@ void relay_chn_ctl_set_run_limit(uint16_t limit_sec)
 
 relay_chn_ctl_t *relay_chn_ctl_get()
 {
-    return &chn_ctl;
+    return &s_chn_ctl;
 }

src/relay_chn_notify.c

@@ -0,0 +1,268 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/queue.h"
+#include "esp_log.h"
+#include "esp_check.h"
+#include "relay_chn_notify.h"
+
+static const char *TAG = "RELAY_CHN_NOTIFY";
+
+// --- Config ---
+#define RELAY_CHN_NOTIFY_QUEUE_LEN  (16 + CONFIG_RELAY_CHN_COUNT * 4)
+#define RELAY_CHN_NOTIFY_TASK_STACK 2048
+#define RELAY_CHN_NOTIFY_TASK_PRIO  (tskIDLE_PRIORITY + 5)
+
+/// @brief Structure to hold a listener entry in the linked list.
+typedef struct relay_chn_listener_entry_type {
+    relay_chn_state_listener_t listener;  /*!< The listener function pointer */
+    ListItem_t list_item;                 /*!< FreeRTOS list item */
+} relay_chn_listener_entry_t;
+
+/// @brief Command types for the notification queue.
+typedef enum {
+    RELAY_CHN_NOTIFY_CMD_BROADCAST,         /*!< A relay channel state has changed. */
+    RELAY_CHN_NOTIFY_CMD_ADD_LISTENER,      /*!< Request to add a new listener. */
+    RELAY_CHN_NOTIFY_CMD_REMOVE_LISTENER,   /*!< Request to remove a listener. */
+} relay_chn_notify_cmd_t;
+
+/// @brief Payload for a state change event.
+typedef struct {
+    uint8_t chn_id;
+    relay_chn_state_t old_state;
+    relay_chn_state_t new_state;
+} relay_chn_notify_event_data_t;
+
+/// @brief The command structure sent to the notification queue.
+typedef struct {
+    relay_chn_notify_cmd_t cmd;
+    union {
+        relay_chn_notify_event_data_t event_data; /*!< Used for RELAY_CHN_NOTIFY_CMD_BROADCAST */
+        relay_chn_state_listener_t listener;      /*!< Used for ADD/REMOVE listener commands */
+    } payload;
+} relay_chn_notify_msg_t;
+
+// The list that holds references to the registered listeners.
+static List_t s_listeners;
+
+static QueueHandle_t s_notify_queue = NULL;
+static TaskHandle_t s_notify_task = NULL;
+
+static void relay_chn_notify_task(void *arg);
+
+
+esp_err_t relay_chn_notify_init(void)
+{
+    if (s_notify_queue != NULL) {
+        return ESP_OK;
+    }
+
+    s_notify_queue = xQueueCreate(RELAY_CHN_NOTIFY_QUEUE_LEN, sizeof(relay_chn_notify_msg_t));
+    if (!s_notify_queue) {
+        ESP_LOGE(TAG, "Failed to create notify queue");
+        return ESP_ERR_NO_MEM;
+    }
+
+    // Create the notify dispatcher task
+    BaseType_t ret = xTaskCreate(relay_chn_notify_task, "task_rlch_ntfy",
+                                 RELAY_CHN_NOTIFY_TASK_STACK, NULL,
+                                 RELAY_CHN_NOTIFY_TASK_PRIO, &s_notify_task);
+    if (ret != pdPASS) {
+        ESP_LOGE(TAG, "Failed to create notify task");
+        return ESP_ERR_NO_MEM;
+    }
+
+    // Init the state listener list
+    vListInitialise(&s_listeners);
+
+    return ESP_OK;
+}
+
+void relay_chn_notify_deinit(void)
+{
+    if (s_notify_task != NULL) {
+        vTaskDelete(s_notify_task);
+        s_notify_task = NULL;
+    }
+
+    if (s_notify_queue != NULL) {
+        vQueueDelete(s_notify_queue);
+        s_notify_queue = NULL;
+    }
+
+    if (!listLIST_IS_EMPTY(&s_listeners)) {
+        // Free the listeners
+        while (listCURRENT_LIST_LENGTH(&s_listeners) > 0) {
+            ListItem_t *pxItem = listGET_HEAD_ENTRY(&s_listeners);
+            relay_chn_listener_entry_t *entry = listGET_LIST_ITEM_OWNER(pxItem);
+            uxListRemove(pxItem);
+            free(entry);
+        }
+    }
+}
+
+/**
+ * @brief Find a listener entry in the list by its function pointer.
+ *
+ * This function replaces the old index-based search and is used to check
+ * for the existence of a listener before registration or for finding it
+ * during unregistration.
+ *
+ * @param listener The listener function pointer to find.
+ * @return Pointer to the listener entry if found, otherwise NULL.
+ */
+static relay_chn_listener_entry_t* find_listener_entry(relay_chn_state_listener_t listener)
+{
+    if (listLIST_IS_EMPTY(&s_listeners)) {
+        ESP_LOGD(TAG, "No listeners registered");
+        return NULL;
+    }
+
+    // Iterate through the linked list of listeners
+    for (ListItem_t *pxListItem = listGET_HEAD_ENTRY(&s_listeners);
+         pxListItem != listGET_END_MARKER(&s_listeners);
+         pxListItem = listGET_NEXT(pxListItem)) {
+
+        relay_chn_listener_entry_t *entry = (relay_chn_listener_entry_t *) listGET_LIST_ITEM_OWNER(pxListItem);
+        if (entry->listener == listener) {
+            // Found the listener, return the entry
+            return entry;
+        }
+    }
+
+    // Listener was not found in the list
+    return NULL;
+}
+
+static void do_add_listener(relay_chn_state_listener_t listener)
+{
+    // This is now only called from the dispatcher task, so no mutex needed.
+    if (find_listener_entry(listener) != NULL) {
+        ESP_LOGD(TAG, "Listener %p already registered", listener);
+        return;
+    }
+    relay_chn_listener_entry_t *entry = malloc(sizeof(relay_chn_listener_entry_t));
+    if (!entry) {
+        ESP_LOGE(TAG, "Failed to allocate memory for listener");
+        return;
+    }
+    entry->listener = listener;
+    vListInitialiseItem(&(entry->list_item));
+    listSET_LIST_ITEM_OWNER(&(entry->list_item), (void *)entry);
+    vListInsertEnd(&s_listeners, &(entry->list_item));
+    ESP_LOGD(TAG, "Registered listener %p", listener);
+}
+
+static void do_remove_listener(relay_chn_state_listener_t listener)
+{
+    // This is now only called from the dispatcher task, so no mutex needed.
+    relay_chn_listener_entry_t *entry = find_listener_entry(listener);
+    if (entry != NULL) {
+        uxListRemove(&(entry->list_item));
+        free(entry);
+        ESP_LOGD(TAG, "Unregistered listener %p", listener);
+    } else {
+        ESP_LOGD(TAG, "Listener %p not found for unregistration.", listener);
+    }
+
+    if (listLIST_IS_EMPTY(&s_listeners)) {
+        // Flush all pending notifications in the queue
+        xQueueReset(s_notify_queue);
+    }
+}
+
+esp_err_t relay_chn_notify_add_listener(relay_chn_state_listener_t listener)
+{
+    ESP_RETURN_ON_FALSE(listener, ESP_ERR_INVALID_ARG, TAG, "Listener cannot be NULL");
+    ESP_RETURN_ON_FALSE(s_notify_queue, ESP_ERR_INVALID_STATE, TAG, "Notify module not initialized");
+
+    relay_chn_notify_msg_t msg = { .cmd = RELAY_CHN_NOTIFY_CMD_ADD_LISTENER, .payload.listener = listener };
+    if (xQueueSend(s_notify_queue, &msg, 0) != pdTRUE) {
+        ESP_LOGE(TAG, "Notify queue is full, failed to queue add_listener");
+        return ESP_FAIL;
+    }
+    return ESP_OK;
+}
+
+void relay_chn_notify_remove_listener(relay_chn_state_listener_t listener)
+{
+    if (listener == NULL) {
+        ESP_LOGD(TAG, "Cannot unregister a NULL listener.");
+        return;
+    }
+    if (!s_notify_queue) {
+        ESP_LOGE(TAG, "Notify module not initialized, cannot remove listener");
+        return;
+    }
+
+    relay_chn_notify_msg_t msg = { .cmd = RELAY_CHN_NOTIFY_CMD_REMOVE_LISTENER, .payload.listener = listener };
+    if (xQueueSendToFront(s_notify_queue, &msg, 0) != pdTRUE) {
+        ESP_LOGW(TAG, "Notify queue is full, failed to queue remove_listener");
+    }
+}
+
+esp_err_t relay_chn_notify_state_change(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state)
+{
+    if (!s_notify_queue) {
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    relay_chn_notify_msg_t msg = {
+        .cmd = RELAY_CHN_NOTIFY_CMD_BROADCAST,
+        .payload.event_data.chn_id = chn_id,
+        .payload.event_data.old_state = old_state,
+        .payload.event_data.new_state = new_state,
+    };
+
+    // Try to send, do not wait if the queue is full
+    if (xQueueSend(s_notify_queue, &msg, 0) != pdTRUE) {
+        ESP_LOGW(TAG, "Notify queue is full, dropping event: %d -> %d for #%d", old_state, new_state, chn_id);
+        return ESP_FAIL;
+    }
+    return ESP_OK;
+}
+
+static void do_notify(relay_chn_notify_event_data_t *event_data)
+{
+    // Iterate through the linked list of listeners and notify them.
+    // No mutex is needed as this is the only task accessing the list.
+    for (ListItem_t *pxListItem = listGET_HEAD_ENTRY(&s_listeners);
+         pxListItem != listGET_END_MARKER(&s_listeners);
+         pxListItem = listGET_NEXT(pxListItem)) {
+        relay_chn_listener_entry_t *entry = (relay_chn_listener_entry_t *) listGET_LIST_ITEM_OWNER(pxListItem);
+        if (entry && entry->listener) {
+            // Emit the state change to the listeners
+            entry->listener(event_data->chn_id, event_data->old_state, event_data->new_state);
+        }
+    }
+}
+
+// ---- Notify Task ----
+static void relay_chn_notify_task(void *arg)
+{
+    relay_chn_notify_msg_t msg;
+    for (;;) {
+        if (xQueueReceive(s_notify_queue, &msg, portMAX_DELAY) == pdTRUE) {
+            switch (msg.cmd) {
+                case RELAY_CHN_NOTIFY_CMD_BROADCAST: {
+                    do_notify(&msg.payload.event_data);
+                    break;
+                }
+                case RELAY_CHN_NOTIFY_CMD_ADD_LISTENER:
+                    do_add_listener(msg.payload.listener);
+                    break;
+                case RELAY_CHN_NOTIFY_CMD_REMOVE_LISTENER:
+                    do_remove_listener(msg.payload.listener);
+                    break;
+                default:
+                    ESP_LOGE(TAG, "Unknown command type in notify queue: %d", msg.cmd);
+                    break;
+            }
+        }
+    }
+}

src/relay_chn_nvs.c

@@ -4,30 +4,104 @@
  * SPDX-License-Identifier: MIT
  */
 
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+#include "freertos/task.h"
+#include "freertos/queue.h"
 #include "esp_check.h"
+#include "esp_log.h"
+#include "nvs.h"
 #include "relay_chn_nvs.h"
 
 #define RELAY_CHN_KEY_DIR          "dir"    /*!< Direction key */
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
-#define RELAY_CHN_KEY_RLIM(ch)  "rlim_%d"   /*!< Run limit key */
+#if CONFIG_RELAY_CHN_COUNT > 1
+#define RELAY_CHN_KEY_RLIM_FMT  "rlim_%d"   /*!< Run limit key format for multi-channel */
+#else
+#define RELAY_CHN_KEY_RLIM      "rlim_0"    /*!< Run limit key for single-channel */
+#endif
 #endif
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
-#define RELAY_CHN_KEY_TSENS(ch) "tsens_%d"  /*!< Tilt sensitivity key */
+#if CONFIG_RELAY_CHN_COUNT > 1
-#define RELAY_CHN_KEY_TCNT(ch)  "tcnt_%d"   /*!< Tilt count key */
+#define RELAY_CHN_KEY_TSENS_FMT "tsens_%d"  /*!< Tilt sensitivity key format for multi-channel */
+#define RELAY_CHN_KEY_TCNT_FMT  "tcnt_%d"   /*!< Tilt count key format for multi-channel */
+#else
+#define RELAY_CHN_KEY_TSENS     "tsens_0"   /*!< Tilt sensitivity key for single-channel */
+#define RELAY_CHN_KEY_TCNT      "tcnt_0"    /*!< Tilt count key for single-channel */
 #endif
+#endif
+
+// --- Task and message queue config ---
+#define RELAY_CHN_NVS_QUEUE_LEN  (8 + CONFIG_RELAY_CHN_COUNT * 8)
+#define RELAY_CHN_NVS_TASK_STACK 2048
+#define RELAY_CHN_NVS_COMMIT_TIMEOUT_MS 200
+#define RELAY_CHN_NVS_TASK_PRIO  (tskIDLE_PRIORITY + 4)
+
+typedef enum {
+    RELAY_CHN_NVS_OP_ERASE_ALL,
+    RELAY_CHN_NVS_OP_SET_DIRECTION,
+#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
+    RELAY_CHN_NVS_OP_SET_RUN_LIMIT,
+#endif
+#if CONFIG_RELAY_CHN_ENABLE_TILTING
+    RELAY_CHN_NVS_OP_SET_TILT_SENSITIVITY,
+    RELAY_CHN_NVS_OP_SET_TILT_COUNT,
+#endif
+    RELAY_CHN_NVS_OP_DEINIT,
+} relay_chn_nvs_op_t;
+
+typedef struct {
+    relay_chn_nvs_op_t op;
+    uint8_t ch;
+    union {
+        uint16_t data_u16;
+        uint8_t data_u8;
+    } data;
+} relay_chn_nvs_msg_t;
 
 static const char *TAG = "RELAY_CHN_NVS";
 
-static nvs_handle_t relay_chn_nvs;
+static nvs_handle_t s_relay_chn_nvs;
+static QueueHandle_t s_nvs_ops_queue = NULL;
+static TaskHandle_t s_nvs_ops_task = NULL;
+static SemaphoreHandle_t s_nvs_deinit_sem = NULL;
+
+
+static void relay_chn_nvs_task(void *arg);
 
 esp_err_t relay_chn_nvs_init()
 {
+    // Already initialized?
+    if (s_nvs_ops_queue != NULL) {
+        return ESP_OK;
+    }
+
+    s_nvs_deinit_sem = xSemaphoreCreateBinary();
+    if (!s_nvs_deinit_sem) {
+        ESP_LOGE(TAG, "Failed to create deinit semaphore");
+        return ESP_ERR_NO_MEM;
+    }
+
+    s_nvs_ops_queue = xQueueCreate(RELAY_CHN_NVS_QUEUE_LEN, sizeof(relay_chn_nvs_msg_t));
+    if (!s_nvs_ops_queue) {
+        ESP_LOGE(TAG, "Failed to create NVS queue");
+        return ESP_ERR_NO_MEM;
+    }
+
+    BaseType_t res = xTaskCreate(relay_chn_nvs_task, "task_rlch_nvs",
+                                 RELAY_CHN_NVS_TASK_STACK, NULL,
+                                 RELAY_CHN_NVS_TASK_PRIO, &s_nvs_ops_task);
+    if (res != pdPASS) {
+        ESP_LOGE(TAG, "Failed to create NVS task");
+        return ESP_ERR_NO_MEM;
+    }
+
     esp_err_t ret;
 #if CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION
     ret = nvs_open_from_partition(CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION_NAME,
                                   CONFIG_RELAY_CHN_NVS_NAMESPACE,
                                   NVS_READWRITE,
-                                  &relay_chn_nvs);
+                                  &s_relay_chn_nvs);
 
     ESP_RETURN_ON_ERROR(ret,
                         TAG,
@@ -36,38 +110,71 @@ esp_err_t relay_chn_nvs_init()
                         CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION_NAME,
                         esp_err_to_name(ret));
 #else
-    ret = nvs_open(CONFIG_RELAY_CHN_NVS_NAMESPACE, NVS_READWRITE, &relay_chn_nvs);
+    ret = nvs_open(CONFIG_RELAY_CHN_NVS_NAMESPACE, NVS_READWRITE, &s_relay_chn_nvs);
     ESP_RETURN_ON_ERROR(ret, TAG, "Failed to open NVS namespace '%s'", CONFIG_RELAY_CHN_NVS_NAMESPACE);
 #endif // CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION
     return ESP_OK;
 }
 
+static esp_err_t relay_chn_nvs_enqueue(relay_chn_nvs_msg_t *msg, const char *op_name)
+{
+    if (!s_nvs_ops_queue) {
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    if (msg->op == RELAY_CHN_NVS_OP_DEINIT || msg->op == RELAY_CHN_NVS_OP_ERASE_ALL) {
+        // Send DEINIT or ERASE_ALL to the front and wait up to 1 sec if needed
+        if (xQueueSendToFront(s_nvs_ops_queue, msg, pdMS_TO_TICKS(1000)) != pdTRUE) {
+            ESP_LOGW(TAG, "NVS queue is full, dropping %s for #%d", op_name, msg->ch);
+            return ESP_FAIL;
+        }
+    } else {
+        // Send async
+        if (xQueueSend(s_nvs_ops_queue, msg, 0) != pdTRUE) {
+            ESP_LOGW(TAG, "NVS queue is full, dropping %s for #%d", op_name, msg->ch);
+            return ESP_FAIL;
+        }
+    }
+    return ESP_OK;
+}
+
 esp_err_t relay_chn_nvs_set_direction(uint8_t ch, relay_chn_direction_t direction)
 {
-    uint8_t direction_val;
+    relay_chn_nvs_msg_t msg = {
-    esp_err_t ret = nvs_get_u8(relay_chn_nvs, RELAY_CHN_KEY_DIR, &direction_val);
+        .op = RELAY_CHN_NVS_OP_SET_DIRECTION,
-    if (ret == ESP_ERR_NVS_NOT_FOUND) {
+        .ch = ch,
-        // The key does not exist yet, set it to zero which is the default direction
+        .data.data_u8 = (uint8_t) direction,
-        direction_val = RELAY_CHN_DIRECTION_DEFAULT;
+    };
-    } else if (ret != ESP_OK) {
+    return relay_chn_nvs_enqueue(&msg, "SET_DIRECTION");
+}
+
+static esp_err_t relay_chn_nvs_task_set_direction(uint8_t ch, uint8_t direction)
+{
+    uint8_t direction_val = 0;
+    esp_err_t ret = nvs_get_u8(s_relay_chn_nvs, RELAY_CHN_KEY_DIR, &direction_val);
+    if (ret != ESP_OK && ret != ESP_ERR_NVS_NOT_FOUND) {
         ESP_RETURN_ON_ERROR(ret, TAG, "Failed to get direction from NVS with error: %s", esp_err_to_name(ret));
     }
     direction_val &= ~(1 << ch); // Clear the bit for the channel
     direction_val |= (((uint8_t) direction) << ch); // Set the new direction bit
-    ret = nvs_set_u8(relay_chn_nvs, RELAY_CHN_KEY_DIR, direction_val);
+    ret = nvs_set_u8(s_relay_chn_nvs, RELAY_CHN_KEY_DIR, direction_val);
     ESP_RETURN_ON_ERROR(ret, TAG, "Failed to set direction for channel %d", ch);
-    return nvs_commit(relay_chn_nvs);
+    return ESP_OK;
 }
 
-esp_err_t relay_chn_nvs_get_direction(uint8_t ch, relay_chn_direction_t *direction)
+esp_err_t relay_chn_nvs_get_direction(uint8_t ch, relay_chn_direction_t *direction, relay_chn_direction_t default_val)
 {
     ESP_RETURN_ON_FALSE(direction != NULL, ESP_ERR_INVALID_ARG, TAG, "Direction pointer is NULL");
 
     uint8_t direction_val;
-    esp_err_t ret = nvs_get_u8(relay_chn_nvs, RELAY_CHN_KEY_DIR, &direction_val);
+    esp_err_t ret = nvs_get_u8(s_relay_chn_nvs, RELAY_CHN_KEY_DIR, &direction_val);
-    if (ret != ESP_OK) {
+    if (ret == ESP_ERR_NVS_NOT_FOUND) {
-        return ret; // Return error if the key does not exist
+        *direction = default_val;
+        return ESP_OK;
+    } else if (ret != ESP_OK) {
+        return ret; // A real error occurred, return it
     }
+    // If ret is ESP_OK, direction_val has the stored value.
     *direction = (relay_chn_direction_t)((direction_val >> ch) & 0x01);
     return ESP_OK;
 }
@@ -75,62 +182,271 @@ esp_err_t relay_chn_nvs_get_direction(uint8_t ch, relay_chn_direction_t *directi
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
 esp_err_t relay_chn_nvs_set_run_limit(uint8_t ch, uint16_t limit_sec)
 {
-    esp_err_t ret = nvs_set_u16(relay_chn_nvs, RELAY_CHN_KEY_RLIM(ch), limit_sec);
+    relay_chn_nvs_msg_t msg = {
-    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to set run limit for channel %d", ch);
+        .op = RELAY_CHN_NVS_OP_SET_RUN_LIMIT,
-    return nvs_commit(relay_chn_nvs);
+        .ch = ch,
+        .data.data_u16 = limit_sec,
+    };
+    return relay_chn_nvs_enqueue(&msg, "SET_RUN_LIMIT");
 }
 
-esp_err_t relay_chn_nvs_get_run_limit(uint8_t ch, uint16_t *limit_sec)
+static esp_err_t relay_chn_nvs_task_set_run_limit(uint8_t ch, uint16_t limit_sec)
+{
+    esp_err_t ret;
+#if CONFIG_RELAY_CHN_COUNT > 1
+    char key[NVS_KEY_NAME_MAX_SIZE];
+    snprintf(key, sizeof(key), RELAY_CHN_KEY_RLIM_FMT, ch);
+    ret = nvs_set_u16(s_relay_chn_nvs, key, limit_sec);
+#else
+    ret = nvs_set_u16(s_relay_chn_nvs, RELAY_CHN_KEY_RLIM, limit_sec);
+#endif
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to set run limit for channel %d", ch);
+    return ESP_OK;
+}
+
+esp_err_t relay_chn_nvs_get_run_limit(uint8_t ch, uint16_t *limit_sec, uint16_t default_val)
 {
     ESP_RETURN_ON_FALSE(limit_sec != NULL, ESP_ERR_INVALID_ARG, TAG, "Run limit value pointer is NULL");
 
-    return nvs_get_u16(relay_chn_nvs, RELAY_CHN_KEY_RLIM(ch), limit_sec);
+    esp_err_t ret;
+#if CONFIG_RELAY_CHN_COUNT > 1
+    char key[NVS_KEY_NAME_MAX_SIZE];
+    snprintf(key, sizeof(key), RELAY_CHN_KEY_RLIM_FMT, ch);
+    ret = nvs_get_u16(s_relay_chn_nvs, key, limit_sec);
+#else
+    ret = nvs_get_u16(s_relay_chn_nvs, RELAY_CHN_KEY_RLIM, limit_sec);
+#endif
+    if (ret == ESP_ERR_NVS_NOT_FOUND) {
+        *limit_sec = default_val;
+        return ESP_OK;
+    }
+    return ret;
 }
 #endif // CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT == 1
 
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
 esp_err_t relay_chn_nvs_set_tilt_sensitivity(uint8_t ch, uint8_t sensitivity)
 {
-    esp_err_t ret = nvs_set_u8(relay_chn_nvs, RELAY_CHN_KEY_TSENS(ch), sensitivity);
+    relay_chn_nvs_msg_t msg = {
-    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to set tilt sensitivity for channel %d", ch);
+        .op = RELAY_CHN_NVS_OP_SET_TILT_SENSITIVITY,
-    return nvs_commit(relay_chn_nvs);
+        .ch = ch,
+        .data.data_u8 = sensitivity,
+    };
+    return relay_chn_nvs_enqueue(&msg, "SET_TILT_SENSITIVITY");
 }
 
-esp_err_t relay_chn_nvs_get_tilt_sensitivity(uint8_t ch, uint8_t *sensitivity)
+static esp_err_t relay_chn_nvs_task_set_tilt_sensitivity(uint8_t ch, uint8_t sensitivity)
+{
+    esp_err_t ret;
+#if CONFIG_RELAY_CHN_COUNT > 1
+    char key[NVS_KEY_NAME_MAX_SIZE];
+    snprintf(key, sizeof(key), RELAY_CHN_KEY_TSENS_FMT, ch);
+    ret = nvs_set_u8(s_relay_chn_nvs, key, sensitivity);
+#else
+    ret = nvs_set_u8(s_relay_chn_nvs, RELAY_CHN_KEY_TSENS, sensitivity);
+#endif
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to set tilt sensitivity for channel %d", ch);
+    return ESP_OK;
+}
+
+esp_err_t relay_chn_nvs_get_tilt_sensitivity(uint8_t ch, uint8_t *sensitivity, uint8_t default_val)
 {
     ESP_RETURN_ON_FALSE(sensitivity != NULL, ESP_ERR_INVALID_ARG, TAG, "Sensitivity pointer is NULL");
 
-    return nvs_get_u8(relay_chn_nvs, RELAY_CHN_KEY_TSENS(ch), sensitivity);
+    esp_err_t ret;
+#if CONFIG_RELAY_CHN_COUNT > 1
+    char key[NVS_KEY_NAME_MAX_SIZE];
+    snprintf(key, sizeof(key), RELAY_CHN_KEY_TSENS_FMT, ch);
+    ret = nvs_get_u8(s_relay_chn_nvs, key, sensitivity);
+#else
+    ret = nvs_get_u8(s_relay_chn_nvs, RELAY_CHN_KEY_TSENS, sensitivity);
+#endif
+    if (ret == ESP_ERR_NVS_NOT_FOUND) {
+        *sensitivity = default_val;
+        return ESP_OK;
+    }
+    return ret;
 }
 
 esp_err_t relay_chn_nvs_set_tilt_count(uint8_t ch, uint16_t tilt_count)
 {
-    esp_err_t ret;
+    relay_chn_nvs_msg_t msg = {
-    ret = nvs_set_u16(relay_chn_nvs, RELAY_CHN_KEY_TCNT(ch), tilt_count);
+        .op = RELAY_CHN_NVS_OP_SET_TILT_COUNT,
-    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to save tilt_count tilt counter");
+        .ch = ch,
-    return nvs_commit(relay_chn_nvs);
+        .data.data_u16 = tilt_count,
+    };
+    return relay_chn_nvs_enqueue(&msg, "SET_TILT_COUNT");
 }
 
-esp_err_t relay_chn_nvs_get_tilt_count(uint8_t ch, uint16_t *tilt_count)
+static esp_err_t relay_chn_nvs_task_set_tilt_count(uint8_t ch, uint16_t tilt_count)
 {
-    ESP_RETURN_ON_FALSE(tilt_count != NULL,
+    esp_err_t ret;
-                        ESP_ERR_INVALID_ARG, TAG, "Counter pointers are NULL");
+#if CONFIG_RELAY_CHN_COUNT > 1
-    return nvs_get_u16(relay_chn_nvs, RELAY_CHN_KEY_TCNT(ch), tilt_count);
+    char key[NVS_KEY_NAME_MAX_SIZE];
+    snprintf(key, sizeof(key), RELAY_CHN_KEY_TCNT_FMT, ch);
+    ret = nvs_set_u16(s_relay_chn_nvs, key, tilt_count);
+#else
+    ret = nvs_set_u16(s_relay_chn_nvs, RELAY_CHN_KEY_TCNT, tilt_count);
+#endif
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to save tilt_count tilt counter");
+    return ESP_OK;
+}
+
+esp_err_t relay_chn_nvs_get_tilt_count(uint8_t ch, uint16_t *tilt_count, uint16_t default_val)
+{
+    ESP_RETURN_ON_FALSE(tilt_count != NULL, ESP_ERR_INVALID_ARG, TAG, "Counter pointers are NULL");
+
+    esp_err_t ret;
+#if CONFIG_RELAY_CHN_COUNT > 1
+    char key[NVS_KEY_NAME_MAX_SIZE];
+    snprintf(key, sizeof(key), RELAY_CHN_KEY_TCNT_FMT, ch);
+    ret = nvs_get_u16(s_relay_chn_nvs, key, tilt_count);
+#else
+    ret = nvs_get_u16(s_relay_chn_nvs, RELAY_CHN_KEY_TCNT, tilt_count);
+#endif
+    if (ret == ESP_ERR_NVS_NOT_FOUND) {
+        *tilt_count = default_val;
+        return ESP_OK;
+    }
+    return ret;
 }
 #endif // CONFIG_RELAY_CHN_ENABLE_TILTING
 
 esp_err_t relay_chn_nvs_erase_all()
 {
-    // Erase all key-value pairs in the relay_chn NVS namespace
+    relay_chn_nvs_msg_t msg = {
-    esp_err_t ret = nvs_erase_all(relay_chn_nvs);
+        .op = RELAY_CHN_NVS_OP_ERASE_ALL,
-    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to erase all keys in NVS namespace '%s'", CONFIG_RELAY_CHN_NVS_NAMESPACE);
+    };
-    
+    return relay_chn_nvs_enqueue(&msg, "ERASE_ALL");
-    // Commit the changes
-    return nvs_commit(relay_chn_nvs);
 }
 
-esp_err_t relay_chn_nvs_deinit()
+static esp_err_t do_nvs_deinit()
 {
-    nvs_close(relay_chn_nvs);
+    relay_chn_nvs_msg_t msg = {
+        .op = RELAY_CHN_NVS_OP_DEINIT,
+    };
+    return relay_chn_nvs_enqueue(&msg, "DEINIT");
+}
+
+static esp_err_t do_nvs_erase_all()
+{
+    // Flush all pending SET operations since ERASE_ALL requested
+    xQueueReset(s_nvs_ops_queue);
+    // Erase all key-value pairs in the relay_chn NVS namespace
+    esp_err_t ret = nvs_erase_all(s_relay_chn_nvs);
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to erase all keys in NVS namespace '%s'", CONFIG_RELAY_CHN_NVS_NAMESPACE);
     return ESP_OK;
 }
+
+void relay_chn_nvs_deinit()
+{
+    if (s_nvs_ops_task) {
+        if (do_nvs_deinit() == ESP_OK) {
+            if (s_nvs_deinit_sem && xSemaphoreTake(s_nvs_deinit_sem, pdMS_TO_TICKS(2000)) != pdTRUE) {
+                ESP_LOGE(TAG, "Failed to get deinit confirmation from NVS task. Forcing deletion.");
+                vTaskDelete(s_nvs_ops_task); // Last resort
+            }
+        } else {
+            ESP_LOGE(TAG, "Failed to send deinit message to NVS task. Forcing deletion.");
+            vTaskDelete(s_nvs_ops_task);
+        }
+    }
+    if (s_nvs_ops_queue) {
+        vQueueDelete(s_nvs_ops_queue);
+        s_nvs_ops_queue = NULL;
+    }
+    if (s_nvs_deinit_sem) {
+        vSemaphoreDelete(s_nvs_deinit_sem);
+        s_nvs_deinit_sem = NULL;
+    }
+
+    // Close NVS handle here, after task has stopped and queue is deleted.
+    nvs_close(s_relay_chn_nvs);
+    s_nvs_ops_task = NULL;
+}
+
+static esp_err_t relay_chn_nvs_task_process_message(const relay_chn_nvs_msg_t *msg, bool *running, bool *dirty)
+{
+    esp_err_t ret = ESP_OK;
+    switch (msg->op) {
+        case RELAY_CHN_NVS_OP_SET_DIRECTION:
+            ret = relay_chn_nvs_task_set_direction(msg->ch, msg->data.data_u8);
+            if (ret == ESP_OK) *dirty = true;
+            break;
+#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
+        case RELAY_CHN_NVS_OP_SET_RUN_LIMIT:
+            ret = relay_chn_nvs_task_set_run_limit(msg->ch, msg->data.data_u16);
+            if (ret == ESP_OK) *dirty = true;
+            break;
+#endif
+#if CONFIG_RELAY_CHN_ENABLE_TILTING
+        case RELAY_CHN_NVS_OP_SET_TILT_SENSITIVITY:
+            ret = relay_chn_nvs_task_set_tilt_sensitivity(msg->ch, msg->data.data_u8);
+            if (ret == ESP_OK) *dirty = true;
+            break;
+        case RELAY_CHN_NVS_OP_SET_TILT_COUNT:
+            ret = relay_chn_nvs_task_set_tilt_count(msg->ch, msg->data.data_u16);
+            if (ret == ESP_OK) *dirty = true;
+            break;
+#endif
+        case RELAY_CHN_NVS_OP_ERASE_ALL:
+            ret = do_nvs_erase_all();
+            if (ret == ESP_OK) *dirty = true;
+            break;
+        case RELAY_CHN_NVS_OP_DEINIT:
+            *running = false;
+            break;
+        default:
+            ESP_LOGE(TAG, "Unknown operation in NVS queue: %d", msg->op);
+            ret = ESP_ERR_INVALID_ARG;
+            break;
+    }
+    return ret;
+}
+
+/*
+ * The ESP-IDF NVS functions are protected by an internal mutex. If this task is killed
+ * while it's holding that mutex, the mutex is never released, which may result in
+ * deadlocks. This is why this task must be terminated gracefully.
+ */
+static void relay_chn_nvs_task(void *arg)
+{
+    relay_chn_nvs_msg_t msg;
+    bool dirty = false;
+    bool running = true;
+
+    while (running) {
+        // Block indefinitely waiting for the first message of a potential batch.
+        if (xQueueReceive(s_nvs_ops_queue, &msg, portMAX_DELAY) == pdTRUE) {
+            // A batch of operations has started. Use a do-while to process the first message
+            // and any subsequent messages that arrive within the timeout.
+            do {
+                esp_err_t ret = relay_chn_nvs_task_process_message(&msg, &running, &dirty);
+                if (ret != ESP_OK) {
+                    ESP_LOGE(TAG, "Failed to process operation %d for #%d with error %s", msg.op, msg.ch, esp_err_to_name(ret));
+                }
+            } while (running && xQueueReceive(s_nvs_ops_queue, &msg, pdMS_TO_TICKS(RELAY_CHN_NVS_COMMIT_TIMEOUT_MS)) == pdTRUE);
+
+            // The burst of messages is over (timeout occurred). Commit if anything changed.
+            if (dirty) {
+                esp_err_t commit_ret = nvs_commit(s_relay_chn_nvs);
+                if (commit_ret == ESP_OK) {
+                    dirty = false;
+                } else {
+                    ESP_LOGE(TAG, "NVS batch commit failed");
+                    // Don't reset dirty flag, so we can try to commit again later.
+                }
+            }
+        }
+    }
+
+    // Before exiting, do one final commit if there are pending changes.
+    if (dirty) {
+        if (nvs_commit(s_relay_chn_nvs) != ESP_OK) {
+            ESP_LOGE(TAG, "Final NVS commit failed on deinit");
+        }
+    }
+    xSemaphoreGive(s_nvs_deinit_sem);
+    s_nvs_ops_task = NULL;
+    vTaskDelete(NULL);
+}

src/relay_chn_output.c

@@ -17,9 +17,9 @@
 static const char *TAG = "RELAY_CHN_OUTPUT";
 
 #if CONFIG_RELAY_CHN_COUNT > 1
-static relay_chn_output_t outputs[CONFIG_RELAY_CHN_COUNT];
+static relay_chn_output_t s_outputs[CONFIG_RELAY_CHN_COUNT];
 #else
-static relay_chn_output_t output;
+static relay_chn_output_t s_output;
 #endif
 
 
@@ -75,13 +75,9 @@ static esp_err_t relay_chn_output_ctl_init(relay_chn_output_t *output,
 #if CONFIG_RELAY_CHN_ENABLE_NVS
 static esp_err_t relay_chn_output_load_direction(uint8_t ch, relay_chn_direction_t *direction)
 {
-    esp_err_t ret = relay_chn_nvs_get_direction(ch, direction);
+    // relay_chn_nvs_get_direction handles the NOT_FOUND case and returns the provided default value.
-    if (ret == ESP_ERR_NVS_NOT_FOUND) {
+    esp_err_t ret = relay_chn_nvs_get_direction(ch, direction, RELAY_CHN_DIRECTION_DEFAULT);
-        // If the key does not exist, use the default direction
+    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to get direction from storage for channel %d: %s", ch, esp_err_to_name(ret));
-        *direction = RELAY_CHN_DIRECTION_DEFAULT;
-    } else if (ret != ESP_OK) {
-        ESP_RETURN_ON_ERROR(ret, TAG, "Failed to get direction from storage for channel %d: %s", ch, esp_err_to_name(ret));
-    }
     return ESP_OK;
 }
 #endif
@@ -94,7 +90,7 @@ esp_err_t relay_chn_output_init(const uint8_t* gpio_map, uint8_t gpio_count)
 
 #if CONFIG_RELAY_CHN_COUNT > 1
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_output_t* output = &outputs[i];
+        relay_chn_output_t* output = &s_outputs[i];
         int gpio_index = i << 1; // gpio_index = i * 2
         gpio_num_t forward_pin = (gpio_num_t) gpio_map[gpio_index];
         gpio_num_t reverse_pin = (gpio_num_t) gpio_map[gpio_index + 1];
@@ -115,7 +111,7 @@ esp_err_t relay_chn_output_init(const uint8_t* gpio_map, uint8_t gpio_count)
     ret = relay_chn_output_load_direction(0, &direction);
     ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load direction from storage for channel %d", 0);
 #endif
-    ret = relay_chn_output_ctl_init(&output, gpio_map[0], gpio_map[1], direction);
+    ret = relay_chn_output_ctl_init(&s_output, gpio_map[0], gpio_map[1], direction);
     ESP_RETURN_ON_ERROR(ret, TAG, "Failed to initialize relay channel");
 #endif
     return ESP_OK;
@@ -131,10 +127,10 @@ void relay_chn_output_deinit()
 {
 #if CONFIG_RELAY_CHN_COUNT > 1
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_output_ctl_deinit(&outputs[i]);
+        relay_chn_output_ctl_deinit(&s_outputs[i]);
     }
 #else
-    relay_chn_output_ctl_deinit(&output);
+    relay_chn_output_ctl_deinit(&s_output);
 #endif // CONFIG_RELAY_CHN_COUNT > 1
 }
 
@@ -144,17 +140,17 @@ relay_chn_output_t *relay_chn_output_get(uint8_t chn_id)
     if (!relay_chn_is_channel_id_valid(chn_id)) {
         return NULL;
     }
-    return &outputs[chn_id];
+    return &s_outputs[chn_id];
 }
 
 relay_chn_output_t *relay_chn_output_get_all(void)
 {
-    return outputs;
+    return s_outputs;
 }
 #else
 relay_chn_output_t *relay_chn_output_get(void)
 {
-    return &output;
+    return &s_output;
 }
 #endif // CONFIG_RELAY_CHN_COUNT > 1
 
@@ -197,7 +193,7 @@ void relay_chn_output_flip(relay_chn_output_t *output)
     uint8_t ch = 0;
 #if CONFIG_RELAY_CHN_COUNT > 1
     for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        if (output == &outputs[i]) {
+        if (output == &s_outputs[i]) {
             ch = i;
             break;
         }

src/relay_chn_run_info.c

@@ -9,21 +9,21 @@
 
 
 #if CONFIG_RELAY_CHN_COUNT > 1
-static relay_chn_run_info_t run_infos[CONFIG_RELAY_CHN_COUNT];
+static relay_chn_run_info_t s_run_infos[CONFIG_RELAY_CHN_COUNT];
 #else
-static relay_chn_run_info_t run_info;
+static relay_chn_run_info_t s_run_info;
 #endif
 
 void relay_chn_run_info_init()
 {
 #if CONFIG_RELAY_CHN_COUNT > 1
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        run_infos[i].last_run_cmd = RELAY_CHN_CMD_NONE;
+        s_run_infos[i].last_run_cmd = RELAY_CHN_CMD_NONE;
-        run_infos[i].last_run_cmd_time_ms = 0;
+        s_run_infos[i].last_run_cmd_time_ms = 0;
     }
 #else
-    run_info.last_run_cmd = RELAY_CHN_CMD_NONE;
+    s_run_info.last_run_cmd = RELAY_CHN_CMD_NONE;
-    run_info.last_run_cmd_time_ms = 0;
+    s_run_info.last_run_cmd_time_ms = 0;
 #endif
 }
 
@@ -33,17 +33,17 @@ relay_chn_run_info_t *relay_chn_run_info_get(uint8_t chn_id)
     if (!relay_chn_is_channel_id_valid(chn_id)) {
         return NULL;
     }
-    return &run_infos[chn_id];
+    return &s_run_infos[chn_id];
 }
 
 relay_chn_run_info_t *relay_chn_run_info_get_all()
 {
-    return run_infos;
+    return s_run_infos;
 }
 #else
 relay_chn_run_info_t *relay_chn_run_info_get()
 {
-    return &run_info;
+    return &s_run_info;
 }
 #endif // CONFIG_RELAY_CHN_COUNT > 1
 

src/relay_chn_tilt.c

@@ -5,6 +5,7 @@
  */
 
 #include "esp_check.h"
+#include "relay_chn.h"
 #include "relay_chn_core.h"
 #include "relay_chn_output.h"
 #include "relay_chn_run_info.h"
@@ -71,9 +72,9 @@ typedef struct relay_chn_tilt_ctl {
 
 
 #if CONFIG_RELAY_CHN_COUNT > 1
-static relay_chn_tilt_ctl_t tilt_ctls[CONFIG_RELAY_CHN_COUNT];
+static relay_chn_tilt_ctl_t s_tilt_ctls[CONFIG_RELAY_CHN_COUNT];
 #else
-static relay_chn_tilt_ctl_t tilt_ctl;
+static relay_chn_tilt_ctl_t s_tilt_ctl;
 #endif
 
 
@@ -103,16 +104,47 @@ static void relay_chn_tilt_start_timer_or_stop(relay_chn_tilt_ctl_t *tilt_ctl, e
     }
 }
 
+/**
+ * @brief Checks if the relay channel can perform the current tilt command.
+ *
+ * This function evaluates whether a tilt command can be executed based on the
+ * channel's history. The rules are as follows:
+ * - Tilting in the same direction as the last full run command (e.g., TILT_FORWARD
+ *   after a FORWARD run) is always allowed.
+ * - Tilting in the opposite direction of the last full run (e.g., TILT_REVERSE
+ *   after a FORWARD run) is only allowed if the tilt counter is greater than zero,
+ *   which indicates that the channel has previously tilted in the primary direction.
+ * - If the channel has not been run before, tilting is not allowed.
+ *
+ * @param tilt_ctl Pointer to the tilt control structure for the channel.
+ * @param tilt_cmd The tilt command to check against.
+ * 
+ * @return true if the tilt command is allowed, false otherwise.
+ */
+static bool relay_chn_can_perform_tilt_cmd(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_tilt_cmd_t tilt_cmd)
+{
+    relay_chn_cmd_t last_run_cmd = relay_chn_run_info_get_last_run_cmd(tilt_ctl->chn_ctl->run_info);
+    if (last_run_cmd == RELAY_CHN_CMD_FORWARD) {
+        return (tilt_cmd == RELAY_CHN_TILT_CMD_FORWARD) ||
+               (tilt_cmd == RELAY_CHN_TILT_CMD_REVERSE && tilt_ctl->tilt_count > 0);
+    } else if (last_run_cmd == RELAY_CHN_CMD_REVERSE) {
+        return (tilt_cmd == RELAY_CHN_TILT_CMD_REVERSE) ||
+               (tilt_cmd == RELAY_CHN_TILT_CMD_FORWARD && tilt_ctl->tilt_count > 0);
+    }
+
+    return false;
+}
+
 // Issue a tilt command to a specific relay channel.
 static void relay_chn_tilt_issue_cmd(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_tilt_cmd_t cmd)
 {
     // TILT_STOP is safe and high priority
     if (cmd == RELAY_CHN_TILT_CMD_STOP) {
-        if (tilt_ctl->chn_ctl->state == RELAY_CHN_STATE_STOPPED) {
+        relay_chn_state_t state = tilt_ctl->chn_ctl->state;
-            return; // Do nothing if already stopped
+        if (state == RELAY_CHN_STATE_TILT_FORWARD || state == RELAY_CHN_STATE_TILT_REVERSE) {
+            // If the command is TILT_STOP, issue it immediately
+            relay_chn_tilt_dispatch_cmd(tilt_ctl, cmd);
         }
-        // If the command is TILT_STOP, issue it immediately
-        relay_chn_tilt_dispatch_cmd(tilt_ctl, cmd);
         return;
     }
 
@@ -127,6 +159,11 @@ static void relay_chn_tilt_issue_cmd(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_t
         return;
     }
 
+    if (!relay_chn_can_perform_tilt_cmd(tilt_ctl, cmd)) {
+        ESP_LOGD(TAG, "Cannot perform tilt command: %d for #%d", cmd, tilt_ctl->chn_ctl->id);
+        return;
+    }
+
     // Set the command that will be processed
     tilt_ctl->cmd = cmd;
     switch (tilt_ctl->chn_ctl->state) {
@@ -184,7 +221,7 @@ static void relay_chn_tilt_issue_cmd(relay_chn_tilt_ctl_t *tilt_ctl, relay_chn_t
             break;
 
         default:
-            ESP_LOGD(TAG, "relay_chn_tilt_issue_cmd: Unexpected relay channel state: %s!", relay_chn_state_str(tilt_ctl->chn_ctl->state));
+            ESP_LOGD(TAG, "relay_chn_tilt_issue_cmd: Unexpected relay channel state: %s!", relay_chn_state_to_str(tilt_ctl->chn_ctl->state));
     }
 }
 
@@ -199,12 +236,17 @@ static void relay_chn_tilt_issue_auto(relay_chn_tilt_ctl_t *tilt_ctl)
     }
 }
 
+uint8_t relay_chn_tilt_get_default_sensitivity()
+{
+    return RELAY_CHN_TILT_DEFAULT_SENSITIVITY;
+}
+
 
 #if CONFIG_RELAY_CHN_COUNT > 1
 static void relay_chn_tilt_issue_cmd_on_all_channels(relay_chn_tilt_cmd_t cmd)
 {
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_tilt_ctl_t* tilt_ctl = &tilt_ctls[i];
+        relay_chn_tilt_ctl_t* tilt_ctl = &s_tilt_ctls[i];
         relay_chn_tilt_issue_cmd(tilt_ctl, cmd);
     }
 }
@@ -212,21 +254,21 @@ static void relay_chn_tilt_issue_cmd_on_all_channels(relay_chn_tilt_cmd_t cmd)
 void relay_chn_tilt_auto(uint8_t chn_id)
 {
     if (relay_chn_is_channel_id_valid(chn_id)) {
-        relay_chn_tilt_issue_auto(&tilt_ctls[chn_id]);
+        relay_chn_tilt_issue_auto(&s_tilt_ctls[chn_id]);
     }
 }
 
 void relay_chn_tilt_auto_all()
 {
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_tilt_issue_auto(&tilt_ctls[i]);
+        relay_chn_tilt_issue_auto(&s_tilt_ctls[i]);
     }
 }
 
 void relay_chn_tilt_forward(uint8_t chn_id)
 {
     if (relay_chn_is_channel_id_valid(chn_id)) {
-        relay_chn_tilt_issue_cmd(&tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_FORWARD);
+        relay_chn_tilt_issue_cmd(&s_tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_FORWARD);
     }
 }
 
@@ -238,7 +280,7 @@ void relay_chn_tilt_forward_all()
 void relay_chn_tilt_reverse(uint8_t chn_id)
 {
     if (relay_chn_is_channel_id_valid(chn_id)) {
-        relay_chn_tilt_issue_cmd(&tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_REVERSE);
+        relay_chn_tilt_issue_cmd(&s_tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_REVERSE);
     }
 }
 
@@ -249,8 +291,8 @@ void relay_chn_tilt_reverse_all()
 
 void relay_chn_tilt_stop(uint8_t chn_id)
 {
-    if (!relay_chn_is_channel_id_valid(chn_id)) {
+    if (relay_chn_is_channel_id_valid(chn_id)) {
-        relay_chn_tilt_dispatch_cmd(&tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_STOP);
+        relay_chn_tilt_dispatch_cmd(&s_tilt_ctls[chn_id], RELAY_CHN_TILT_CMD_STOP);
     }
 }
 
@@ -263,22 +305,22 @@ void relay_chn_tilt_stop_all()
 
 void relay_chn_tilt_auto()
 {
-    relay_chn_tilt_issue_auto(&tilt_ctl);
+    relay_chn_tilt_issue_auto(&s_tilt_ctl);
 }
 
 void relay_chn_tilt_forward()
 {
-    relay_chn_tilt_issue_cmd(&tilt_ctl, RELAY_CHN_TILT_CMD_FORWARD);
+    relay_chn_tilt_issue_cmd(&s_tilt_ctl, RELAY_CHN_TILT_CMD_FORWARD);
 }
 
 void relay_chn_tilt_reverse()
 {
-    relay_chn_tilt_issue_cmd(&tilt_ctl, RELAY_CHN_TILT_CMD_REVERSE);
+    relay_chn_tilt_issue_cmd(&s_tilt_ctl, RELAY_CHN_TILT_CMD_REVERSE);
 }
 
 void relay_chn_tilt_stop()
 {
-    relay_chn_tilt_dispatch_cmd(&tilt_ctl, RELAY_CHN_TILT_CMD_STOP);
+    relay_chn_tilt_issue_cmd(&s_tilt_ctl, RELAY_CHN_TILT_CMD_STOP);
 }
 #endif // CONFIG_RELAY_CHN_COUNT > 1
 
@@ -330,7 +372,7 @@ void relay_chn_tilt_set_sensitivity(uint8_t chn_id, uint8_t sensitivity)
 {
     if (relay_chn_is_channel_id_valid(chn_id)) {
         ADJUST_TILT_SENS_BOUNDARIES(sensitivity);
-        relay_chn_tilt_compute_set_sensitivity(&tilt_ctls[chn_id], sensitivity);
+        relay_chn_tilt_compute_set_sensitivity(&s_tilt_ctls[chn_id], sensitivity);
 
 #if CONFIG_RELAY_CHN_ENABLE_NVS
         relay_chn_nvs_set_tilt_sensitivity(chn_id, sensitivity);
@@ -349,7 +391,7 @@ esp_err_t relay_chn_tilt_set_sensitivity_all(uint8_t *sensitivities)
             break;
         }
         ADJUST_TILT_SENS_BOUNDARIES(*src_sensitivity);
-        relay_chn_tilt_compute_set_sensitivity(&tilt_ctls[i], *src_sensitivity);
+        relay_chn_tilt_compute_set_sensitivity(&s_tilt_ctls[i], *src_sensitivity);
 #if CONFIG_RELAY_CHN_ENABLE_NVS
         relay_chn_nvs_set_tilt_sensitivity(i, *src_sensitivity);
 #endif // CONFIG_RELAY_CHN_ENABLE_NVS
@@ -361,7 +403,7 @@ void relay_chn_tilt_set_sensitivity_all_with(uint8_t sensitivity)
 {
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
         ADJUST_TILT_SENS_BOUNDARIES(sensitivity);
-        relay_chn_tilt_compute_set_sensitivity(&tilt_ctls[i], sensitivity);
+        relay_chn_tilt_compute_set_sensitivity(&s_tilt_ctls[i], sensitivity);
 #if CONFIG_RELAY_CHN_ENABLE_NVS
         relay_chn_nvs_set_tilt_sensitivity(i, sensitivity);
 #endif // CONFIG_RELAY_CHN_ENABLE_NVS
@@ -371,7 +413,7 @@ void relay_chn_tilt_set_sensitivity_all_with(uint8_t sensitivity)
 uint8_t relay_chn_tilt_get_sensitivity(uint8_t chn_id)
 {
     return relay_chn_is_channel_id_valid(chn_id) ?
-           tilt_ctls[chn_id].tilt_timing.sensitivity : 0;
+           s_tilt_ctls[chn_id].tilt_timing.sensitivity : 0;
 }
 
 esp_err_t relay_chn_tilt_get_sensitivity_all(uint8_t *sensitivities)
@@ -384,7 +426,7 @@ esp_err_t relay_chn_tilt_get_sensitivity_all(uint8_t *sensitivities)
             ESP_LOGW(TAG, "get_sensitivity_all: Sensitivites have been copied until channel %d since sensitivities[%d] is NULL", i, i);
             break;
         }
-        *dest_sensitivity = tilt_ctls[i].tilt_timing.sensitivity;
+        *dest_sensitivity = s_tilt_ctls[i].tilt_timing.sensitivity;
     }
     return ESP_OK;
 }
@@ -394,7 +436,7 @@ esp_err_t relay_chn_tilt_get_sensitivity_all(uint8_t *sensitivities)
 void relay_chn_tilt_set_sensitivity(uint8_t sensitivity)
 {
     ADJUST_TILT_SENS_BOUNDARIES(sensitivity);
-    relay_chn_tilt_compute_set_sensitivity(&tilt_ctl, sensitivity);
+    relay_chn_tilt_compute_set_sensitivity(&s_tilt_ctl, sensitivity);
 
 #if CONFIG_RELAY_CHN_ENABLE_NVS
     relay_chn_nvs_set_tilt_sensitivity(0, sensitivity);
@@ -403,7 +445,7 @@ void relay_chn_tilt_set_sensitivity(uint8_t sensitivity)
 
 uint8_t relay_chn_tilt_get_sensitivity()
 {
-    return tilt_ctl.tilt_timing.sensitivity;
+    return s_tilt_ctl.tilt_timing.sensitivity;
 }
 #endif // CONFIG_RELAY_CHN_COUNT > 1
 
@@ -636,24 +678,16 @@ static void relay_chn_tilt_timer_cb(void *arg)
 #if CONFIG_RELAY_CHN_ENABLE_NVS
 static esp_err_t relay_chn_tilt_load_sensitivity(uint8_t ch, uint8_t *sensitivity)
 {
-    esp_err_t ret = relay_chn_nvs_get_tilt_sensitivity(ch, sensitivity);
+    ESP_RETURN_ON_ERROR(relay_chn_nvs_get_tilt_sensitivity(ch, sensitivity, RELAY_CHN_TILT_DEFAULT_SENSITIVITY),
-    if (ret == ESP_ERR_NVS_NOT_FOUND) {
+                        TAG, "Failed to load tilt sensitivity for channel %d", ch);
-        *sensitivity = RELAY_CHN_TILT_DEFAULT_SENSITIVITY;
-        return ESP_OK;
-    }
-    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt sensitivity for channel %d", ch);
     return ESP_OK;
 }
 
 static esp_err_t relay_chn_tilt_load_tilt_count(uint8_t ch, uint16_t *tilt_count)
 {
-    esp_err_t ret = relay_chn_nvs_get_tilt_count(ch, tilt_count);
+    ESP_RETURN_ON_ERROR(relay_chn_nvs_get_tilt_count(ch, tilt_count, 0),
-    if (ret == ESP_ERR_NVS_NOT_FOUND) {
+                        TAG, "Failed to load tilt counters for channel %d", ch);
-        ESP_LOGD(TAG, "relay_chn_tilt_load_tilt_count: No tilt count found in NVS for channel %d, initializing to zero", ch);
+    ESP_LOGD(TAG, "Loaded tilt count for channel %d: %d", ch, *tilt_count);
-        tilt_count = 0;
-        return ESP_OK;
-    }
-    ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt counters for channel %d", ch);
     return ESP_OK;
 }
 #endif // CONFIG_RELAY_CHN_ENABLE_NVS
@@ -710,7 +744,7 @@ esp_err_t relay_chn_tilt_init(relay_chn_ctl_t *chn_ctls)
         sensitivity = RELAY_CHN_TILT_DEFAULT_SENSITIVITY;
         tilt_count = 0;
 #endif // CONFIG_RELAY_CHN_ENABLE_NVS == 1
-        ret = relay_chn_tilt_ctl_init(&tilt_ctls[i], &chn_ctls[i], tilt_count, sensitivity);
+        ret = relay_chn_tilt_ctl_init(&s_tilt_ctls[i], &chn_ctls[i], tilt_count, sensitivity);
         ESP_RETURN_ON_ERROR(ret, TAG, "Failed to init tilt control for channel %d", i);
     }
     return ESP_OK;
@@ -723,7 +757,7 @@ esp_err_t relay_chn_tilt_init(relay_chn_ctl_t *chn_ctls)
     ret = relay_chn_tilt_load_tilt_count(0, &tilt_count);
     ESP_RETURN_ON_ERROR(ret, TAG, "Failed to load tilt count for channel %d", 0);
 #endif // CONFIG_RELAY_CHN_ENABLE_NVS == 1
-    return relay_chn_tilt_ctl_init(&tilt_ctl, chn_ctls, tilt_count, sensitivity);
+    return relay_chn_tilt_ctl_init(&s_tilt_ctl, chn_ctls, tilt_count, sensitivity);
 #endif // CONFIG_RELAY_CHN_COUNT > 1
 }
 
@@ -745,9 +779,9 @@ void relay_chn_tilt_deinit()
 {
 #if CONFIG_RELAY_CHN_COUNT > 1
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_tilt_ctl_deinit(&tilt_ctls[i]);
+        relay_chn_tilt_ctl_deinit(&s_tilt_ctls[i]);
     }
 #else
-    relay_chn_tilt_ctl_deinit(&tilt_ctl);
+    relay_chn_tilt_ctl_deinit(&s_tilt_ctl);
 #endif // CONFIG_RELAY_CHN_COUNT > 1
 }

test_apps/main/CMakeLists.txt

@@ -1,16 +1,18 @@
 # === These files must be included in any case ===
 set(srcs "test_common.c"
+         "test_relay_chn_notify_common.c"
          "test_app_main.c")
 
-set(incdirs ".")
+set(incdirs "."
+            "../../private_include")
 
 # === Selective compilation based on channel count ===
 if(CONFIG_RELAY_CHN_COUNT GREATER 1)
     list(APPEND srcs "test_relay_chn_core_multi.c"
-                     "test_relay_chn_listener_multi.c")
+                     "test_relay_chn_notify_multi.c")
 else()
     list(APPEND srcs "test_relay_chn_core_single.c"
-                     "test_relay_chn_listener_single.c")
+                     "test_relay_chn_notify_single.c")
 endif()
 
 if(CONFIG_RELAY_CHN_ENABLE_TILTING)
@@ -22,7 +24,6 @@ if(CONFIG_RELAY_CHN_ENABLE_TILTING)
 endif()
 
 if(CONFIG_RELAY_CHN_ENABLE_NVS)
-    list(APPEND incdirs "../../private_include")
     list(APPEND srcs "../../src/relay_chn_nvs.c")
     if(CONFIG_RELAY_CHN_COUNT GREATER 1)
         list(APPEND srcs "test_relay_chn_nvs_multi.c")

test_apps/main/test_app_main.c

@@ -1,3 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
 
 #include <stdbool.h>
 #include "esp_log.h"

test_apps/main/test_common.c

@@ -1,4 +1,15 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
 #include "test_common.h"
+#include "relay_chn_ctl.h" // For resetting the channels
+
+#if CONFIG_RELAY_CHN_ENABLE_TILTING
+#include "relay_chn_tilt.h" // For resetting tilt count
+#endif
 
 const char *TEST_TAG = "RELAY_CHN_TEST";
 
@@ -32,36 +43,45 @@ const uint8_t gpio_map[] = {4, 5};
 
 const uint8_t gpio_count = sizeof(gpio_map) / sizeof(gpio_map[0]);
 
+static void reset_channel(relay_chn_ctl_t *ctl)
+{
+    ctl->pending_cmd = RELAY_CHN_CMD_NONE;
+    ctl->state = RELAY_CHN_STATE_IDLE;
+    ctl->output->direction = RELAY_CHN_DIRECTION_DEFAULT;
+    ctl->run_info->last_run_cmd = RELAY_CHN_CMD_NONE;
+    ctl->run_info->last_run_cmd_time_ms = 0;
+    esp_timer_stop(ctl->inertia_timer);
+#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
+    esp_timer_stop(ctl->run_limit_timer);
+    ctl->run_limit_sec = CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC;
+#endif
+#if CONFIG_RELAY_CHN_ENABLE_TILTING
+    relay_chn_tilt_reset_count(ctl->tilt_ctl);
+#endif
+#if CONFIG_RELAY_CHN_COUNT > 1
+    #else
+#endif
+}
+
 void reset_channels_to_defaults()
 {
 #if CONFIG_RELAY_CHN_COUNT > 1
-    relay_chn_stop_all();
+    relay_chn_ctl_t *ctls = relay_chn_ctl_get_all();
-#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
+    TEST_ASSERT_NOT_NULL_MESSAGE(ctls, "reset_channels_to_defaults: relay_chn_ctl_get_all() returned NULL");
-    relay_chn_set_run_limit_all_with(CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC);
-#endif
-    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
-    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state(i));
 
-        // Reset directions
+    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        if (relay_chn_get_direction(i) != RELAY_CHN_DIRECTION_DEFAULT) {
+        relay_chn_ctl_t *ctl = &ctls[i];
-            relay_chn_flip_direction(i);
+        TEST_ASSERT_NOT_NULL_MESSAGE(ctl, "ctl is NULL");
-            TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, relay_chn_get_direction(i));
+        reset_channel(ctl);
-        }
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state(i));
+        TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, relay_chn_get_direction(i));
     }
 #else
-    relay_chn_stop();
+    relay_chn_ctl_t *ctl = relay_chn_ctl_get();
-#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
+    TEST_ASSERT_NOT_NULL_MESSAGE(ctl, "reset_channels_to_defaults: relay_chn_ctl_get() returned NULL");
-    relay_chn_set_run_limit(CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC);
+    reset_channel(ctl);
-#endif
-
-    // Reset direction
-    if (relay_chn_get_direction() != RELAY_CHN_DIRECTION_DEFAULT) {
-        relay_chn_flip_direction();
-        TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, relay_chn_get_direction());
-    }
-    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state());
+    TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, relay_chn_get_direction());
 #endif
 }
 

test_apps/main/test_common.h

@@ -1,3 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
 #pragma once
 
 #include <string.h> // For memset

test_apps/main/test_relay_chn_core_multi.c

@@ -1,19 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
 #include "test_common.h"
 
-relay_chn_state_t states[CONFIG_RELAY_CHN_COUNT], expect_states[CONFIG_RELAY_CHN_COUNT];
+static relay_chn_state_t s_states[CONFIG_RELAY_CHN_COUNT], s_expect_states[CONFIG_RELAY_CHN_COUNT];
-relay_chn_direction_t directions[CONFIG_RELAY_CHN_COUNT], expect_directions[CONFIG_RELAY_CHN_COUNT];
+static relay_chn_direction_t s_directions[CONFIG_RELAY_CHN_COUNT], s_expect_directions[CONFIG_RELAY_CHN_COUNT];
 
 static void test_set_expected_state_all(relay_chn_state_t state)
 {
     for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        expect_states[i] = state;
+        s_expect_states[i] = state;
     }
 }
 
 static void test_set_expected_direction_all(relay_chn_direction_t direction)
 {
     for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        expect_directions[i] = direction;
+        s_expect_directions[i] = direction;
     }
 }
 
@@ -85,7 +91,7 @@ TEST_CASE("Run reverse does nothing if channel id is invalid", "[relay_chn][core
 TEST_CASE("Relay channels run reverse and update state", "[relay_chn][core]")
 {
     for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        relay_chn_run_reverse(i); // relay_chn_run_reverse returns void
+        relay_chn_run_reverse(i);
         vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
         TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state(i));
     }
@@ -142,7 +148,7 @@ TEST_CASE("Relay channels stop and update to FREE state", "[relay_chn][core]")
         TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, relay_chn_get_state(i));
 
         // Now, issue the stop command
-        relay_chn_stop(i); // relay_chn_stop returns void
+        relay_chn_stop(i);
         // Immediately after stop, state should be STOPPED
         vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
         TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state(i));
@@ -195,19 +201,19 @@ TEST_CASE("Multiple channels can operate independently", "[relay_chn][core]")
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state(1)); // Other channel should not be affected
 
     // Start Channel 1 in reverse direction
-    relay_chn_run_reverse(1); // relay_chn_run_reverse returns void
+    relay_chn_run_reverse(1);
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, relay_chn_get_state(0));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state(1));
 
     // Stop Channel 0 and wait for it to become FREE
-    relay_chn_stop(0); // relay_chn_stop returns void
+    relay_chn_stop(0);
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state(0));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state(1)); // Other channel should continue running
 
     // Stop Channel 1 and wait for it to become FREE
-    relay_chn_stop(1); // relay_chn_stop returns void
+    relay_chn_stop(1);
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state(0));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state(1));
@@ -225,24 +231,24 @@ TEST_CASE("Forward to Reverse transition with opposite inertia", "[relay_chn][co
     // 1. Start in forward direction
     relay_chn_run_forward_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Short delay for state stabilization
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_FORWARD);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 
     // 2. Issue reverse command
-    relay_chn_run_reverse_all(); // relay_chn_run_reverse returns void
+    relay_chn_run_reverse_all();
     // Immediately after the command, the motor should be stopped
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_REVERSE_PENDING);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 
     // Wait for the inertia period (after which the reverse command will be dispatched)
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     // Should now be in reverse state
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_REVERSE);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 }
 
 // TEST_CASE: Test transition from reverse to forward with inertia and state checks
@@ -250,24 +256,24 @@ TEST_CASE("Forward to Reverse transition with opposite inertia", "[relay_chn][co
 TEST_CASE("Reverse to Forward transition with opposite inertia", "[relay_chn][core][inertia]")
 {
     // 1. Start in reverse direction
-    relay_chn_run_reverse_all(); // relay_chn_run_reverse returns void
+    relay_chn_run_reverse_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_REVERSE);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 
     // 2. Issue forward command
     relay_chn_run_forward_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_FORWARD_PENDING);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 
     // Wait for inertia
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_FORWARD);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 }
 
 // TEST_CASE: Test issuing the same run command while already running (no inertia expected)
@@ -277,18 +283,18 @@ TEST_CASE("Running in same direction does not incur inertia", "[relay_chn][core]
     // 1. Start in forward direction
     relay_chn_run_forward_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_FORWARD);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 
     // 2. Issue the same forward command again
     relay_chn_run_forward_all();
     // As per the code, is_direction_opposite_to_current_motion should return false, so no inertia.
     // Just a short delay to check state remains the same.
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_FORWARD);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 }
 
 // ### Direction Flipping Tests
@@ -330,44 +336,44 @@ TEST_CASE("All channels direction can be flipped simultaneously", "[relay_chn][c
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
     // 2. Verify all channels are flipped
-    TEST_ESP_OK(relay_chn_get_direction_all(directions));
+    TEST_ESP_OK(relay_chn_get_direction_all(s_directions));
     test_set_expected_direction_all(RELAY_CHN_DIRECTION_FLIPPED);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_directions, directions, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_directions, s_directions, CONFIG_RELAY_CHN_COUNT);
 
     // 3. Flip all back
     relay_chn_flip_direction_all();
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
     // 4. Verify all channels are back to default
-    TEST_ESP_OK(relay_chn_get_direction_all(directions));
+    TEST_ESP_OK(relay_chn_get_direction_all(s_directions));
     test_set_expected_direction_all(RELAY_CHN_DIRECTION_DEFAULT);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_directions, directions, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_directions, s_directions, CONFIG_RELAY_CHN_COUNT);
 }
 
 TEST_CASE("Flipping a running channel stops it and flips direction", "[relay_chn][core][direction]")
 {
     // 1. Start channel running and verify state
     relay_chn_run_forward_all();
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_FORWARD);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
     // 2. Flip the direction while running
     relay_chn_flip_direction_all();
     // 3. The channel should stop as part of the flip process
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_STOPPED);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 
     // 4. Wait for the flip inertia to pass, after which it should be idle and FLIPPED
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_IDLE);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 
-    TEST_ESP_OK(relay_chn_get_direction_all(directions));
+    TEST_ESP_OK(relay_chn_get_direction_all(s_directions));
     test_set_expected_direction_all(RELAY_CHN_DIRECTION_FLIPPED);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_directions, directions, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_directions, s_directions, CONFIG_RELAY_CHN_COUNT);
 }
 
 TEST_CASE("Direction flip handles invalid channel ID gracefully", "[relay_chn][core][direction]")
@@ -381,7 +387,7 @@ TEST_CASE("Direction flip handles invalid channel ID gracefully", "[relay_chn][c
 TEST_CASE("get_state_all retrieves all channel states", "[relay_chn][core][batch]")
 {
     // 1. All should be IDLE initially
-    TEST_ESP_OK(relay_chn_get_state_all(states));
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
     test_set_expected_state_all(RELAY_CHN_STATE_IDLE);
 
     // 2. Set some states
@@ -397,29 +403,30 @@ TEST_CASE("get_state_all retrieves all channel states", "[relay_chn][core][batch
     // 3. Get all states and verify
     for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
         if (i % 2 == 0) {
-            expect_states[i] = RELAY_CHN_STATE_FORWARD;
+            s_expect_states[i] = RELAY_CHN_STATE_FORWARD;
         } else {
-            expect_states[i] = RELAY_CHN_STATE_REVERSE;
+            s_expect_states[i] = RELAY_CHN_STATE_REVERSE;
         }
     }
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_states, states, CONFIG_RELAY_CHN_COUNT);
+    TEST_ESP_OK(relay_chn_get_state_all(s_states));
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_states, s_states, CONFIG_RELAY_CHN_COUNT);
 }
 
 TEST_CASE("get_direction_all retrieves all channel directions", "[relay_chn][core][direction][batch]")
 {
      // 1. All should be default initially
-    TEST_ESP_OK(relay_chn_get_direction_all(directions));
+    TEST_ESP_OK(relay_chn_get_direction_all(s_directions));
     test_set_expected_direction_all(RELAY_CHN_DIRECTION_DEFAULT);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_directions, directions, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_directions, s_directions, CONFIG_RELAY_CHN_COUNT);
 
     // 2. Flip all
     relay_chn_flip_direction_all();
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
     // 3. Get all directions and verify
-    TEST_ESP_OK(relay_chn_get_direction_all(directions));
+    TEST_ESP_OK(relay_chn_get_direction_all(s_directions));
     test_set_expected_direction_all(RELAY_CHN_DIRECTION_FLIPPED);
-    TEST_ASSERT_EQUAL_UINT_ARRAY(expect_directions, directions, CONFIG_RELAY_CHN_COUNT);
+    TEST_ASSERT_EQUAL_UINT_ARRAY(s_expect_directions, s_directions, CONFIG_RELAY_CHN_COUNT);
 }
 
 TEST_CASE("get_all functions handle NULL arguments", "[relay_chn][core][batch]")
@@ -485,13 +492,15 @@ TEST_CASE("Test run limit stops channel after timeout", "[relay_chn][run_limit]"
 
 TEST_CASE("Test run limit reset on direction change and time out finally", "[relay_chn][run_limit]")
 {
-    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+    relay_chn_set_run_limit_all_with(TEST_SHORT_RUN_LIMIT_SEC);
-        // Set a short run limit
-        relay_chn_set_run_limit(i, TEST_SHORT_RUN_LIMIT_SEC);
 
-        // Start running forward
+#if CONFIG_RELAY_CHN_ENABLE_NVS
-        relay_chn_run_forward(i);
+    // Wait for the NVS module task to process operations
-    }
+    vTaskDelay(300 / portTICK_PERIOD_MS); // Wait 1 second
+#endif
+
+    // Start running forward
+    relay_chn_run_forward_all();
 
     vTaskDelay(1000 / portTICK_PERIOD_MS); // Wait 1 second
 

test_apps/main/test_relay_chn_core_single.c

@@ -1,3 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
 #include "test_common.h"
 
 
@@ -38,7 +44,7 @@ TEST_CASE("Relay channels run forward and update state", "[relay_chn][core]")
 // TEST_CASE: Test that relays run in the reverse direction and update their state
 TEST_CASE("Relay channels run reverse and update state", "[relay_chn][core]")
 {
-    relay_chn_run_reverse(); // relay_chn_run_reverse returns void
+    relay_chn_run_reverse();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state());
 }
@@ -54,7 +60,7 @@ TEST_CASE("Relay channels stop and update to IDLE state", "[relay_chn][core]")
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, relay_chn_get_state());
 
     // Now, issue the stop command
-    relay_chn_stop(); // relay_chn_stop returns void
+    relay_chn_stop();
     // Immediately after stop, state should be STOPPED
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_STOPPED, relay_chn_get_state());
@@ -79,7 +85,7 @@ TEST_CASE("Forward to Reverse transition with opposite inertia", "[relay_chn][co
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, relay_chn_get_state());
 
     // 2. Issue reverse command
-    relay_chn_run_reverse(); // relay_chn_run_reverse returns void
+    relay_chn_run_reverse();
     // Immediately after the command, the motor should be stopped
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE_PENDING, relay_chn_get_state());
@@ -94,7 +100,7 @@ TEST_CASE("Forward to Reverse transition with opposite inertia", "[relay_chn][co
 TEST_CASE("Reverse to Forward transition with opposite inertia", "[relay_chn][core][inertia]")
 {
     // 1. Start in reverse direction
-    relay_chn_run_reverse(); // relay_chn_run_reverse returns void
+    relay_chn_run_reverse();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state());
 

test_apps/main/test_relay_chn_listener_multi.c

@@ -1,127 +0,0 @@
-#include "test_common.h"
-
-
-// --- Listener Test Globals ---
-typedef struct {
-    uint8_t chn_id;
-    relay_chn_state_t old_state;
-    relay_chn_state_t new_state;
-    int call_count;
-} listener_callback_info_t;
-
-static listener_callback_info_t listener1_info;
-static listener_callback_info_t listener2_info;
-
-// --- Listener Test Helper Functions ---
-
-// Clear the memory from possible garbage values
-static void reset_listener_info(listener_callback_info_t* info) {
-    memset(info, 0, sizeof(listener_callback_info_t));
-}
-
-static void test_listener_1(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
-    listener1_info.chn_id = chn_id;
-    listener1_info.old_state = old_state;
-    listener1_info.new_state = new_state;
-    listener1_info.call_count++;
-}
-
-static void test_listener_2(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
-    listener2_info.chn_id = chn_id;
-    listener2_info.old_state = old_state;
-    listener2_info.new_state = new_state;
-    listener2_info.call_count++;
-}
-
-// ### Listener Functionality Tests
-
-TEST_CASE("Listener is called on state change", "[relay_chn][listener]")
-{
-    uint8_t ch = 0;
-    reset_listener_info(&listener1_info);
-
-    // 1. Register the listener
-    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
-
-    // 2. Trigger a state change
-    relay_chn_run_forward(ch);
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow event to be processed
-
-    // 3. Verify the listener was called with correct parameters
-    TEST_ASSERT_EQUAL(1, listener1_info.call_count);
-    TEST_ASSERT_EQUAL(ch, listener1_info.chn_id);
-    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, listener1_info.old_state);
-    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, listener1_info.new_state);
-
-    // 4. Unregister to clean up
-    relay_chn_unregister_listener(test_listener_1);
-}
-
-TEST_CASE("Unregistered listener is not called", "[relay_chn][listener]")
-{
-    uint8_t ch = 0;
-    reset_listener_info(&listener1_info);
-
-    // 1. Register and then immediately unregister the listener
-    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
-    relay_chn_unregister_listener(test_listener_1);
-
-    // 2. Trigger a state change
-    relay_chn_run_forward(ch);
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-
-    // 3. Verify the listener was NOT called
-    TEST_ASSERT_EQUAL(0, listener1_info.call_count);
-}
-
-TEST_CASE("Multiple listeners are called on state change", "[relay_chn][listener]")
-{
-    uint8_t ch = 0;
-    reset_listener_info(&listener1_info);
-    reset_listener_info(&listener2_info);
-
-    // 1. Register two different listeners
-    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
-    TEST_ESP_OK(relay_chn_register_listener(test_listener_2));
-
-    // 2. Trigger a state change
-    relay_chn_run_forward(ch);
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-
-    // 3. Verify listener 1 was called correctly
-    TEST_ASSERT_EQUAL(1, listener1_info.call_count);
-    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, listener1_info.old_state);
-    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, listener1_info.new_state);
-
-    // 4. Verify listener 2 was also called correctly
-    TEST_ASSERT_EQUAL(1, listener2_info.call_count);
-    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, listener2_info.old_state);
-    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, listener2_info.new_state);
-
-    // 5. Clean up
-    relay_chn_unregister_listener(test_listener_1);
-    relay_chn_unregister_listener(test_listener_2);
-}
-
-TEST_CASE("Listener registration handles invalid arguments and duplicates", "[relay_chn][listener]")
-{
-    reset_listener_info(&listener1_info);
-
-    // 1. Registering a NULL listener should fail
-    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_register_listener(NULL));
-
-    // 2. Unregistering a NULL listener should not crash
-    relay_chn_unregister_listener(NULL);
-
-    // 3. Registering the same listener twice should be handled gracefully
-    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
-    TEST_ESP_OK(relay_chn_register_listener(test_listener_1)); // Second call should be a no-op
-
-    // 4. Trigger a state change and verify the listener is only called ONCE
-    relay_chn_run_forward(0);
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-    TEST_ASSERT_EQUAL(1, listener1_info.call_count);
-
-    // 5. Clean up
-    relay_chn_unregister_listener(test_listener_1);
-}

test_apps/main/test_relay_chn_notify_common.c

@@ -0,0 +1,55 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include "test_relay_chn_notify_common.h"
+
+listener_callback_info_t listener1_info;
+listener_callback_info_t listener2_info;
+
+// --- Globals for Advanced Tests ---
+SemaphoreHandle_t blocking_listener_sem = NULL;
+SemaphoreHandle_t log_check_sem = NULL;
+volatile int blocking_listener_call_count = 0;
+vprintf_like_t original_vprintf = NULL;
+
+// --- Listener Test Helper Functions ---
+
+// Clear the memory from possible garbage values
+void reset_listener_info(listener_callback_info_t* info) {
+    memset(info, 0, sizeof(listener_callback_info_t));
+}
+
+void test_listener_1(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
+    listener1_info.chn_id = chn_id;
+    listener1_info.old_state = old_state;
+    listener1_info.new_state = new_state;
+    listener1_info.call_count++;
+}
+
+void test_listener_2(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
+    listener2_info.chn_id = chn_id;
+    listener2_info.old_state = old_state;
+    listener2_info.new_state = new_state;
+    listener2_info.call_count++;
+}
+
+void blocking_listener(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
+    blocking_listener_call_count++;
+    // Block until the main test task unblocks us
+    xSemaphoreTake(blocking_listener_sem, portMAX_DELAY);
+}
+
+int log_check_vprintf(const char *format, va_list args) {
+    // Buffer to hold the formatted log message
+    char buffer[256];
+    vsnprintf(buffer, sizeof(buffer), format, args);
+
+    if (strstr(buffer, "Notify queue is full")) {
+        xSemaphoreGive(log_check_sem);
+    }
+
+    return original_vprintf(format, args);
+}

test_apps/main/test_relay_chn_notify_common.h

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+#include "test_common.h"
+#include "freertos/semphr.h"
+#include <stdarg.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// This is defined in the source file, we redefine it here for the test.
+// The test build must have the same CONFIG_RELAY_CHN_COUNT.
+#define TEST_RELAY_CHN_NOTIFY_QUEUE_LEN  (16 + CONFIG_RELAY_CHN_COUNT * 4)
+
+// --- Listener Test Globals ---
+typedef struct {
+    uint8_t chn_id;
+    relay_chn_state_t old_state;
+    relay_chn_state_t new_state;
+    int call_count;
+} listener_callback_info_t;
+
+// --- Listener callback infos to be defined ---
+extern listener_callback_info_t listener1_info;
+extern listener_callback_info_t listener2_info;
+
+// --- Globals for Advanced Tests ---
+extern SemaphoreHandle_t blocking_listener_sem;
+extern SemaphoreHandle_t log_check_sem;
+extern volatile int blocking_listener_call_count;
+extern vprintf_like_t original_vprintf;
+
+
+// --- Listener Test Helper Functions ---
+
+// Clear the memory from possible garbage values
+void reset_listener_info(listener_callback_info_t* info);
+
+// State listeners for notify module testing
+void test_listener_1(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state);
+void test_listener_2(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state);
+void blocking_listener(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state);
+
+int log_check_vprintf(const char *format, va_list args);
+
+#ifdef __cplusplus
+}
+#endif

test_apps/main/test_relay_chn_notify_multi.c

@@ -0,0 +1,172 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#include "test_relay_chn_notify_common.h"
+
+// This is a private header, but we need it for direct notification calls and queue length.
+// It's included conditionally in the build via CMakeLists.txt when NVS is enabled.
+#include "relay_chn_notify.h"
+
+// ### Listener Functionality Tests
+
+TEST_CASE("Listener is called on state change for each channel", "[relay_chn][notify]")
+{
+    // 1. Register the listener and reset info
+    reset_listener_info(&listener1_info);
+    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow registration to be processed
+
+    // Loop through each channel
+    for (uint8_t ch = 0; ch < CONFIG_RELAY_CHN_COUNT; ch++) {
+        // 2. Trigger a state change on the current channel.
+        // tearDown() ensures each channel starts as IDLE.
+        relay_chn_run_forward(ch);
+        vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow event to be processed
+
+        // 3. Verify the listener was called with correct parameters for this channel.
+        // The listener_info struct is overwritten each time, but we check it before the next iteration.
+        TEST_ASSERT_EQUAL(ch, listener1_info.chn_id);
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, listener1_info.old_state);
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, listener1_info.new_state);
+    }
+
+    // 4. Verify the total call count after the loop
+    TEST_ASSERT_EQUAL(CONFIG_RELAY_CHN_COUNT, listener1_info.call_count);
+
+    // 5. Unregister to clean up
+    relay_chn_unregister_listener(test_listener_1);
+}
+
+TEST_CASE("Unregistered listener is not called for any channel", "[relay_chn][notify]")
+{
+    reset_listener_info(&listener1_info);
+
+    // 1. Register and then immediately unregister the listener
+    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
+    relay_chn_unregister_listener(test_listener_1);
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow commands to process
+
+    // 2. Trigger a state change on all channels
+    relay_chn_run_forward_all();
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS * CONFIG_RELAY_CHN_COUNT)); // Allow all events to be processed
+
+    // 3. Verify the listener was NOT called
+    TEST_ASSERT_EQUAL(0, listener1_info.call_count);
+}
+
+TEST_CASE("Multiple listeners are called on state change for each channel", "[relay_chn][notify]")
+{
+    // 1. Register listeners and reset info
+    reset_listener_info(&listener1_info);
+    reset_listener_info(&listener2_info);
+    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
+    TEST_ESP_OK(relay_chn_register_listener(test_listener_2));
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow registration commands to be processed
+
+    // Loop through each channel
+    for (uint8_t ch = 0; ch < CONFIG_RELAY_CHN_COUNT; ch++) {
+        // 2. Trigger a state change on the current channel
+        relay_chn_run_forward(ch);
+        vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+
+        // 3. Verify listener 1 was called correctly for this channel
+        TEST_ASSERT_EQUAL(ch, listener1_info.chn_id);
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, listener1_info.old_state);
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, listener1_info.new_state);
+
+        // 4. Verify listener 2 was also called correctly for this channel
+        TEST_ASSERT_EQUAL(ch, listener2_info.chn_id);
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, listener2_info.old_state);
+        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_FORWARD, listener2_info.new_state);
+    }
+
+    // 5. Verify total call counts
+    TEST_ASSERT_EQUAL(CONFIG_RELAY_CHN_COUNT, listener1_info.call_count);
+    TEST_ASSERT_EQUAL(CONFIG_RELAY_CHN_COUNT, listener2_info.call_count);
+
+    // 6. Clean up
+    relay_chn_unregister_listener(test_listener_1);
+    relay_chn_unregister_listener(test_listener_2);
+}
+
+TEST_CASE("Listener registration handles invalid arguments and duplicates", "[relay_chn][notify]")
+{
+    reset_listener_info(&listener1_info);
+
+    // 1. Registering a NULL listener should fail
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_register_listener(NULL));
+
+    // 2. Unregistering a NULL listener should not crash
+    relay_chn_unregister_listener(NULL);
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow commands to process
+
+    // 3. Registering the same listener twice should be handled gracefully
+    TEST_ESP_OK(relay_chn_register_listener(test_listener_1));
+    TEST_ESP_OK(relay_chn_register_listener(test_listener_1)); // Second call should be a no-op
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow registration commands to be processed
+
+    // 4. Trigger a state change on all channels and verify the listener is only called ONCE per channel
+    relay_chn_run_forward_all();
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS * CONFIG_RELAY_CHN_COUNT)); // Allow all events to be processed
+    TEST_ASSERT_EQUAL(CONFIG_RELAY_CHN_COUNT, listener1_info.call_count);
+
+    // 5. Clean up
+    relay_chn_unregister_listener(test_listener_1);
+}
+
+TEST_CASE("Notify queue full scenario is handled gracefully", "[relay_chn][notify]")
+{
+    // 1. Setup
+    blocking_listener_sem = xSemaphoreCreateBinary();
+    log_check_sem = xSemaphoreCreateBinary();
+    blocking_listener_call_count = 0;
+
+    // Intercept logs to check for the "queue full" warning
+    original_vprintf = esp_log_set_vprintf(log_check_vprintf);
+
+    // 2. Register a listener that will block, allowing the queue to fill up
+    TEST_ESP_OK(relay_chn_register_listener(blocking_listener));
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow task to start
+
+    // 3. Fill the queue. The first event will be consumed immediately by the dispatcher,
+    // which will then call the blocking_listener and block. The remaining (LEN - 1)
+    // events will sit in the queue, leaving one empty slot.
+    // Use different channel IDs to make the test more robust.
+    for (int i = 0; i < TEST_RELAY_CHN_NOTIFY_QUEUE_LEN; i++) {
+        uint8_t ch = i % CONFIG_RELAY_CHN_COUNT;
+        TEST_ESP_OK(relay_chn_notify_state_change(ch, RELAY_CHN_STATE_IDLE, RELAY_CHN_STATE_FORWARD));
+    }
+
+    // 4. Send one more event to fill the last slot in the queue. This should succeed.
+    TEST_ESP_OK(relay_chn_notify_state_change(0, RELAY_CHN_STATE_IDLE, RELAY_CHN_STATE_FORWARD)); // Use any valid channel
+
+    // 5. Now the queue is full. Trigger one more event to cause an overflow.
+    // This call should fail and log the warning.
+    TEST_ASSERT_EQUAL(ESP_FAIL, relay_chn_notify_state_change(1 % CONFIG_RELAY_CHN_COUNT, RELAY_CHN_STATE_IDLE, RELAY_CHN_STATE_FORWARD));
+
+    // 6. Wait for the "queue full" log message to be captured by our vprintf hook
+    TEST_ASSERT_TRUE_MESSAGE(xSemaphoreTake(log_check_sem, pdMS_TO_TICKS(1000)) == pdTRUE, "Did not receive 'queue full' log message");
+
+    // 7. Unblock the listener so it can process all queued items.
+    // There was 1 initial event + QUEUE_LEN events that were successfully queued.
+    for (int i = 0; i < TEST_RELAY_CHN_NOTIFY_QUEUE_LEN + 1; i++) {
+        xSemaphoreGive(blocking_listener_sem);
+        // Give the dispatcher task a moment to process one item from the queue
+        vTaskDelay(pdMS_TO_TICKS(10));
+    }
+
+    // 8. Verify the listener was called exactly QUEUE_LEN + 1 times
+    TEST_ASSERT_EQUAL_INT(TEST_RELAY_CHN_NOTIFY_QUEUE_LEN + 1, blocking_listener_call_count);
+
+    // 9. Cleanup
+    esp_log_set_vprintf(original_vprintf);
+    relay_chn_unregister_listener(blocking_listener);
+    vSemaphoreDelete(blocking_listener_sem);
+    vSemaphoreDelete(log_check_sem);
+    blocking_listener_sem = NULL;
+    log_check_sem = NULL;
+    original_vprintf = NULL;
+}

test_apps/main/test_relay_chn_notify_single.c

@@ -1,40 +1,18 @@
-#include "test_common.h"
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
 
+#include "test_relay_chn_notify_common.h"
 
-// --- Listener Test Globals ---
+// This is a private header, but we need it for direct notification calls and queue length.
-typedef struct {
+// It's included conditionally in the build via CMakeLists.txt when NVS is enabled.
-    relay_chn_state_t old_state;
+#include "relay_chn_notify.h"
-    relay_chn_state_t new_state;
-    int call_count;
-} listener_callback_info_t;
-
-static listener_callback_info_t listener1_info;
-static listener_callback_info_t listener2_info;
-
-// --- Listener Test Helper Functions ---
-
-// Clear the memory from possible garbage values
-static void reset_listener_info(listener_callback_info_t* info) {
-    memset(info, 0, sizeof(listener_callback_info_t));
-}
-
-static void test_listener_1(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
-    /* Just ignore the channel id */
-    listener1_info.old_state = old_state;
-    listener1_info.new_state = new_state;
-    listener1_info.call_count++;
-}
-
-static void test_listener_2(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
-    /* Just ignore the channel id */
-    listener2_info.old_state = old_state;
-    listener2_info.new_state = new_state;
-    listener2_info.call_count++;
-}
 
 // ### Listener Functionality Tests
 
-TEST_CASE("Listener is called on state change", "[relay_chn][listener]")
+TEST_CASE("Listener is called on state change", "[relay_chn][notify]")
 {
     reset_listener_info(&listener1_info);
 
@@ -54,7 +32,7 @@ TEST_CASE("Listener is called on state change", "[relay_chn][listener]")
     relay_chn_unregister_listener(test_listener_1);
 }
 
-TEST_CASE("Unregistered listener is not called", "[relay_chn][listener]")
+TEST_CASE("Unregistered listener is not called", "[relay_chn][notify]")
 {
     reset_listener_info(&listener1_info);
 
@@ -70,7 +48,7 @@ TEST_CASE("Unregistered listener is not called", "[relay_chn][listener]")
     TEST_ASSERT_EQUAL(0, listener1_info.call_count);
 }
 
-TEST_CASE("Multiple listeners are called on state change", "[relay_chn][listener]")
+TEST_CASE("Multiple listeners are called on state change", "[relay_chn][notify]")
 {
     reset_listener_info(&listener1_info);
     reset_listener_info(&listener2_info);
@@ -98,7 +76,7 @@ TEST_CASE("Multiple listeners are called on state change", "[relay_chn][listener
     relay_chn_unregister_listener(test_listener_2);
 }
 
-TEST_CASE("Listener registration handles invalid arguments and duplicates", "[relay_chn][listener]")
+TEST_CASE("Listener registration handles invalid arguments and duplicates", "[relay_chn][notify]")
 {
     reset_listener_info(&listener1_info);
 
@@ -120,3 +98,55 @@ TEST_CASE("Listener registration handles invalid arguments and duplicates", "[re
     // 5. Clean up
     relay_chn_unregister_listener(test_listener_1);
 }
+
+TEST_CASE("Notify queue full scenario is handled gracefully", "[relay_chn][notify]")
+{
+    // 1. Setup
+    blocking_listener_sem = xSemaphoreCreateBinary();
+    log_check_sem = xSemaphoreCreateBinary();
+    blocking_listener_call_count = 0;
+
+    // Intercept logs to check for the "queue full" warning
+    original_vprintf = esp_log_set_vprintf(log_check_vprintf);
+
+    // 2. Register a listener that will block, allowing the queue to fill up
+    TEST_ESP_OK(relay_chn_register_listener(blocking_listener));
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow task to start
+
+    // 3. Fill the queue. The first event will be consumed immediately by the dispatcher,
+    // which will then call the blocking_listener and block. The remaining (LEN - 1)
+    // events will sit in the queue, leaving one empty slot.
+    for (int i = 0; i < TEST_RELAY_CHN_NOTIFY_QUEUE_LEN; i++) {
+        TEST_ESP_OK(relay_chn_notify_state_change(0, RELAY_CHN_STATE_IDLE, RELAY_CHN_STATE_FORWARD));
+    }
+
+    // 4. Send one more event to fill the last slot in the queue. This should succeed.
+    TEST_ESP_OK(relay_chn_notify_state_change(0, RELAY_CHN_STATE_IDLE, RELAY_CHN_STATE_FORWARD));
+
+    // 5. Now the queue is full. Trigger one more event to cause an overflow.
+    // This call should fail and log the warning.
+    TEST_ASSERT_EQUAL(ESP_FAIL, relay_chn_notify_state_change(0, RELAY_CHN_STATE_IDLE, RELAY_CHN_STATE_FORWARD));
+
+    // 6. Wait for the "queue full" log message to be captured by our vprintf hook
+    TEST_ASSERT_TRUE_MESSAGE(xSemaphoreTake(log_check_sem, pdMS_TO_TICKS(1000)) == pdTRUE, "Did not receive 'queue full' log message");
+
+    // 7. Unblock the listener so it can process all queued items.
+    // There was 1 initial event + QUEUE_LEN events that were successfully queued.
+    for (int i = 0; i < TEST_RELAY_CHN_NOTIFY_QUEUE_LEN + 1; i++) {
+        xSemaphoreGive(blocking_listener_sem);
+        // Give the dispatcher task a moment to process one item from the queue
+        vTaskDelay(pdMS_TO_TICKS(10));
+    }
+
+    // 8. Verify the listener was called exactly QUEUE_LEN + 1 times
+    TEST_ASSERT_EQUAL_INT(TEST_RELAY_CHN_NOTIFY_QUEUE_LEN + 1, blocking_listener_call_count);
+
+    // 9. Cleanup
+    esp_log_set_vprintf(original_vprintf);
+    relay_chn_unregister_listener(blocking_listener);
+    vSemaphoreDelete(blocking_listener_sem);
+    vSemaphoreDelete(log_check_sem);
+    blocking_listener_sem = NULL;
+    log_check_sem = NULL;
+    original_vprintf = NULL;
+}

test_apps/main/test_relay_chn_nvs_multi.c

@@ -9,144 +9,181 @@
 #include "esp_system.h"
 #include "nvs_flash.h"
 #include "relay_chn_nvs.h"
+#include "test_common.h"
 
-TEST_CASE("Test relay storage init/deinit", "[relay_chn][nvs]")
+#define TEST_NVS_TASK_TIME_OUT_MS 300
-{
-    TEST_ESP_OK(relay_chn_nvs_init());
-    TEST_ESP_OK(relay_chn_nvs_deinit());
-}
 
 TEST_CASE("Test direction setting and getting", "[relay_chn][nvs]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     // Test all channels
-    relay_chn_direction_t dir;
+    relay_chn_direction_t dir, expect;
-    relay_chn_direction_t test_directions[] = {
-        RELAY_CHN_DIRECTION_DEFAULT,
-        RELAY_CHN_DIRECTION_FLIPPED
-    };
 
-    for (int channel = 0; channel < 2; channel++) {
+    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-        TEST_ESP_OK(relay_chn_nvs_set_direction(channel, test_directions[channel]));
+        dir = channel % 2 == 0 ? RELAY_CHN_DIRECTION_DEFAULT : RELAY_CHN_DIRECTION_FLIPPED;
-        TEST_ESP_OK(relay_chn_nvs_get_direction(channel, &dir));
+        TEST_ESP_OK(relay_chn_nvs_set_direction(channel, dir));
-        TEST_ASSERT_EQUAL(test_directions[channel], dir);
     }
 
-    TEST_ESP_OK(relay_chn_nvs_deinit());
+    // Wait for the batch commit timeout to ensure the value is written
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS));
+
+    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
+        expect = channel % 2 == 0 ? RELAY_CHN_DIRECTION_DEFAULT : RELAY_CHN_DIRECTION_FLIPPED;
+        TEST_ESP_OK(relay_chn_nvs_get_direction(channel, &dir, RELAY_CHN_DIRECTION_DEFAULT));
+        TEST_ASSERT_EQUAL(expect, dir);
+    }
 }
 
 TEST_CASE("Test invalid parameters", "[relay_chn][nvs]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     // Test NULL pointer for all channels
     for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-        TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_direction(channel, NULL));
+        TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_direction(channel, NULL, RELAY_CHN_DIRECTION_DEFAULT));
     }
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 
 TEST_CASE("Test relay_chn_nvs_erase_all", "[relay_chn][nvs]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-
     // Store some test data first
-    relay_chn_direction_t direction = RELAY_CHN_DIRECTION_FLIPPED;
     for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-        TEST_ESP_OK(relay_chn_nvs_set_direction(0, direction));
+        // Set direction for all channels
-    }
+        TEST_ESP_OK(relay_chn_nvs_set_direction(channel, RELAY_CHN_DIRECTION_FLIPPED));
+
+#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
+        TEST_ESP_OK(relay_chn_nvs_set_run_limit(channel, 100 + channel));
+#endif
 
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
-    uint8_t sensitivity = 50;
+        TEST_ESP_OK(relay_chn_nvs_set_tilt_sensitivity(channel, 50));
-    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
+        TEST_ESP_OK(relay_chn_nvs_set_tilt_count(channel, 100 + channel));
-        TEST_ESP_OK(relay_chn_nvs_set_tilt_sensitivity(0, sensitivity));
-        TEST_ESP_OK(relay_chn_nvs_set_tilt_count(0, 100));
     }
 #endif
 
+    // Wait for the set operations and subsequent commits to complete
+    // Wait 4 times more since 4 x 8 = 32 operations to process
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS * 8));
+
     // Test erase all
     TEST_ESP_OK(relay_chn_nvs_erase_all());
 
+    // Wait for the erase operation and subsequent commit to complete
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS));
     // Verify data was erased by trying to read it back
-    relay_chn_direction_t read_direction;
+    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-    TEST_ASSERT_EQUAL(ESP_ERR_NVS_NOT_FOUND, relay_chn_nvs_get_direction(0, &read_direction));
+        relay_chn_direction_t read_direction;
+        TEST_ESP_OK(relay_chn_nvs_get_direction(0, &read_direction, RELAY_CHN_DIRECTION_DEFAULT));
+        TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, read_direction);
+    }
 
-#if CONFIG_RELAY_CHN_ENABLE_TILTING
+#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
-    uint8_t read_sensitivity;
+    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-    TEST_ASSERT_EQUAL(ESP_ERR_NVS_NOT_FOUND, relay_chn_nvs_get_tilt_sensitivity(0, &read_sensitivity));
+        uint16_t read_run_limit;
-
+        TEST_ESP_OK(relay_chn_nvs_get_run_limit(channel, &read_run_limit, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC));
-    uint16_t tilt_count;
+        TEST_ASSERT_EQUAL(CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC, read_run_limit);
-    TEST_ASSERT_EQUAL(ESP_ERR_NVS_NOT_FOUND, relay_chn_nvs_get_tilt_count(0, &tilt_count));
+    }
 #endif
 
-    TEST_ESP_OK(relay_chn_nvs_deinit());
+#if CONFIG_RELAY_CHN_ENABLE_TILTING
+    const uint8_t default_sensitivity_for_test = 42;
+    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
+        uint8_t read_sensitivity;
+        TEST_ESP_OK(relay_chn_nvs_get_tilt_sensitivity(channel, &read_sensitivity, default_sensitivity_for_test));
+        TEST_ASSERT_EQUAL(default_sensitivity_for_test, read_sensitivity);
+        uint16_t tilt_count;
+        TEST_ESP_OK(relay_chn_nvs_get_tilt_count(channel, &tilt_count, 0));
+        TEST_ASSERT_EQUAL(0, tilt_count);
+    }
+#endif
 }
 
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
 TEST_CASE("Test run limit setting and getting", "[relay_chn][nvs][run_limit]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
+    // Use different values for each channel to detect overwrites
-    
+    uint16_t test_limits[CONFIG_RELAY_CHN_COUNT];
-    const uint16_t run_limit_sec = 32;
     for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-        TEST_ESP_OK(relay_chn_nvs_set_run_limit(i, run_limit_sec));
+        test_limits[i] = 30 + i; // e.g., 30, 31, 32...
-        
-        uint16_t run_limit_read;
-        TEST_ESP_OK(relay_chn_nvs_get_run_limit(i, &run_limit_read));
-        TEST_ASSERT_EQUAL(run_limit_sec, run_limit_read);
     }
-    TEST_ESP_OK(relay_chn_nvs_deinit());
+
+    // 1. Set all values first
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        TEST_ESP_OK(relay_chn_nvs_set_run_limit(i, test_limits[i]));
+    }
+
+    // Allow the NVS task to process the batch and commit
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS));
+
+    // 2. Then, read them all back and verify
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        uint16_t run_limit_read;
+        TEST_ESP_OK(relay_chn_nvs_get_run_limit(i, &run_limit_read, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC));
+        TEST_ASSERT_EQUAL_UINT16(test_limits[i], run_limit_read);
+    }
+
+    // 3. Verify that changing one channel doesn't affect another
+    uint16_t new_limit_ch0 = 99;
+    TEST_ESP_OK(relay_chn_nvs_set_run_limit(0, new_limit_ch0));
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS)); // Allow NVS task to write
+    uint16_t read_val_ch0, read_val_ch1;
+    TEST_ESP_OK(relay_chn_nvs_get_run_limit(0, &read_val_ch0, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC));
+    TEST_ESP_OK(relay_chn_nvs_get_run_limit(1, &read_val_ch1, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC));
+    TEST_ASSERT_EQUAL_UINT16(new_limit_ch0, read_val_ch0);
+    TEST_ASSERT_EQUAL_UINT16(test_limits[1], read_val_ch1); // Should still be the old value
 }
 #endif
 
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
 TEST_CASE("Test sensitivity setting and getting", "[relay_chn][nvs][tilt]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
+    uint8_t test_sensitivities[CONFIG_RELAY_CHN_COUNT];
-    
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-    const uint8_t test_sensitivity = 75;
+        test_sensitivities[i] = 70 + i; // e.g., 70, 71, 72...
-    uint8_t sensitivity;
-    
-    // Test all channels
-    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-        TEST_ESP_OK(relay_chn_nvs_set_tilt_sensitivity(channel, test_sensitivity));
-        TEST_ESP_OK(relay_chn_nvs_get_tilt_sensitivity(channel, &sensitivity));
-        TEST_ASSERT_EQUAL(test_sensitivity, sensitivity);
     }
 
-    TEST_ESP_OK(relay_chn_nvs_deinit());
+    // 1. Set all values first
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        TEST_ESP_OK(relay_chn_nvs_set_tilt_sensitivity(i, test_sensitivities[i]));
+    }
+
+    // Allow the NVS task to process the batch and commit
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS));
+
+    // 2. Then, read them all back and verify
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        uint8_t sensitivity_read;
+        TEST_ESP_OK(relay_chn_nvs_get_tilt_sensitivity(i, &sensitivity_read, 0));
+        TEST_ASSERT_EQUAL_UINT8(test_sensitivities[i], sensitivity_read);
+    }
 }
 
 TEST_CASE("Test tilt counter operations", "[relay_chn][nvs][tilt]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
+    uint16_t test_counts[CONFIG_RELAY_CHN_COUNT];
-    
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-    const uint16_t tilt_count = 100;
+        test_counts[i] = 100 + i; // e.g., 100, 101, 102...
-    uint16_t tilt_count_read;
-    
-    // Test all channels
-    for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-        // Test setting counters
-        TEST_ESP_OK(relay_chn_nvs_set_tilt_count(channel, tilt_count));
-        TEST_ESP_OK(relay_chn_nvs_get_tilt_count(channel, &tilt_count_read));
-        TEST_ASSERT_EQUAL(tilt_count, tilt_count_read);
     }
 
-    TEST_ESP_OK(relay_chn_nvs_deinit());
+    // 1. Set all values first
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        TEST_ESP_OK(relay_chn_nvs_set_tilt_count(i, test_counts[i]));
+    }
+
+    // Allow the NVS task to process the batch and commit
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS));
+
+    // 2. Then, read them all back and verify
+    for (uint8_t i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        uint16_t count_read;
+        TEST_ESP_OK(relay_chn_nvs_get_tilt_count(i, &count_read, 0));
+        TEST_ASSERT_EQUAL_UINT16(test_counts[i], count_read);
+    }
 }
 
 TEST_CASE("Test tilting invalid parameters", "[relay_chn][nvs][tilt]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     // Test NULL pointers for all channels
     for (int channel = 0; channel < CONFIG_RELAY_CHN_COUNT; channel++) {
-        TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_sensitivity(channel, NULL));
+        TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_sensitivity(channel, NULL, 0));
-        TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_count(channel, NULL));
+        TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_count(channel, NULL, 0));
     }
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 #endif // CONFIG_RELAY_CHN_ENABLE_TILTING

test_apps/main/test_relay_chn_nvs_single.c

@@ -9,50 +9,43 @@
 #include "esp_system.h"
 #include "nvs_flash.h"
 #include "relay_chn_nvs.h"
+#include "test_common.h"
 
-
+#define TEST_NVS_TASK_TIME_OUT_MS 300
-TEST_CASE("Test relay storage init/deinit", "[relay_chn][nvs]")
-{
-    TEST_ESP_OK(relay_chn_nvs_init());
-    TEST_ESP_OK(relay_chn_nvs_deinit());
-}
 
 TEST_CASE("Test direction setting and getting", "[relay_chn][nvs]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     // Test channel 0
     TEST_ESP_OK(relay_chn_nvs_set_direction(0, RELAY_CHN_DIRECTION_DEFAULT));
     relay_chn_direction_t dir;
-    TEST_ESP_OK(relay_chn_nvs_get_direction(0, &dir));
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS)); // Allow NVS task to write and commit
+    TEST_ESP_OK(relay_chn_nvs_get_direction(0, &dir, RELAY_CHN_DIRECTION_DEFAULT));
     TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, dir);
 
     // Test channel 1
     TEST_ESP_OK(relay_chn_nvs_set_direction(0, RELAY_CHN_DIRECTION_FLIPPED));
-    TEST_ESP_OK(relay_chn_nvs_get_direction(0, &dir));
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS)); // Allow NVS task to write and commit
+    TEST_ESP_OK(relay_chn_nvs_get_direction(0, &dir, RELAY_CHN_DIRECTION_DEFAULT));
     TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_FLIPPED, dir);
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 
 TEST_CASE("Test invalid parameters", "[relay_chn][nvs]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     // Test NULL pointer
-    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_direction(0, NULL));
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_direction(0, NULL, RELAY_CHN_DIRECTION_DEFAULT));
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 
 TEST_CASE("Test relay_chn_nvs_erase_all", "[relay_chn][nvs]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-
     // Store some test data first
     relay_chn_direction_t direction = RELAY_CHN_DIRECTION_FLIPPED;
     TEST_ESP_OK(relay_chn_nvs_set_direction(0, direction));
 
+#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
+    uint16_t run_limit = 123;
+    TEST_ESP_OK(relay_chn_nvs_set_run_limit(0, run_limit));
+#endif
+
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
     uint8_t sensitivity = 50;
     TEST_ESP_OK(relay_chn_nvs_set_tilt_sensitivity(0, sensitivity));
@@ -62,76 +55,71 @@ TEST_CASE("Test relay_chn_nvs_erase_all", "[relay_chn][nvs]")
     // Test erase all
     TEST_ESP_OK(relay_chn_nvs_erase_all());
 
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS)); // Allow NVS task to write and commit
     // Verify data was erased by trying to read it back
     relay_chn_direction_t read_direction;
-    TEST_ASSERT_EQUAL(ESP_ERR_NVS_NOT_FOUND, relay_chn_nvs_get_direction(0, &read_direction));
+    TEST_ESP_OK(relay_chn_nvs_get_direction(0, &read_direction, RELAY_CHN_DIRECTION_DEFAULT));
+    TEST_ASSERT_EQUAL(RELAY_CHN_DIRECTION_DEFAULT, read_direction);
 
-#if CONFIG_RELAY_CHN_ENABLE_TILTING
+#if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
-    uint8_t read_sensitivity;
+    uint16_t read_run_limit;
-    TEST_ASSERT_EQUAL(ESP_ERR_NVS_NOT_FOUND, relay_chn_nvs_get_tilt_sensitivity(0, &read_sensitivity));
+    TEST_ESP_OK(relay_chn_nvs_get_run_limit(0, &read_run_limit, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC));
-
+    TEST_ASSERT_EQUAL(CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC, read_run_limit);
-    uint16_t tilt_count;
-    TEST_ASSERT_EQUAL(ESP_ERR_NVS_NOT_FOUND, relay_chn_nvs_get_tilt_count(0, &tilt_count));
 #endif
 
-    TEST_ESP_OK(relay_chn_nvs_deinit());
+#if CONFIG_RELAY_CHN_ENABLE_TILTING
+    const uint8_t default_sensitivity_for_test = 42;
+    uint8_t read_sensitivity;
+    TEST_ESP_OK(relay_chn_nvs_get_tilt_sensitivity(0, &read_sensitivity, default_sensitivity_for_test));
+    TEST_ASSERT_EQUAL(default_sensitivity_for_test, read_sensitivity);
+    uint16_t tilt_count;
+    TEST_ESP_OK(relay_chn_nvs_get_tilt_count(0, &tilt_count, 0));
+    TEST_ASSERT_EQUAL(0, tilt_count);
+#endif
 }
 
 #if CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT
 TEST_CASE("Test run limit setting and getting", "[relay_chn][nvs][run_limit]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     const uint16_t run_limit_sec = 32;
     TEST_ESP_OK(relay_chn_nvs_set_run_limit(0, run_limit_sec));
 
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS)); // Allow NVS task to write and commit
     uint16_t run_limit_read;
-    TEST_ESP_OK(relay_chn_nvs_get_run_limit(0, &run_limit_read));
+    TEST_ESP_OK(relay_chn_nvs_get_run_limit(0, &run_limit_read, CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC));
     TEST_ASSERT_EQUAL(run_limit_sec, run_limit_read);
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 #endif
 
 #if CONFIG_RELAY_CHN_ENABLE_TILTING
 TEST_CASE("Test sensitivity setting and getting", "[relay_chn][nvs][tilt]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     const uint8_t test_sensitivity = 75;
     TEST_ESP_OK(relay_chn_nvs_set_tilt_sensitivity(0, test_sensitivity));
 
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS)); // Allow NVS task to write and commit
     uint8_t sensitivity;
-    TEST_ESP_OK(relay_chn_nvs_get_tilt_sensitivity(0, &sensitivity));
+    TEST_ESP_OK(relay_chn_nvs_get_tilt_sensitivity(0, &sensitivity, 0));
     TEST_ASSERT_EQUAL(test_sensitivity, sensitivity);
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 
 TEST_CASE("Test tilt counter operations", "[relay_chn][nvs][tilt]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     const uint16_t tilt_count = 100;
 
     // Test setting counters
     TEST_ESP_OK(relay_chn_nvs_set_tilt_count(0, tilt_count));
 
+    vTaskDelay(pdMS_TO_TICKS(TEST_NVS_TASK_TIME_OUT_MS)); // Allow NVS task to write and commit
     uint16_t tilt_count_read;
-    TEST_ESP_OK(relay_chn_nvs_get_tilt_count(0, &tilt_count_read));
+    TEST_ESP_OK(relay_chn_nvs_get_tilt_count(0, &tilt_count_read, 0));
     TEST_ASSERT_EQUAL(tilt_count, tilt_count_read);
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 
 TEST_CASE("Test tilting invalid parameters", "[relay_chn][nvs][tilt]")
 {
-    TEST_ESP_OK(relay_chn_nvs_init());
-    
     // Test NULL pointers
-    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_sensitivity(0, NULL));
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_sensitivity(0, NULL, 0));
-    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_count(0, NULL));
+    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_ARG, relay_chn_nvs_get_tilt_count(0, NULL, 0));
-    
-    TEST_ESP_OK(relay_chn_nvs_deinit());
 }
 #endif // CONFIG_RELAY_CHN_ENABLE_TILTING

test_apps/main/test_relay_chn_tilt_multi.c

@@ -1,3 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
 #include "test_common.h"
 
 
@@ -15,14 +21,13 @@
 void check_all_channels_for_state(relay_chn_state_t state)
 {
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
+        // ESP_LOGI(TEST_TAG, "Checking channel %d for state %d", i, state);
         TEST_ASSERT_EQUAL(state, relay_chn_get_state(i));
     }
 }
 
 // Helper function to prepare channel for tilt tests
 void prepare_channels_for_tilt_with_mixed_runs() {
-    // Ensure the channel reset tilt control
-    relay_chn_tilt_stop_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
 
     // Ensure the channel has had a 'last_run_cmd'
@@ -34,16 +39,19 @@ void prepare_channels_for_tilt_with_mixed_runs() {
         }
     }
 
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow command to process
+    for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
-    relay_chn_stop_all(); // Stop it to set last_run_cmd but return to FREE for next test
+        relay_chn_state_t expect_state;
-    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
+        if (i % 2 == 0) {
-    check_all_channels_for_state(RELAY_CHN_STATE_IDLE);
+            expect_state = RELAY_CHN_STATE_FORWARD;
+        } else { // Assuming initial_cmd is RELAY_CHN_CMD_REVERSE
+            expect_state = RELAY_CHN_STATE_REVERSE;
+        }
+        TEST_ASSERT_EQUAL(expect_state, relay_chn_get_state(i));
+    }
 }
 
 // Helper function to prepare channel for tilt tests
 void prepare_all_channels_for_tilt(int initial_cmd) {
-    // Ensure the channel reset tilt control
-    relay_chn_tilt_stop_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
 
     // If the channels are not IDLE yet, wait more
@@ -58,6 +66,8 @@ void prepare_all_channels_for_tilt(int initial_cmd) {
     if (not_idle) {
         vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS));
     }
+    // Ensure all channels are IDLE
+    check_all_channels_for_state(RELAY_CHN_STATE_IDLE);
 
     // Ensure the channel has had a 'last_run_cmd'
     if (initial_cmd == RELAY_CHN_CMD_FORWARD) {
@@ -65,20 +75,17 @@ void prepare_all_channels_for_tilt(int initial_cmd) {
     } else { // Assuming initial_cmd is RELAY_CHN_CMD_REVERSE
         relay_chn_run_reverse_all();
     }
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow command to process
-    relay_chn_stop_all(); // Stop all to set last_run_cmd but return to FREE for next test
-    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
-    check_all_channels_for_state(RELAY_CHN_STATE_IDLE);
+    relay_chn_state_t expect_state = initial_cmd == RELAY_CHN_CMD_FORWARD 
+                                     ? RELAY_CHN_STATE_FORWARD : RELAY_CHN_STATE_REVERSE;
+    check_all_channels_for_state(expect_state);
+    ESP_LOGI(TEST_TAG, "All channels prepared for tilt test");
 }
 
 // TEST_CASE: Test transition from running forward to tilt forward
 // Scenario: RELAY_CHN_STATE_FORWARD -> (relay_chn_tilt_forward) -> RELAY_CHN_STATE_STOPPED -> (inertia) -> RELAY_CHN_STATE_TILT_FORWARD
 TEST_CASE("Run Forward to Tilt Forward transition with inertia", "[relay_chn][tilt][inertia]")
 {
-    // Prepare channel by running forward first to set last_run_cmd
-    prepare_all_channels_for_tilt(RELAY_CHN_CMD_FORWARD);
-
     // 1. Start in forward direction
     relay_chn_run_forward_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
@@ -93,15 +100,15 @@ TEST_CASE("Run Forward to Tilt Forward transition with inertia", "[relay_chn][ti
     // Wait for the inertia period (after which the tilt command will be dispatched)
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // TEST_CASE: Test transition from running reverse to tilt reverse
 // Scenario: RELAY_CHN_STATE_REVERSE -> (relay_chn_tilt_reverse) -> RELAY_CHN_STATE_STOPPED -> (inertia) -> RELAY_CHN_STATE_TILT_REVERSE
 TEST_CASE("Run Reverse to Tilt Reverse transition with inertia", "[relay_chn][tilt][inertia]")
 {
-    // Prepare channel by running reverse first to set last_run_cmd
-    prepare_all_channels_for_tilt(RELAY_CHN_CMD_REVERSE);
-
     // 1. Start in reverse direction
     relay_chn_run_reverse_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
@@ -114,6 +121,9 @@ TEST_CASE("Run Reverse to Tilt Reverse transition with inertia", "[relay_chn][ti
 
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_REVERSE);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // TEST_CASE: Test transition from FREE state to tilt forward (now with preparation)
@@ -122,12 +132,19 @@ TEST_CASE("FREE to Tilt Forward transition with inertia (prepared)", "[relay_chn
 {
     // Prepare channel by running forward first to set last_run_cmd
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_FORWARD);
+    relay_chn_stop_all(); // Stop to trigger IDLE
+    // Wait for the channel to transition to IDLE
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
+    check_all_channels_for_state(RELAY_CHN_STATE_IDLE); // Ensure we are back to IDLE
 
     // Issue tilt forward command
     relay_chn_tilt_forward_all();
     // From FREE state, tilt command should still incur the inertia due to the internal timer logic
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // TEST_CASE: Test transition from FREE state to tilt reverse (now with preparation)
@@ -136,11 +153,18 @@ TEST_CASE("FREE to Tilt Reverse transition with inertia (prepared)", "[relay_chn
 {
     // Prepare channel by running reverse first to set last_run_cmd
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_REVERSE);
+    relay_chn_stop_all(); // Stop to trigger IDLE
+    // Wait for the channel to transition to IDLE
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
+    check_all_channels_for_state(RELAY_CHN_STATE_IDLE); // Ensure we are back to IDLE
 
     // Issue tilt reverse command
     relay_chn_tilt_reverse_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_REVERSE);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // TEST_CASE: Test transition from tilt forward to run forward (inertia expected for run)
@@ -159,6 +183,9 @@ TEST_CASE("Tilt Forward to Run Forward transition with inertia", "[relay_chn][ti
     check_all_channels_for_state(RELAY_CHN_STATE_FORWARD_PENDING);
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_FORWARD);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // TEST_CASE: Test transition from tilt reverse to run reverse (no inertia expected for run)
@@ -176,6 +203,9 @@ TEST_CASE("Tilt Reverse to Run Reverse transition with inertia", "[relay_chn][ti
     check_all_channels_for_state(RELAY_CHN_STATE_REVERSE_PENDING);
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_REVERSE);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // TEST_CASE: Test transition from tilt forward to run reverse (without inertia)
@@ -192,6 +222,9 @@ TEST_CASE("Tilt Forward to Run Reverse transition without inertia", "[relay_chn]
     relay_chn_run_reverse_all();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_REVERSE);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // TEST_CASE: Test stopping from a tilt state (no inertia for stop command itself)
@@ -222,10 +255,14 @@ TEST_CASE("tilt_forward_all sets all channels to TILT_FORWARD", "[relay_chn][til
 
     // 2. Issue tilt forward to all channels
     relay_chn_tilt_forward_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Tilt from FREE doesn't have stop-inertia
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
     // 3. Verify all channels are tilting forward
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 TEST_CASE("tilt_reverse_all sets all channels to TILT_REVERSE", "[relay_chn][tilt][batch]")
@@ -235,10 +272,14 @@ TEST_CASE("tilt_reverse_all sets all channels to TILT_REVERSE", "[relay_chn][til
 
     // 2. Issue tilt reverse to all channels
     relay_chn_tilt_reverse_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
     // 3. Verify all channels are tilting reverse
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_REVERSE);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 TEST_CASE("tilt_stop_all stops all tilting channels", "[relay_chn][tilt][batch]")
@@ -247,7 +288,10 @@ TEST_CASE("tilt_stop_all stops all tilting channels", "[relay_chn][tilt][batch]"
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_FORWARD);
 
     relay_chn_tilt_forward_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
+    // 3. Verify all channels are tilting forward
+    check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
 
     // 2. Stop tilting on all channels
     relay_chn_tilt_stop_all();
@@ -259,15 +303,13 @@ TEST_CASE("tilt_stop_all stops all tilting channels", "[relay_chn][tilt][batch]"
 
 TEST_CASE("tilt_auto_all tilts channels based on last run direction", "[relay_chn][tilt][batch]")
 {
-    // This test requires at least 2 channels to demonstrate different behaviors
-    TEST_ASSERT_GREATER_OR_EQUAL_MESSAGE(2, CONFIG_RELAY_CHN_COUNT, "Test requires at least 2 channels");
-
     // 1. Prepare channel 0 with last run FORWARD and channel 1 with last run REVERSE
     prepare_channels_for_tilt_with_mixed_runs();
 
     // 2. Issue auto tilt command to all channels
     relay_chn_tilt_auto_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Tilt from FREE state is dispatched immediately
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
 
     // 3. Verify even channels tilt forward (last run was forward) and odd channels tilt reverse (last run was reverse)
     for (int i = 0; i < CONFIG_RELAY_CHN_COUNT; i++) {
@@ -276,6 +318,9 @@ TEST_CASE("tilt_auto_all tilts channels based on last run direction", "[relay_ch
 
         TEST_ASSERT_EQUAL(state, relay_chn_get_state(i));
     }
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // Test relay_chn_tilt_auto() chooses correct tilt direction
@@ -284,19 +329,24 @@ TEST_CASE("relay_chn_tilt_auto chooses correct direction", "[relay_chn][tilt][au
     // Prepare FORWARD
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_FORWARD);
     relay_chn_tilt_auto_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     // Verify all tilt forward
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
 
+    // Ensure the channel reset tilt control
     relay_chn_tilt_stop_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
 
     // Prepare REVERSE
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_REVERSE);
     relay_chn_tilt_auto_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     // Verify all tilt reverse
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_REVERSE);
+
+    // Ensure the channel reset tilt control
+    relay_chn_tilt_stop_all();
 }
 
 // Test sensitivity set/get
@@ -322,6 +372,17 @@ TEST_CASE("relay_chn_tilt_set_sensitivity and get", "[relay_chn][tilt][sensitivi
     TEST_ASSERT_EQUAL_UINT8_ARRAY(expect, vals, CONFIG_RELAY_CHN_COUNT);
 }
 
+TEST_CASE("relay_chn_tilt_get_default_sensitivity returns correct value", "[relay_chn][tilt][sensitivity]")
+{
+    // The default sensitivity is calculated from default timing values.
+    // Default run time: 15ms, Min run time: 50ms, Max run time: 10ms.
+    // Formula: ( (DEFAULT_RUN - MIN_RUN) * 100 ) / (MAX_RUN - MIN_RUN)
+    // ( (15 - 50) * 100 ) / (10 - 50) = (-35 * 100) / -40 = -3500 / -40 = 87.5
+    // As integer arithmetic, this is 87.
+    uint8_t expected_sensitivity = 87;
+    TEST_ASSERT_EQUAL_UINT8(expected_sensitivity, relay_chn_tilt_get_default_sensitivity());
+}
+
 // Test sensitivity upper boundary for all set functions
 TEST_CASE("relay_chn_tilt_set_sensitivity functions handle upper boundary", "[relay_chn][tilt][sensitivity]")
 {
@@ -354,34 +415,41 @@ TEST_CASE("relay_chn_tilt_set_sensitivity functions handle upper boundary", "[re
 // Test tilt counter logic: forward x3, reverse x3, extra reverse fails
 TEST_CASE("tilt counter logic: forward and reverse consumption", "[relay_chn][tilt][counter]")
 {
-
 // Tilt execution time at 100% sensitivity in milliseconds (10 + 90)
 #define TEST_TILT_EXECUTION_TIME_MS 100
 
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_FORWARD);
+
     relay_chn_tilt_set_sensitivity_all_with(100); // Set sentivity to max for fastest execution
+    // Ensure sensitivities are set correctly
+    uint8_t sensitivities[CONFIG_RELAY_CHN_COUNT];
+    uint8_t expect[CONFIG_RELAY_CHN_COUNT];
+    memset(expect, 100, CONFIG_RELAY_CHN_COUNT);
+    relay_chn_tilt_get_sensitivity_all(sensitivities);
+    TEST_ASSERT_EQUAL_UINT8_ARRAY(expect, sensitivities, CONFIG_RELAY_CHN_COUNT);
 
     // Tilt forward 3 times
-    for (int i = 0; i < 3; ++i) {
+    relay_chn_tilt_forward_all();
-        relay_chn_tilt_forward_all();
+    vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS * 3 + TEST_DELAY_MARGIN_MS));
-        vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS));
+    check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
-        check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
+
-        relay_chn_tilt_stop_all();
+    // Stop tilt on all channels
-    }
+    relay_chn_tilt_stop_all();
+#if CONFIG_RELAY_CHN_ENABLE_NVS
+    // Tilt stop should save the latest tilt count to the NVS
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS + 300));
+#else
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+#endif
 
     // Now tilt reverse 3 times (should succeed)
-    for (int i = 0; i < 3; ++i) {
-        relay_chn_tilt_reverse_all();
-        vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS));
-        check_all_channels_for_state(RELAY_CHN_STATE_TILT_REVERSE);
-        relay_chn_tilt_stop_all();
-    }
-
-    // Extra reverse tilt should fail (counter exhausted)
     relay_chn_tilt_reverse_all();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS));
-    // Should not enter TILT_REVERSE, should remain IDLE
+    check_all_channels_for_state(RELAY_CHN_STATE_TILT_REVERSE);
+    // Let it execute 2 at least, or more
+    vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS * 3));
+
+    // More reverse tilt should fail (counter exhausted)
     check_all_channels_for_state(RELAY_CHN_STATE_IDLE);
 }
 
@@ -406,12 +474,12 @@ TEST_CASE("run_all command during active tilt cycle stops tilt", "[relay_chn][ti
     // Set a known sensitivity for predictable timing.
     // For sensitivity=50, move_time=30ms, pause_time=270ms.
     relay_chn_tilt_set_sensitivity_all_with(50);
-    const uint32_t move_time_ms = 30;
 
     // --- Test interrupting during MOVE step ---
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_FORWARD);
     relay_chn_tilt_forward_all();
-    vTaskDelay(pdMS_TO_TICKS(move_time_ms / 2)); // Wait for half of the move time
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
 
     // Interrupt with run_reverse_all while in the MOVE part of the cycle
@@ -421,9 +489,12 @@ TEST_CASE("run_all command during active tilt cycle stops tilt", "[relay_chn][ti
     check_all_channels_for_state(RELAY_CHN_STATE_REVERSE);
 
     // --- Test interrupting during PAUSE step ---
+    relay_chn_stop_all(); // Stop the reverse runs
+    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     prepare_all_channels_for_tilt(RELAY_CHN_CMD_FORWARD);
     relay_chn_tilt_forward_all();
-    vTaskDelay(pdMS_TO_TICKS(move_time_ms + TEST_DELAY_MARGIN_MS)); // Wait past MOVE, into PAUSE
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS)); // Wait past MOVE, into PAUSE
     check_all_channels_for_state(RELAY_CHN_STATE_TILT_FORWARD);
 
     // Interrupt with run_forward_all while in the PAUSE part of the cycle

test_apps/main/test_relay_chn_tilt_single.c

@@ -1,3 +1,9 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kozmotronik Tech
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
 #include "test_common.h"
 
 
@@ -24,19 +30,15 @@ void prepare_channel_for_tilt(int initial_cmd) {
     } else { // Assuming initial_cmd is RELAY_CHN_CMD_REVERSE
         relay_chn_run_reverse();
     }
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS)); // Allow command to process
-    relay_chn_stop(); // Stop it to set last_run_cmd but return to FREE for next test
     vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
-    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state());
+    relay_chn_state_t expect_state = initial_cmd == RELAY_CHN_CMD_FORWARD ? RELAY_CHN_STATE_FORWARD : RELAY_CHN_STATE_REVERSE;
+    TEST_ASSERT_EQUAL(expect_state, relay_chn_get_state());
 }
 
 // Test transition from running forward to tilt forward
 // Scenario: RELAY_CHN_STATE_FORWARD -> (relay_chn_tilt_forward) -> RELAY_CHN_STATE_STOPPED -> (inertia) -> RELAY_CHN_STATE_TILT_FORWARD
 TEST_CASE("Run Forward to Tilt Forward transition with inertia", "[relay_chn][tilt][inertia]")
 {
-    // Prepare channel by running forward first to set last_run_cmd
-    prepare_channel_for_tilt(RELAY_CHN_CMD_FORWARD);
-
     // 1. Start in forward direction
     relay_chn_run_forward();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
@@ -57,9 +59,6 @@ TEST_CASE("Run Forward to Tilt Forward transition with inertia", "[relay_chn][ti
 // Scenario: RELAY_CHN_STATE_REVERSE -> (relay_chn_tilt_reverse) -> RELAY_CHN_STATE_STOPPED -> (inertia) -> RELAY_CHN_STATE_TILT_REVERSE
 TEST_CASE("Run Reverse to Tilt Reverse transition with inertia", "[relay_chn][tilt][inertia]")
 {
-    // Prepare channel by running reverse first to set last_run_cmd
-    prepare_channel_for_tilt(RELAY_CHN_CMD_REVERSE);
-
     // 1. Start in reverse direction
     relay_chn_run_reverse();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
@@ -80,6 +79,9 @@ TEST_CASE("FREE to Tilt Forward transition with inertia (prepared)", "[relay_chn
 {
     // Prepare channel by running forward first to set last_run_cmd
     prepare_channel_for_tilt(RELAY_CHN_CMD_FORWARD);
+    relay_chn_stop(); // Stop to trigger IDLE
+    // Wait for the channel to transition to IDLE
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state()); // Ensure we are back to FREE
 
     // Issue tilt forward command
@@ -95,6 +97,9 @@ TEST_CASE("FREE to Tilt Reverse transition with inertia (prepared)", "[relay_chn
 {
     // Prepare channel by running reverse first to set last_run_cmd
     prepare_channel_for_tilt(RELAY_CHN_CMD_REVERSE);
+    relay_chn_stop(); // Stop to trigger IDLE
+    // Wait for the channel to transition to IDLE
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state()); // Ensure we are back to FREE
 
     // Issue tilt reverse command
@@ -155,7 +160,7 @@ TEST_CASE("Tilt Forward to Run Reverse transition without inertia", "[relay_chn]
 }
 
 // Test stopping from a tilt state (no inertia for stop command itself)
-// Scenario: RELAY_CHN_STATE_TILT_FORWARD -> (relay_chn_stop) -> RELAY_CHN_STATE_STOPPED -> (inertia) -> RELAY_CHN_STATE_IDLE
+// Scenario: RELAY_CHN_STATE_TILT_FORWARD -> (relay_chn_tilt_stop) -> RELAY_CHN_STATE_IDLE
 TEST_CASE("Tilt to Stop transition without immediate inertia for stop", "[relay_chn][tilt][inertia]")
 {
     // Prepare channel by running forward first to set last_run_cmd, then tilt
@@ -165,7 +170,7 @@ TEST_CASE("Tilt to Stop transition without immediate inertia for stop", "[relay_
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_FORWARD, relay_chn_get_state());
 
     // 2. Issue stop command
-    relay_chn_stop();
+    relay_chn_tilt_stop();
     // Stop command should apply immediately, setting state to FREE since last state was tilt.
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_IDLE, relay_chn_get_state());
@@ -177,7 +182,8 @@ TEST_CASE("relay_chn_tilt_auto chooses correct direction", "[relay_chn][tilt][au
     // Prepare FORWARD
     prepare_channel_for_tilt(RELAY_CHN_CMD_FORWARD);
     relay_chn_tilt_auto();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_FORWARD, relay_chn_get_state());
     relay_chn_tilt_stop();
     vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
@@ -185,7 +191,8 @@ TEST_CASE("relay_chn_tilt_auto chooses correct direction", "[relay_chn][tilt][au
     // Prepare REVERSE
     prepare_channel_for_tilt(RELAY_CHN_CMD_REVERSE);
     relay_chn_tilt_auto();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_REVERSE, relay_chn_get_state());
 }
 
@@ -205,6 +212,17 @@ TEST_CASE("relay_chn_tilt_set_sensitivity and get", "[relay_chn][tilt][sensitivi
     TEST_ASSERT_EQUAL_UINT8(42, relay_chn_tilt_get_sensitivity());
 }
 
+TEST_CASE("relay_chn_tilt_get_default_sensitivity returns correct value", "[relay_chn][tilt][sensitivity]")
+{
+    // The default sensitivity is calculated from default timing values.
+    // Default run time: 15ms, Min run time: 50ms, Max run time: 10ms.
+    // Formula: ( (DEFAULT_RUN - MIN_RUN) * 100 ) / (MAX_RUN - MIN_RUN)
+    // ( (15 - 50) * 100 ) / (10 - 50) = (-35 * 100) / -40 = -3500 / -40 = 87.5
+    // As integer arithmetic, this is 87.
+    uint8_t expected_sensitivity = 87;
+    TEST_ASSERT_EQUAL_UINT8(expected_sensitivity, relay_chn_tilt_get_default_sensitivity());
+}
+
 // Test sensitivity upper boundary
 TEST_CASE("relay_chn_tilt_set_sensitivity handles upper boundary", "[relay_chn][tilt][sensitivity]")
 {
@@ -220,31 +238,25 @@ TEST_CASE("relay_chn_tilt_set_sensitivity handles upper boundary", "[relay_chn][
 // Test tilt counter logic: forward x3, reverse x3, extra reverse fails
 TEST_CASE("tilt counter logic: forward and reverse consumption", "[relay_chn][tilt][counter]")
 {
+// Tilt execution time at 100% sensitivity in milliseconds (10 + 90)
+#define TEST_TILT_EXECUTION_TIME_MS 100
+
     prepare_channel_for_tilt(RELAY_CHN_CMD_FORWARD);
 
     // Tilt forward 3 times
-    for (int i = 0; i < 3; ++i) {
+    relay_chn_tilt_forward();
-        relay_chn_tilt_forward();
+    vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS * 3 + TEST_DELAY_MARGIN_MS));
-        vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_FORWARD, relay_chn_get_state());
-        TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_FORWARD, relay_chn_get_state());
+    relay_chn_tilt_stop();
-        relay_chn_tilt_stop();
-        vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-    }
 
     // Now tilt reverse 3 times (should succeed)
-    for (int i = 0; i < 3; ++i) {
-        relay_chn_tilt_reverse();
-        vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-        if (i < 3) {
-            TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_REVERSE, relay_chn_get_state());
-            relay_chn_tilt_stop();
-            vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
-        }
-    }
-
-    // Extra reverse tilt should fail (counter exhausted)
     relay_chn_tilt_reverse();
-    vTaskDelay(pdMS_TO_TICKS(TEST_DELAY_MARGIN_MS));
+    // Let it execute one time
+    vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS));
+    TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_REVERSE, relay_chn_get_state());
+    // Let it execute 2 at least, or more
+    vTaskDelay(pdMS_TO_TICKS(TEST_TILT_EXECUTION_TIME_MS * 3));
+    
     // Should not enter TILT_REVERSE, should remain FREE or STOPPED
     relay_chn_state_t state = relay_chn_get_state();
     TEST_ASSERT(state != RELAY_CHN_STATE_TILT_REVERSE);
@@ -272,12 +284,12 @@ TEST_CASE("run command during active tilt cycle stops tilt", "[relay_chn][tilt][
     // Set a known sensitivity for predictable timing.
     // For sensitivity=50, move_time=30ms, pause_time=270ms.
     relay_chn_tilt_set_sensitivity(50);
-    const uint32_t move_time_ms = 30;
 
     // --- Test interrupting during MOVE step ---
     prepare_channel_for_tilt(RELAY_CHN_CMD_FORWARD);
     relay_chn_tilt_forward();
-    vTaskDelay(pdMS_TO_TICKS(move_time_ms / 2)); // Wait for half of the move time
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_FORWARD, relay_chn_get_state());
 
     // Interrupt with run_reverse while in the MOVE part of the cycle
@@ -287,9 +299,14 @@ TEST_CASE("run command during active tilt cycle stops tilt", "[relay_chn][tilt][
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_REVERSE, relay_chn_get_state());
 
     // --- Test interrupting during PAUSE step ---
-    prepare_channel_for_tilt(RELAY_CHN_CMD_FORWARD);
+    relay_chn_stop(); // Stop the reverse run
+    // Wait the channel to be IDLE
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
+
+    prepare_channel_for_tilt(RELAY_CHN_CMD_FORWARD); // Prepare channel again
     relay_chn_tilt_forward();
-    vTaskDelay(pdMS_TO_TICKS(move_time_ms + TEST_DELAY_MARGIN_MS)); // Wait past MOVE, into PAUSE
+    // Should incur inertia timer
+    vTaskDelay(pdMS_TO_TICKS(CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS + TEST_DELAY_MARGIN_MS));
     TEST_ASSERT_EQUAL(RELAY_CHN_STATE_TILT_FORWARD, relay_chn_get_state());
 
     // Interrupt with run_forward while in the PAUSE part of the cycle

test_apps/sdkconfig.defaults

@@ -1,6 +1,9 @@
 # Disable task WDT for tests
 CONFIG_ESP_TASK_WDT_INIT=n
 
+CONFIG_LOG_MAXIMUM_LEVEL_DEBUG=y
+CONFIG_LOG_MAXIMUM_LEVEL=4
+
 # Relay Channel Driver Default Configuration for Testing
 # Keep this as short as possible for tests
 CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS=200