pt2258_ctrl (Controller)

An ESP-IDF volume management engine for the PT2258 IC, featuring logarithmic scaling, channel masking, per-channel balance offsets, and internal state caching.

Features

  • Master volume control: 0-100% volume with logarithmic LUT or linear (optional) scaling

  • Volume stepping: Increment/decrement volume by percentage steps

  • Per-channel offsets: Adjust individual channel levels relative to master volume

  • Global mute: Chip-level mute control for all channels

  • Offset limits: Configurable range for channel offsets

  • State tracking: Maintains internal state for volume, offsets, and mute status

  • Channel Masking: Initialize only the channels you actually wired on your PCB layout.

Dependencies & Integration

This component acts as a high-level software engine and strictly requires the low-level hardware driver romr/pt2258 component to communicate with the chip.

Note

Automatic Resolution The core pt2258 driver is already declared as a direct dependency inside this component’s idf_component.yml. When you add pt2258_ctrl to your project, the ESP-IDF Component Manager will automatically fetch and install both components.

You only need to add the controller to your project’s dependencies:

idf.py add-dependency romr/pt2258_ctrl

or manually add to your project’s idf_component.yml:

dependencies:
  romr/pt2258_ctrl: "*" # Automatically resolves and installs romr/pt2258

Usage example

Because the core driver is pulled automatically, you can directly include both interfaces (pt2258.h and pt2258_ctrl.h) in your application code:

Note

Thread Safety

This component is not thread-safe. Use from a single task or add external synchronization if accessing from multiple contexts.

#include "esp_log.h"
#include "i2c_bus.h"
#include "pt2258.h"
#include "pt2258_ctrl.h"

static const char *TAG = "main";

void app_main(void)
{
    // 1. Initialize your I2C master bus and add PT2258 device (see pt2258 documentation for example)
    
    // ... your I2C bus and device initialization code ...
    // You should have a pt2258_handle variable at this point (can be initialized by one of the adapters)

    // 2. Configure PT2258 controller
    // Enable channels 1, 2, and 3 (stereo setup)
    pt2258_ctrl_config_t ctrl_cfg = {
        .pt2258 = pt2258_handle,
        .active_channels_mask = PT2258_CH1_ENABLE | PT2258_CH2_ENABLE | PT2258_CH3_ENABLE,
        .init_volume = 50,              // Start at 50% volume
        .offset_limits = 20,            // Allow +/- 20 dB offset per channel (must be <= PT2258_MAX_ATTENUATION)
        .use_linear_volume = false,     // Use logarithmic volume scaling (false = LUT, true = linear)
        .init_mute = true,              // Start with audio disabled
    };

    pt2258_ctrl_handle_t ctrl_handle = NULL;
    esp_err_t ret = pt2258_ctrl_create(&ctrl_cfg, &ctrl_handle);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to initialize PT2258 controller");
        pt2258_delete(&pt2258_handle);
        return;
    }

    // 3. Control volume and offsets example
    // Boost channel 1 by +5 dB, reduce channel 2 by -3 dB
    pt2258_ctrl_set_offset(ctrl_handle, 1, 5);
    pt2258_ctrl_set_offset(ctrl_handle, 2, -3);

    // Set master volume to 70%
    pt2258_ctrl_set_master_volume(ctrl_handle, 70);

    // Unmute to enable audio output
    pt2258_ctrl_set_mute(ctrl_handle, false);

    // Increase volume by 10%
    pt2258_ctrl_volume_step_up(ctrl_handle, 10);
    
    // Decrease volume by 5%
    pt2258_ctrl_volume_step_down(ctrl_handle, 5);

    // Get current state
    uint8_t current_volume;
    pt2258_ctrl_get_master_volume(ctrl_handle, &current_volume);
    ESP_LOGI(TAG, "Current volume: %d%%", current_volume);

    int16_t ch1_offset;
    pt2258_ctrl_get_offset(ctrl_handle, 1, &ch1_offset);
    ESP_LOGI(TAG, "Channel 1 offset: %d dB", ch1_offset);

    uint8_t ch1_attenuation;
    pt2258_ctrl_get_attenuation(ctrl_handle, 1, &ch1_attenuation);
    ESP_LOGI(TAG, "Channel 1 attenuation: %d dB", ch1_attenuation);

    // ... your application logic ...

    // 4. Clean up resources when done
    pt2258_ctrl_delete(&ctrl_handle);
    pt2258_delete(&pt2258_handle);
}

API Reference

PT2258 Channel Enable Masks

PT2258_CH1_ENABLE

Channel 1 (Pins 1->20)

PT2258_CH2_ENABLE

Channel 2 (Pins 2->19)

PT2258_CH3_ENABLE

Channel 3 (Pins 3->18)

PT2258_CH4_ENABLE

Channel 4 (Pins 8->13)

PT2258_CH5_ENABLE

Channel 5 (Pins 9->12)

PT2258_CH6_ENABLE

Channel 6 (Pins 10->11)

Typedefs

