RA Flexible Software Package Documentation  Release v5.5.0

 
Operational Amplifier (r_opamp)

Functions

fsp_err_t R_OPAMP_Open (opamp_ctrl_t *const p_api_ctrl, opamp_cfg_t const *const p_cfg)
 
fsp_err_t R_OPAMP_InfoGet (opamp_ctrl_t *const p_api_ctrl, opamp_info_t *const p_info)
 
fsp_err_t R_OPAMP_Start (opamp_ctrl_t *const p_api_ctrl, uint32_t const channel_mask)
 
fsp_err_t R_OPAMP_Stop (opamp_ctrl_t *const p_api_ctrl, uint32_t const channel_mask)
 
fsp_err_t R_OPAMP_StatusGet (opamp_ctrl_t *const p_api_ctrl, opamp_status_t *const p_status)
 
fsp_err_t R_OPAMP_Trim (opamp_ctrl_t *const p_api_ctrl, opamp_trim_cmd_t const cmd, opamp_trim_args_t const *const p_args)
 
fsp_err_t R_OPAMP_Close (opamp_ctrl_t *const p_api_ctrl)
 

Detailed Description

Driver for the OPAMP peripheral on RA MCUs. This module implements the OPAMP Interface.

Overview

The OPAMP HAL module provides a high level API for signal amplification applications and supports the OPAMP peripheral available on RA MCUs.

Features

Configuration

Build Time Configurations for r_opamp

The following build time configurations are defined in fsp_cfg/r_opamp_cfg.h:

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.

Configurations for Analog > Operational Amplifier (r_opamp)

This module can be added to the Stacks tab via New Stack > Analog > Operational Amplifier (r_opamp).

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_opamp0 Module name.
AGT Start Trigger Configuration (N/A unless AGT Start Trigger is Selected for the Channel)
  • AGT1 Compare Match Starts OPAMPs 0 and 2 if configured for AGT Start, AGT0 Compare Match Starts OPAMPs 1 and 3 if configured for AGT Start
  • AGT1 Compare Match Starts OPAMPs 0 and 1 if configured for AGT Start, AGT0 Compare Match Starts OPAMPs 2 and 3 if configured for AGT Start
  • AGT1 Compare Match Starts all OPAMPs configured for AGT Start
AGT1 Compare Match Starts all OPAMPs configured for AGT Start Configure which AGT channel event triggers which op-amp channel. The AGT compare match event only starts the op-amp channel if the AGT Start trigger is selected in the Trigger configuration for the channel.
Power ModeMCU Specific OptionsConfigure the op-amp based on power or speed requirements. This setting affects the minimum required stabilization time. Middle speed is not available for all MCUs.
Trigger Channel 0MCU Specific OptionsSelect the event triggers to start or stop op-amp channel 0. If the event trigger is selected for start, the start() API enables the event trigger for this channel. If the event trigger is selected for stop, the stop() API disables the event trigger for this channel.
Trigger Channel 1MCU Specific OptionsSelect the event triggers to start or stop op-amp channel 1. If the event trigger is selected for start, the start() API enables the event trigger for this channel. If the event trigger is selected for stop, the stop() API disables the event trigger for this channel.
Trigger Channel 2
  • Software Start Software Stop
  • AGT Start Software Stop
  • AGT Start ADC Stop
Software Start Software Stop Select the event triggers to start or stop op-amp channel 2. If the event trigger is selected for start, the start() API enables the event trigger for this channel. If the event trigger is selected for stop, the stop() API disables the event trigger for this channel.
Trigger Channel 3MCU Specific OptionsSelect the event triggers to start or stop op-amp channel 3. If the event trigger is selected for start, the start() API enables the event trigger for this channel. If the event trigger is selected for stop, the stop() API disables the event trigger for this channel.
OPAMP AMP0OSMCU Specific OptionsSelect output to connect to AMP0O pin
OPAMP AMP0PSMCU Specific OptionsSelect input to connect to AMP0+ pin
OPAMP AMP0MSMCU Specific OptionsSelect input to connect to AMP0- pin
OPAMP AMP1PSMCU Specific OptionsSelect input to connect to AMP1+ pin
OPAMP AMP1MSMCU Specific OptionsSelect input to connect to AMP1- pin
OPAMP AMP2PSMCU Specific OptionsSelect input to connect to AMP2+ pin
OPAMP AMP2MSMCU Specific OptionsSelect input to connect to AMP2- pin

