ES8388
The es8388 component allows your ESPHome devices to use the es8388 low power audio codec (datasheet)
This allows the playback of audio through two channel high performance audio DAC output via the microcontroller from a range of sources via Speaker or
Media Player.
It also allows your ESPHome devices to use the es8388 high performance two channel audio ADC.
This allows attached microphones to be used as a microphone input via I2S Audio.
The I²C bus is required in your configuration as this is used to communicate with the es8388.
Audio DAC
Section titled “Audio DAC”# Example configuration entryaudio_dac: - platform: es8388Configuration variables
Section titled “Configuration variables”- address (Optional, int): The I²C address of the driver. Defaults to
0x10. - i2c_id (Optional): The ID of the I²C bus the ES8388 is connected to.
- volume_min_db (Optional, float): The DAC attenuation at volume 0, from
-96dBto0dB. Defaults to-96dB. - volume_max_db (Optional, float): The DAC attenuation at volume 1, from
-96dBto0dB. Must be higher thanvolume_min_db. Defaults to0dB. The volume maps linearly in dB between the two. With a small speaker that is barely heard at low volumes, raisevolume_min_db(for example to-50dB) so the whole volume range can be used. - mic_gain (Optional, enum): The ADC PGA gain applied to both channels at startup, in dB.
One of
0DB,3DB,6DB,9DB,12DB,15DB,18DB,21DB,24DB. Defaults to0DB. Set this if you record from a microphone and the input level is too low for speech recognition. On some boards the default is too quiet to transcribe; see Microphone recording level. - All other options from Audio DAC.
NOTE
The default is 0DB for backwards compatibility: a higher default would raise the input level
for every existing configuration. The ES8311 component, by
contrast, defaults to 42DB.
Microphone Recording Level
Section titled “Microphone Recording Level”The ES8388 ADC PGA gain is set by register 0x09, where bits 7:4 hold the left channel gain
(MicAmpL) and bits 3:0 the right channel gain (MicAmpR). See the
datasheet, register 9. Each nibble is the gain
in 3 dB steps, where 0111 is +21 dB. So 0x77 is +21 dB on both channels and 0x00 is 0 dB on
both channels.
mic_gain selects this value. For example, mic_gain: 21DB writes 0x77:
audio_dac: - platform: es8388 id: es8388_dac mic_gain: 21DBThe configured value is logged at startup:
[C][es8388:xxx]: ES8388 Audio Codec:[C][es8388:xxx]: Mic gain: 21 dBWhy This Option Exists
Section titled “Why This Option Exists”The ES8388’s ADC PGA gain defaults to 0 dB. On some boards, such as the ESP32-A1S Audio Kit
V2.2, that is too quiet for speech-to-text to work, and a higher gain is needed. mic_gain
exposes that gain directly, and the 0DB default is unchanged, so this option does nothing unless
you set it.
If you are unsure what value your board needs, start from the default (0DB) and raise mic_gain
until recording works.
NOTE
mic_gain raises the input level, not the signal-to-noise ratio: it is an analog gain in front
of the ADC, so any noise already present at the microphone is amplified with the signal. It
helps where the problem is a recording level too low to transcribe.
NOTE
Adjusting mic_gain only changes the analog PGA in front of the ADC. Other microphone-level
settings such as automatic level control (ALC) and the noise gate
are separate and still apply.
Noise Gate and ALC
Section titled “Noise Gate and ALC”The ES8388 also has an automatic level control (ALC) block and a noise gate. Both are separate
from mic_gain and are configured by the component with fixed values based on the ES8388 User
Guide’s voice-recording recommendations:
- Register
0x12(ADCCONTROL10) =0xE2enables the ALC on both channels, with a maximum gain of +17.5 dB and a minimum gain of 0 dB. - Register
0x16(ADCCONTROL14) =0xC3enables the noise gate at −40.5 dBFS with the “mute ADC output” option.
These values are not configurable through this component. The ALC is intended to keep the
recording level roughly constant, so it may interact with mic_gain.
Select
Section titled “Select”The es8388 select controls the DAC output and ADC input routing of your ES8388.
select: - platform: es8388 es8388_id: es8388_parent dac_output: name: "DAC Output" adc_input_mic: name: "ADC Input MIC"Configuration variables
Section titled “Configuration variables”-
es8388_id (Optional, ID): Manually specify the ID of the ES8388 component.
-
dac_output (Optional): Control the DAC output routing. Options are
LINE1,LINE2andBOTH.- initial_option (Optional, string): The routing to apply at startup. Without it the select reports
whatever the codec is set to, which is
LINE1after a power-on reset. - All other options from Select.
- initial_option (Optional, string): The routing to apply at startup. Without it the select reports
whatever the codec is set to, which is
-
adc_input_mic (Optional): Control the ADC input routing. Options are
LINE1,LINE2andDIFFERENCE.- initial_option (Optional, string): The routing to apply at startup. Without it the select reports
whatever the codec is set to, which is
LINE1after a power-on reset. - All other options from Select.
- initial_option (Optional, string): The routing to apply at startup. Without it the select reports
whatever the codec is set to, which is
Automations
Section titled “Automations”All Audio DAC Automations are supported by this platform.
Configuration Examples
Section titled “Configuration Examples”ESP32 Audio Kit:
i2c: sda: GPIO33 scl: GPIO32 frequency: 100kHz id: bus_a
audio_dac: - platform: es8388 id: es8388_dac
select: - platform: es8388 es8388_id: es8388_dac dac_output: name: "DAC Output" adc_input_mic: name: "ADC Input MIC"
i2s_audio: id: i2s_output i2s_lrclk_pin: GPIO25 i2s_bclk_pin: GPIO27 i2s_mclk_pin: GPIO0
speaker: - platform: i2s_audio i2s_audio_id: i2s_output sample_rate: 48000 id: speaker_id i2s_dout_pin: GPIO26 bits_per_sample: 32bit dac_type: external channel: stereo buffer_duration: 100ms audio_dac: es8388_dac
microphone: - platform: i2s_audio i2s_din_pin: GPIO35 id: mic1 adc_type: external pdm: false sample_rate: 16000 bits_per_sample: 16bit
switch: - platform: gpio pin: GPIO21 id: mute_switch name: "AMP Switch" restore_mode: ALWAYS_ONStartup routing:
select: - platform: es8388 es8388_id: es8388_dac dac_output: name: "DAC Output" initial_option: BOTH adc_input_mic: name: "ADC Input MIC" initial_option: LINE2