 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The analog connection HAL module implements the analog connect API on r_analog_connect to simplify the connection of the analog components that comprise the analog front end on select Synergy MCUs. Previously these connections needed to be made using low-level register-based configuration instead of using the Synergy configurator. The analog connection module supports the OPAMP (operational amplifier), ACMPHS (high speed analog comparator), and ACMPLP (low power analog comparator) peripherals, and their allowed interconnections, available on the Synergy microcontroller hardware.
The Analog Connection HAL module defines API functions for making single or multiple connections. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
Analog Connection HAL Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| init | g_analog_connect.p_api ->init(g_analog_connect.p_cfg);Initialize the analog connection module. |
| connect | g_analog_connect.p_api ->connect(ANALOG_CONNECT_OPAMP0_AMPP_TO_PORT0_P013);Make connection between specified analog module input and output using a connection option enum. Enum definitions are explained in the operational notes later in this document. |
| connectMultiple | g_analog_connect.p_api->connectMultiple(&connection_table);Make all connection between specified analog module input and output as specified in the connection table analog_connect_table_t. |
| versionGet | g_analog_connect.p_api ->versionGet (&version);Get the version information of the underlying driver. |
Analog Connection HAL Module Status Return Values
| Name | Description |
|---|---|
| SSP_SUCCESS | Function completed successfully |
| SSP_ERR_ASSERTION | Data table pointer is NULL or size is 0 |
The analog connection HAL module controls the internal analog connections for the OPAMP, ACMPLP, and ACMPHS peripherals on a Synergy microcontroller. It directly controls the hardware without using any RTOS elements and provides convenient APIs to simplify development.
The following operational notes describe the available connections, the enumeration format used to describe connections, general notes and module specific notes on operations important when using the analog connect module in an application.
Available Connections
The list of connection options is unique for each MCU. This list is found in the analog_connect_t enumeration in synergy\ssp\src\bsp\mcu\<mcu_name>\bsp_analog.h, where <mcu_name> is the name of the MCU series, for example S7G2.
You can find the descriptions of the analog_connect_t enumeration for each MCU as follows:
analog_connect_t for S124analog_connect_t for S128analog_connect_t for S1JAanalog_connect_t for S3A1analog_connect_t for S3D3analog_connect_t for S3A6analog_connect_t for S3A7analog_connect_t for S5D5analog_connect_t for S5D9analog_connect_t for S7G2The connection enum format is described below:
The connection options are grouped by peripheral, channel, and signal in the analog_connect_t enumeration. All signals should be configured for each peripheral/channel combination used. For example, if an application uses ACMPHS channel 0, then exactly one connection must be made for each node that begins with ACMPHS0. Exactly one connection must be made for ACMPHS0_IVREF and ACMPHS0_IVCMP. Likewise, if an application uses OPAMP channel 0, then a connection must be made for OPAMP0_AMPP, OPAMP0_AMPM, and OPAMP0_AMPO.
General Notes Regarding Connections
The analog connect module makes internal connections only. If an application interfaces to analog signals external to the MCU, it will also require pin configurations on the Pins tab in the Synergy Configuration Tool.
Calling analog_connect_api_t::connect or analog_connect_api_t::connectMultiple overwrites any existing connection and replaces it with the new connection.
The APIs in this module have no prerequisite. They can be called before or after the associated driver's comparator_api_t::open() or opamp_api_t::open(). If the analog_connect_api_t::connect or analog_connect_api_t::connectMultiple APIs are called before the open() of the associated driver, the module stop bit for the associated peripheral channel is cleared.
The analog_connect_api_t::connectMultiple API is most efficient when connections for the same peripheral/channel combination are grouped together in the list of connections.
Connection Aliases
Not all connection aliases are listed in the analog_connect_t enumeration. For example, take the S1JA connection to connect the IVCMP input of the ACMPHS comparator to P013 (ANALOG_CONNECT_ACMPHS0_IVCMP_TO_PORT0_P013). P013 can be used as the DAC8 channel 0 output. If P013 is used as the DAC8 channel 0 output, then making this connection connects the DAC8 channel 0 output to the ACMPHS0 IVCMP input. Refer to the Synergy Configuration tool Pins tab or the hardware manual I/O Ports chapter, "Peripheral Select Settings for each Product" section for pin aliasing options.
Multiple Connection Table
The table used to make multiple connections includes the number of connections followed by the list of connections. The multiple connection table structure follows the below definition:
ACMPLP Connections Operational Notes
ACMPLP connections should only be made before comparator_api_t::outputEnable() is called. To modify connections, call comparator_api_t::close() first.
On some MCUs, the ACMPLP peripheral has 2 internal nodes that can be configured. They are called ACMPLP0_IVREF0 and ACMPLP1_IVREF1. These nodes must be configured exactly once if they are used. Two enums must be used to make connections involving these nodes. For example, to connect ACMPLP channel 0 to the output of DAC8 channel 0, the following two connections must be made:
The node ACMPLP0_IVREF0 can be connected to the IVREF signal of either channel of the ACMPLP (ACMPLP0_IVREF or ACMPLP1_IVREF). The user should be aware when modifying this node that it may affect the setting of the other channel.
ACMPHS Connections Operational Notes
On MCUs that have an ADC PGA, the associated ADC PGA must be configured or bypassed to use IVCMP2 as the IVCMP input to the comparator. If the associated ADC unit is open, the PGA is bypassed. To enable the ADC PGA or bypass the PGA without opening the ADC driver, follow the instructions in the Usage Notes section of the ADC chapter of the hardware manual. This chapter typically starts with "Available Functions and Register Settings of AN000 to AN002".
ACMPHS connections can be reconfigured at runtime. If an ACMPHS connection is reconfigured after comparator_api_t::outputEnable() is called, the comparator will be disabled before reconfiguring the connection. If the comparator was already enabled, it will be re-enabled after a stabilization wait time of 48 ICLK.
OPAMP Connections Operational Notes
OPAMP connections are only supported on MCUs that have AMPnPS, AMPnMS, and AMPnOS registers. OPAMP connections are only listed in the analog_connect_t enumeration if they exist.
OPAMP connections require a change pump to be enabled if AVCC0 < 2.7 V. Make sure the setting for MCU Analog Power Supply AVCC0 (mV) on the BSP tab of the Synergy Configuration tool is correct if OPAMP connections are used. If AVCC0 < 2.7 V, the MOCO must also be operating to use the charge pump. When using the charge pump for the amplifier:
OPAMP connections can be reconfigured at runtime.
OPAMP connections can be combined by OR'ing connections for the same node. Connection enumerations that start with the same value up to the '_TO_' part of the enum name (ANALOG_CONNECT_<NODE>_TO_) can be OR'ed together. See the paragraph above regarding charge pump operation for limits on the total number of connections that can be made when the charge pump is operating. Any number of connections can be made if AVCC0 >= 2.7 V.
An illustration of combining connections is shown in the code snippet below:
If a connection must be broken before a new connection is made, use the _BREAK enumeration. This is illustrated by the code snippet that follows.
This section describes how to include the analog connection HAL Module in an application using the SSP configurator.
To add the analog connection HAL module to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the analog connect module is g_analog_connect0. This name can be changed in the associated Properties window.)
Analog Connection HAL Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_analog_connect0 Analog Connection Driver on r_analog_connect | Threads | New Stack> Driver> Analog> Analog ConnectionDriver on r_analog_connect<MCU> |
When the Analog Connection Driver on r_analog_connect is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
The Analog Connection HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the Analog Connection HAL Module on r_analog_connect
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Enable or disable the parameter error checking. |
| Name | g_analog_connect0 | Module name. |
| Connection Table Name | g_analog_connect0_table | This connection table name is passed to the connectMultiple API function to make all configured connections. |
| ACMPHS0 IVCMP | No Connection, PORT5 P500, PORT0 P013, PORT1 P100 Default: No Connection | Select the connection for ACMPHS0 IVCMP. |
| ACMHS0 IVREF | No Connection, PORT5 P501, PORT0 P014, PORT1 P101, DAC80 DA, DAC120 DA, Analog0 VREF Default: No Connection | Select the connection for ACMPHS0 IVREF. |
| ACMPL0 IVREF0 | No Connection, PORT1 P109, DAC80 DA Default: No Connection | Select the connection for ACMPL0 IVREF0. |
| ACMPLP1 IVREF1 | No Connection, PORT1 P110, DAC81 DA Default: No Connection | Select the connection for ACMPLP1 IVREF1. |
| ACMPLP0 IVCMP | No Connection, PORT4 P400, OPAMP0 AMPO Default: No Connection | Select the connection for ACMPLP0 IVCMP. |
| ACMPLP0 IVREF | No Connection, ANALOG0 VREF, ACMPLP0 IVREF0 Default: No Connection | Select the connection for ACMPLP0 IVREF. |
| ACMPLP1 IVCMP | No Connection, PORT4 P408, OPAMP1 AMPO Default: No Connection | Select the connection for ACMPLP1 IVCMP. |
| ACMPLP1 IVREF | No Connection, ANALOG0 VREF, ACMPLP0 IVREF0, ACMPLP1 IVREF1 Default: No Connection | Select the connection for ACMPLP1 VREF. |
| OPAMP0 AMPO | No Connection, PORT0 P014, PORT0 P013, PORT0 P003, PORT0 P002 Default: No Connection | Select the connection for OAMP0 AMPO. |
| OPAMP0 AMPM | No Connection, PORT5 P501, PORT5 500, PORT0 P014, PORT0 P113, PORT0 P003, OPAMP0 AMPO Default: No Connection | Select the connection for OPAMP0 AMPM. |
| OPAMP0 AMPP | No Connection, PORT5 P500, PORT0 P014, PORT0 P013, PORT0 P002, DAC120 DA Default: No Connection | Select the connection for OPAMP0 AMPP. |
| OPAMP1 AMPM | No Connection, PORT0 P014, OPAMP1 AMPO Default: No Connection | Select the connection for OPAMP1 AMPM. |
| OPAMP1 AMPP | No Connection, PORT0 P014, PORT0 P013, PORT0 P003, PORT0 P002, DAC80 DA Default: No Connection | Select the connection for OPAMP1 AMPP. |
| OPAMP2 AMPM | No Connection, PORT0 P003, OPAMP2 AMPO Default: No Connection | Select the connection for OPAMP2 AMPM. |
| OPAMP2 AMPP | No Connection, PORT0 P003, PORT0 P002, DAC81 DA Default: No Connection | Select the connection for OPAMP2 AMPP. |
The Analog Connection HAL module needs no clock. Clocks are supplied by the individual analog modules.
The Analog Connection HAL module has no pins to configure. They are configured by the individual analog modules as needed.
Once the analog connect module has been configured and the files generated, it is ready to be used in an application.
The typical steps in using the analog connect HAL module in an application are:
g_analog_connect0.p_api->connectMultiple(&g_analog_connect0_table);These common steps are illustrated in a typical operational flow diagram in the following figure:
