PWM Audio¶

Supported Socs

ESP32

ESP32-S2

ESP32-S3

ESP32-C3

The PWM audio function uses the internal LEDC peripheral in ESP32 to generate PWM audio, which does not need an external audio Codec chip. This is mainly used for cost-sensitive applications with low audio quality requirements.

Features¶

Allows any GIPO with output capability as an audio output pin

Supports 8-bit ~ 10-bit PWM resolution

Supports stereo

Supports 8 ～ 48 KHz sampling rate

Structure¶

../_images/pwm_audio_diagram.png — Structure¶

First, the data is recoded to meet the PWM input requirements, including the shift and offset of the data;
Send data to the ISR (Interrupt Service Routines) function of the Timer Group via Ring Buffer;
The Timer Group reads data from the Ring Buffer according to the pre-defined sampling rate, and write the data into LEDC.

Note

Since the output is a PWM signal, it needs to be low-pass filtered to get the audio waveform.

PWM Frequency¶

The frequency of the output PWM cannot be configured directly, but needs to be calculated by configuring the number of PWM resolution bits, as shown below:

\[f_{pwm}=\frac{f_{APB\_CLK}}{2^{res\_bits}}-\left (\frac{f_{APB\_CLK}}{2^{res\_bits}} MOD 1000\right )\]

The \(f_{APB\_CLK}\) here is 80 MHz, and \(res\_bits\) is the number of PWM resolution bits. When the resolution is LEDC_TIMER_10_BIT, the PWM frequency is 78 KHz. As we all know, a higher PWM frequency and resolution can better reproduce the audio signal. However, this formula shows that increasing PWM frequency means lower resolution and increasing resolution means lower PWM frequency. Thus, please adjust these parameters according to the actual application scenario to achieve a good balance.

Application Example¶

pwm_audio_config_t pac;
pac.duty_resolution    = LEDC_TIMER_10_BIT;
pac.gpio_num_left      = LEFT_CHANNEL_GPIO;
pac.ledc_channel_left  = LEDC_CHANNEL_0;
pac.gpio_num_right     = RIGHT_CHANNEL_GPIO;
pac.ledc_channel_right = LEDC_CHANNEL_1;
pac.ledc_timer_sel     = LEDC_TIMER_0;
pac.tg_num             = TIMER_GROUP_0;
pac.timer_num          = TIMER_0;
pac.ringbuf_len        = 1024 * 8;

pwm_audio_init(&pac));             /**< Initialize pwm audio */
pwm_audio_set_param(48000, 8, 2);  /**< Set sample rate, bits and channel numner */
pwm_audio_start();                 /**< Start to run */

while(1) {

    //< Perpare audio data, such as decode mp3/wav file

    /**< Write data to paly */
    pwm_audio_write(audio_data, length, &written, 1000 / portTICK_PERIOD_MS);
}

API Reference¶

Header File¶

audio/pwm_audio/include/pwm_audio.h

Functions¶

esp_err_t pwm_audio_init(const pwm_audio_config_t *cfg)¶

Initializes and configure the pwm audio.

Return

ESP_OK Success
ESP_FAIL timer_group or ledc initialize failed
ESP_ERR_INVALID_ARG if argument wrong
ESP_ERR_INVALID_STATE The pwm audio already configure
ESP_ERR_NO_MEM Memory allocate failed

Parameters

cfg: configurations - see pwm_audio_config_t struct

esp_err_t pwm_audio_deinit(void)¶

Deinitialize LEDC timer_group and output gpio.

Return

ESP_OK Success
ESP_FAIL pwm_audio not initialized

esp_err_t pwm_audio_start(void)¶

Start to run pwm audio.

Return

ESP_OK Success
ESP_ERR_INVALID_STATE pwm_audio not initialized or it already running

esp_err_t pwm_audio_stop(void)¶

Stop pwm audio.

Attention

Only stop timer, and the pwm will keep to output. If you want to stop pwm output, call pwm_audio_deinit function

Return

ESP_OK Success
ESP_ERR_INVALID_STATE pwm_audio not initialized or it already idle

esp_err_t pwm_audio_write(uint8_t *inbuf, size_t len, size_t *bytes_written, TickType_t ticks_to_wait)¶

Write data to play.

Return

ESP_OK Success
ESP_FAIL Write encounter error
ESP_ERR_INVALID_ARG Parameter error

Parameters

inbuf: Pointer source data to write
len: length of data in bytes
[out] bytes_written: Number of bytes written, if timeout, the result will be less than the size passed in.
ticks_to_wait: TX buffer wait timeout in RTOS ticks. If this many ticks pass without space becoming available in the DMA transmit buffer, then the function will return (note that if the data is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.

esp_err_t pwm_audio_set_param(int rate, ledc_timer_bit_t bits, int ch)¶

Set audio parameter, Similar to pwm_audio_set_sample_rate(), but also sets bit width.

Attention

After start pwm audio, it can’t modify parameters by call function pwm_audio_set_param. If you want to change the parameters, must stop pwm audio by call function pwm_audio_stop.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

rate: sample rate (ex: 8000, 44100…)
bits: bit width
ch: channel number

esp_err_t pwm_audio_set_sample_rate(int rate)¶

Set sample rate.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

rate: sample rate (ex: 8000, 44100…)

esp_err_t pwm_audio_set_volume(int8_t volume)¶

Set volume for pwm audio.

Attention

when the volume is too small, it will produce serious distortion

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

volume: Volume to set (-16 ~ 16). Set to 0 for original output; Set to less then 0 for attenuation, and -16 is mute; Set to more than 0 for enlarge, and 16 is double output

esp_err_t pwm_audio_get_volume(int8_t *volume)¶

Get current volume.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

volume: Pointer to volume

esp_err_t pwm_audio_get_param(int *rate, int *bits, int *ch)¶

Get parameter for pwm audio.

Return

Always return ESP_OK

Parameters

rate: sample rate, if you don’t care about this parameter, set it to NULL
bits: bit width, if you don’t care about this parameter, set it to NULL
ch: channel number, if you don’t care about this parameter, set it to NULL

esp_err_t pwm_audio_get_status(pwm_audio_status_t *status)¶

get pwm audio status

Return

ESP_OK Success

Parameters

status: current pwm_audio status

Structures¶

struct pwm_audio_config_t¶

Configuration parameters for pwm_audio_init function.

Public Members

int gpio_num_left¶: the LEDC output gpio_num, Left channel

int gpio_num_right¶: the LEDC output gpio_num, Right channel

ledc_channel_t ledc_channel_left¶: LEDC channel (0 - 7), Corresponding to left channel

ledc_channel_t ledc_channel_right¶: LEDC channel (0 - 7), Corresponding to right channel

ledc_timer_t ledc_timer_sel¶: Select the timer source of channel (0 - 3)

ledc_timer_bit_t duty_resolution¶: ledc pwm bits

uint32_t ringbuf_len¶: ringbuffer size

Enumerations¶

enum pwm_audio_status_t¶

pwm audio status

Values:

PWM_AUDIO_STATUS_UN_INIT = 0¶: pwm audio uninitialized

PWM_AUDIO_STATUS_IDLE = 1¶: pwm audio idle

PWM_AUDIO_STATUS_BUSY = 2¶: pwm audio busy

enum pwm_audio_channel_t¶

pwm audio channel define

Values:

PWM_AUDIO_CH_MONO = 0¶: 1 channel (mono)

PWM_AUDIO_CH_STEREO = 1¶: 2 channel (stereo)

PWM_AUDIO_CH_MAX¶

Provide feedback about this document