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

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.

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

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

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:

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

// 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:

// 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

// 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:

// 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:

// 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:

// 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:

// 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 - Copyright (c) 2025 kozmotronik.