API Reference
adafruit_tlv320
CircuitPython driver for the TLV320DAC3100 I2S DAC
Author(s): Liz Clark, Sam Blenny
Implementation Notes
Hardware:
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 = Trueorheadphone_output = Trueto 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:
Adafruit CircuitPython firmware for the supported boards: https://circuitpython.org/downloads
Adafruit’s Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
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
- 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 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, andheadphone_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 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, andheadphone_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, andheadphone_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, andheadphone_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 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 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, andspeaker_mutealso 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, andspeaker_mutealso 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
- 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