romr/pt2258

Readme

# PT2258 Component
ESP-IDF component driver for the **PT2258** 6-Channel Electronic Volume Controller (I2C Interface)

## 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) | 7-bit Address (ESP-IDF Standard) | C Macro Definition |
| :---: | :---: | :---: | :---: | :---: |
| **GND (0)** | **GND (0)** | 0x80 | 0x40 | `PT2258_ADDRESS_0` |
| **GND (0)** | **VCC (1)** | 0x84 | 0x42 | `PT2258_ADDRESS_1` |
| **VCC (1)** | **GND (0)** | 0x88 | 0x44 | `PT2258_ADDRESS_2` |
| **VCC (1)** | **VCC (1)** | 0x8C | 0x46 | `PT2258_ADDRESS_3` |

### Power-On Initialization Timing (I2C Bus Interface Start Time)
After power is turned ON, the PT2258 requires a brief stabilization period. You **must wait at least 200ms** before sending any I2C bus signals to the chip. If the waiting period is shorter than 200ms, the internal logic may lock up, and I2C control will fail. 

[!WARNING]
Important Hardware Behavior (as specified in the datasheet):
The PT2258 function registers do not have any default power-on settings. After clearing the registers (which happens automatically inside `pt2258_create()`), an initial attenuation value must be explicitly sent to each register/channel. If a register is left unconfigured, it is highly likely that no sound will be output from that specific channel.

## Installation

This component can be installed as a Git submodule or directly from the ESP-IDF Component Registry.

### Option 1: Install via Git Submodule

```bash
cd <your_project_root>
git submodule add https://github.com/romr/esp-idf-pt2258.git components/pt2258
```

### Option 2: Install via ESP-IDF Component Registry

Add the following line to your `idf_component.yml` file:

```yaml
dependencies:
  romr/pt2258:
    version: "*"
```

### Option 3: Install via ESP-IDF Commander (if available)

```bash
idf.py add-dependency romr/pt2258
```

## Usage example

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

static const char *TAG = "main";

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

    // 1. Initialize your I2C master bus using i2c_bus component configuration
    i2c_bus_handle_t i2c_bus_handle = /* Your I2C bus initialization logic */;

    // 2. Configure PT2258 device settings (using 7-bit address from the table)
    pt2258_i2c_config_t pt2258_cfg = {
        .i2c_bus = i2c_bus_handle,
        .i2c_addr = PT2258_ADDRESS_2
    };

    pt2258_dev_handle_t pt2258_handle = NULL;

    // 3. Create and initialize the device instance
    esp_err_t ret = pt2258_create(&pt2258_cfg, &pt2258_handle);
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "Failed to initialize PT2258");
        return;
    }
    // Mute the chip initially
    pt2258_set_mute(pt2258_handle, true);

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

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

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

    // ... your application logic ...

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