Drive.A.2

uint8_t tile_drive_a_2_find(tiles_pal_t *hal, uint8_t instance)

Check whether a DAC63202W is present on the bus.

hal

Platform HAL handle

instance

Instance index (see mapping table)

Returns 1 if device ACKs (I2C) or responds to WHO_AM_I (SPI), 0 otherwise

void tile_drive_a_2_init(tiles_pal_t *hal, uint8_t instance, tile_t *tile, const drive_a_2_cfg_t *cfg)

Verifies DEVICE-ID, powers up both VOUT channels at mid-scale, configures gain, and (in I2C mode) probes and configures the amplifiers: shutdown, fixed gain, compression 1:1, output limiter on at DRIVE_A_2_LIMITER_DEFAULT with the chip-default attack / release / hold times, then wake. Init starts unmuted: it clears the mute state.

hal

Platform HAL handle (see core_tiles.h).

instance

Instance index (I2C: address variant, SPI: CS index)

tile

Pointer to tile handle (populated by this function)

cfg

Optional config, or NULL for defaults (1x ext VREF, 6 dB amp)

void tile_drive_a_2_sleep(tile_t *tile)

Powers down both DAC VOUT channels (Hi-Z) and puts the amplifiers into software shutdown.

void tile_drive_a_2_wake(tile_t *tile)

Powers up both VOUT channels, parks them at mid-scale, restores the cached DAC gains, then brings the amplifiers back to the state they were in before sleep: a pair that was muted (mute()) or disabled (amp_disable()) stays in software shutdown; otherwise it is enabled once the DAC has settled.

void tile_drive_a_2_reset(tile_t *tile)

All DAC registers return to defaults. tile->state becomes TILE_STATE_NONE; call init() again to reconfigure.

void tile_drive_a_2_set(tile_t *tile, uint8_t channel, uint16_t value)

Set a DAC channel output by raw 12-bit code (0–4095).

channel

0 or 1

value

12-bit DAC code (0 = 0V, 4095 = full-scale)

void tile_drive_a_2_set_mv(tile_t *tile, uint8_t channel, uint16_t mv)

Computes the DAC code from this channel's gain: full scale is V+ (set_supply_mv() / cfg->vdd_mv) in the 1x gains (the VDD reference, or the VREF pin, which the tile ties to V+), or 1.21 V times 1.5, 2, 3 or 4 with the internal reference (SLASF73A Eq 1-3). The output cannot exceed V+, so requests above it are clamped to V+.

channel

0 or 1

mv

Desired output in millivolts

uint16_t tile_drive_a_2_get(tile_t *tile, uint8_t channel)

Read back the current DAC code for a channel.

channel

0 or 1

Returns 12-bit DAC code currently loaded

void tile_drive_a_2_set_waveform(tile_t *tile, uint8_t channel, drive_a_2_wave_t wave)

Sets FUNC-CONFIG-X in DAC-X-FUNC-CONFIG. Triangle and sawtooth waves oscillate between DAC-X-MARGIN-LOW and DAC-X-MARGIN-HIGH at the configured slew rate and code step. The sine uses 24 fixed codes (0x19A to 0xE66, about 80 % of full scale) and ignores the margins and code step. Set a non-zero slew rate first, then call start_waveform() to begin output.

channel

0 or 1

wave

Waveform shape

void tile_drive_a_2_start_waveform(tile_t *tile, uint8_t channel)

