romr/pt2258

Readme

[![Component Registry](https://components.espressif.com/components/romr/pt2258/badge.svg)](https://components.espressif.com/components/romr/pt2258)

# PT2258

ESP-IDF component driver for the PT2258 6-channel electronic volume controller with I2C interface. This component provides a fully decoupled interface to interact with the PT2258 using a user-defined I2C write callback. This architecture ensures out-of-the-box compatibility with the native ESP-IDF v5 `driver/i2c_master.h`, custom I2C wrappers, or the `i2c_bus` abstraction from Espressif's IoT Solution. **It is specifically designed to bypass the notorious I2C driver conflicts in ESP-ADF (Espressif Audio Development Framework) projects, which relies on its own separate `i2c_bus` implementation.**

See [PT2258 datasheet](https://www.alldatasheet.com/datasheet-pdf/view/201161/PTC/PT2258.html)

## Features

- **6-channel volume control**: Individual attenuation control for each channel plus master volume.
- **Fine-grained attenuation**: 0 to 79 dB in 1 dB steps.
- **Global mute**: Chip-level mute control for all channels.
- **Multiple I2C addresses**: Up to 4 configurable addresses via hardware pins.
- **Transport Independent**: Easily integrates into any project by injecting your own I2C write function.
- **ESP-IDF integration**: Fully compatible with ESP-IDF v5.0 and later.

## Hardware Specifications & Timing

### I2C Addressing
The PT2258 supports up to 4 selectable I2C addresses via the hardware configuration of the `CODE1` (Pin 17) and `CODE2` (Pin 4) pins. This allows you to daisy-chain up to 4 chips on a single I2C bus.

| CODE1 (Pin 17) | CODE2 (Pin 4) | 8-bit Address (Datasheet) | C Macro Definition (8-bit) | 7-bit Address (ESP-IDF Standard) | C Macro Definition (7-bit) |
| :---: | :---: | :---: | :---: | :---: | :---: |
| **GND (0)** | **GND (0)** | 0x80 | `PT2258_I2C_ADDR_0_8BIT` | 0x40 | `PT2258_I2C_ADDR_0` |
| **GND (0)** | **VCC (1)** | 0x84 | `PT2258_I2C_ADDR_1_8BIT` | 0x42 | `PT2258_I2C_ADDR_1` |
| **VCC (1)** | **GND (0)** | 0x88 | `PT2258_I2C_ADDR_2_8BIT` | 0x44 | `PT2258_I2C_ADDR_2` |
| **VCC (1)** | **VCC (1)** | 0x8C | `PT2258_I2C_ADDR_3_8BIT` | 0x46 | `PT2258_I2C_ADDR_3` |

### Critical Hardware Considerations

> [!IMPORTANT]
> **Power-On Stabilization Delay** > After power-up, the PT2258 requires a stabilization period. You **must wait at least 200 ms** before transmitting any I2C signals. Initiating communication early can lock up the chip's internal logic, requiring a hard power cycle.

> [!WARNING]
> **Uninitialized Register Silence** > The PT2258 does not load default volume values on boot. While `pt2258_create()` automatically clears internal registers, you must explicitly set an attenuation value for each channel. Unconfigured channels will likely output no audio.

## Usage Example

The following example demonstrates how to initialize the PT2258 using the native ESP-IDF v5 master driver:

```c
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "pt2258.h"

static const char *TAG = "main";

// 1. Define the I2C write callback matching the pt2258_write_fn_t signature
static esp_err_t pt2258_i2c_write(void *dev_handle, const uint8_t *data, size_t len)
{
    // Directly use the injected native ESP-IDF device handle
    return i2c_master_transmit((i2c_master_dev_handle_t)dev_handle, data, len, -1);
}

void app_main(void)
{
    // 0. Crucial: Wait at least 200ms after Power-ON to ensure PT2258 stability
    vTaskDelay(pdMS_TO_TICKS(200));

    // 2. Initialize the I2C master bus
    i2c_master_bus_config_t bus_config = {
        .clk_source = I2C_CLK_SRC_DEFAULT,
        .i2c_port = I2C_NUM_0,
        .sda_io_num = GPIO_NUM_21,
        .scl_io_num = GPIO_NUM_22,
        .glitch_ignore_cnt = 7,
        .flags.enable_internal_pullup = true,
    };
    i2c_master_bus_handle_t bus_handle;
    ESP_ERROR_CHECK(i2c_master_new_bus(&bus_config, &bus_handle));

    // 3. Add the PT2258 device to the I2C bus (using 7-bit address)
    i2c_device_config_t dev_config = {
        .dev_addr_length = I2C_ADDR_BIT_LEN_7,
        .device_address = PT2258_I2C_ADDR_0, // 0x40
        .scl_speed_hz = 100000,              // 100 kHz Standard Mode
    };
    i2c_master_dev_handle_t pt2258_i2c_handle;
    ESP_ERROR_CHECK(i2c_master_bus_add_device(bus_handle, &dev_config, &pt2258_i2c_handle));

    // 4. Configure PT2258 driver settings by injecting the transport dependencies
    pt2258_config_t pt2258_cfg = {
        .write_fn = pt2258_i2c_write,
        .i2c_dev_handle = pt2258_i2c_handle // Injecting the i2c_master_dev_handle_t
    };

    pt2258_handle_t pt2258_handle = NULL;

    // 5. Create and initialize the device instance (automatically executes System Reset)
    esp_err_t ret = pt2258_create(&pt2258_cfg, &pt2258_handle);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to initialize PT2258 driver");
        return;
    }

    // Mute channels before changing configurations to avoid audio pops
    pt2258_set_mute(pt2258_handle, true);

    // 6. Adjust volume (attenuation)
    // Set Master Volume (All channels) to -15 dB
    pt2258_set_attenuation(pt2258_handle, PT2258_CH_ALL, 15);

    // Set Channel 1 specifically to -40 dB
    pt2258_set_attenuation(pt2258_handle, PT2258_CH_1, 40);

    // Unmute the chip to let audio pass through
    pt2258_set_mute(pt2258_handle, false);

    // ... your application logic ...

    // 7. Clean up resources when done
    pt2258_delete(&pt2258_handle);
}