API Reference

adafruit_tlv320

CircuitPython driver for the TLV320DAC3100 I2S DAC

  • Author(s): Liz Clark, Sam Blenny

Implementation Notes

Hardware:

  • Adafruit TLV320DAC3100 - I2S DAC

  • Adafruit Fruit Jam

  • The TLV320DAC chip has moderately complex onboard audio filtering, routing, and amplification capability. Each of the signal chains for speaker, headphone left, and headphone right start with the DAC, then they go through a mixer stage, an analog volume (attenuation) stage, and finally an analog amplifier stage. Parameters for each stage of each signal chain can be separately set with different properties. But, you can ignore most of that if you use speaker_output = True or headphone_output = True to load defaults.

  • To understand how the different audio stages (DAC, volume, amplifier gain) relate to each other, it can help to look at the Functional Block Diagram in the TLV320DAC3100 datasheet: https://learn.adafruit.com/adafruit-tlv320dac3100-i2s-dac/downloads

  • CAUTION: The TLV320 amplifiers have enough power to easily burn out small 1W speakers or drive headphones to levels that could damage your hearing. To be safe, start with low volume and gain levels, then increase them carefully to find a comfortable listening level. This is why the default levels set by speaker_output and headphone_output are relatively low.

Software and Dependencies:

Usage Examples

Fruit Jam Mini-Speaker

This will start you off with a relatively low volume for the Fruit Jam’s bundled 8-Ohm 1 Watt speaker. Your code can adjust the volume by increasing or decreasing dac_volume. To use a higher wattage speaker that needs more power, you might want to increase speaker_volume.

dac = TLV320DAC3100(board.I2C())
dac.speaker_output = True            # set defaults for speaker
dac.dac_volume = dac.dac_volume + 1  # increase volume by 1 dB
dac.dac_volume = dac.dac_volume - 1  # decrease volume by 1 dB

Low Impedance Earbuds

This will start you off with a relatively low volume for low impedance earbuds (e.g. JVC Gumy) plugged into the Fruit Jam’s headphone jack. Your code can adjust the volume by increasing or decreasing dac_volume. To use high impedance headphones that need more power, you might want to increase headphone_volume.

dac = TLV320DAC3100(board.I2C())
dac.speaker_output = False           # make sure speaker amp is off
dac.headphone_output = True          # set defaults for headphones
dac.dac_volume = dac.dac_volume + 1  # increase volume by 1 dB
dac.dac_volume = dac.dac_volume - 1  # decrease volume by 1 dB

Line Level Output to Mixer

For this one, the default headphone output volume will be way too low for use with a device that expects consumer line level input (-10 dBV). To fix that, you can increase dac_volume or headphone_volume. If you want to experiment with different ways of setting the levels, check out the volume test example: Volume test

dac = TLV320DAC3100(board.I2C())
dac.speaker_output = False    # make sure speaker amp is off
dac.headphone_output = True   # set defaults for headphones (note: too low!)

# Make it louder by increasing headphone_volume. We could also use
# dac_volume, but doing it this way gives a better balance between
# the speaker signal chain and the headphone jack signal chain. (think
# of headphone_volume as a mixer channel's pad switch or gain trim knob
# and dac_volume as the main volume control fader)
#
# CAUTION: This will be *way* too loud for earbuds, please be careful!
dac.headphone_volume = -15.5  # default is -30.1 dB

15 MHz PWM Clock to I2S_MCLK for Better Audio Quality

You can get better audio quality (less hiss and distortion) by sending a 15 MHz clock to the I2S_MCLK pin with pwmio.PWMOut. For example, this lets you get very good audio quality (at limited bandwidth) using 8 kHz WAV file samples.

sample_rate = 8000  # can also use 11025, 22050, 44100, or 48000

# 1. Begin sending the MCLK PWM clock signal
mclk_out = pwmio.PWMOut(board.I2S_MCLK, frequency=15_000_000, duty_cycle=2**15)

# 2. Initialize DAC (this includes a soft reset and sets minimum volume)
dac = TLV320DAC3100(board.I2C())

