Merge pull request 'fix/162-fix-error-handling' from fix/162-fix-error-handling into dev

Reviewed-on: https://dev.kozmotronik.com.tr/gitea/KozmotronikTech/relay_chn/pulls/21

.gitignore

@@ -1,102 +1,111 @@
-# ---> C
-# Prerequisites
-*.d
-
-# Object files
+.config
 *.o
-*.ko
-*.obj
-*.elf
+*.pyc
 
-# Linker output
-*.ilk
-*.map
-*.exp
+# gtags
+GTAGS
+GRTAGS
+GPATH
 
-# Precompiled Headers
-*.gch
-*.pch
+# emacs
+.dir-locals.el
 
-# Libraries
-*.lib
-*.a
-*.la
-*.lo
+# emacs temp file suffixes
+*~
+.#*
+\#*#
 
-# Shared objects (inc. Windows DLLs)
-*.dll
-*.so
-*.so.*
-*.dylib
+# eclipse setting
+.settings
 
-# Executables
-*.exe
-*.out
-*.app
-*.i*86
-*.x86_64
-*.hex
+# MacOS directory files
+.DS_Store
 
-# Debug files
-*.dSYM/
-*.su
-*.idb
-*.pdb
+# cache dir
+.cache/
 
-# Kernel Module Compile Results
-*.mod*
-*.cmd
-.tmp_versions/
-modules.order
-Module.symvers
-Mkfile.old
-dkms.conf
+# Doc build artifacts
+docs/_build/
+docs/doxygen_sqlite3.db
 
-# ---> C++
-# Prerequisites
-*.d
+# Downloaded font files
+docs/_static/DejaVuSans.ttf
+docs/_static/NotoSansSC-Regular.otf
 
-# Compiled Object files
-*.slo
-*.lo
-*.o
-*.obj
+# Components Unit Test Apps files
+components/**/build/
+components/**/build_*_*/
+components/**/sdkconfig
+components/**/sdkconfig.old
 
-# Precompiled Headers
-*.gch
-*.pch
+# Example project files
+examples/**/build/
+examples/**/build_*_*/
+examples/**/sdkconfig
+examples/**/sdkconfig.old
 
-# Compiled Dynamic libraries
-*.so
-*.dylib
-*.dll
+# Unit test app files
+tools/unit-test-app/build
+tools/unit-test-app/build_*_*/
+tools/unit-test-app/sdkconfig
+tools/unit-test-app/sdkconfig.old
 
-# Fortran module files
-*.mod
-*.smod
+# test application build files
+tools/test_apps/**/build/
+tools/test_apps/**/build_*_*/
+tools/test_apps/**/sdkconfig
+tools/test_apps/**/sdkconfig.old
 
-# Compiled Static libraries
-*.lai
-*.la
-*.a
-*.lib
+TEST_LOGS/
+build_summary_*.xml
 
-# Executables
-*.exe
-*.out
-*.app
+# gcov coverage reports
+*.gcda
+*.gcno
+coverage.info
+coverage_report/
 
-# ---> CMake
-CMakeLists.txt.user
-CMakeCache.txt
-CMakeFiles
-CMakeScripts
-Testing
-Makefile
-cmake_install.cmake
-install_manifest.txt
-compile_commands.json
-CTestTestfile.cmake
-_deps
-CMakeUserPresets.json
+test_multi_heap_host
 
