cb7b9850c8
In components/soc/esp32c5/register/soc/gpio_ext_struct.h (ESP32-C5), components/soc/esp32c61/register/soc/gpio_ext_struct.h (ESP32-C61), and components/soc/esp32p4/register/hw_ver3/soc/gpio_struct.h (ESP32-P4), the analog comparator raw/status/enable/clear register fields are named comp_neg_0_*/comp0_neg_* for bit 0 and comp_pos_0_*/comp0_pos_* for bit 1, but each field's own comment says the opposite: bit 0 is documented as "analog comparator pos edge interrupt raw/status/enable/clear" and bit 1 as the "neg" counterpart. The LL masks were defined from the field names rather than from this documented behavior, so ANALOG_CMPR_LL_POS_CROSS_INTR_MASK() ended up selecting bit 1 and ANALOG_CMPR_LL_NEG_CROSS_INTR_MASK() bit 0. A new test case, added in the following commit, arms only one cross direction at a time and checks that a matching transition fires the callback while the opposite, never-armed direction does not; without this fix it reproducibly fails on ESP32-C5, ESP32-P4, and ESP32-C61. Signed-off-by: Tiago Medicci <tiago.medicci@espressif.com>
ESP Hardware Abstraction Layer for Analog Comparator Peripheral
Note
This component is currently in beta. Its API, behavior, and compatibility may change at any time and without notice; backward compatibility is not guaranteed. Use caution when integrating into production systems.
Overview
The esp_hal_ana_cmpr component provides a Hardware Abstraction Layer for Analog Comparator peripherals across supported ESP-IDF targets. Analog comparators compare two analog voltage signals and generate digital outputs based on the comparison result, enabling threshold detection, zero-crossing detection, and analog signal monitoring applications.
Architecture
The Analog Comparator HAL is structured in two main sub-layers:
-
HAL Layer (Upper): Defines the operational steps and data structures required to control analog comparator peripherals (e.g., initialization, reference voltage configuration, cross detection setup, interrupt handling).
-
Low-Level Layer (Bottom): Serves as a translation layer between the HAL and the register files defined in the
soccomponent, handling target-specific register configurations.
Supported Controllers
This HAL supports analog comparator controllers on the following ESP chips:
- ESP32-P4: Dual analog comparator units (ANA_CMPR_U0, ANA_CMPR_U1)
- Others: Single analog comparator unit
Features
Reference Voltage Configuration
- Internal Reference Voltage: Configurable internal reference voltage from 0% to 70% VDD in 10% steps (0.0V, 0.1VDD, 0.2VDD, ..., 0.7VDD)
- External Reference Voltage: Support for external reference voltage via dedicated GPIO pad (typically GPIO10)
- Reference Source Selection: Switch between internal and external reference sources
Cross Detection
- Positive Cross Detection: Detects when the input analog signal crosses the reference voltage from low to high
- Negative Cross Detection: Detects when the input analog signal crosses the reference voltage from high to low
- Any Cross Detection: Detects both positive and negative crossings
- Debounce Filtering: Configurable debounce cycle to ensure stable cross detection and filter out noise
Interrupt Handling
- Multiple Interrupt Types: Support for positive cross, negative cross, and any cross interrupts
- Interrupt Masking: Flexible interrupt enable/disable control per interrupt type
- Interrupt Status: Read interrupt status and clear interrupt flags
- Interrupt Register Access: Direct access to interrupt status register for advanced use cases
Signal Processing
- Debounce Cycle: Configurable debounce cycle count to filter out glitches and ensure stable detection
- Hardware Filtering: Built-in hardware filtering for noise reduction
Event Task Matrix (ETM) Support
- ETM Event Source: Analog comparator cross events can be used as ETM event sources for precise timing and synchronization
- Multiple Event Types: Support for positive and negative cross events as separate ETM sources
Peripheral Configuration
- GPIO Mapping: Each comparator unit has dedicated source GPIO and external reference GPIO pins
- Module Identification: Each comparator unit has a unique module name for identification
- Interrupt Source: Each comparator unit has a dedicated interrupt source
Usage
The HAL functions primarily serve ESP-IDF peripheral drivers such as esp_driver_ana_cmpr.
Advanced developers can use these interfaces directly when implementing custom drivers, with the understanding that API stability is not guaranteed.
Dependencies
soc: Provides chip-specific register definitionshal: Core hardware abstraction utilities and macros