# 3. Configure headphone/speaker routing and volumes (order matters here)
dac.speaker_output = False
dac.headphone_output = True
dac.dac_volume = -3  # Keep this below 0 to avoid DSP filter clipping
dac.headphone_volume = 0  # CAUTION! Line level. Too loud for headphones!

# 4. Configure the right PLL and CODEC settings for our sample rate
dac.configure_clocks(sample_rate=sample_rate, mclk_freq=15_000_000)

# 5. Wait for power-on volume ramp-up to finish
time.sleep(0.35)

# After this, you can do audio.play(whatever) to play samples, synths, etc.
audio = audiobusio.I2SOut(bit_clock=board.I2S_BCLK, word_select=board.I2S_WS,
    data=board.I2S_DIN)

API

class adafruit_tlv320.TLV320DAC3100(i2c: busio.I2C, address: int = 0x18)

Driver for the TI TLV320DAC3100 Stereo DAC with Headphone Amplifier.

Initialize the TLV320DAC3100.

Parameters:
  • i2c – The I2C bus the device is connected to

  • address – The I2C device address (default is 0x18)

config_delay_divider(use_mclk: bool = True, divider: int = 1) bool

Programmable delay timer clock source and divider.

Parameters:
  • use_mclk – True to use external MCLK, False for internal oscillator

  • divider – Clock divider (1-127, or 0 for 128)

Returns:

True if successful, False otherwise

config_mic_bias(power_down: bool = False, always_on: bool = False, voltage: int = 0) bool

MICBIAS settings.

Parameters:
  • power_down – Enable software power down

  • always_on – Keep MICBIAS on even without headset

  • voltage – MICBIAS voltage setting (0-3)

Returns:

True if successful, False otherwise

configure_analog_inputs(left_dac: int = 0, right_dac: int = 0, left_ain1: bool = False, left_ain2: bool = False, right_ain2: bool = False, hpl_routed_to_hpr: bool = False) bool

DAC and analog input routing.

Parameters:
  • left_dac – One of the DAC_ROUTE_* constants for left DAC routing

  • right_dac – One of the DAC_ROUTE_* constants for right DAC routing

  • left_ain1 – Boolean to route left AIN1 to output

  • left_ain2 – Boolean to route left AIN2 to output

  • right_ain2 – Boolean to route right AIN2 to output

  • hpl_routed_to_hpr – Boolean to route HPL to HPR

Raises:

ValueError – If DAC route values are not valid constants

Returns:

True if successful, False otherwise

configure_clocks(sample_rate: int, bit_depth: int = 16, mclk_freq: int | None = None)

Configure the TLV320DAC3100 clock settings.

This function configures all necessary clock settings including PLL, dividers, and interface settings to achieve the requested sample rate.

Parameters:
  • sample_rate – The desired sample rate in Hz. Supported sample rates are 8000, 11025, 22050, 44100, and 48000. But, to get good quality at low sample rates, you need to use MCLK instead of BCLK.

  • bit_depth – The bit depth (16). CircuitPython I2S always sends 16-bit stereo, so set this to 16.

  • mclk_freq – The main clock (MCLK) frequency (None or 15_000_000). This controls how the DAC uses its PLL to generate the delta-sigma modulator’s oversampling clock. For None (the default), the PLL uses the bit clock pin (BCLK) as its input clock. Sound quality for BCLK has a higher noise floor and lots of harmonic distortion at lower sample rates. For better audio quality, set mclk_freq to 15_000_000 and supply a 15 MHz clock signal to the MCLK pin. You can use pwmio.PWMOut to generate the 15 MHz clock.

Returns:

True if successful, False otherwise

configure_headphone_pop(wait_for_powerdown: bool = True, powerup_time: int = 0x07, ramp_time: int = 0x03) bool

Headphone pop removal settings.

Parameters:
  • wait_for_powerdown – Wait for amp powerdown before DAC powerdown

  • powerup_time – Driver power-on time (0-11)

  • ramp_time – Driver ramp-up step time (0-3)

Returns:

True if successful, False otherwise

int1_source(headset_detect: bool, button_press: bool, dac_drc: bool, agc_noise: bool, over_current: bool, multiple_pulse: bool) bool

The INT1 interrupt sources.

