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 simple interface to interact with the PT2258 using the i2c_bus abstraction from Espressif's IoT Solution. Supports individual channel and master volume attenuation (0-79 dB), global mute control, and up to 4 configurable I2C addresses.
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
- **ESP-IDF integration**: Designed for 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) | 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` |

### 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.

## Add component to your project

### Option 1: Component manager

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

### Option 2: Git Submodule

```bash
cd <your_project_root>
git submodule add https://github.com/romr/esp-idf-pt2258.git components/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 channels before changing configurations to avoid audio pops
    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);
}
```

## API Documentation

### Functions

#### `pt2258_create`
Creates and initializes a PT2258 device handle.

```c
esp_err_t pt2258_create(const pt2258_i2c_config_t *i2c_cfg, pt2258_dev_handle_t *handle);
```

**Parameters:**
- `i2c_cfg`: Pointer to I2C configuration structure
- `handle`: Pointer to store the device handle

**Returns:** ESP_OK on success, error code otherwise

#### `pt2258_delete`
Deletes a PT2258 device handle and frees resources.

```c
esp_err_t pt2258_delete(pt2258_dev_handle_t *handle);
```

**Parameters:**
- `handle`: Pointer to the device handle (will be set to NULL on success)

**Returns:** ESP_OK on success, error code otherwise

#### `pt2258_set_attenuation`
Sets the attenuation level for a specific channel or all channels.

```c
esp_err_t pt2258_set_attenuation(pt2258_dev_handle_t handle, uint8_t ch, uint8_t attenuation_db);
```

**Parameters:**
- `handle`: PT2258 device handle
- `ch`: Channel number (0 for all channels, 1-6 for individual channels)
- `attenuation_db`: Attenuation value in dB (0-79)

**Returns:** ESP_OK on success, error code otherwise

#### `pt2258_set_mute`
Sets the global mute state of the PT2258.

```c
esp_err_t pt2258_set_mute(pt2258_dev_handle_t handle, bool mute);
```

**Parameters:**
- `handle`: PT2258 device handle
- `mute`: true to mute, false to unmute

**Returns:** ESP_OK on success, error code otherwise

#### `pt2258_clear_registers`
Clears all internal registers (system reset).

```c
esp_err_t pt2258_clear_registers(pt2258_dev_handle_t handle);
```

**Parameters:**
- `handle`: PT2258 device handle

**Returns:** ESP_OK on success, error code otherwise