3.18 WEX - Waveform Extension

3.18.1 Introduction

The Waveform Extension (WEX) provides extra functions to the timer/counter in Waveform Generation (WG) modes. It is primarily intended for use in different types of motor control and other power control applications.

3.18.2 Supported Device Families

AVR® EB

3.18.3 Required header files:


#include "mcc_generated_files/timer/wex[X].h"
Note: Replace [X] with the selected instance number of the WEX module.

3.18.4 Module Documentation

3.18.4.1 Waveform Extension for the 16-Bit Timer/Counter Type E (WEX)

3.18.4.1.1 Module description

Version:

WEX0 Driver Version 1.0.1

Copyright:

© 2024 Microchip Technology Inc. and its subsidiaries.

Subject to your compliance with these terms, you may use Microchip software and any derivatives exclusively with Microchip products. You're responsible for complying with 3rd party license terms applicable to your use of 3rd party software (including open source software) that may accompany Microchip software.

SOFTWARE IS "AS IS." NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS RELATED TO THE SOFTWARE WILL NOT EXCEED AMOUNT OF FEES, IF ANY, YOU PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.

Typedefs

  • typedef void(* WEX0_cb_t) (void)

    Pointer to a function to be used as a callback handler when an interrupt event occurs.

Definitions

  • #define WEX0_NS_TO_TICKS(VALUE, F_CLOCK, WEX_PRESCALER) (uint8_t)( (float)(VALUE) / ( (1000000000.0 / (F_CLOCK) ) * (WEX_PRESCALER) ) + 0.5)

    Converts from nanoseconds to clock increments. Used for setting the dead-time or blanking time.

Functions

3.18.4.1.2 Definition Documentation

WEX0_NS_TO_TICKS

#define WEX0_NS_TO_TICKS( VALUE, F_CLOCK, WEX_PRESCALER) (uint8_t)( (float)(VALUE) / ( (1000000000.0 / (F_CLOCK) ) * (WEX_PRESCALER) ) + 0.5)

Converts from nanoseconds to clock increments. Used for setting the dead-time or blanking time.

Note:
The macro arguments:

  • VALUE must be a constant number rather than a variable

  • F_CLOCK is the WEX Peripheral Clock Frequency

  • WEX_PRESCALER can be 1, 2, 4, 8, 16, 64, 256, or 1024

3.18.4.1.3 Typedef Documentation

WEX0_cb_t

typedef void(* WEX0_cb_t) (void)

Pointer to a function to be used as a callback handler when an interrupt event occurs.

3.18.4.1.4 Function Documentation

ISR(WEX0_FAULTDET_vect)

ISR(WEX0_FAULTDET_vect)

Interrupt Service Routine (ISR) for the Fault Interrupt.

Parameters:
None.
Returns:

None.

WEX0_BlankingPrescaler()

void WEX0_BlankingPrescaler (WEX_BLANKPRESC_t prescaler)

Sets the Blanking Prescaler for the WEX0 module.

Parameters:
in prescaler
Prescaler:

  • WEX_BLANKPRESC_DIV1_gc - No prescaler

  • WEX_BLANKPRESC_DIV4_gc - Prescaler 4

  • WEX_BLANKPRESC_DIV16_gc - Prescaler 16

  • WEX_BLANKPRESC_DIV64_gc - Prescaler 64

Returns:

None.

WEX0_BlankingTimeGet()

uint8_t WEX0_BlankingTimeGet (void )

Gets the Blanking Time for the WEX0 module.

Parameters:
None.
Returns:

Blanking Time in clock cycles

WEX0_BlankingTimeSet()

void WEX0_BlankingTimeSet (uint8_t cnt)

Sets the Blanking Time for the WEX0 module.

Parameters:
in cnt

Blanking Time in clock cycles

Returns:

None.

WEX0_BlankingTrigger()

void WEX0_BlankingTrigger (WEX_BLANKTRIG_t trig)

Sets the Blanking Trigger source for the WEX0 module.