Parameters:
  • headset_detect – Enable headset detection interrupt

  • button_press – Enable button press detection interrupt

  • dac_drc – Enable DAC DRC signal power interrupt

  • agc_noise – Enable DAC data overflow interrupt

  • over_current – Enable short circuit interrupt

  • multiple_pulse – If true, INT1 generates multiple pulses until flag read

Returns:

True if successful, False otherwise

int2_sources(headset_detect: bool = False, button_press: bool = False, dac_drc: bool = False, agc_noise: bool = False, over_current: bool = False, multiple_pulse: bool = False) bool

Configure the INT2 interrupt sources.

Parameters:
  • headset_detect – Enable headset detection interrupt

  • button_press – Enable button press detection interrupt

  • dac_drc – Enable DAC DRC signal power interrupt

  • agc_noise – Enable DAC data overflow interrupt

  • over_current – Enable short circuit interrupt

  • multiple_pulse – If true, INT2 generates multiple pulses until flag read

Returns:

True if successful, False otherwise

manual_headphone_driver(left_powered: bool, right_powered: bool, common: int = 0, power_down_on_scd: bool = False) bool

Headphone driver settings.

Parameters:
  • left_powered – Boolean to power left headphone driver

  • right_powered – Boolean to power right headphone driver

  • common – One of the HP_COMMON_* constants for common mode voltage

  • power_down_on_scd – Boolean to power down on short circuit detection

Raises:

ValueError – If common is not a valid HP_COMMON_* constant

Returns:

True if successful, False otherwise

manual_headphone_left_volume(route_enabled: bool, gain: int = 0x7F) bool

HPL analog volume control.

Parameters:
  • route_enabled – Enable routing to HPL

  • gain – Analog volume control value (0-127)

Returns:

True if successful, False otherwise

manual_headphone_right_volume(route_enabled: bool, gain: int = 0x7F) bool

HPR analog volume control.

Parameters:
  • route_enabled – Enable routing to HPR

  • gain – Analog volume control value (0-127)

Returns:

True if successful, False otherwise

reset() bool

Reset the device.

Returns:

True if reset successful, False otherwise

set_headset_detect(enable: bool, detect_debounce: int = 0, button_debounce: int = 0) bool

Headset detection settings.

Parameters:
  • enable – Boolean to enable/disable headset detection

  • detect_debounce – One of the DEBOUNCE_* constants for headset detect

  • button_debounce – One of the BTN_DEBOUNCE_* constants for button press

Raises:

ValueError – If debounce values are not valid constants

Returns:

True if successful, False otherwise

set_input_common_mode(ain1_cm: bool, ain2_cm: bool) bool

Analog input common mode connections.

Parameters:
  • ain1_cm – Connect AIN1 to common mode when unused

  • ain2_cm – Connect AIN2 to common mode when unused

Returns:

True if successful, False otherwise

property bit_depth: int

Configured bit depth.

Getter:

Return The bit depth

property codec_interface: Dict[str, Any]

The current codec interface settings.

Getter:

Return dictionary with codec interface settings

property dac_flags: Dict[str, Any]

The DAC and output driver status flags.

Getter:

Return dictionary with status flags

property dac_volume: float

Current DAC digital volume in dB.

Range is -63.5 dB (soft) to 24 dB (loud).

This acts on two registers at once. In the datasheet, they are:

  • Page 0 / Register 65 (0x41): DAC Left Volume Control

  • Page 0 / Register 66 (0x42): DAC Right Volume Control

Changing the DAC volume will change the signal level feeding into the analog signal chains of the speaker and both headphone channels. You should also be aware of speaker_volume, speaker_gain, speaker_mute, headphone_volume, headphone_left_gain, headphone_right_gain, headphone_left_mute, and headphone_right_mute.

Getter:

Return volume

Setter:

Set volume

property dac_volume_control_mode: int

The DAC volume control mode.

One of the VOL_* constants.

Getter:

Return mode

Setter:

Set mode

Raises:

ValueError – If mode is not a valid VOL_* constant

property dac_volume_step: int

The DAC volume step setting.

One of the VOLUME_STEP_* constants.

Getter:

Return current volume step

Setter:

Set volume step

Raises:

ValueError – If step is not a valid VOLUME_STEP_* constant

property din_input: int

