TAS58xx
The tas58xx platform allows your ESPHome devices to use the Texas Instruments TAS58xx family of stereo Class-D audio
amplifiers with digital (I²S) input. This allows the playback of audio via the microcontroller from a range of sources
via Speaker or Media Player.
Supported models:
tas5805m: TAS5805Mtas5825m: TAS5825M
The I²C bus is required in your configuration as this is used to configure the amplifier and read its fault status. Audio data is delivered via I²S, for example with the I²S Audio Speaker.
# Example configuration entryaudio_dac: - platform: tas58xx model: tas5805m id: ampConfiguration Variables
Section titled “Configuration Variables”- model (Required, enum): The amplifier model. One of the supported models listed above.
- enable_pin (Optional, Pin): The pin connected to the
PDN(power down) pin of the amplifier. During setup the pin is briefly driven low and then high to power up the amplifier cleanly. Omit ifPDNis hardwired high. Without this pin, and withPDNnot pulled high, the amplifier does not respond on I²C and setup fails. - ignore_enable_pin_warning (Optional, boolean): Set to
trueto hide the config validation warning shown whenenable_pinis not set. Use this whenPDNis hardwired high. Cannot be used together withenable_pin. Defaults tofalse. - analog_gain (Optional, dB): The analog gain of the output stage, in
0.5dBsteps. Use it to match the output swing to the supply voltage. Range:-15.5dBto0dB. Defaults to-15.5dB, the lowest gain. - dac_mode (Optional, enum): How the output stage drives the speakers. Defaults to
btl.btl: Bridge tied load, two speakers (stereo).pbtl: Parallel bridge tied load, one speaker driven by both output channels. Requiresmixer_modeto bemono,leftorright.
- fault_output (Optional, enum): The amplifier pin that reports faults. The pin goes low while a fault is present
(the
FAULTZsignal of the datasheet). Withnonethe pin is not configured and keeps its power on state.tas5805m:adrornone. Defaults toadr.tas5825m:gpio0,gpio1,gpio2ornone. Defaults togpio1.
- mixer_mode (Optional, enum): How the left and right input channels are routed to the outputs.
Defaults to
stereo.stereo: Left input to the left output, right input to the right output.stereo_inverse: Left and right swapped.mono: Left and right mixed (each at -6 dB) to both outputs.left: Left input to both outputs.right: Right input to both outputs.
- modulation (Optional, enum): The modulation scheme of the output stage. Defaults to
bd_mode.bd_mode: BD modulation, lower distortion, lower efficiency.1spw_mode: 1SPW modulation, higher efficiency and less heat at the cost of slightly higher distortion. Use it at higher supply voltages, where the amplifier cannot sustain full power without cooling (a heatsink, a fan or both).
- volume_min_db (Optional, dB): The digital volume that maps to the minimum volume (0%). Must be less than
volume_max_db. Range:-103dBto24dB. Defaults to-103dB. - volume_max_db (Optional, dB): The digital volume that maps to the maximum volume (100%). Must be greater than
volume_min_db. Range:-103dBto24dB. Defaults to24dB. - address (Optional, int): The I²C address of the amplifier. The address is selected with a resistor on the
ADRpin (see the datasheet). Defaults to0x2Dfortas5805mand0x4Cfortas5825m. - update_interval (Optional, Time): How often the fault and power state
registers are read. Defaults to
1s. - i2c_id (Optional, ID): The ID of the I²C bus the amplifier is connected to.
- All other options from Audio DAC.
The volume is mapped linearly in dB between volume_min_db and volume_max_db, in 0.5dB steps. A volume of 0%
is not silent unless volume_min_db is -103dB; use the Audio DAC
mute actions to silence the output.
TIP
Digital volume above 0dB can clip full-scale audio. Set volume_max_db to 0dB or lower when the source plays
at full scale, and use analog_gain to set the maximum output level.
Several amplifiers, of the same or different models, can be used in one configuration. Log messages for faults and power state changes start with the I²C address of the amplifier.
Operation
Section titled “Operation”The amplifier enters play mode after setup. It stays in Hi-Z (outputs off) until an I²S clock is present. The mixer
setting (mixer_mode, or the mode chosen with the mixer mode select) is written when audio first starts,
and the amplifier keeps it while the clock stops and starts again.
The fault registers are read every update_interval, and a log message is written each time a fault appears or
clears. Faults that only report a past event are cleared automatically, so the fault state follows the current
condition. The fault_output pin is configured after startup. On the TAS5805M, the default fault output pin is the
ADR pin. It also selects the I²C address, but the address is latched at power up, so the pin is free to use for
reporting faults afterwards.
IMPORTANT
DC and over current faults are not cleared automatically. After one of these faults the output stays off until
tas58xx.activate is called or the amplifier is power cycled. Fix the cause of the fault first.
Automations
Section titled “Automations”tas58xx.activate Action
Section titled “tas58xx.activate Action”Clears faults, wakes the amplifier from deep sleep and switches it to play mode. The device waits in Hi-Z until an I²S clock is present. This action also restarts the output after a DC or over current fault.
on_...: - tas58xx.activate: ampConfiguration variables:
- id (Required, ID): The ID of the
tas58xxplatform.
tas58xx.deactivate Action
Section titled “tas58xx.deactivate Action”Puts the amplifier into deep sleep, its lowest power state that keeps the I²C interface and DSP running. Settings
are kept, and tas58xx.activate resumes playback.
on_...: - tas58xx.deactivate: ampConfiguration variables:
- id (Required, ID): The ID of the
tas58xxplatform.
All Audio DAC Automations are supported by this platform as well.
Binary Sensor
Section titled “Binary Sensor”The tas58xx binary sensor platform exposes the fault status of the amplifier. Each sensor is ON while the fault
is present and is updated every update_interval of the tas58xx platform.
binary_sensor: - platform: tas58xx have_fault: name: "Amplifier Fault"Binary Sensor Configuration Variables
Section titled “Binary Sensor Configuration Variables”- tas58xx_id (Optional, ID): The ID of the
tas58xxplatform. Required when more than one amplifier is configured. - have_fault (Optional):
ONwhen any of the faults below is present, exceptclock_faultand the warnings (over_temp_warning,over_temp_146c_warning,left_channel_cbc_over_current_warningandright_channel_cbc_over_current_warning). - left_channel_dc_fault (Optional): DC offset detected on the left output.
- right_channel_dc_fault (Optional): DC offset detected on the right output.
- left_channel_over_current (Optional): Over current on the left output.
- right_channel_over_current (Optional): Over current on the right output.
- left_channel_cbc_over_current (Optional): Cycle-by-cycle over current on the left output. Only available on TAS5825M.
- right_channel_cbc_over_current (Optional): Cycle-by-cycle over current on the right output. Only available on TAS5825M.
- pvdd_over_voltage (Optional): PVDD supply voltage too high.
- pvdd_under_voltage (Optional): PVDD supply voltage too low.
- over_temp_shutdown (Optional): The device shut down because it is too hot.
- left_channel_cbc_over_current_warning (Optional): Cycle-by-cycle current on the left output is close to the fault threshold. Logged as a warning. Only available on TAS5825M.
- right_channel_cbc_over_current_warning (Optional): Cycle-by-cycle current on the right output is close to the fault threshold. Logged as a warning. Only available on TAS5825M.
- over_temp_146c_warning (Optional): The device temperature has reached 146°C. Logged as a warning. Only available on TAS5825M.
- over_temp_warning (Optional): The device temperature is close to the shutdown threshold. Logged as a warning.
- otp_crc_check (Optional): The CRC check of the internal OTP memory failed.
- bq_write_failed (Optional): Writing the biquad filter coefficients failed.
- load_eeprom_error (Optional): Loading from EEPROM at boot failed. Only available on TAS5825M.
- clock_fault (Optional): The I²S clock is missing or invalid. This is normal whenever no audio is playing,
so it is not logged and not included in
have_fault.
A sensor marked as only available on TAS5825M fails validation when the amplifier is model: tas5805m.
All sensors accept the options from Binary Sensor. They default to the problem device
class and the diagnostic entity category.
Switch
Section titled “Switch”The activate switch activates the amplifier or puts it into deep sleep. Turning the switch ON does the
tas58xx.activate action, and turning it OFF does tas58xx.deactivate.
switch: - platform: tas58xx activate: name: "Amplifier"Switch Configuration Variables
Section titled “Switch Configuration Variables”- tas58xx_id (Optional, ID): The ID of the
tas58xxplatform. Required when more than one amplifier is configured. - activate (Optional): ON activates the amplifier, OFF puts it into deep sleep. All options from
Switch, except
restore_mode,restore_stateandinitial_state. Defaults to theconfigentity category.
The switch shows whether the amplifier is active, and changes only after the amplifier accepted the command, whether
it came from the switch or from the tas58xx.activate and tas58xx.deactivate actions. At every boot the amplifier
starts in play mode, which is activated, so the switch is always ON after a boot. The restore options have no effect,
so restore_mode, restore_state and initial_state are not supported and fail validation.
Select
Section titled “Select”The tas58xx select platform changes the mixer mode while the device is running.
select: - platform: tas58xx mixer_mode: name: "Amplifier Mixer Mode"Select Configuration Variables
Section titled “Select Configuration Variables”- tas58xx_id (Optional, ID): The ID of the
tas58xxplatform. Required when more than one amplifier is configured. - mixer_mode (Optional): A select for the input mixer, with the options
Stereo,Stereo inverse,Mono,LeftandRight, as described formixer_modeabove. Withdac_mode: pbtlonlyMono,LeftandRightare available. All options from Select. Defaults to theconfigentity category.
At every restart the select starts with the mixer_mode of the audio_dac, so a selected mode lasts until the next
restart. A new mode is written immediately if audio is playing, otherwise when audio next starts.
Configuration Examples
Section titled “Configuration Examples”Stereo Speakers
Section titled “Stereo Speakers”i2c: sda: GPIOXX scl: GPIOXX
i2s_audio: - id: i2s_output i2s_lrclk_pin: GPIOXX i2s_bclk_pin: GPIOXX
audio_dac: - platform: tas58xx model: tas5805m id: amp enable_pin: GPIOXX volume_max_db: 0dB
speaker: - platform: i2s_audio id: amp_speaker i2s_audio_id: i2s_output i2s_dout_pin: GPIOXX dac_type: external channel: stereo audio_dac: ampSingle Speaker (PBTL)
Section titled “Single Speaker (PBTL)”audio_dac: - platform: tas58xx model: tas5805m id: amp dac_mode: pbtl mixer_mode: monoDeep Sleep When Idle
Section titled “Deep Sleep When Idle”media_player: - platform: speaker # ... on_play: - tas58xx.activate: amp on_idle: - tas58xx.deactivate: amp