Merge pull request 'fix-v0.2.1' (#19) from fix-v0.2.1 into dev

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

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

@@ -205,19 +205,73 @@ 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);
 
-uint8_t relay_chn_tilt_sensitivity_get(uint8_t chn_id);
+/**
+ * @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
+#endif // CONFIG_RELAY_CHN_ENABLE_TILTING
 
 #ifdef __cplusplus
 }

src/relay_chn.c

@@ -588,6 +588,9 @@ static void relay_chn_issue_cmd(relay_chn_t* relay_chn, relay_chn_cmd_t cmd)
                 return;
             }
             
+            // Stop the channel first before the schedule
+            relay_chn_dispatch_cmd(relay_chn, RELAY_CHN_CMD_STOP);
+
             // If the last run command is different from the current command, wait for the opposite inertia time
             relay_chn->pending_cmd = cmd;
             relay_chn_state_t new_state = cmd == RELAY_CHN_CMD_FORWARD 
@@ -1035,45 +1038,70 @@ static void relay_chn_set_tilt_timing_values(relay_chn_tilt_timing_t *tilt_timin
     tilt_timing->pause_time_ms = pause_time_ms;
 }
 
-void relay_chn_tilt_sensitivity_set(uint8_t chn_id, uint8_t sensitivity)
+static void _relay_chn_tilt_sensitivity_set(relay_chn_t *relay_chn, uint8_t sensitivity)
 {
-    if (!relay_chn_is_channel_id_valid(chn_id)) {
-        return;
-    }
-    relay_chn_t* relay_chn = &relay_channels[chn_id];
-
     if (sensitivity >= 100) {
         relay_chn_set_tilt_timing_values(&relay_chn->tilt_control.tilt_timing,
                                               100,
                                               RELAY_CHN_TILT_RUN_MAX_MS,
                                               RELAY_CHN_TILT_PAUSE_MAX_MS);
-        return;
     }
     else if (sensitivity == 0) {
         relay_chn_set_tilt_timing_values(&relay_chn->tilt_control.tilt_timing,
                                               0,
-                                              RELAY_CHN_TILT_RUN_MAX_MS,
-                                              RELAY_CHN_TILT_PAUSE_MAX_MS);
-        return;
+                                              RELAY_CHN_TILT_RUN_MIN_MS,
+                                              RELAY_CHN_TILT_PAUSE_MIN_MS);
     }
-    
-    // Compute the new timing values from the sensitivity percent value by using linear interpolation
-    uint32_t tilt_run_time_ms = 0, tilt_pause_time_ms = 0;
-    tilt_run_time_ms = RELAY_CHN_TILT_RUN_MIN_MS + (sensitivity * (RELAY_CHN_TILT_RUN_MAX_MS - RELAY_CHN_TILT_RUN_MIN_MS) / 100);
-    tilt_pause_time_ms = RELAY_CHN_TILT_PAUSE_MIN_MS + (sensitivity * (RELAY_CHN_TILT_PAUSE_MAX_MS - RELAY_CHN_TILT_PAUSE_MIN_MS) / 100);
-    relay_chn_set_tilt_timing_values(&relay_chn->tilt_control.tilt_timing,
+    else {
+        // Compute the new timing values from the sensitivity percent value by using linear interpolation
+        uint32_t tilt_run_time_ms = 0, tilt_pause_time_ms = 0;
+        tilt_run_time_ms = RELAY_CHN_TILT_RUN_MIN_MS + (sensitivity * (RELAY_CHN_TILT_RUN_MAX_MS - RELAY_CHN_TILT_RUN_MIN_MS) / 100);
+        tilt_pause_time_ms = RELAY_CHN_TILT_PAUSE_MIN_MS + (sensitivity * (RELAY_CHN_TILT_PAUSE_MAX_MS - RELAY_CHN_TILT_PAUSE_MIN_MS) / 100);
+        relay_chn_set_tilt_timing_values(&relay_chn->tilt_control.tilt_timing,
                                           sensitivity,
                                           tilt_run_time_ms,
                                           tilt_pause_time_ms);
+    }
 }
 
-uint8_t relay_chn_tilt_sensitivity_get(uint8_t chn_id)
+void relay_chn_tilt_sensitivity_set(uint8_t chn_id, uint8_t sensitivity)
 {
     if (!relay_chn_is_channel_id_valid(chn_id)) {
-        return 0;
+        return;
     }
-    relay_chn_t* relay_chn = &relay_channels[chn_id];
-    return relay_chn->tilt_control.tilt_timing.sensitivity;
+    
+    if (chn_id == RELAY_CHN_ID_ALL) {
+        for (int i = 0; i < RELAY_CHN_COUNT; i++) {
+            _relay_chn_tilt_sensitivity_set(&relay_channels[i], sensitivity);
+        }
+    }
+    else {
+        _relay_chn_tilt_sensitivity_set(&relay_channels[chn_id], sensitivity);
+    }
+}
+
+esp_err_t relay_chn_tilt_sensitivity_get(uint8_t chn_id, uint8_t *sensitivity, size_t length)
+{
+    if (!relay_chn_is_channel_id_valid(chn_id)) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (sensitivity == NULL) {
+        ESP_LOGD(TAG, "relay_chn_tilt_sensitivity_get: sensitivity is NULL");
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (chn_id == RELAY_CHN_ID_ALL) {
+        if (length < RELAY_CHN_COUNT) {
+            ESP_LOGD(TAG, "relay_chn_tilt_sensitivity_get: length is too short to store all sensitivity values");
+            return ESP_ERR_INVALID_ARG;
+        }
+
+        for (int i = 0; i < RELAY_CHN_COUNT; i++) {
+            sensitivity[i] = relay_channels[i].tilt_control.tilt_timing.sensitivity;
+        }
+        return ESP_OK;
+    }
+    *sensitivity = relay_channels[chn_id].tilt_control.tilt_timing.sensitivity;
+    return ESP_OK;
 }
 
 static esp_err_t relay_chn_init_tilt_control(relay_chn_t *relay_chn)