The current DIN input value.

Getter:

Return the DIN input value

property gpio1_mode: int

The current GPIO1 pin mode.

One of the GPIO1_* mode constants.

Getter:

Return mode

Setter:

Set mode

Raises:

ValueError – If mode is not a valid GPIO1_* constant

property headphone_left_gain: int

Left headphone amplifier gain in dB.

Range is 0 dB (soft) to 9 dB (loud) in steps of 1 dB.

In the datasheet, this is Page 1 / Register 40 (0x28): HPL Driver.

Note that the headphone left channel volume is also affected by dac_volume, headphone_volume, and headphone_left_mute.

Getter:

Return gain

Setter:

Set gain

Raises:

ValueError – If set to a value outside the range of 0 to 9

property headphone_left_mute: bool

Left headphone mute status.

True means left headphone is muted, False means not muted.

Getter:

Return status

Setter:

Set status

property headphone_lineout: bool

The current headphone line-out configuration.

Getter:

Return True if both channels are configured as line-out, False otherwise

Setter:

True to configure both channels as line-out, False otherwise

property headphone_output: bool

Headphone output helper with quickstart default settings.

If you set this property to True, the setter will set defaults that are intended for listening at a quiet-ish level with sensitive low impedance earbuds:

  • dac_volume = -20

  • headphone_volume = -30.1

  • headphone_left_gain = headphone_right_gain = 0

If you set this to False, the setter turns off the headphone amp.

Getter:

Return headphone output state: True if either left or right headphone amplifier is powered, False otherwise.

Setter:

This sets several properties to prepare for headphone use. Changed properties include DAC channel enable/volume/mute, DAC path, headphone gain, headphone common mode voltage, and headphone mute.

property headphone_right_gain: int

Right headphone amplifier gain in dB.

Range is 0 dB (soft) to 9 dB (loud) in steps of 1 dB.

In the datasheet, this is Page 1 / Register 41 (0x29): HPR Driver.

Note that the headphone right channel volume is also affected by dac_volume, headphone_volume, and headphone_right_mute.

Getter:

Return gain

Setter:

Set gain

Raises:

ValueError – If set to a value outside the range of 0 to 9

property headphone_right_mute: bool

Right headphone mute status.

True means right headphone is muted, False means not muted.

Getter:

Return status

Setter:

Set status

property headphone_shorted: bool

Check if headphone short circuit is detected.

Getter:

Return True if headphone is shorted, False otherwise

property headphone_volume: float

Current headphone analog volume in dB.

Range is 0 (loud) to -78.3 (very soft).

This acts on two registers at once. In the datasheet they are:

  • Page 1 / Register 36 (0x24): Left Analog Volume to HPL

  • Page 1 / Register 37 (0x25) Right Analog Volume to HPR

Note that headphone output is also affected by dac_volume, headphone_left_gain, headphone_right_gain, headphone_left_mute, and headphone_right_mute.

Getter:

Return volume

Setter:

Set volume

property headset_status: int

Current headset detection status.

Getter:

Return Integer value representing headset status (0=none, 1=without mic, 3=with mic)

property hpl_gain_applied: bool

Check if all programmed gains have been applied to HPL.

Getter:

Return True if gains are applied, False otherwise

property hpr_gain_applied: bool

Check if all programmed gains have been applied to HPR.

Getter:

Return True if gains are applied, False otherwise

property left_dac: bool

The left DAC enabled status.

True if left DAC is enabled, False otherwise

Getter:

Return status

Setter:

Set status

property left_dac_channel_volume: float

Left DAC channel volume in dB.

Getter:

Return volume

Setter:

Set volume

property left_dac_mute: bool

The left DAC mute status.

True if left DAC is muted, False otherwise.

Getter:

Return status

Setter:

Set status

property left_dac_path: int

The left DAC path setting.

One of the DAC_PATH_* constants

Getter:

Return left DAC path

Setter:

Set left DAC path

Raises:

ValueError – If set to something that’s not a DAC_PATH_* constant

property mclk_freq: int

Configured MCLK frequency in Hz.

Getter:

Return The MCLK frequency in Hz

property overtemperature: bool

Check if the chip is overheating.

Getter:

