Zero_Detection

[中文]

The zero cross detection driver is a component designed to analyze zero cross signals. By examining the period and triggering edges of zero cross signals, it can determine the signal’s validity, invalidity, whether it exceeds the expected frequency range, and if there are signal losses, among other conditions.

The zero cross detection component supports the detection of two types of zero cross signals.

Square Wave: Inverts the current voltage level when the signal crosses zero.
Pulse Wave: A pulse generated when the signal crosses zero.

Due to factors such as response delay, this component supports two driving modes, including GPIO interrupt and MCPWM capture.

Users can flexibly configure the component’s drive modes, as well as adjust parameters such as the effective frequency range and the number of valid signal judgments. This provides a high level of flexibility.

The program returns results and data in the form of events, meeting the user’s need for timely processing of signals.

Zero Detection event

Triggering conditions for each zero detection event are enlisted in the table below:

Event	Trigger Condition
SIGNAL_RISING_EDGE	Rising edge
SIGNAL_FALLING_EDGE	Falling edge
SIGNAL_VALID	The number of times the frequency is within the valid range exceeds the valid times.
SIGNAL_INVALID	The number of times the frequency is within the invalid range exceeds the invalid times.
SIGNAL_LOST	No rising or falling edges in the signal within 100ms.
SIGNAL_FREQ_OUT_OF_RANGE	The calculated frequency is outside the set frequency range

Attention

No blocking operations such as TaskDelay are allowed in the call-back function

Configuration

USE_GPTIMER : Decide whether to use the GPTimer driver; default is to use the ESPTimer

Demonstration

Create a zero detection

void IRAM_ATTR zero_detection_event_cb(zero_detect_event_t zero_detect_event, zero_detect_cb_param_t *param, void *usr_data)  //User's callback API
{
    switch (zero_detect_event) {
    case SIGNAL_FREQ_OUT_OF_RANGE:
        ESP_LOGE(TAG, "SIGNAL_FREQ_OUT_OF_RANGE");
        break;
    case SIGNAL_VALID:
        ESP_LOGE(TAG, "SIGNAL_VALID");
        break;
    case SIGNAL_LOST:
        ESP_LOGE(TAG, "SIGNAL_LOST");
        break;
    default:
        break;
    }
}

// Create a zero detection and register call-back
zero_detect_config_t config = {
    .capture_pin = 2,
    .freq_range_max_hz = 65,
    .freq_range_min_hz = 45,  //Hz
    .valid_times = 6,
    .invalid_times = 5,
    .zero_signal_type = SQUARE_WAVE,
    .zero_driver_type = MCPWM_TYPE,
};
zero_detect_handle_t *g_zcds = zero_detect_create(&config);
if(NULL == g_zcds) {
    ESP_LOGE(TAG, "Zero Detection create failed");
}
zero_detect_register_cb(g_zcds, zero_detection_event_cb, NULL);

API Reference

Header File

components/zero_detection/include/zero_detection.h

Functions

zero_detect_handle_t zero_detect_create(zero_detect_config_t *config)

Create a zero detect target.

Parameters

config – A zero detect object to config

Returns

zero_detect_handle_t A zero cross detection object

void zero_show_data(zero_detect_handle_t zcd_handle)

Show zero detect test data.

Parameters: zcd_handle – A zero detect handle

esp_err_t zero_detect_delete(zero_detect_handle_t zcd_handle)

Delete a zero detect device.

Parameters

zcd_handle – A zero detect handle

Returns

ESP_OK Success
ESP_FAIL Failure

bool zero_detect_get_power_status(zero_detect_handle_t zcd_handle)

Get relay power status.

Parameters

zcd_handle – A zero detect handle

Returns

true Power on
false Power off

bool zero_detect_singal_invaild_status(zero_detect_handle_t zcd_handle)

Get signal invalid status.

Parameters

zcd_handle – A zero detect handle

Returns

true Signal is invalid
false Signal is valid

zero_signal_type_t zero_detect_get_signal_type(zero_detect_handle_t zcd_handle)

Get signal type.

Parameters

zcd_handle – A zero detect handle

Returns

SQUARE_WAVE Signal type is square
PULSE_WAVE Signal type is pulse

