COMP (Analog Comparator)

General Description

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:

• Output to pin
• Read state via firmware (see cyhal_comp_read)
• Event triggered on rising or falling edge (see cyhal_comp_event_t)

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 PIN_VINP for the input, pin PIN_VINM for the reference and
    // PIN_VOUT for the output
    rslt = cyhal_comp_init(&comp_obj, PIN_VINP, PIN_VINM, PIN_VOUT, &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 PIN_VINP for the input and pin PIN_VINM for the reference.
    // No output pin is used.
    rslt = cyhal_comp_init(&comp_obj, PIN_VINP, PIN_VINM, 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);

API Reference
	Comparator HAL Results
	Comparator specific return codes.

Data Structures
struct	cyhal_comp_config_t
	Configuration options for the Comparator. More...

Typedefs
typedef void(*	cyhal_comp_event_callback_t) (void *callback_arg, cyhal_comp_event_t event)
	Handler for Comparator events. More...

Enumerations
enum	cyhal_comp_event_t {   CYHAL_COMP_RISING_EDGE = 0x01,   CYHAL_COMP_FALLING_EDGE = 0x02 }
	Comparator event types. More...

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. More...
cy_rslt_t	cyhal_comp_init_cfg (cyhal_comp_t *obj, const cyhal_comp_configurator_t *cfg)
	Initialize the comparator peripheral using a configurator generated configuration struct. More...
void	cyhal_comp_free (cyhal_comp_t *obj)
	Deinitialize the Comparator peripheral. More...
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. More...
cy_rslt_t	cyhal_comp_configure (cyhal_comp_t *obj, cyhal_comp_config_t *cfg)
	Reconfigure the Comparator. More...
bool	cyhal_comp_read (cyhal_comp_t *obj)
	Reads the Comparator state. More...
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. More...
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. More...

---

Data Structure Documentation

cyhal_comp_config_t

struct cyhal_comp_config_t

Data Fields
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

Typedef Documentation

cyhal_comp_event_callback_t

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

Enumeration Type Documentation

cyhal_comp_event_t

enum cyhal_comp_event_t

Comparator event types.

Enumerator
CYHAL_COMP_RISING_EDGE	Rising edge on comparator output.
CYHAL_COMP_FALLING_EDGE	Falling edge on comparator output.

Function Documentation

cyhal_comp_init()

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.

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

Returns

The status of the init request

cyhal_comp_init_cfg()

cy_rslt_t cyhal_comp_init_cfg	(	cyhal_comp_t *	obj,
		const cyhal_comp_configurator_t *	cfg
	)

Initialize the comparator peripheral using a configurator generated configuration struct.

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]	cfg	Configuration structure generated by a configurator.

Returns

The status of the init request

cyhal_comp_free()

void cyhal_comp_free

(

cyhal_comp_t *

obj

)

Deinitialize the Comparator peripheral.

Parameters

[in]

obj

Comparator object

cyhal_comp_set_power()

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.

Parameters

[in]	obj	Comparator object
[in]	power	The power level to set

Returns

The status of the set power request

cyhal_comp_configure()

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.

Parameters

[in]	obj	Comparator object
[in]	cfg	New configuration to apply

Returns

The status of the configure request

cyhal_comp_read()

bool cyhal_comp_read

(

cyhal_comp_t *

obj

)

Reads the Comparator state.

Parameters

[in]

obj

Comparator object

Returns

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

cyhal_comp_register_callback()

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

cyhal_comp_enable_event()

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