+# VS Code Settings
+.vscode/
+
+# VIM files
+*.swp
+*.swo
+
+# Sublime Text files
+*.sublime-project
+*.sublime-workspace
+
+# Clion IDE CMake build & config
+.idea/
+cmake-build-*/
+
+# Results for the checking of the Python coding style and static analysis
+.mypy_cache
+flake8_output.txt
+
+# ESP-IDF default build directory name
+build
+
+# lock files for examples and components
+dependencies.lock
+
+# managed_components for examples
+managed_components
+
+# pytest log
+pytest-embedded/
+# legacy one
+pytest_embedded_log/
+list_job*.txt
+size_info*.txt
+XUNIT_RESULT*.xml
+.manifest_sha
+
+# clang config (for LSP)
+.clangd
+
+# Vale
+.vale/styles/*

.vscode/settings.json

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

Kconfig

@@ -17,4 +17,13 @@ menu "Relay Channel Driver Configuration"
         help
             Number of relay channels between 1 and 8.
     
+    config RELAY_CHN_ENABLE_TILTING
+        bool "Enable tilting on relay channels"
+        default n
+        help
+            This option controls enabling tilting on channels. Tilting makes
+            a channel move with a specific pattern moving with small steps
+            at a time. Tilting is specifically designed for controlling some
+            types of curtains that need to be adjusted to let enter specific
+            amount of day light.
 endmenu

README.md

@@ -11,17 +11,23 @@ An ESP-IDF component for controlling relay channels, specifically designed for d
 - Forward/Reverse direction control
 - Direction flipping capability
 - State monitoring and reporting
+- Optional sensitivty adjustable tilting feature
 
 ## Description
 
 Each relay channel consists of 2 output relays controlled by 2 GPIO pins. The component provides APIs to control these relay pairs while ensuring safe operation, particularly for driving bipolar motors. It prevents short-circuits by automatically managing direction changes with configurable inertia timing.
 
+It also provides an optional tilting interface per channel base. Tilting makes a channel move with a specific pattern moving with small steps at a time. Tilting is specifically designed for controlling some types of curtains that need to be adjusted to let enter specific amount of day light.  
+Since it operates on relays, the switching frequency is limited to 10Hz which complies with the most of the general purpose relays' requirements. The minimum frequency is 2Hz and the duty cycle is about 10% in all ranges.  
+The module also handles all the required timing between the movement transitions automatically to ensure reliable operation.
+
 ## Configuration
 
 Configure the component through menuconfig under "Relay Channel Driver Configuration":
 
 - `CONFIG_RELAY_CHN_OPPOSITE_INERTIA_MS`: Time to wait before changing direction (200-1500ms, default: 800ms)
 - `CONFIG_RELAY_CHN_COUNT`: Number of relay channels (1-8, default: 1)
+- `CONFIG_RELAY_CHN_ENABLE_TILTING`: Enable tilting interface on all channels. (default: n)
 
 ## Installation
 
@@ -77,6 +83,30 @@ char *state_str = relay_chn_get_state_str(0);
 relay_chn_direction_t direction = relay_chn_get_direction(0);
 ```
 
+### 4. Tilting Interface (if enabled)
+
+```c
+// Assuming CONFIG_RELAY_CHN_ENABLE_TILTING is enabled
+
+// Start tilting automatically (channel 0)
+relay_chn_tilt_auto(0);
+
+// Tilt forward (channel 0)
+relay_chn_tilt_forward(0);
+
+// Tilt reverse (channel 0)
+relay_chn_tilt_reverse(0);
+
+// Stop tilting (channel 0)
+relay_chn_tilt_stop(0);
+
+// Set tilting sensitivity (channel 0, sensitivity as percentage)
+relay_chn_tilt_sensitivity_set(0, 90);
+
+// Get tilting sensitivity (channel 0, sensitivty as percentage)
+uint8_t sensitivity = relay_chn_tilt_sensitivity_get(0);
+```
+
 ## License
 
 [MIT License](LICENSE) - Copyright (c) 2025 kozmotronik.

include/relay_chn.h

@@ -23,11 +23,14 @@
 
 #include "esp_err.h"
 #include "driver/gpio.h"
+#include <stdint.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#define RELAY_CHN_ID_ALL   CONFIG_RELAY_CHN_COUNT ///< Special ID to address all channels
+
 /**
  * @brief Enumeration for relay channel direction.
  */
@@ -51,6 +54,10 @@ enum relay_chn_state_enum {
     RELAY_CHN_STATE_REVERSE,    ///< The relay channel is running in the reverse direction.
     RELAY_CHN_STATE_FORWARD_PENDING,    ///< The relay channel is pending to run in the forward direction.
     RELAY_CHN_STATE_REVERSE_PENDING,    ///< The relay channel is pending to run in the reverse direction.
+#if CONFIG_RELAY_CHN_ENABLE_TILTING == 1
+    RELAY_CHN_STATE_TILT_FORWARD,    ///< The relay channel is tilting for forward.
+    RELAY_CHN_STATE_TILT_REVERSE,    ///< The relay channel is tilting for reverse.
+#endif
 };
 
 /**
@@ -58,6 +65,20 @@ enum relay_chn_state_enum {
  */
 typedef enum relay_chn_state_enum relay_chn_state_t;
 
+/**
+ * @brief Relay channel state change listener.
+ *
+ * An optional interface to listen to the channel state change events.
+ * The listeners SHOULD be implemented as light functions and SHOULD NOT contain
+ * any blocking calls. Otherwise the relay_chn module would not function properly
+ * since it is designed as event driven.
+ *
+ * @param chn_id The ID of the channel whose state has changed.
+ * @param old_state The old state of the channel.
+ * @param new_state The new state of the channel.
+ */
+typedef void (*relay_chn_state_listener_t)(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state);
+
 
 /**
  * @brief Create and initialize relay channels.
@@ -74,6 +95,26 @@ typedef enum relay_chn_state_enum relay_chn_state_t;
  */
 esp_err_t relay_chn_create(const gpio_num_t* gpio_map, uint8_t gpio_count);
 
