COMP (Analog Comparator)

group group_hal_comp

High level interface for interacting with an analog Comparator.

Features

The analog comparator measures one input voltage from the non-inverting pin against a second voltage provided on the inverting pin. The result of this comparison can be used in three ways:

These three abilities can be used in any combination.

Quickstart

Call cyhal_comp_init to initialize a comparator instance by providing the comparator object (obj), non-inverting input pin (vin_p), inverting input pin (vin_m), optional output pin (output), and configuration (cfg).

Use cyhal_comp_read to read the comparator state from firmware.

Use cyhal_comp_register_callback and cyhal_comp_enable_event to configure a callback that will be invoked on a rising and/or falling edge of the comparator output.

Code Snippets:

note

Error checking is omitted for clarity

Snippet 1: Comparator initialization

The following snippet initializes the comparator and powers it on

    cy_rslt_t           rslt;
    cyhal_comp_t        comp_obj;
    cyhal_comp_config_t config = { .power = CYHAL_POWER_LEVEL_HIGH, .hysteresis = false };

    // Initialize comparator, using pin P9_0 for the input, pin P9_1 for the reference and P9_2 for
    // the output
    rslt = cyhal_comp_init(&comp_obj, P9_0, P9_1, P9_2, &config);

    // Release comparator object after use
    cyhal_comp_free(&comp_obj);

Snippet 2: Comparator read value

The following snippet reads the current comparator value into a variable

    cy_rslt_t           rslt;
    cyhal_comp_t        comp_obj;
    cyhal_comp_config_t config = { .power = CYHAL_POWER_LEVEL_HIGH, .hysteresis = false };

    // Initialize comparator, using pin P9_0 for the input and pin P9_1 for the reference.
    // No output pin is used.
    rslt = cyhal_comp_init(&comp_obj, P9_0, P9_1, NC, &config);

    // Read the comparator value
    bool comp_value = cyhal_comp_read(&comp_obj);

    // Release comparator object after use
    cyhal_comp_free(&comp_obj);

Snippet 3: Comparator event registration

The following snippet registers a callback that will be called on either a rising or falling edge of the comparator output.

static void comp_event_handler(void* arg, cyhal_comp_event_t event)
{
    CY_UNUSED_PARAMETER(arg);
    // Note: arg is configured below to be a pointer to the cyhal_comp_t instance that caused the
    //       event
    if (0u != (event & CYHAL_COMP_RISING_EDGE))
    {
        // Handle rising edge
    }
    if (0u != (event & CYHAL_COMP_FALLING_EDGE))
    {
        // Handle falling edge
    }
}


void snippet_cyhal_comp_event_handling(void)
{
    cyhal_comp_t comp_obj;
    // Initialize the object as shown in Snippet 1

    // Register a callback and set the callback argument to be a pointer to the comparator object,
    // so that we can easily reference it from the callback handler.
    cyhal_comp_register_callback(&comp_obj, &comp_event_handler, &comp_obj);

    // Subscribe to both the rising and falling edges, so that the event handler is called whenever
    // the comparator output changes
    cyhal_comp_enable_event(&comp_obj,
                            (cyhal_comp_event_t)(CYHAL_COMP_RISING_EDGE | CYHAL_COMP_FALLING_EDGE),
                            CYHAL_ISR_PRIORITY_DEFAULT, true);
}

Snippet 4: Comparator powering-off and on

The following snippet demonstrates temporarily powering-off the comparator without freeing it.

    // This assumes that the comparator has already been initialized as shown in snippet 1 or 2

    // Power-on the comparator
    rslt = cyhal_comp_set_power(&comp_obj, CYHAL_POWER_LEVEL_DEFAULT);

    rslt = cyhal_comp_set_power(&comp_obj, CYHAL_POWER_LEVEL_OFF);

    // When the comparator is needed again, power it back on
    rslt = cyhal_comp_set_power(&comp_obj, CYHAL_POWER_LEVEL_DEFAULT);

Typedefs

