Volume service

Sole writer of the PCM5242 digital volume (pot -> DAC, with L/R balance). More...

Collaboration diagram for Volume service:

Files
file	components/services/audio/volume.c
	Volume service: pot -> active output (DAC byte or Bluetooth AVRCP), deadband write.

Functions
esp_err_t	volume_init (void)
	Bring up the volume pot and push the current knob position to the DAC.
bool	volume_poll (int *out_mv, uint8_t *out_level)
	Sample the pot and write the active output only if the mapped level changed.
bool	volume_read_mv (int *out_mv)
	Read the pot wiper voltage without touching any output (for diagnostics).
void	volume_set_output (volume_output_t out)
	Select which output volume_poll() drives. Default VOLUME_OUT_DAC.
volume_output_t	volume_get_output (void)
	The output volume_poll() currently drives (see volume_set_output()).
void	volume_set_fixed (int percent)
	Override the pot with a fixed volume (for a deterministic measurement).
void	volume_clear_fixed (void)
	Release the fixed-volume override; the pot drives the level again from the next poll.
uint8_t	volume_get_level (void)
	The level that would be applied to the active output under the current setting.
void	volume_set_bt_handler (esp_err_t(*set_abs_vol)(uint8_t volume))
	Register the Bluetooth absolute-volume setter (e.g. bluetooth_set_absolute_volume).
void	volume_set_balance (int8_t steps)
	Trim the L/R balance to compensate the analog imbalance (driver is independent L/R).
int8_t	volume_get_balance (void)
	The current L/R balance trim in register steps (see volume_set_balance()).
void	volume_save_balance (void)
	Persist the current balance trim to NVS so it survives a reboot.

Detailed Description

Sole writer of the PCM5242 digital volume (pot -> DAC, with L/R balance).

Function Documentation

volume_clear_fixed()

void volume_clear_fixed

(

void

)

Release the fixed-volume override; the pot drives the level again from the next poll.

volume_get_balance()

int8_t volume_get_balance

(

void

)

The current L/R balance trim in register steps (see volume_set_balance()).

Returns

Signed step offset; positive attenuates RIGHT, negative LEFT, 0 = equal.

volume_get_level()

uint8_t volume_get_level

(

void

)

The level that would be applied to the active output under the current setting.

With a fixed override this is the exact level volume_poll() applies (a pure computation from the fixed percent: the PCM5242 register byte for the DAC, the AVRCP value for Bluetooth). For the autonomy CSV. Meaningful mainly while a fixed override is active.

Returns

DAC volume byte (VOLUME_OUT_DAC) or AVRCP value (VOLUME_OUT_BT); 0 for VOLUME_OUT_NONE.

volume_get_output()

volume_output_t volume_get_output

(

void

)

The output volume_poll() currently drives (see volume_set_output()).

Returns

VOLUME_OUT_DAC (jack), VOLUME_OUT_BT (speaker) or VOLUME_OUT_NONE (mute).

volume_init()

esp_err_t volume_init

(

void

)

Bring up the volume pot and push the current knob position to the DAC.

Call once at startup, after audio_dac_init() (this service writes the DAC). Owns the ADC unit handle internally. Idempotent.

Returns

ESP_OK; otherwise the underlying ADC init error.

volume_poll()

bool volume_poll	(	int *	out_mv,
		uint8_t *	out_level )

Sample the pot and write the active output only if the mapped level changed.

Call periodically (~10..20 Hz) from a maintenance/UI loop. The ADC read happens every call (cheap; skipped under a fixed-volume override); the I2C/AVRCP write is skipped when the level is unchanged (deadband).

Parameters

[out]	out_mv	Optional: wiper voltage in millivolts (for display). May be NULL.
[out]	out_level	Optional: the level applied to the active output (DAC byte or AVRCP value, per the current output). May be NULL.

Returns

true if a new level was sent to the active output this call, false otherwise.

volume_read_mv()

bool volume_read_mv

(

int *

out_mv

)

Read the pot wiper voltage without touching any output (for diagnostics).

Unlike volume_poll(), this never writes the DAC or AVRCP — it only samples the ADC. Brings up the pot ADC on first call if volume_init() has not run yet, so the diagnostics screen can show the knob voltage before the audio path is wired.

Parameters

[out]

out_mv

Receives the wiper voltage in millivolts.

Returns

true on a successful read, false if the ADC is unavailable.

volume_save_balance()

void volume_save_balance

(

void

)

Persist the current balance trim to NVS so it survives a reboot.

Call sparingly (e.g. when the user leaves the audio-settings screen), not on every step: the live trim is applied by volume_set_balance(), this only writes flash. volume_init() restores the saved value on boot.

volume_set_balance()

void volume_set_balance

(

int8_t

steps

)

Trim the L/R balance to compensate the analog imbalance (driver is independent L/R).

Applied on top of the knob level from the next poll onward. Each step is one DAC volume register step (0.5 dB). Positive attenuates the RIGHT channel (the louder analog side on this board), negative attenuates the LEFT. 0 = equal.

Parameters

steps

Signed register-step offset.

volume_set_bt_handler()

void volume_set_bt_handler

(

esp_err_t(*

set_abs_vol )(uint8_t volume)

)

Register the Bluetooth absolute-volume setter (e.g. bluetooth_set_absolute_volume).

Indirection so the volume service does not hard-link the Bluetooth stack when BT is unused. The callback takes an AVRCP absolute volume (0..0x7F). Pass NULL to clear.

Parameters

set_abs_vol

The setter, or NULL.

volume_set_fixed()

void volume_set_fixed

(

int

percent

)

Override the pot with a fixed volume (for a deterministic measurement).

While active, volume_poll() ignores the wiper and applies percent to the active output (same curve as the equivalent knob position), so the physical knob no longer affects the level. Used by the autonomy test to run at a repeatable volume. Clear with volume_clear_fixed().

Parameters

percent

Fixed volume, 0..100 (clamped).

volume_set_output()

void volume_set_output

(

volume_output_t

out

)

Select which output volume_poll() drives. Default VOLUME_OUT_DAC.

Switching re-applies the current knob position to the new output on the next poll. VOLUME_OUT_BT requires a handler registered via volume_set_bt_handler().

Parameters

out	The output to drive.