Clock Configuration

The OPAMP runs on PCLKB.

Pin Configuration

To use the OPAMP HAL module, the port pins for the channels receiving the analog input must be set as inputs on the Pins tab of the RA Configuration editor.

Refer to the most recent FSP Release Notes for any additional operational limitations for this module.

Usage Notes

Trimming the OPAMP

Examples

Basic Example

This is a basic example of minimal use of the R_OPAMP in an application. The example demonstrates configuring OPAMP channel 0 for high speed mode, starting the OPAMP and reading the status of the OPAMP channel running. It also verifies that the stabilization wait time is the expected time for selected power mode

#define OPAMP_EXAMPLE_CHANNEL (0U)
void basic_example (void)
{
fsp_err_t err;
/* Initialize the OPAMP module. */
err = R_OPAMP_Open(&g_opamp_ctrl, &g_opamp_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Start the OPAMP module. */
err = R_OPAMP_Start(&g_opamp_ctrl, 1 << OPAMP_EXAMPLE_CHANNEL);
assert(FSP_SUCCESS == err);
/* Look up the required stabilization wait time. */
err = R_OPAMP_InfoGet(&g_opamp_ctrl, &info);
assert(FSP_SUCCESS == err);
/* Wait for the OPAMP to stabilize. */
}

Trim Example

This example demonstrates the typical trimming procedure for opamp channel 0 using R_OPAMP_Trim() API.

#ifndef OPAMP_EXAMPLE_CHANNEL
#define OPAMP_EXAMPLE_CHANNEL (0U)
#endif
#ifndef OPAMP_EXAMPLE_ADC_CHANNEL
#define OPAMP_EXAMPLE_ADC_CHANNEL (ADC_CHANNEL_2)
#endif
#define ADC_SCAN_END_DELAY (100U)
#define OPAMP_TRIM_LOOP_COUNT (5)
#define ADC_SCAN_END_MAX_TIMEOUT (0xFFFF)
uint32_t g_callback_event_counter = 0;
opamp_trim_args_t trim_args_ch =
{
.channel = OPAMP_EXAMPLE_CHANNEL,
};
/* This callback is called when ADC Scan Complete event is generated. */
void adc_callback (adc_callback_args_t * p_args)
{
g_callback_event_counter++;
}
void trimming_example (void)
{
fsp_err_t err;
/* On RA2A1, configure negative feedback and put DAC12 signal on AMP0+ Pin. */
g_opamp_cfg_extend.plus_input_select_opamp0 = OPAMP_PLUS_INPUT_AMPPS7;
g_opamp_cfg_extend.minus_input_select_opamp0 = OPAMP_MINUS_INPUT_AMPMS7;
/* Initialize the OPAMP module. */
err = R_OPAMP_Open(&g_opamp_ctrl, &g_opamp_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Start the OPAMP module. */
err = R_OPAMP_Start(&g_opamp_ctrl, 1 << OPAMP_EXAMPLE_CHANNEL);
assert(FSP_SUCCESS == err);
/* Look up the required stabilization wait time. */
err = R_OPAMP_InfoGet(&g_opamp_ctrl, &info);
assert(FSP_SUCCESS == err);
/* Wait for the OPAMP to stabilize. */
/* Call trim() for the Pch (+) side input */
trim_procedure(&trim_args_ch);
assert(FSP_SUCCESS == err);
trim_args_ch.input = OPAMP_TRIM_INPUT_NCH;
/* Call trim() for the Nch (-) side input */
trim_procedure(&trim_args_ch);
}
void trim_procedure (opamp_trim_args_t * trim_args)
{
fsp_err_t err;
/* Call trim() for the selected channel and input with command OPAMP_TRIM_CMD_START. */
err = R_OPAMP_Trim(&g_opamp_ctrl, OPAMP_TRIM_CMD_START, trim_args);
assert(FSP_SUCCESS == err);
/* Measure the fixed voltage connected to the channel input using the SAR ADC and save the value
* (referred to as result_a later in this procedure). */
/* Reset the ADC callback counter */
g_callback_event_counter = 0;
err = R_ADC_ScanStart(&g_adc_ctrl);
assert(FSP_SUCCESS == err);
/* Wait for ADC scan complete flag */
uint32_t timeout = ADC_SCAN_END_MAX_TIMEOUT;
while (g_callback_event_counter == 0 && timeout != 0)
{
timeout--;
}
if (0 == timeout)
{
assert(FSP_SUCCESS == err);
}
uint16_t result_a;
err = R_ADC_Read(&g_adc_ctrl, OPAMP_EXAMPLE_ADC_CHANNEL, &result_a);
assert(FSP_SUCCESS == err);
/* Iterate over the following loop 5 times: */
/* Call trim() with command OPAMP_TRIM_CMD_NEXT_STEP for the selected channel and given input. */
uint8_t count = OPAMP_TRIM_LOOP_COUNT;
while (count > 0)
{
count--;
err = R_OPAMP_Trim(&g_opamp_ctrl, OPAMP_TRIM_CMD_NEXT_STEP, trim_args);
assert(FSP_SUCCESS == err);
/* Reset the ADC callback counter */
g_callback_event_counter = 0;
/* Read converted value after trim completes. */
err = R_ADC_ScanStart(&g_adc_ctrl);
assert(FSP_SUCCESS == err);
/* Wait for ADC scan complete flag */
timeout = ADC_SCAN_END_MAX_TIMEOUT;
while (g_callback_event_counter == 0 && timeout != 0)
{
timeout--;
}
if (0 == timeout)
{
assert(FSP_SUCCESS == err);
}
uint16_t result_b;
err = R_ADC_Read(&g_adc_ctrl, OPAMP_EXAMPLE_ADC_CHANNEL, &result_b);
assert(FSP_SUCCESS == err);
/* Measure the op-amp output using the SAR ADC (referred to as result_b in the next step). */
/* If result_a <= result_b, call trim() for the selected channel and input with command OPAMP_TRIM_CMD_CLEAR_BIT. */
if (result_a <= result_b)
{
err = R_OPAMP_Trim(&g_opamp_ctrl, OPAMP_TRIM_CMD_CLEAR_BIT, trim_args);
assert(FSP_SUCCESS == err);
}
}
}

Data Structures

struct  opamp_extended_cfg_t
 
struct  opamp_instance_ctrl_t
 

Macros

#define OPAMP_MASK_CHANNEL_0
 

Enumerations

enum  opamp_trigger_t
 
enum  opamp_agt_link_t
 
enum  opamp_mode_t
 
enum  opamp_plus_input_t
 
enum  opamp_minus_input_t
 
enum  opamp_output_t
 

Variables

const opamp_api_t g_opamp_on_opamp
 

Data Structure Documentation

◆ opamp_extended_cfg_t

struct opamp_extended_cfg_t

OPAMP configuration extension. This extension is required and must be provided in opamp_cfg_t::p_extend.

Data Fields
opamp_agt_link_t agt_link

Configure which AGT links are paired to which channel. Only applies to channels if OPAMP_TRIGGER_AGT_START_SOFTWARE_STOP or OPAMP_TRIGGER_AGT_START_ADC_STOP is selected for the channel.

opamp_mode_t mode Low power, middle speed, or high speed mode.
opamp_trigger_t trigger_channel_0 Start and stop triggers for channel 0.
opamp_trigger_t trigger_channel_1 Start and stop triggers for channel 1.
opamp_trigger_t trigger_channel_2 Start and stop triggers for channel 2.
opamp_trigger_t trigger_channel_3 Start and stop triggers for channel 3.
opamp_plus_input_t plus_input_select_opamp0 OPAMP0+ connection.
opamp_minus_input_t minus_input_select_opamp0 OPAMP0- connection.
opamp_output_t output_select_opamp0 OPAMP0O connection.
opamp_plus_input_t plus_input_select_opamp1 OPAMP1+ connection.
opamp_minus_input_t minus_input_select_opamp1 OPAMP1- connection.
opamp_plus_input_t plus_input_select_opamp2 OPAMP2+ connection.
opamp_minus_input_t minus_input_select_opamp2 OPAMP2- connection.

◆ opamp_instance_ctrl_t

struct opamp_instance_ctrl_t

OPAMP instance control block. DO NOT INITIALIZE. Initialized in opamp_api_t::open().

Macro Definition Documentation

◆ OPAMP_MASK_CHANNEL_0

#define OPAMP_MASK_CHANNEL_0

Version of code that implements the API defined in this file

Enumeration Type Documentation

◆ opamp_trigger_t

Start and stop trigger for the op-amp.

Enumerator
OPAMP_TRIGGER_SOFTWARE_START_SOFTWARE_STOP 

Start and stop with APIs.

OPAMP_TRIGGER_AGT_START_SOFTWARE_STOP 

Start by AGT compare match and stop with API.

OPAMP_TRIGGER_AGT_START_ADC_STOP 

Start by AGT compare match and stop after ADC conversion.

◆ opamp_agt_link_t

Which AGT timer starts the op-amp. Only applies to channels if OPAMP_TRIGGER_AGT_START_SOFTWARE_STOP or OPAMP_TRIGGER_AGT_START_ADC_STOP is selected for the channel. If OPAMP_TRIGGER_SOFTWARE_START_SOFTWARE_STOP is selected for a channel, then no AGT compare match event will start that op-amp channel.

Enumerator
OPAMP_AGT_LINK_AGT1_OPAMP_0_2_AGT0_OPAMP_1_3 

OPAMP channel 0 and 2 are started by AGT1 compare match. OPAMP channel 1 and 3 are started by AGT0 compare match.

OPAMP_AGT_LINK_AGT1_OPAMP_0_1_AGT0_OPAMP_2_3 

OPAMP channel 0 and 1 are started by AGT1 compare match. OPAMP channel 2 and 3 are started by AGT0 compare match.

OPAMP_AGT_LINK_AGT1_OPAMP_0_1_2_3 

All OPAMP channels are started by AGT1 compare match.

◆ opamp_mode_t

Op-amp mode.

Enumerator
OPAMP_MODE_LOW_POWER 

Low power mode.

OPAMP_MODE_MIDDLE_SPEED 

Middle speed mode (not supported on all MCUs)

OPAMP_MODE_HIGH_SPEED 

High speed mode.

◆ opamp_plus_input_t

Options to connect AMPnPS pins.

Enumerator
OPAMP_PLUS_INPUT_NONE 

No Connection.

OPAMP_PLUS_INPUT_AMPPS0 

Set AMPPS0. See hardware manual for channel specific options.

OPAMP_PLUS_INPUT_AMPPS1 

Set AMPPS1. See hardware manual for channel specific options.

OPAMP_PLUS_INPUT_AMPPS2 

Set AMPPS2. See hardware manual for channel specific options.

OPAMP_PLUS_INPUT_AMPPS3 

Set AMPPS3. See hardware manual for channel specific options.

OPAMP_PLUS_INPUT_AMPPS7 

Set AMPPS7. See hardware manual for channel specific options.

◆ opamp_minus_input_t

Options to connect AMPnMS pins.

Enumerator
OPAMP_MINUS_INPUT_NONE 

No Connection.

OPAMP_MINUS_INPUT_AMPMS0 

Set AMPMS0. See hardware manual for channel specific options.

OPAMP_MINUS_INPUT_AMPMS1 

Set AMPMS1. See hardware manual for channel specific options.

OPAMP_MINUS_INPUT_AMPMS2 

Set AMPMS2. See hardware manual for channel specific options.

OPAMP_MINUS_INPUT_AMPMS3 

Set AMPMS3. See hardware manual for channel specific options.

OPAMP_MINUS_INPUT_AMPMS4 

Set AMPMS4. See hardware manual for channel specific options.

OPAMP_MINUS_INPUT_AMPMS7 

Set AMPMS7. See hardware manual for channel specific options.

◆ opamp_output_t

Options to connect AMP0OS pin.

Enumerator
OPAMP_OUTPUT_NONE 

No Connection.

OPAMP_OUTPUT_AMPOS0 

Set AMPOS0. See hardware manual for channel specific options.

OPAMP_OUTPUT_AMPOS1 

Set AMPOS1. See hardware manual for channel specific options.

OPAMP_OUTPUT_AMPOS2 

Set AMPOS2. See hardware manual for channel specific options.

OPAMP_OUTPUT_AMPOS3 

Set AMPOS3. See hardware manual for channel specific options.

Function Documentation

◆ R_OPAMP_Open()

fsp_err_t R_OPAMP_Open ( opamp_ctrl_t *const  p_api_ctrl,
opamp_cfg_t const *const  p_cfg 
)

Applies power to the OPAMP and initializes the hardware based on the user configuration. Implements opamp_api_t::open.

The op-amp is not operational until the opamp_api_t::start is called. If the op-amp is configured to start after AGT compare match, the op-amp is not operational until opamp_api_t::start and the associated AGT compare match event occurs.

Some MCUs have switches that must be set before starting the op-amp. These switches must be set in the application code after opamp_api_t::open and before opamp_api_t::start.

Example:

/* Initialize the OPAMP module. */
err = R_OPAMP_Open(&g_opamp_ctrl, &g_opamp_cfg);
Return values
FSP_SUCCESSConfiguration successful.
FSP_ERR_ASSERTIONAn input pointer is NULL.
FSP_ERR_ALREADY_OPENControl block is already opened.
FSP_ERR_INVALID_ARGUMENTAn attempt to configure OPAMP in middle speed mode on MCU that does not support middle speed mode.

◆ R_OPAMP_InfoGet()

fsp_err_t R_OPAMP_InfoGet ( opamp_ctrl_t *const  p_api_ctrl,
opamp_info_t *const  p_info 
)

Provides the minimum stabilization wait time in microseconds. Implements opamp_api_t::infoGet.

◆ R_OPAMP_Start()

fsp_err_t R_OPAMP_Start ( opamp_ctrl_t *const  p_api_ctrl,
uint32_t const  channel_mask 
)

If the OPAMP is configured for hardware triggers, enables hardware triggers. Otherwise, starts the op-amp. Implements opamp_api_t::start.

Some MCUs have switches that must be set before starting the op-amp. These switches must be set in the application code after opamp_api_t::open and before opamp_api_t::start.

Example:

/* Start the OPAMP module. */
err = R_OPAMP_Start(&g_opamp_ctrl, 1 << OPAMP_EXAMPLE_CHANNEL);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSOp-amp started or hardware triggers enabled successfully.
FSP_ERR_ASSERTIONAn input pointer was NULL.
FSP_ERR_NOT_OPENInstance control block is not open.
FSP_ERR_INVALID_ARGUMENTchannel_mask includes a channel that does not exist on this MCU.

◆ R_OPAMP_Stop()

fsp_err_t R_OPAMP_Stop ( opamp_ctrl_t *const  p_api_ctrl,
uint32_t const  channel_mask 
)

Stops the op-amp. If the OPAMP is configured for hardware triggers, disables hardware triggers. Implements opamp_api_t::stop.

Return values
FSP_SUCCESSOp-amp stopped or hardware triggers disabled successfully.
FSP_ERR_ASSERTIONAn input pointer was NULL.
FSP_ERR_NOT_OPENInstance control block is not open.
FSP_ERR_INVALID_ARGUMENTchannel_mask includes a channel that does not exist on this MCU.

◆ R_OPAMP_StatusGet()

fsp_err_t R_OPAMP_StatusGet ( opamp_ctrl_t *const  p_api_ctrl,
opamp_status_t *const  p_status 
)

Provides the operating status for each op-amp in a bitmask. This bit is set when operation begins, before the stabilization wait time has elapsed. Implements opamp_api_t::statusGet.

Return values
FSP_SUCCESSOperating status of each op-amp provided in p_status.
FSP_ERR_ASSERTIONAn input pointer was NULL.
FSP_ERR_NOT_OPENInstance control block is not open.

◆ R_OPAMP_Trim()

fsp_err_t R_OPAMP_Trim ( opamp_ctrl_t *const  p_api_ctrl,
opamp_trim_cmd_t const  cmd,
opamp_trim_args_t const *const  p_args 
)

On MCUs that support trimming, the op-amp trim register is set to the factory default after open(). This function allows the application to trim the operational amplifier to a user setting, which overwrites the factory default factory trim values.

Not supported on all MCUs. See hardware manual for details. Not supported if configured for low power mode (OPAMP_MODE_LOW_POWER).

This function is not reentrant. Only one side of one op-amp can be trimmed at a time. Complete the procedure for one side of one channel before calling trim() with command OPAMP_TRIM_CMD_START again.

Implements opamp_api_t::trim.

Reference: Section 37.9 "User Offset Trimming" RA2A1 hardware manual R01UM0008EU0130. The trim procedure works as follows:

  • Call trim() for the Pch (+) side input with command OPAMP_TRIM_CMD_START.
  • Connect a fixed voltage to the Pch (+) input.
  • Connect the Nch (-) input to the op-amp output to create a voltage follower.
  • Ensure the op-amp is operating and stabilized.
  • Call trim() for the Pch (+) side input with command OPAMP_TRIM_CMD_START.
  • Measure the fixed voltage connected to the Pch (+) input using the SAR ADC and save the value (referred to as A later in this procedure).
  • Iterate over the following loop 5 times:
    • Call trim() for the Pch (+) side input with command OPAMP_TRIM_CMD_NEXT_STEP.
    • Measure the op-amp output using the SAR ADC (referred to as B in the next step).
    • If A <= B, call trim() for the Pch (+) side input with command OPAMP_TRIM_CMD_CLEAR_BIT.
  • Call trim() for the Nch (-) side input with command OPAMP_TRIM_CMD_START.
  • Measure the fixed voltage connected to the Pch (+) input using the SAR ADC and save the value (referred to as A later in this procedure).
  • Iterate over the following loop 5 times:
    • Call trim() for the Nch (-) side input with command OPAMP_TRIM_CMD_NEXT_STEP.
    • Measure the op-amp output using the SAR ADC (referred to as B in the next step).
    • If A <= B, call trim() for the Nch (-) side input with command OPAMP_TRIM_CMD_CLEAR_BIT.
Return values
FSP_SUCCESSConversion result in p_data.
FSP_ERR_UNSUPPORTEDTrimming is not supported on this MCU.
FSP_ERR_INVALID_STATEThe command is not valid in the current state of the trim state machine.
FSP_ERR_INVALID_ARGUMENTThe requested channel is not operating or the trim procedure is not in progress for this channel/input combination.
FSP_ERR_INVALID_MODETrim is not allowed in low power mode.
FSP_ERR_ASSERTIONAn input pointer was NULL.
FSP_ERR_NOT_OPENInstance control block is not open.

◆ R_OPAMP_Close()

fsp_err_t R_OPAMP_Close ( opamp_ctrl_t *const  p_api_ctrl)

Stops the op-amps. Implements opamp_api_t::close.

Return values
FSP_SUCCESSInstance control block closed successfully.
FSP_ERR_ASSERTIONAn input pointer was NULL.
FSP_ERR_NOT_OPENInstance control block is not open.

Variable Documentation

◆ g_opamp_on_opamp

const opamp_api_t g_opamp_on_opamp

OPAMP Implementation of OPAMP interface.