Parameters:
in trig
Blanking Trigger:

  • WEX_BLANKTRIG_NONE_gc - Software command only

  • WEX_BLANKTRIG_TCE0UPD_gc - Timer/Counter Type E Update Condition

  • WEX_BLANKTRIG_TCE0CMP0_gc - Timer/Counter Type E Compare 0 Condition

  • WEX_BLANKTRIG_TCE0CMP1_gc - Timer/Counter Type E Compare 1 Condition

  • WEX_BLANKTRIG_TCE0CMP2_gc - Timer/Counter Type E Compare 2 Condition

  • WEX_BLANKTRIG_TCE0CMP3_gc - Timer/Counter Type E Compare 3 Condition

Returns:

None.

WEX0_DeadTimeBothSidesBufferSet()

void WEX0_DeadTimeBothSidesBufferSet (uint8_t buff)

Sets the dead-time on both sides of the output channels using a buffer register on the WEX0 module.

Parameters:
in buff

Dead-time in clock cycles

Returns:

None.

WEX0_DeadTimeBothSidesSet()

void WEX0_DeadTimeBothSidesSet (uint8_t cnt)

Sets the dead-time on both sides of the side output channels on the WEX0 module.

Parameters:
in cnt

Dead-time in clock cycles

Returns:

None.

WEX0_DeadTimeHighSideBufferSet()

void WEX0_DeadTimeHighSideBufferSet (uint8_t buff)

Sets the dead-time on the high side of the output channels using a buffer register on the WEX0 module.

Parameters:
in buff

Dead-time in clock cycles

Returns:

None.

WEX0_DeadTimeHighSideSet()

void WEX0_DeadTimeHighSideSet (uint8_t cnt)

Sets the dead-time on the high side of the output channels on the WEX0 module.

Parameters:
in cnt

Dead-time in clock cycles

Returns:

None.

WEX0_DeadTimeInsertionSet()

void WEX0_DeadTimeInsertionSet (uint8_t channels)

Enables the dead-time insertion on each of the Waveform Output channels.

Parameters:
in channels

Bitmask value for the channels

Returns:

None.

WEX0_DeadTimeLowSideBufferSet()

void WEX0_DeadTimeLowSideBufferSet (uint8_t buff)

Sets the dead-time on the low side of the output channels using a buffer register on the WEX0 module.

Parameters:
in buff

Dead-time in clock cycles

Returns:

None.

WEX0_DeadTimeLowSideSet()

void WEX0_DeadTimeLowSideSet (uint8_t cnt)

Sets the dead-time on the low side of the output channels on the WEX0 module.

Parameters:
in cnt

Dead-time in clock cycles

Returns:

None.

WEX0_Deinitialize()

void WEX0_Deinitialize (void )

Deinitializes the WEX0 module.

Parameters:
None.
Returns:

None.

WEX0_FaultAEventBlankingEnable()

void WEX0_FaultAEventBlankingEnable (bool en)

Enables or disables Fault Event Blanking A for the WEX0 module.

Parameters:
in en
Enable or disable:

  • true - Enable fault event blanking

  • false - Disable fault event blanking

Returns:

None.

WEX0_FaultAEventFilter()

void WEX0_FaultAEventFilter (WEX_FILTER_t samples)

Sets the Fault Event A Filter for the WEX0 module.

Parameters:
in samples
Number of samples:

  • WEX_FILTER_ZERO_gc - No filtering

  • WEX_FILTER_SAMPLE1_gc - One sample

  • WEX_FILTER_SAMPLE2_gc - Two samples

  • WEX_FILTER_SAMPLE3_gc - Three samples

  • WEX_FILTER_SAMPLE4_gc - Four samples

  • WEX_FILTER_SAMPLE5_gc - Five samples

  • WEX_FILTER_SAMPLE6_gc - Six samples

  • WEX_FILTER_SAMPLE7_gc - Seven samples

Returns:

None.

WEX0_FaultAEventInputEnable()

void WEX0_FaultAEventInputEnable (bool en)

Enables or disables Fault Event Input A for the WEX0 module.

Parameters:
in en
Enable or disable:

  • true - Enable fault event input

  • false - Disable fault event input

Returns:

None.

WEX0_FaultBEventBlankingEnable()

void WEX0_FaultBEventBlankingEnable (bool en)

Enables or disables Fault Event Blanking B for the WEX0 module.

Parameters:
in en
Enable or disable:

  • true - Enable fault event blanking

  • false - Disable fault event blanking

