README.md

@@ -12,14 +12,20 @@ An ESP-IDF component for controlling relay channels, specifically designed for d
 - Direction flipping capability
 - State monitoring and reporting
 - Optional sensitivty adjustable tilting feature
+- Optional NVS storage for persistent configuration
 
 ## 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. To prevent mechanical strain on the motor, the component automatically manages direction changes with a configurable inertia delay, protecting it from abrupt reversals.
+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. To prevent mechanical strain on the motor, the component automatically manages direction changes with a configurable inertia delay, protecting it from abrupt reversals. Hence, the component handles all the required timing between the movement transitions automatically to ensure reliable operation.
 
 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.
+
+Another optional feature is NVS storage, which saves the configuration permanently across reboots of the device. These configurations are:
+
+- Direction
+- Tilt sensitivity
+- Last tilt position
 
 ## Configuration
 
@@ -28,6 +34,71 @@ Configure the component through menuconfig under "Relay Channel Driver Configura
 - `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)
+- `CONFIG_RELAY_CHN_ENABLE_NVS`: Enable persistent storage in NVS (default: n)
+
+When NVS storage is enabled (`CONFIG_RELAY_CHN_ENABLE_NVS`), additional configuration options become available:
+
+- `CONFIG_RELAY_CHN_NVS_NAMESPACE`: NVS namespace for storing relay channel data (default: "relay_chn")
+- `CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION`: Use custom NVS partition instead of default (default: n)
+- `CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION_NAME`: Name of the custom partition if enabled (default "app_data")
+
+### NVS Storage Prerequisites
+
+> [!WARNING]
+> `relay_chn` component does not initialize the NVS flash.
+
+If NVS storage is enabled, you must initialize NVS flash before calling `relay_chn_create()` in your application code. The `relay_chn` component can use either the default or a custom NVS partition from your application, depending on the configuration settings.
+
+#### Initialize for Default Partition
+
+1. Enable NVS, but keep the custom partition option disabled in `menuconfig`:
+
+```ini
+CONFIG_RELAY_CHN_ENABLE_NVS=y
+CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION=n
+```
+
+2. Initialize the default NVS flash:
+
+```c
+// Initialize default NVS partition
+esp_err_t ret = nvs_flash_init();
+if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+    ESP_ERROR_CHECK(nvs_flash_erase());
+    ret = nvs_flash_init();
+}
+ESP_ERROR_CHECK(ret);
+
+// Now you can create relay channels
+ret = relay_chn_create(gpio_map, gpio_count);
+```
+
+#### Initialize for Custom Partition
+
+1. Enable both NVS and custom partition, also set the custom partition name in `menuconfig`.
+
+```ini
+CONFIG_RELAY_CHN_ENABLE_NVS=y
+CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION=n
+CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION_NAME=my_custom_partition
+```
+
+> [!IMPORTANT]
+> The `CONFIG_RELAY_CHN_NVS_CUSTOM_PARTITION_NAME` **must match exactly the label** defined for the custom NVS partition in the partition table. Otherwise the component initialisation will fail due to the `ESP_ERR_NVS_PART_NOT_FOUND` error.
+
+2. Initialize the custom NVS partition:
+
+```c
+esp_err_t ret = nvs_flash_init_partition(YOUR_CUSTOM_PARTITION_NAME);
+if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+    ESP_ERROR_CHECK(nvs_flash_erase_partition(YOUR_CUSTOM_PARTITION_NAME));
+    ret = nvs_flash_init_partition(YOUR_CUSTOM_PARTITION_NAME);
+}
+ESP_ERROR_CHECK(ret);
+
+// Now you can create relay channels
+ret = relay_chn_create(gpio_map, gpio_count);
+```
 
 ## Installation