Return True if overtemperature condition exists, False otherwise

property reset_headphone_on_scd: bool

The headphone reset mode for short circuit detection.

True if headphone resets on short circuit, False otherwise.

Getter:

Return mode

Setter:

Set mode

property reset_speaker_on_scd: bool

The speaker reset mode for short circuit detection.

True if speaker resets on short circuit, False otherwise.

Getter:

Return mode

Setter:

Set mode

property right_dac: bool

The right DAC enabled status.

True if right DAC is enabled, False otherwise.

Getter:

Return status

Setter:

Set status

property right_dac_channel_volume: float

Right DAC channel volume in dB.

Getter:

Return volume

Setter:

Set volume

property right_dac_mute: bool

The right DAC mute status.

True if right DAC is muted, False otherwise.

Getter:

Return status

Setter:

Set status

property right_dac_path: int

The right DAC path setting.

One of the DAC_PATH_* constants

Getter:

Return right DAC path

Setter:

Set right DAC path

Raises:

ValueError – If set to something that’s not a DAC_PATH_* constant

property sample_rate: int

Configured sample rate in Hz.

Getter:

Return The sample rate in Hz

property speaker_gain: int

Speaker amplifier gain setting in dB.

Range is 6 dB (soft) to 24 dB (loud) in steps of 6 dB.

In the datasheet, this is Page 1 / Register 42 (0x2A): Class-D Speaker (SPK) Driver.

Note that dac_volume, speaker_volume, and speaker_mute also affect the speaker output level.

Getter:

Return gain

Setter:

Set gain

Raises:

ValueError – If set to anything other than 6, 12, 18, or 24

property speaker_gain_applied: bool

Check if all programmed gains have been applied to Speaker.

Getter:

Return True if gains are applied, False otherwise

property speaker_mute: bool

The speaker mute status.

True means speaker is muted, False means unmuted.

Getter:

Return status

Setter:

Set status

property speaker_output: bool

Speaker output helper with quickstart default settings.

If you set this property to True, the setter will set defaults intended for a relatively quiet listening level using the 8Ω 1W mini speaker that comes bundled with the Fruit Jam:

  • dac_volume = -20

  • speaker_volume = -20.1

  • speaker_gain = 6

If you set this to False, the setter turns off the speaker amp.

Getter:

Return speaker output state: True if speaker amplifier is powered, False otherwise.

Setter:

This sets several properties to prepare for speaker use. Changed properties include DAC channel enable/volume/mute, DAC path, speaker volume, speaker amplifier gain, and speaker mute.

property speaker_shorted: bool

Check if speaker short circuit is detected.

Getter:

Return True if speaker is shorted, False otherwise

property speaker_volume: float

Current speaker analog volume in dB.

Range is 0 (loud) to -78.3 (very soft).

In the datasheet, this is Page 1 / Register 38 (0x26): Left Analog Volume to SPK.

Note that dac_volume, speaker_gain, and speaker_mute also affect the speaker output level.

Getter:

Return volume

Setter:

Set volume

property speaker_wait_time: int

The current speaker power-up wait time.

Speaker power-up wait duration (0-7).

Getter:

Return wait time

Setter:

Set wait time

property vol_adc_db: float

The current volume from the Volume ADC in dB.

Getter:

Return Volume in dB

property vol_adc_hysteresis: int

The volume ADC hysteresis setting.

Hysteresis value (0-3).

Getter:

Return value

Setter:

Set value

property vol_adc_pin_control: bool

The volume ADC pin control status.

True if volume ADC pin control is enabled, False otherwise.

This is for using an analog input pin, probably connected to a potentiometer, to control the volume. You can ignore this if you want to control volume from software over I2C.

Getter:

Return status

Setter:

Set status

property vol_adc_rate: int

The volume ADC sampling rate.

Rate value (0-7).

Getter:

Return value

Setter:

Set value

property vol_adc_use_mclk: bool

The volume ADC use MCLK status.

True means volume ADC uses MCLK, False means internal oscillator.

Getter:

Return status

Setter:

Set status

adafruit_tlv320.BTN_DEBOUNCE_0MS = 0

No debounce

Type:

Button press debounce time option

adafruit_tlv320.BTN_DEBOUNCE_16MS = 2

