# MCPWM ETM: Hardware Linking Between Peripherals

The Event Task Matrix (ETM) can route an MCPWM timer or comparator event directly to an ETM task, avoiding ISR latency. Use it when another peripheral must respond at an exact PWM phase.

Create an ETM event from the timer or comparator, create a compatible task from the destination peripheral, then connect both with an ETM channel. The destination driver's documentation defines its task and the complete channel setup. For the general ETM workflow — allocating a channel and connecting an event to a task — see the ETM documentation.

            flowchart LR
        T["MCPWM Timer<br/>TEZ/TEP event"]:::source --> E["ETM Channel"]:::route
        C["MCPWM Comparator<br/>compare event"]:::source --> E
        E --> D["Destination<br/>peripheral task"]:::dest
        classDef source fill:#dbeafe,stroke:#2563eb,color:#172554
        classDef route fill:#ede9fe,stroke:#7c3aed,color:#2e1065
        classDef dest fill:#dcfce7,stroke:#16a34a,color:#14532d

A timer emits a TEZ (timer reaches zero) or TEP (timer reaches peak) event. To get one:

    esp_etm_event_handle_t timer_event = NULL;
    ESP_ERROR_CHECK(mcpwm_timer_new_etm_event(timer,
        &(mcpwm_timer_etm_event_config_t) {
            .event_type = MCPWM_TIMER_ETM_EVENT_TEZ,
        }, &timer_event));
    // Create a destination ETM task, allocate a channel, then connect:
    // esp_etm_channel_connect(channel, timer_event, destination_task);

A comparator provides an EQUAL event, firing each time the timer count equals the comparator value. This pins the event to an arbitrary phase of the PWM period rather than just the crest or trough. To get one:

    esp_etm_event_handle_t cmp_event = NULL;
    ESP_ERROR_CHECK(mcpwm_comparator_new_etm_event(cmp,
        &(mcpwm_cmpr_etm_event_config_t) {
            .event_type = MCPWM_CMPR_ETM_EVENT_EQUAL,
        }, &cmp_event));
    // esp_etm_channel_connect(channel, cmp_event, destination_task);

Release the event with `esp_etm_del_event()` when no longer needed.

A very common use of a comparator event is to trigger an ADC sampling: place the comparator at the phase you want to sample, then have the comparator event start an ADC so the converter samples a clean, settled waveform exactly in phase with the PWM cycle. Because the whole link is done in hardware, the ADC sample point tracks the PWM with no CPU and no ISR latency.

Which comparator feeds the event matters. The operator comparator (`mcpwm_new_comparator()`) also drives the generators, so its compare value defines an actual PWM output edge, and its ETM event is limited to that edge — you cannot ask it for a phase that is not one of the edges it produces. The event comparator (`mcpwm_new_event_comparator()`) is a dedicated ETM timing marker: it drives no generator, consumes none of the operator-comparator slots, and therefore can fire at any phase inside the PWM period, with no effect on the PWM waveform. That freedom is exactly what an ADC trigger needs, so the event comparator is the recommended source — pick a sample point where the voltage has settled, not just where an edge happens to be.

## API Reference

### MCPWM ETM Driver Functions

#### Header File

- components/esp_driver_mcpwm/include/driver/mcpwm_etm.h

- This header file can be included with:

  >     #include "driver/mcpwm_etm.h"

- This header file is a part of the API provided by the `esp_driver_mcpwm` component. To declare that your component depends on `esp_driver_mcpwm`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_mcpwm

  > or

  >     PRIV_REQUIRES esp_driver_mcpwm

#### Functions

esp_err_t mcpwm_comparator_new_etm_event(mcpwm_cmpr_handle_t cmpr, const mcpwm_cmpr_etm_event_config_t *config, esp_etm_event_handle_t *out_event)

  Get the ETM event for MCPWM comparator.

  Note

  The created ETM event object can be deleted later by calling `esp_etm_del_event`

  Parameters:

    - cmpr -- [in] MCPWM comparator, allocated by `mcpwm_new_comparator()` or `mcpwm_new_event_comparator()`

    - config -- [in] MCPWM ETM comparator event configuration

    - out_event -- [out] Returned ETM event handle

  Returns:

    - ESP_OK: Get ETM event successfully

    - ESP_ERR_INVALID_ARG: Get ETM event failed because of invalid argument

    - ESP_FAIL: Get ETM event failed because of other error

esp_err_t mcpwm_timer_new_etm_event(mcpwm_timer_handle_t timer, const mcpwm_timer_etm_event_config_t *config, esp_etm_event_handle_t *out_event)

  Get the ETM event for MCPWM timer.

  Note

  The created ETM event object can be deleted later by calling `esp_etm_del_event`

  Parameters:

    - timer -- [in] MCPWM timer, allocated by `mcpwm_new_timer()`

    - config -- [in] MCPWM ETM timer event configuration

    - out_event -- [out] Returned ETM event handle

  Returns:

    - ESP_OK: Get ETM event successfully

    - ESP_ERR_INVALID_ARG: Get ETM event failed because of invalid argument

    - ESP_FAIL: Get ETM event failed because of other error

#### Structures

struct mcpwm_cmpr_etm_event_config_t

  MCPWM event comparator ETM event configuration.

  Public Members

  mcpwm_comparator_etm_event_type_t event_type

    MCPWM comparator ETM event type

struct mcpwm_timer_etm_event_config_t

  MCPWM timer ETM event configuration.

  Public Members

  mcpwm_timer_etm_event_type_t event_type

    MCPWM timer ETM event type

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.