Sets START-FUNC-X in COMMON-DAC-TRIG (read-modify-write, so the other channel's generator keeps running).

channel

0 or 1

void tile_drive_a_2_stop_waveform(tile_t *tile, uint8_t channel)

Clears START-FUNC-X and sets FUNC-CONFIG-X to "disabled".

channel

0 or 1

void tile_drive_a_2_amp_set_gain(tile_t *tile, int8_t gain_db)

Both TPA2028D1 amplifiers share I2C address 0x58, so this write affects both channels simultaneously. No-op in SPI mode.

gain_db

[-28..30] Gain in dB. Clamped if out of range.

• init() turns AGC compression off (1:1), and with compression off the TPA2028D1 fixed gain is only specified from 0 to +30 dB (SLOS660C Table 10), so negative gains are raised to 0 dB. Negative gains need compression on (amp_set_agc()). The output limiter still caps the output level.

int8_t tile_drive_a_2_amp_get_gain(tile_t *tile)

Read the current amplifier fixed gain.

Returns Gain in dB (-28 to +30), or 0 if amp not available

void tile_drive_a_2_amp_enable(tile_t *tile)

While the tile is asleep this only records the request, and wake() applies it once the DAC has settled at mid-scale. No-op in SPI mode.

void tile_drive_a_2_amp_disable(tile_t *tile)

The amplifiers stay off across sleep() / wake(). No-op in SPI mode.

void tile_drive_a_2_amp_set_agc(tile_t *tile, const drive_a_2_agc_cfg_t *cfg)

Writes all AGC registers (attack, release, hold, fixed gain, limiter, compression, noise gate, max gain). Affects both amps. No-op in SPI mode. The compression register is written before the limiter register, because the limiter can only be disabled while compression is 1:1 (SLOS660C Table 11). The limiter stays on unless cfg->limiter_disable is set. The compression ratio also sets the valid fixed-gain range that amp_set_gain() and set_volume_pct() use.

cfg

AGC configuration

uint8_t tile_drive_a_2_amp_read_status(tile_t *tile)

Check bit 3 (FAULT) for short-circuit and bit 2 (Thermal) for over-temperature. Write 0 to the respective bit to clear.

Returns Raw register 0x01 value, or 0 if amp not available

uint16_t tile_drive_a_2_read_status(tile_t *tile)

Contains DEVICE-ID, VERSION-ID, NVM CRC status, and DAC busy flags.

Returns 16-bit GENERAL-STATUS value

void tile_drive_a_2_play_tone(tile_t *tile, drive_a_2_channel_t channel, uint16_t freq_hz, uint16_t ms)

Configures DAC margins for full-scale swing, sets a sine waveform, and uses the on-chip parametric generator together with a software-tuned slew rate / code step to approximate `freq_hz`. The chip's sine generator runs at 1 / (24 × slew step), so only 15 pitches exist (10417, 5208, 3472, 2315, 1541, 1029, 686, 457, 305, 174, 99.5, 56.9, 32.5, 16.3, 8.1 Hz); the nearest one is played. The sine spans about 80 % of the DAC's range. The amplifier is unmuted for the duration of the tone and restored to its prior mute state on return.

channel

DRIVE_A_2_CH_LEFT, _RIGHT, or _BOTH

freq_hz

[8..10417] Tone frequency in Hz (rounded to the nearest generator pitch)

ms

Duration in milliseconds

• Blocks for `ms` milliseconds via `hal->delay_ms`.

void tile_drive_a_2_play_silence(tile_t *tile, drive_a_2_channel_t channel, uint16_t ms)

Stops any active waveform on `channel`, parks the DAC code at mid-scale (= zero differential at the amp input), and blocks for `ms` milliseconds. Useful to insert a precise gap between tones without toggling the amp shutdown — the amp stays alive but draws minimal idle current with no signal.

channel

DRIVE_A_2_CH_LEFT, _RIGHT, or _BOTH

ms

Duration in milliseconds

• Blocks for `ms` milliseconds via `hal->delay_ms`.

void tile_drive_a_2_play_chirp(tile_t *tile, drive_a_2_channel_t channel, uint16_t start_hz, uint16_t end_hz, uint16_t ms)

Software sine-LUT chirp delivered through `set` (raw DAC code) at ~8 kHz update rate. Frequency advances linearly across `ms`. For ascending sweeps pass start < end; for descending, start > end. The amp is unmuted for the duration and restored to its prior mute state on return.

channel

DRIVE_A_2_CH_LEFT, _RIGHT, or _BOTH

start_hz

Initial frequency in Hz

end_hz

Final frequency in Hz

ms

Sweep duration in milliseconds

• Blocks for `ms` milliseconds via `hal->delay_ms`.

void tile_drive_a_2_set_volume_pct(tile_t *tile, drive_a_2_channel_t channel, uint8_t pct)

Linear-in-dB mapping from `pct` onto the fixed-gain range the TPA2028D1 specifies for the active compression ratio (SLOS660C Table 10): compression 1:1 (init's default): gain_db = (pct × 30) / 100 compression 2:1, 4:1 or 8:1: gain_db = -28 + (pct × 58) / 100 With compression off, 0 % → 0 dB (the lowest valid gain, not silence; use mute() for silence), 50 % → +15 dB, 100 % → +30 dB. The output limiter still caps the level. The mapping is intentionally linear-in-dB rather than perceptually weighted; for finer dB control use @ref tile_drive_a_2_amp_set_gain directly. Because both amps share an I²C address, the channel argument is accepted for symmetry with the rest of the tier-2 API but the write lands on both physical amps.

channel

DRIVE_A_2_CH_LEFT, _RIGHT, or _BOTH (advisory)

pct

[0..100] Percent (clamped if out of range)

void tile_drive_a_2_mute(tile_t *tile, drive_a_2_channel_t channel)

Stashes the current fixed-gain register so a later @ref tile_drive_a_2_unmute restores it byte-exact, then puts the amp pair into software shutdown (SWS=1). Both physical amps mute regardless of `channel` (shared I²C address). The mute survives sleep() / wake(); only unmute(), amp_enable() or init() clear it.

channel

DRIVE_A_2_CH_LEFT, _RIGHT, or _BOTH (advisory)

void tile_drive_a_2_unmute(tile_t *tile, drive_a_2_channel_t channel)

Re-applies the gain that was active at the time of @ref tile_drive_a_2_mute and clears software shutdown (SWS=0). If the channel was never muted by this driver instance the call still wakes the amp using whatever gain is currently in the register. While the tile is asleep the amp is woken by wake().

channel

DRIVE_A_2_CH_LEFT, _RIGHT, or _BOTH (advisory)

void tile_drive_a_2_set_gain(tile_t *tile, uint8_t channel, drive_a_2_gain_t gain)

Automatically enables the internal reference when an internal-reference gain is selected, and records the gain for this channel so set_mv() uses the right full scale (each channel keeps its own).

channel

0 or 1

gain

One of the drive_a_2_gain_t values

void tile_drive_a_2_set_supply_mv(tile_t *tile, uint16_t mv)

The DAC63202W's VDD is the tile's V+ (2.5–5.5 V). In the 1x gains the DAC's full scale is V+, so set_mv() needs it to pick the right code; the internal-reference gains need it to clamp requests above V+. No bus traffic. Default 3300 mV (or cfg->vdd_mv).

mv

[2500..5500] V+ in millivolts (clamped).

void tile_drive_a_2_set_slew_rate(tile_t *tile, uint8_t channel, drive_a_2_slew_t slew)

Programs SLEW-RATE-X bits[3:0] in DAC-X-FUNC-CONFIG. Affects both slewed direct-output updates and the on-chip function generator's frequency. The default is no-slew — outputs settle as fast as the analog stage allows. Use a slower slew to soften zero-crossings for capacitive / inductive loads, or to dial in a target waveform frequency together with set_code_step() and set_margins().

channel

0 or 1

slew

Slew-rate code (drive_a_2_slew_t value 0–15)

void tile_drive_a_2_set_code_step(tile_t *tile, uint8_t channel, drive_a_2_step_t step)

Programs CODE-STEP-X bits[6:4] in DAC-X-FUNC-CONFIG. Larger steps give faster ramps / higher waveform frequencies at the cost of coarser resolution.

channel

0 or 1

step

Code-step code (drive_a_2_step_t value 0–7)

void tile_drive_a_2_set_margins(tile_t *tile, uint8_t channel, uint16_t low, uint16_t high)

Writes DAC-X-MARGIN-HIGH and DAC-X-MARGIN-LOW. The function generator oscillates between these levels, and they also serve as the thresholds for the chip's window / hysteresis comparator modes. Values are 12-bit DAC codes; high must be > low.

channel

0 or 1

low

12-bit DAC code for the lower bound (0–4095)

high

12-bit DAC code for the upper bound (0–4095)

void tile_drive_a_2_set_phase(tile_t *tile, uint8_t channel, drive_a_2_phase_t phase)

Programs PHASE-SEL-X bits[12:11] in DAC-X-FUNC-CONFIG. Take effect the next time start_waveform() is called. Use phase = 90° on one channel and 0° on the other to drive a quadrature pair.

channel

0 or 1

phase

Phase offset (drive_a_2_phase_t)

void tile_drive_a_2_set_waveform_params(tile_t *tile, uint8_t channel, drive_a_2_wave_t wave, drive_a_2_step_t step, drive_a_2_slew_t slew)

Convenience helper that sets up the waveform shape, full-scale margins (0 → 4095), code step, and slew rate in one call. The resulting frequency is (SLASF73A Eq 6-8): f_triangle = 1 / (2 × time_step × ceil((margin_high − margin_low) / code_step)) f_sawtooth = 1 / ( time_step × ceil((margin_high − margin_low + 1) / code_step)) f_sine = 1 / (24 × time_step) Call start_waveform() to begin output once configured. For fine-grained control, call set_margins() / set_code_step() / set_slew_rate() / set_waveform() / set_phase() individually.

channel

0 or 1

wave

Waveform shape (drive_a_2_wave_t)

step

Code-step (drive_a_2_step_t)

slew

Time per step (drive_a_2_slew_t)

void tile_drive_a_2_amp_set_limiter(tile_t *tile, uint8_t enabled, uint8_t level)

The limiter caps the amplifier output at level n = -6.5 + 0.5 n dBV (SLOS660C Table 11; power figures are for 8 ohm): 0 = 0.67 V peak, 0.03 W; 19 = 2.0 V peak, 0.25 W (init's default); 26 = 3.0 V peak, 0.56 W (chip default); 31 = 3.99 V peak, 0.99 W. A level whose peak is above V+ cannot be reached, so the output clips first. Read- modify-write of AGC_CTRL1 (the noise-gate bits are kept). Affects both amps. No-op in SPI mode. speaker's rating, is unsafe for small speakers. The chip only honours a disable while AGC compression is 1:1 (init's default); with compression on the driver keeps the limiter enabled and only sets the level.

enabled

1 = limiter on (default), 0 = off (unsafe)

level

[0..31] Limiter level (clamped)

void tile_drive_a_2_nvm_save(tile_t *tile)

Triggers NVM-PROG in COMMON-TRIGGER. The DAC's user-programmable registers (gain, margins, slew, waveform shape, COMMON-CONFIG, etc. — see datasheet "highlighted gray" rows) are committed to non-volatile storage and become the new power-on defaults. Blocking: holds the bus busy for the NVM write cycle. Limited write endurance — TI specs ~1000 cycles. Use only for one-time factory tuning, not for runtime configuration storage.

void tile_drive_a_2_nvm_reload(tile_t *tile)

Triggers NVM-RELOAD in COMMON-TRIGGER. Restores the saved power-on configuration without a full reset — equivalent to the load that happens automatically on POR. Blocks until the reload completes, then re-reads both channels' VOUT-GAIN so set_mv() follows whatever gain the NVM held.

uint16_t tile_drive_a_2_read_reg(tile_t *tile, uint8_t reg)

Escape hatch for advanced users wanting to touch registers the driver doesn't expose. Caller is responsible for not bricking the chip — most useful registers have typed setters above.

reg

Register address (7-bit)

Returns 16-bit register value

void tile_drive_a_2_write_reg(tile_t *tile, uint8_t reg, uint16_t value)

Write any 16-bit DAC63202W register.

reg

Register address (7-bit)

value

16-bit value to write (big-endian on the wire)