16ms debounce (2ms clock)

Type:

Button press debounce time option

adafruit_tlv320.BTN_DEBOUNCE_32MS = 3

32ms debounce (4ms clock)

Type:

Button press debounce time option

adafruit_tlv320.BTN_DEBOUNCE_8MS = 1

8ms debounce (1ms clock)

Type:

Button press debounce time option

adafruit_tlv320.DAC_PATH_MIXED = 3

Mixed L+R path

Type:

DAC channel data path option

adafruit_tlv320.DAC_PATH_NORMAL = 1

Normal path (L->L or R->R)

Type:

DAC channel data path option

adafruit_tlv320.DAC_PATH_OFF = 0

DAC data path off

Type:

DAC channel data path option

adafruit_tlv320.DAC_PATH_SWAPPED = 2

Swapped path (R->L or L->R)

Type:

DAC channel data path option

adafruit_tlv320.DAC_ROUTE_HP = 2

DAC routed directly to HP driver

Type:

DAC output routing option

adafruit_tlv320.DAC_ROUTE_MIXER = 1

DAC routed to mixer amplifier

Type:

DAC output routing option

adafruit_tlv320.DAC_ROUTE_NONE = 0

DAC not routed

Type:

DAC output routing option

adafruit_tlv320.DEBOUNCE_128MS = 3

128ms debounce (16ms clock)

Type:

Headset detection debounce time option

adafruit_tlv320.DEBOUNCE_16MS = 0

16ms debounce (2ms clock)

Type:

Headset detection debounce time option

adafruit_tlv320.DEBOUNCE_256MS = 4

256ms debounce (32ms clock)

Type:

Headset detection debounce time option

adafruit_tlv320.DEBOUNCE_32MS = 1

32ms debounce (4ms clock)

Type:

Headset detection debounce time option

adafruit_tlv320.DEBOUNCE_512MS = 5

512ms debounce (64ms clock)

Type:

Headset detection debounce time option

adafruit_tlv320.DEBOUNCE_64MS = 2

64ms debounce (8ms clock)

Type:

Headset detection debounce time option

adafruit_tlv320.GPIO1_BCLK_OUT = 8

Secondary BCLK output for codec interface

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_CLKOUT = 4

CLKOUT output

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_DISABLED = 0

GPIO1 disabled (input and output buffers powered down)

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_GPI = 2

General-purpose input

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_GPO = 3

General-purpose output

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_INPUT_MODE = 1

Input mode (secondary BCLK/WCLK/DIN input or ClockGen)

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_INT1 = 5

INT1 output

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_INT2 = 6

INT2 output

Type:

GPIO1 pin mode options

adafruit_tlv320.GPIO1_WCLK_OUT = 9

Secondary WCLK output for codec interface

Type:

GPIO1 pin mode options

adafruit_tlv320.HP_COMMON_1_35V = 0

Common-mode voltage 1.35V

Type:

Headphone common mode voltage option

adafruit_tlv320.HP_COMMON_1_50V = 1

Common-mode voltage 1.50V

Type:

Headphone common mode voltage option

adafruit_tlv320.HP_COMMON_1_65V = 2

Common-mode voltage 1.65V

Type:

Headphone common mode voltage option

adafruit_tlv320.HP_COMMON_1_80V = 3

Common-mode voltage 1.80V

Type:

Headphone common mode voltage option

adafruit_tlv320.VOLUME_STEP_1SAMPLE = 0

One step per sample

Type:

DAC volume control soft stepping option

adafruit_tlv320.VOLUME_STEP_2SAMPLE = 1

One step per two samples

Type:

DAC volume control soft stepping option

adafruit_tlv320.VOLUME_STEP_DISABLED = 2

Soft stepping disabled

Type:

DAC volume control soft stepping option

adafruit_tlv320.VOL_INDEPENDENT = 0

Left and right channels independent

Type:

DAC volume control configuration option

adafruit_tlv320.VOL_LEFT_TO_RIGHT = 1

Left follows right volume

Type:

DAC volume control configuration option

adafruit_tlv320.VOL_RIGHT_TO_LEFT = 2

Right follows left volume

Type:

DAC volume control configuration option