typedef void (*cyhal_comp_event_callback_t)(void *callback_arg, cyhal_comp_event_t event)

Handler for Comparator events.

note

Not all hardware is capable of differentiating which type of edge triggered an event when both rising and falling edges are enabled. If the edge cannot be determined, the event argument will be CYHAL_COMP_RISING_EDGE | CYHAL_COMP_FALLING_EDGE

Enums

enum cyhal_comp_event_t

cyhal_comp_event_t: Comparator event types.

Values:

enumerator CYHAL_COMP_RISING_EDGE

Rising edge on comparator output.

enumerator CYHAL_COMP_FALLING_EDGE

Falling edge on comparator output.

Functions

cy_rslt_t cyhal_comp_init(cyhal_comp_t *obj, cyhal_gpio_t vin_p, cyhal_gpio_t vin_m, cyhal_gpio_t output, cyhal_comp_config_t *cfg)

Initialize the Comparator peripheral.

Return

The status of the init request

Parameters
  • [out] obj: Pointer to a Comparator object. The caller must allocate the memory for this object but the init function will initialize its contents.

  • [in] vin_p: Non-inverting input pin

  • [in] vin_m: Inverting input pin

  • [in] output: Comparator output pin. May be NC.

  • [in] cfg: Configuration structure

void cyhal_comp_free(cyhal_comp_t *obj)

Deinitialize the Comparator peripheral.

Parameters
  • [in] obj: Comparator object

cy_rslt_t cyhal_comp_set_power(cyhal_comp_t *obj, cyhal_power_level_t power)

Changes the current operating power level of the comparator.

If the power level is set to CYHAL_POWER_LEVEL_OFF, the comparator will be powered-off but it will retain its configuration, so it is not necessary to reconfigure it when changing the power level from CYHAL_POWER_LEVEL_OFF to any other value.

Return

The status of the set power request

Parameters
  • [in] obj: Comparator object

  • [in] power: The power level to set

cy_rslt_t cyhal_comp_configure(cyhal_comp_t *obj, cyhal_comp_config_t *cfg)

Reconfigure the Comparator.

This retains the powered state of the comparator. Depending on the implementation, it may be necessary to temporarily deconfigure and/or power off the comparator in order to apply the new configuration. However, if the comparator is powered-off when this function is called, it will remain powered-off after it returns. Likewise, if the comparator is powered-on when this function is called, it will remain powered-on after it returns.

Return

The status of the configure request

Parameters
  • [in] obj: Comparator object

  • [in] cfg: New configuration to apply

bool cyhal_comp_read(cyhal_comp_t *obj)

Reads the Comparator state.

Return

The Comparator state. True if the non-inverting pin voltage is greater than the inverting pin voltage, false otherwise.

Parameters
  • [in] obj: Comparator object

void cyhal_comp_register_callback(cyhal_comp_t *obj, cyhal_comp_event_callback_t callback, void *callback_arg)

Register/clear a callback handler for Comparator events.

This function will be called when one of the events enabled by cyhal_comp_enable_event occurs.

Parameters
  • [in] obj: Comparator object

  • [in] callback: Function to call when the specified event happens

  • [in] callback_arg: Generic argument that will be provided to the handler when called

void cyhal_comp_enable_event(cyhal_comp_t *obj, cyhal_comp_event_t event, uint8_t intr_priority, bool enable)

Enable or Disable a Comparator event.

When an enabled event occurs, the function specified by cyhal_comp_register_callback will be called.

Parameters
  • [in] obj: Comparator object

  • [in] event: Comparator event

  • [in] intr_priority: Priority for NVIC interrupt events

  • [in] enable: True to turn on event, False to turn off

struct cyhal_comp_config_t
#include <cyhal_comp.h>

Configuration options for the Comparator.

Public Members

cyhal_power_level_t power

Power mode the comparator should operate in.

Lower modes save power but operate at lower speed.

bool hysteresis

Whether hysteresis should be used.

See the implementation-specific documentation for the hysteresis value