esp_err_t zero_detect_register_cb(zero_detect_handle_t zcd_handle, zero_cross_cb_t cb, void *usr_data)

Register zero cross detection callback.

Parameters

zcd_handle – A zero detect handle
cb – A callback function
usr_data – User data

Returns

ESP_OK Success
ESP_FAIL Failure

Unions

union zero_detect_cb_param_t

#include <zero_detection.h>

Event callback parameters union.

Public Members

struct zero_detect_cb_param_t::signal_freq_event_data_t signal_freq_event_data: Signal freq event data struct

struct zero_detect_cb_param_t::signal_valid_event_data_t signal_valid_event_data: Signal valid event data struct

struct zero_detect_cb_param_t::signal_invalid_event_data_t signal_invalid_event_data: Signal invalid event data struct

struct zero_detect_cb_param_t::signal_rising_edge_event_data_t signal_rising_edge_event_data: Signal rising edge event data struct

struct zero_detect_cb_param_t::signal_falling_edge_event_data_t signal_falling_edge_event_data: Signal falling edge event_data

struct signal_falling_edge_event_data_t

#include <zero_detection.h>

Signal falling edge data return type.

Public Members

uint16_t valid_count: Counting when the signal is valid

uint16_t invalid_count: Counting when the signal is invalid

uint32_t full_cycle_us: Current signal cycle

struct signal_freq_event_data_t

#include <zero_detection.h>

Signal exceeds frequency range data return type.

Public Members

zero_signal_edge_t cap_edge: Trigger edge of zero cross signal

uint32_t full_cycle_us: Current signal cycle

struct signal_invalid_event_data_t

#include <zero_detection.h>

Signal invalid data return type.

Public Members

zero_signal_edge_t cap_edge: Trigger edge of zero cross signal

uint32_t full_cycle_us: Current signal cycle

uint16_t invalid_count: Counting when the signal is invalid

struct signal_rising_edge_event_data_t

#include <zero_detection.h>

Signal rising edge data return type.

Public Members

uint16_t valid_count: Counting when the signal is valid

uint16_t invalid_count: Counting when the signal is invalid

uint32_t full_cycle_us: Current signal cycle

struct signal_valid_event_data_t

#include <zero_detection.h>

Signal valid data return type.

Public Members

zero_signal_edge_t cap_edge: Trigger edge of zero cross signal

uint32_t full_cycle_us: Current signal cycle

uint16_t valid_count: Counting when the signal is valid

Structures

struct zero_detect_config_t

User config data type.

Public Members

int32_t capture_pin: GPIO number for zero cross detect capture

uint16_t valid_times: Minimum required number of times for detecting signal validity

uint16_t invalid_times: Minimum required number of times for detecting signal invalidity

uint64_t signal_lost_time_us: Minimum required duration for detecting signal loss

zero_signal_type_t zero_signal_type: Zero Crossing Signal type

zero_driver_type_t zero_driver_type: Zero crossing driver type

double freq_range_max_hz: Maximum value of the frequency range when determining a valid signal

double freq_range_min_hz: Minimum value of the frequency range when determining a valid signal

Macros

ZERO_DETECTION_INIT_CONFIG_DEFAULT()

Type Definitions

typedef void (*zero_cross_cb_t)(zero_detect_event_t zero_detect_event, zero_detect_cb_param_t *param, void *usr_data): Callback format.

typedef void *zero_detect_handle_t

Enumerations

enum zero_detect_event_t

Zero detection events.

Values:

enumerator SIGNAL_FREQ_OUT_OF_RANGE

enumerator SIGNAL_VALID

enumerator SIGNAL_INVALID

enumerator SIGNAL_LOST

enumerator SIGNAL_RISING_EDGE

enumerator SIGNAL_FALLING_EDGE

enum zero_signal_type_t

Zero detection wave type.

Values:

enumerator SQUARE_WAVE

enumerator PULSE_WAVE

enum zero_signal_edge_t

Zero detection signal edge type.

Values:

enumerator CAP_EDGE_POS

enumerator CAP_EDGE_NEG

enum zero_driver_type_t

Zero detection driver type.

Values:

enumerator GPIO_TYPE: Use GPIO as driver

Provide feedback about this document