Merge pull request 'release-v0.2.1' (#15) from release-v0.2.1 into main

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

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,69 @@ 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.
+ * @return The current sensitivity in percentage: 0 - 100%.
+ */
 uint8_t relay_chn_tilt_sensitivity_get(uint8_t chn_id);
 
-#endif
+#endif // CONFIG_RELAY_CHN_ENABLE_TILTING
 
 #ifdef __cplusplus
 }

src/relay_chn.c

@@ -582,11 +582,14 @@ static void relay_chn_issue_cmd(relay_chn_t* relay_chn, relay_chn_cmd_t cmd)
                 relay_chn_dispatch_cmd(relay_chn, cmd);
                 return;
             }
-
+            
             if (relay_chn->run_info.last_run_cmd == cmd) {
                 // If the last run command is the same as the current command, do nothing
                 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;