# relay_chn - Relay Channel Controller

An ESP-IDF component for controlling relay channels, specifically designed for driving bipolar motors through relay pairs.

## Features

- Controls multiple relay channel pairs (up to 8 channels)
- Built-in direction change inertia protection
- Automatic command sequencing and timing
- Event-driven architecture for reliable operation
- Forward/Reverse direction control
- Direction flipping capability
- State monitoring and reporting
- Optional sensitivty adjustable tilting feature
- Optional NVS storage for persistent configuration
- Optional configurable run limit protection

## 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. Hence, the component handles all the required timing between the movement transitions automatically to ensure reliable operation.

The run limit feature provides an additional layer of protection by automatically stopping channels after a configurable time period. This is particularly useful for motor-driven applications where continuous operation beyond a certain duration could cause damage or safety issues. Each channel can have its own run limit setting, and when enabled, the component will automatically stop the channel once it has been running for the specified duration.

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.  

Another optional feature is NVS storage, which saves the configuration permanently across reboots of the device. These configurations are:

- Direction
- Run limit duration
- Tilt sensitivity
- Last tilt position

## 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_RUN_LIMIT`: Enable run limit protection (default: n)
- `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 run limit is enabled (`CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT`), the following configuration options become available:

- `CONFIG_RELAY_CHN_RUN_LIMIT_MIN_SEC`: Minimum allowed run limit duration (1-60s, default: 10s)
- `CONFIG_RELAY_CHN_RUN_LIMIT_MAX_SEC`: Maximum allowed run limit duration (60-3600s, default: 600s)
- `CONFIG_RELAY_CHN_RUN_LIMIT_DEFAULT_SEC`: Default run limit duration for channels (10-3600s, default: 60s)

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

Just add it as a custom dependency to your project's `idf_component.yml`:

```yaml
dependencies:
  # Add as a custom component from git repository
  relay_chn:
    git: https://git.kozmotronik.com.tr/KozmotronikTech/relay_chn.git
    version: '>=0.5.0'
```

## 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 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
esp_err_t ret = relay_chn_create(gpio_map, gpio_count);
if (ret != ESP_OK) {
    // Handle error
}
```

### 2. Control relay channels

For single mode:

```c
// 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 #1 reverse
relay_chn_run_reverse(1);
// Run all channels reverse
relay_chn_run_reverse(RELAY_CHN_ID_ALL);

// Stop channel #1 
relay_chn_stop(1);
// Stop all channels 
relay_chn_stop(RELAY_CHN_ID_ALL);

// 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();
// 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. Run Limit Control (if enabled)

For single mode:

```c
// Assuming CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT is enabled

// Get current run limit (in seconds)
uint16_t limit = relay_chn_get_run_limit();

// Set new run limit (in seconds)
relay_chn_set_run_limit(120); // Set to 120 seconds
```

For multi mode:

```c
// Assuming CONFIG_RELAY_CHN_ENABLE_RUN_LIMIT is enabled

// Get run limit for channel #0 (in seconds)
uint16_t limit = relay_chn_get_run_limit(0);

// Set new run limit for specific channels (in seconds)
relay_chn_set_run_limit(0, 120);          // Set channel #0 to 120 seconds
relay_chn_set_run_limit(1, 180);          // Set channel #1 to 180 seconds
relay_chn_set_run_limit(RELAY_CHN_ID_ALL, 90); // Set all channels to 90 seconds
```
> [!NOTE]
> When a channel reaches its run limit, it will automatically stop. The run limit timer is reset whenever the channel starts running in either direction.

### 5. Tilting Interface (if enabled)

For single mode:

```c
// Assuming CONFIG_RELAY_CHN_ENABLE_TILTING is enabled

// 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 on channel #1
relay_chn_tilt_forward(1);
relay_chn_tilt_forward(RELAY_CHN_ID_ALL);

// Tilt reverse on channel #2
relay_chn_tilt_reverse(2);
relay_chn_tilt_reverse(RELAY_CHN_ID_ALL);

// Stop tilting on channel #0
relay_chn_tilt_stop(0);
relay_chn_tilt_stop(RELAY_CHN_ID_ALL);

// 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 (sensitivty as percentage)
uint8_t sensitivity;
relay_chn_tilt_get_sensitivity(0, &sensitivity, sizeof(sensitivity));
```

## License

[MIT License](LICENSE) - Copyright (c) 2025 kozmotronik.