Hardware Abstraction Layer (HAL)
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:

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);
cyhal_power_level_t power
Power mode the comparator should operate in.
Definition: cyhal_comp.h:116
void cyhal_comp_free(cyhal_comp_t *obj)
Deinitialize the Comparator peripheral.
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.
Configuration options for the Comparator.
Definition: cyhal_comp.h:114
@ CYHAL_POWER_LEVEL_HIGH
High comparator power and speed.
Definition: cyhal_general_types.h:150
Comparator object.
Definition: cyhal_hw_types.h:571
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426

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);
bool cyhal_comp_read(cyhal_comp_t *obj)
Reads the Comparator state.
@ NC
No Connect/Invalid Pin.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:53

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
}
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.
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.
cyhal_comp_event_t
Comparator event types.
Definition: cyhal_comp.h:107
@ CYHAL_COMP_FALLING_EDGE
Falling edge on comparator output.
Definition: cyhal_comp.h:109
@ CYHAL_COMP_RISING_EDGE
Rising edge on comparator output.
Definition: cyhal_comp.h:108
#define CYHAL_ISR_PRIORITY_DEFAULT
Priority that is applied by default to all drivers when initialized.
Definition: cyhal_hw_types.h:114

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
// When the comparator is needed again, power it back on
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.
@ CYHAL_POWER_LEVEL_OFF
Power-off the comparator, while retaining configuration.
Definition: cyhal_general_types.h:144
@ CYHAL_POWER_LEVEL_DEFAULT
Default comparator power and speed.
Definition: cyhal_general_types.h:152

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

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]objPointer to a Comparator object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]vin_pNon-inverting input pin
[in]vin_mInverting input pin
[in]outputComparator output pin. May be NC.
[in]cfgConfiguration 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]objPointer to a comparator object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]cfgConfiguration 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]objComparator 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]objComparator object
[in]powerThe 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]objComparator object
[in]cfgNew 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]objComparator 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]objComparator object
[in]callbackFunction to call when the specified event happens
[in]callback_argGeneric 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]objComparator object
[in]eventComparator event
[in]intr_priorityPriority for NVIC interrupt events
[in]enableTrue to turn on event, False to turn off