+/**
+ * @brief Register a channel state change listener.
+ * 
+ * @param listener A function that implements relay_chn_state_listener_t interface.
+ *
+ * @return
+ *     - ESP_OK: Success
+ *     - ESP_ERR_INVALID_ARG: Invalid argument
+ *     - ESP_ERR_NO_MEM: No enough memory
+ *     - ESP_FAIL: General failure
+ */
+esp_err_t relay_chn_register_listener(relay_chn_state_listener_t listener);
+
+/**
+ * @brief Unregister a channel state change listener.
+ * 
+ * @param listener A function that implements relay_chn_state_listener_t interface.
+ */
+void relay_chn_unregister_listener(relay_chn_state_listener_t listener);
+
 /**
  * @brief Get the state of the specified relay channel.
  *
@@ -100,6 +141,14 @@ relay_chn_state_t relay_chn_get_state(uint8_t chn_id);
  */
 char *relay_chn_get_state_str(uint8_t chn_id);
 
+/**
+ * @brief Return the text presentation of an state.
+ * 
+ * @param state A state with type of relay_chn_state_t.
+ * @return char* The text presentation of the state. "UNKNOWN" if the state is not known.
+ */
+char *relay_chn_state_str(relay_chn_state_t state);
+
 /**
  * @brief Runs the relay channel in the forward direction.
  *
@@ -153,6 +202,77 @@ void relay_chn_flip_direction(uint8_t chn_id);
  */
 relay_chn_direction_t relay_chn_get_direction(uint8_t chn_id);
 
+
+#if CONFIG_RELAY_CHN_ENABLE_TILTING == 1
+
+/**
+ * @brief Enables automatic tilting for the specified relay channel.
+ *
+ * This function enables automatic tilting mode for the given relay channel.  The channel will automatically
+ * switch between forward and reverse tilting based on some internal sensing mechanism (not detailed here).  
+ * Requires appropriate hardware support and configuration.
+ *
+ * @param chn_id The ID of the relay channel to enable automatic tilting.
+ */
+void relay_chn_tilt_auto(uint8_t chn_id);
+
+/**
+ * @brief Tilts the specified relay channel forward.
+ *
+ * This function initiates a forward tilting action for the specified relay channel.  This is a manual tilting 
+ * operation, unlike `relay_chn_tilt_auto()`.
+ *
+ * @param chn_id The ID of the relay channel to tilt forward.
+ */
+void relay_chn_tilt_forward(uint8_t chn_id);
+
+/**
+ * @brief Tilts the specified relay channel reverse.
+ *
+ * This function initiates a reverse tilting action for the specified relay channel. This is a manual tilting
+ * operation, unlike `relay_chn_tilt_auto()`.
+ *
+ * @param chn_id The ID of the relay channel to tilt reverse.
+ */
+void relay_chn_tilt_reverse(uint8_t chn_id);
+
+/**
+ * @brief Stops the tilting action on the specified relay channel.
+ *
+ * This function stops any ongoing tilting action (automatic or manual) on the specified relay channel.
+ *
+ * @param chn_id The ID of the relay channel to stop tilting.
+ */
+void relay_chn_tilt_stop(uint8_t chn_id);
+
+/**
+ * @brief Sets the tilting sensitivity for the specified relay channel.
+ *
+ * This function sets the sensitivity for the automatic tilting mechanism. A higher sensitivity value
+ * typically means the channel will react more readily to tilting events.
+ *
+ * @param chn_id The ID of the relay channel to set the sensitivity for.
+ * @param sensitivity The sensitivity in percentage: 0 - 100%.
+ */
+void relay_chn_tilt_sensitivity_set(uint8_t chn_id, uint8_t sensitivity);
+
+/**
+ * @brief Gets the tilting sensitivity for the specified relay channel.
+ *
+ * This function retrieves the currently set sensitivity for the specified relay channel's automatic
+ * tilting mechanism.
+ *
+ * @param chn_id The ID of the relay channel to get the sensitivity for.
+ * @param sensitivity The pointer to the memory in to which the sensitivity values will be copied.
+ * @param length The length of the sensitvity memory.
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_ERR_INVALID_ARG: Invalid argument
+ */
+esp_err_t relay_chn_tilt_sensitivity_get(uint8_t chn_id, uint8_t *sensitivity, size_t length);
+
+#endif // CONFIG_RELAY_CHN_ENABLE_TILTING
+
 #ifdef __cplusplus
 }
 #endif