Returns:

None.

WEX0_FaultBEventFilter()

void WEX0_FaultBEventFilter (WEX_FILTER_t samples)

Sets the Fault Event B Filter for the WEX0 module.

Parameters:
in samples
Number of samples:

  • WEX_FILTER_ZERO_gc - No filtering

  • WEX_FILTER_SAMPLE1_gc - One sample

  • WEX_FILTER_SAMPLE2_gc - Two samples

  • WEX_FILTER_SAMPLE3_gc - Three samples

  • WEX_FILTER_SAMPLE4_gc - Four samples

  • WEX_FILTER_SAMPLE5_gc - Five samples

  • WEX_FILTER_SAMPLE6_gc - Six samples

  • WEX_FILTER_SAMPLE7_gc - Seven samples

Returns:

None.

WEX0_FaultBEventInputEnable()

void WEX0_FaultBEventInputEnable (bool en)

Enables or disables Fault Event Input B for the WEX0 module.

Parameters:
in en
Enable or disable:

  • true - Enable fault event input

  • false - Disable fault event input

Returns:

None.

WEX0_FaultCEventBlankingEnable()

void WEX0_FaultCEventBlankingEnable (bool en)

Enables or disables Fault Event Blanking C for the WEX0 module.

Parameters:
in en
Enable or disable:

  • true - Enable fault event blanking

  • false - Disable fault event blanking

Returns:

None.

WEX0_FaultCEventFilter()

void WEX0_FaultCEventFilter (WEX_FILTER_t samples)

Sets the Fault Event C Filter for the WEX0 module.

Parameters:
in samples
Number of samples:

  • WEX_FILTER_ZERO_gc - No filtering

  • WEX_FILTER_SAMPLE1_gc - One sample

  • WEX_FILTER_SAMPLE2_gc - Two samples

  • WEX_FILTER_SAMPLE3_gc - Three samples

  • WEX_FILTER_SAMPLE4_gc - Four samples

  • WEX_FILTER_SAMPLE5_gc - Five samples

  • WEX_FILTER_SAMPLE6_gc - Six samples

  • WEX_FILTER_SAMPLE7_gc - Seven samples

Returns:

None.

WEX0_FaultCEventInputEnable()

void WEX0_FaultCEventInputEnable (bool en)

Enables or disables Fault Event Input C for the WEX0 module.

Parameters:
in en
Enable or disable:

  • true - Enable fault event input

  • false - Disable fault event input

Returns:

None.

WEX0_FaultDetectionAction()

void WEX0_FaultDetectionAction (WEX_FDACT_t action)

Sets the Fault Detection Action for the WEX0 module.

Parameters:
in action
Action:

  • WEX_FDACT_NONE_gc - Fault protection is disabled

  • WEX_FDACT_LOW_gc - Fault protection is enabled and the output is driven low

  • WEX_FDACT_CUSTOM_gc - Fault protection is enabled and drive all pins to setting defined by FAULTDRV and FAULTOUT registers

Returns:

None.

WEX0_FaultDetectionDebugBreak()

void WEX0_FaultDetectionDebugBreak (WEX_FDDBD_t mode)

Sets the Fault Detection on Debug Break Detection for the WEX0 module.

Parameters:
in mode
Mode:

  • WEX_FDDBD_FAULT_gc - If fault protection is enabled, the fault is triggered on debug request

  • WEX_FDDBD_IGNORE_gc - Debug request isn't going to trigger a fault

Returns:

None.

WEX0_FaultDetectionRestartMode()

void WEX0_FaultDetectionRestartMode (WEX_FDMODE_t mode)

Sets the Fault Detection Restart Mode for the WEX0 module.

Parameters:
in mode
Mode:

  • WEX_FDMODE_LATCHED_gc - Latched mode -> Output will remain in a Fault state until the fault condition is no longer active and the fault is cleared by software

  • WEX_FDMODE_CBC_gc - Cycle-by-Cycle mode -> Output will remain in the fault state until the fault condition is no longer active

Returns:

None.

WEX0_FaultDisable()

void WEX0_FaultDisable (void )

Disables the Fault Interrupt on the WEX0 module.

