Refactor and update the relay_chn component.

Refactor relay channel component to support single and multi-channel modes; update CMake configuration and enhance API documentation.

README.md

@@ -43,11 +43,28 @@ dependencies:
 
 ## Usage
 
+The `relay_chn` component can be used in two different modes, which are determined by the 'CONFIG_RELAY_CHN_COUNT' configuration:
+
+- Single channel mode (`CONFIG_RELAY_CHN_COUNT == 1`)
+- Multi channel mode (`CONFIG_RELAY_CHN_COUNT > 1`)
+
+Depending on the mode, the component will be built selectively, so the signatures of some available API functions may vary, either including or excluding a channel ID parameter:
+
+```c
+relay_chn_run_forward(); // No channel ID parameter for single channel mode
+// or
+relay_chn_run_forward(2); // Channel ID parameters will be needed in multi channel mode 
+```
+
+See the examples for further reference
+
 ### 1. Initialize relay channels
 
 ```c
 // Define GPIO pins for relay channels
-const gpio_num_t gpio_map[] = {GPIO_NUM_4, GPIO_NUM_5};  // One channel example
+const uint8_t gpio_map[] = {4, 5};  // One channel example
+/*------------------------------------------------------------------------*/
+const uint8_t gpio_map[] = {4, 5, 9, 10, 18, 19};  // Or a 3 channel example
 const uint8_t gpio_count = sizeof(gpio_map) / sizeof(gpio_map[0]);
 
 // Create and initialize relay channels
@@ -59,53 +76,138 @@ if (ret != ESP_OK) {
 
 ### 2. Control relay channels
 
+For single mode:
+
 ```c
-// Run channel 0 forward
+// Run the channel forward
+relay_chn_run_forward();
+
+// Run the channel reverse
+relay_chn_run_reverse();
+
+// Stop the channel
+relay_chn_stop();
+
+// Flip the direction of the channel
+relay_chn_flip_direction();
+```
+
+For multi mode
+
+```c
+// Run channel #0 forward
 relay_chn_run_forward(0);
+// Run all channels forward
+relay_chn_run_forward(RELAY_CHN_ID_ALL);
 
-// Run channel 0 reverse
-relay_chn_run_reverse(0);
+// Run channel #1 reverse
+relay_chn_run_reverse(1);
+// Run all channels reverse
+relay_chn_run_reverse(RELAY_CHN_ID_ALL);
 
-// Stop channel 0
-relay_chn_stop(0);
+// Stop channel #1 
+relay_chn_stop(1);
+// Stop all channels 
+relay_chn_stop(RELAY_CHN_ID_ALL);
 
-// Flip direction of channel 0
+// Flip direction of channel #0
 relay_chn_flip_direction(0);
+// Flip direction of all channels
+relay_chn_flip_direction(RELAY_CHN_ID_ALL);
 ```
 
 ### 3. Monitor channel state
 
+For single mode:
+
 ```c
 // Get channel state
-relay_chn_state_t state = relay_chn_get_state(0);
-char *state_str = relay_chn_get_state_str(0);
+relay_chn_state_t state = relay_chn_get_state();
+// Get the string representation of the state of the channel
+char *state_str = relay_chn_get_state_str();
 
 // Get channel direction
+relay_chn_direction_t direction = relay_chn_get_direction();
+
+// Listen to relay channel state changes
+static void relay_chn_listener(uint8_t chn_id, relay_chn_state_t old_state, relay_chn_state_t new_state) {
+    /* The channel id can be ignored in single mode */
+    /* Handle state changes */
+}
+// Register the listener callback
+relay_chn_register_listener(relay_chn_listener);
+// Unregister the listener when it is not needed anymore
+relay_chn_unregister_listener(relay_chn_listener);
+```
+
+For multi mode:
+
+```c
+// Get channel #0 state
+relay_chn_state_t state = relay_chn_get_state(0);
+// Get the string representation of the state of the channel #0
+char *state_str = relay_chn_get_state_str(0);
+
+// Get channel #0 direction
 relay_chn_direction_t direction = relay_chn_get_direction(0);
+
+/* The listener is same for multi mode */
 ```
 
 ### 4. Tilting Interface (if enabled)
 
+For single mode:
+
 ```c
 // Assuming CONFIG_RELAY_CHN_ENABLE_TILTING is enabled
 
-// Start tilting automatically (channel 0)
+// Start tilting automatically
+relay_chn_tilt_auto();
+
+// Tilt forward
+relay_chn_tilt_forward();
+
+// Tilt reverse
+relay_chn_tilt_reverse();
+
+// Stop tilting
+relay_chn_tilt_stop();
+
+// Set tilting sensitivity (sensitivity as percentage)
+relay_chn_tilt_sensitivity_set(90);
+
+// Get tilting sensitivity (sensitivty as percentage)
+uint8_t sensitivity = relay_chn_tilt_get_sensitivity();
+```
+
+For multi mode:
+
+```c
+// Assuming CONFIG_RELAY_CHN_ENABLE_TILTING is enabled
+
+// Start tilting automatically on channel #0
 relay_chn_tilt_auto(0);
+relay_chn_tilt_auto(RELAY_CHN_ID_ALL); // on all channels
 
-// Tilt forward (channel 0)
-relay_chn_tilt_forward(0);
+// Tilt forward on channel #1
+relay_chn_tilt_forward(1);
+relay_chn_tilt_forward(RELAY_CHN_ID_ALL);
 
-// Tilt reverse (channel 0)
-relay_chn_tilt_reverse(0);
+// Tilt reverse on channel #2
+relay_chn_tilt_reverse(2);
+relay_chn_tilt_reverse(RELAY_CHN_ID_ALL);
 
-// Stop tilting (channel 0)
+// Stop tilting on channel #0
 relay_chn_tilt_stop(0);
+relay_chn_tilt_stop(RELAY_CHN_ID_ALL);
 
-// Set tilting sensitivity (channel 0, sensitivity as percentage)
+// Set tilting sensitivity (sensitivity as percentage) for channel #0
 relay_chn_tilt_sensitivity_set(0, 90);
+relay_chn_tilt_sensitivity_set(RELAY_CHN_ID_ALL, 90);
 
-// Get tilting sensitivity (channel 0, sensitivty as percentage)
-uint8_t sensitivity = relay_chn_tilt_sensitivity_get(0);
+// Get tilting sensitivity (sensitivty as percentage)
+uint8_t sensitivity;
+relay_chn_tilt_get_sensitivity(0, &sensitivity, sizeof(sensitivity));
 ```
 
 ## License