typedef struct pt2258_ctrl_ctx_t *pt2258_ctrl_handle_t

Opaque handle structure definition for the PT2258 controller instance.

Functions

esp_err_t pt2258_ctrl_create(const pt2258_ctrl_config_t *cfg, pt2258_ctrl_handle_t *handle)

Initialize a PT2258 controller.

Parameters:

  • cfg – [in] Pointer to the controller configuration structure

  • handle – [out] Pointer to store the allocated controller instance handle

Returns:

  • ESP_OK on success

  • ESP_ERR_NO_MEM if memory allocation fails

  • ESP_ERR_INVALID_ARG if parameters are invalid

esp_err_t pt2258_ctrl_delete(pt2258_ctrl_handle_t *handle)

Free controller resources and delete instance.

Parameters:

handle – [inout] Pointer to the controller handle to be destroyed

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if handle pointer is NULL

esp_err_t pt2258_ctrl_set_offset(pt2258_ctrl_handle_t handle, uint8_t channel, int16_t offset)

Set channel offset relative to master volume.

Parameters:

  • handle – [in] Controller instance handle

  • channel – [in] Channel number (1-6)

  • offset – [in] Offset value in dB

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if channel or offset bounds are invalid

  • ESP_ERR_INVALID_STATE if requested channel is masked out as inactive

esp_err_t pt2258_ctrl_reset_offsets(pt2258_ctrl_handle_t handle)

Reset all channel offsets back to 0 dB (Restore balance)

Parameters:

handle – [in] Controller instance handle

Returns:

ESP_OK on success, error code otherwise

esp_err_t pt2258_ctrl_set_master_volume(pt2258_ctrl_handle_t handle, uint8_t volume)

Set master volume percentage for all active channels.

Parameters:

  • handle – [in] Controller instance handle

  • volume – [in] Volume percentage value (0-100)

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if volume is out of bounds (> 100%)

esp_err_t pt2258_ctrl_volume_step_up(pt2258_ctrl_handle_t handle, uint8_t step_percent)

Increase master volume by a relative percentage step.

Parameters:

  • handle – [in] Controller instance handle

  • step_percent – [in] Step up value percentage (1-100%)

Returns:

ESP_OK on success, error code otherwise

esp_err_t pt2258_ctrl_volume_step_down(pt2258_ctrl_handle_t handle, uint8_t step_percent)

Decrease master volume by a relative percentage step.

Parameters:

  • handle – [in] Controller instance handle

  • step_percent – [in] Step down value percentage (1-100%)

Returns:

ESP_OK on success, error code otherwise

esp_err_t pt2258_ctrl_set_mute(pt2258_ctrl_handle_t handle, bool mute)

Toggle the absolute mute state for all channels.

Parameters:

  • handle – [in] Controller instance handle

  • mute – [in] Set true to activate global mute, false to restore volume state

Returns:

ESP_OK on success, error code otherwise

esp_err_t pt2258_ctrl_get_attenuation(pt2258_ctrl_handle_t handle, uint8_t channel, uint8_t *attenuation)

Get the actual current attenuation for a specific channel.

Parameters:

  • handle – [in] Controller instance handle

  • channel – [in] Channel number (1-6)

  • attenuation – [out] Pointer to store the computed attenuation value (0-79 dB)

Returns:

  • ESP_OK on success

  • ESP_ERR_INVALID_ARG if destination pointer is NULL or channel is out of range

esp_err_t pt2258_ctrl_get_offset(pt2258_ctrl_handle_t handle, uint8_t channel, int16_t *offset)

Get current channel offset value relative to master volume.

Parameters:

  • handle – [in] Controller instance handle

  • channel – [in] Channel number (1-6)

  • offset – [out] Pointer to store the channel’s offset value in dB

Returns:

ESP_OK on success, error code otherwise

esp_err_t pt2258_ctrl_get_master_volume(pt2258_ctrl_handle_t handle, uint8_t *volume)

Get current tracked master volume percentage.

Parameters:

  • handle – [in] Controller instance handle

  • volume – [out] Pointer to store the volume percentage status (0-100)

Returns:

ESP_OK on success, error code otherwise

esp_err_t pt2258_ctrl_get_mute(pt2258_ctrl_handle_t handle, bool *mute)

Get current tracked global mute state.

Parameters:

  • handle – [in] Controller instance handle

  • mute – [out] Pointer to store the boolean mute state status

Returns:

ESP_OK on success, error code otherwise

struct pt2258_ctrl_config_t
#include <pt2258_ctrl.h>

PT2258 controller configuration structure.

Public Members

pt2258_handle_t pt2258

PT2258 handle

uint8_t active_channels_mask

Mask of active channels (e.g., PT2258_CH1_ENABLE | PT2258_CH2_ENABLE)

uint8_t init_volume

Initial master volume at power-on (0-100%)

uint8_t offset_limits

Offset limits in dB (must be <= PT2258_MAX_ATTENUATION)

bool init_mute

Initial mute state

bool use_linear_volume

Use linear volume scaling (false = logarithmic LUT, true = linear)