Parameters:
None.
Returns:

None.

WEX0_FaultDriveSet()

void WEX0_FaultDriveSet (uint8_t channels)

Sets if an output channel is tri-stated or overwritten by the custom fault value defined by the user in case a fault is detected.

Parameters:
in channels

Bitmask value for the channels

Returns:

None.

WEX0_FaultEnable()

void WEX0_FaultEnable (void )

Enables the Fault Interrupt on the WEX0 module.

Parameters:
None.
Returns:

None.

WEX0_FaultFlagsClear()

void WEX0_FaultFlagsClear (uint8_t flags)

Clears interrupt flags on the WEX0 module.

Parameters:
in flags

Bitmask value for the channels

Returns:

None.

WEX0_FaultFlagsGet()

uint8_t WEX0_FaultFlagsGet (void )

Returns the interrupt flags on the WEX0 module.

Parameters:
None.
Returns:
Interrupt flag status:

  • Bit 0 is set by the the Fault Interrupt

  • Bit 2 is set by the the Fault Detection Flag Event Input A

  • Bit 3 is set by the the Fault Detection Flag Event Input B

  • Bit 4 is set by the the Fault Detection Flag Event Input C

WEX0_FAULTIsrCallbackRegister()

void WEX0_FAULTIsrCallbackRegister (WEX0_cb_t callback)

Sets the Fault Interrupt callback for the WEX0 module.

Parameters:
in callback

Pointer to custom callback

Returns:

None.

WEX0_FaultOutputSet()

void WEX0_FaultOutputSet (uint8_t channels)

Sets the output values of the channels in case of a fault detection.

Parameters:
in channels

Bitmask value for the channels

Returns:

None.

WEX0_Initialize()

void WEX0_Initialize (void )

Initializes the WEX0 module.

Parameters:
None.
Returns:

None.

WEX0_InputMatrixSet()

void WEX0_InputMatrixSet (WEX_INMX_t config)

Selects the Input Matrix mode of the WEX0 module.

Parameters:
in config
Input Matrix:

  • WEX_INMX_DIRECT_gc - Direct Input

  • WEX_INMX_CWCMA_gc - Common Waveform Channel Mode A. Waveform output on a single PWM channel

  • WEX_INMX_CWCMB_gc - Common Waveform Channel Mode B. Waveform output on two PWM channels

Returns:

None.

WEX0_IsFaultEnabled()

bool WEX0_IsFaultEnabled (void )

Returns the status of the Fault Interrupt on the WEX0 module.

Parameters:
None.
Returns:

bool Whether the fault is enabled or not

Return values:
true

Fault interrupt is enabled

false

Fault interrupt is disabled

WEX0_IsPatternGenerationSet()

bool WEX0_IsPatternGenerationSet (void )

Returns the Pattern Generation mode status of the WEX0 module.

Parameters:
None.
Returns:

Whaether the Pattern Generation mode is enabled or not

Return values:
true

Pattern Generation mode is enabled

false

Pattern Generation mode is disabled

WEX0_OutputOverrideEnable()

void WEX0_OutputOverrideEnable (uint8_t channels)

Enables or disables the output override on the WEX0 module.

Parameters:
in channels

Bitmask value for the channels

Returns:

None.

WEX0_PatternGenerationMode()

void WEX0_PatternGenerationMode (bool mode)

Enables or disables the Pattern Generation mode of the WEX0 module.

Parameters:
in mode
Enable or disable:

  • true - Enable Pattern Generation mode

  • false - Disable Pattern Generation mode

Returns:

None.

WEX0_PatternGenerationOutputBufferSet()

void WEX0_PatternGenerationOutputBufferSet (uint8_t buff)

Sets the output values of the channels in the Pattern Generation Mode using a buffer register on the WEX0 module.

Parameters:
in buff

Bitmask value for the channels

Returns:

None.

WEX0_PatternGenerationOutputSet()

void WEX0_PatternGenerationOutputSet (uint8_t channels)

Sets the output values of the channels in the Pattern Generation Mode on the WEX0 module.

Parameters:
in channels

Bitmask value for the channels

Returns:

None.

WEX0_PatternGenerationOverrideBufferSet()

void WEX0_PatternGenerationOverrideBufferSet (uint8_t buff)

Sets which channels will have the output overridden by the Pattern Generation Mode using a buffer register on the WEX0 module.

Parameters:
in buff

Bitmask value for the channels

Returns:

None.

WEX0_PatternGenerationOverrideSet()

void WEX0_PatternGenerationOverrideSet (uint8_t channels)

Sets which channels will have the output overridden by the Pattern Generation Mode on the WEX0 module.

Parameters:
in channels

Bitmask value for the channels

Returns:

None.

WEX0_SoftwareCommand()

void WEX0_SoftwareCommand (WEX_CMD_t command)

Sends software commands to the WEX0 module.

Parameters:
in command
Command:

  • WEX_CMD_NONE_gc - No Command

  • WEX_CMD_UPDATE_gc - Update buffered registers

  • WEX_CMD_FAULTSET_gc - Set fault detection

  • WEX_CMD_FAULTCLR_gc - Clear fault detection

  • WEX_CMD_BLANKSET_gc - Set software blanking

  • WEX_CMD_BLANKCLR_gc - Clear software blanking

Returns:

None.

WEX0_StatusRegisterGet()

uint8_t WEX0_StatusRegisterGet (void )

Gets the status of the WEX0's blanking or fault detection.

Parameters:
None.
Returns:

The current status

WEX0_SwapChannelBufferSet()

void WEX0_SwapChannelBufferSet (uint8_t buff)

Sets which pair channels will have the output swapped (output [2n] with output [2n+1]) using a buffer register on the WEX0 module.

Parameters:
in buff

Bitmask value for the channels

Returns:

None.

WEX0_SwapChannelSet()

void WEX0_SwapChannelSet (uint8_t channels)

Sets which pair channels will have the output swapped (output [2n] with output [2n+1]) on the WEX0 module.

Parameters:
in channels

Bitmask value for the channels

Returns:

None.

WEX0_UpdateSourceSet()

void WEX0_UpdateSourceSet (WEX_UPDSRC_t config)

Selects the update source for the WEX0 module.

Parameters:
in config
Update Source:

  • WEX_UPDSRC_TCPWM0_gc - Timer/Counter Type E

  • WEX_UPDSRC_SW_gc - Software Commands

Returns:

None.

3.18.4.1.5 Variable Documentation

WEX0_FAULT_isr_cb

WEX0_cb_t WEX0_FAULT_isr_cb = NULL[static]

Function pointer that stores the callback address.

3.18.5 File Documentation

3.18.5.1 source/wex0.c File Reference

Waveform Extension Driver API Header File. 

#include "wex0.h"
#include <stddef.h>
#include <avr/interrupt.h>
#include <util/atomic.h>

3.18.5.1.1 Functions

3.18.5.1.3 Detailed Description

Waveform Extension Driver API Header File.

Version:

WEX0 Driver Version 1.0.1

Copyright:

© 2024 Microchip Technology Inc. and its subsidiaries.

Subject to your compliance with these terms, you may use Microchip software and any derivatives exclusively with Microchip products. You're responsible for complying with 3rd party license terms applicable to your use of 3rd party software (including open source software) that may accompany Microchip software.

SOFTWARE IS "AS IS." NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT WILL MICROCHIP BE LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS RELATED TO THE SOFTWARE WILL NOT EXCEED AMOUNT OF FEES, IF ANY, YOU PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.

3.18.5.2 source/wex0.h File Reference

Waveform Extension Driver API Header File. 

#include <stdbool.h>
#include <stdint.h>
#include <avr/io.h>

3.18.5.2.1 Functions

3.18.5.2.2 Macros

  • #define WEX0_NS_TO_TICKS(VALUE, F_CLOCK, WEX_PRESCALER) (uint8_t)( (float)(VALUE) / ( (1000000000.0 / (F_CLOCK) ) * (WEX_PRESCALER) ) + 0.5)

    Converts from nanoseconds to clock increments. Used for setting the dead-time or blanking time.

3.18.5.2.3 Typedefs

  • typedef void(* WEX0_cb_t) (void)

    Pointer to a function to be used as a callback handler when an interrupt event occurs.

3.18.5.2.4 Detailed Description

Waveform Extension Driver API Header File.