# idfxx_adc
One-shot and continuous ADC reads with calibrated voltages for ESP32, with type-safe C++23
interfaces.
[API documentation](https://cleishm.github.io/idfxx/group__idfxx__adc.html)
## Features
- One-shot reads (`adc::input`): on-demand conversions — the battery-voltage / sensor-divider case
- Continuous sampling (`adc::sampler`): fixed-rate background (DMA) sampling of one or more pins,
delivered as parsed per-pin samples with overrun accounting
- Single-call setup: ADC unit and channel resolved from the GPIO pin
- Typed voltage readings (`quanta::electro::millivolts`) using the chip's factory calibration when
available
- Attenuation selection for the full input-range spectrum
- Dual error handling: exception-based and `result`-based (`try_*`) APIs
## Requirements
- ESP-IDF 5.5 or later
- C++23 compiler support
- Components: `idfxx_core`, `idfxx_gpio`, `quanta` (plus ESP-IDF `esp_adc`)
## Installation
### ESP-IDF Component Manager
Add to your project's `idf_component.yml`:
```yaml
dependencies:
cleishm/idfxx_adc: "^2.1.0"
```
## Usage
### Exception-based
```cpp
#include <idfxx/adc>
// One-shot: read a battery behind a 2:1 divider on demand.
idfxx::adc::input battery({.pin = idfxx::gpio_3, .divider = {2, 1}});
quanta::electro::millivolts v = battery.read_voltage(); // battery-side voltage
```
To get both the pin and source voltage from a single sample, read the pin voltage and convert it:
```cpp
quanta::electro::millivolts at_pin = battery.read_pin_voltage();
quanta::electro::millivolts at_source = battery.divider().source_voltage(at_pin);
```
```cpp
using namespace quanta::frequency_literals;
// Continuous: sample a signal at 20 kHz in the background.
idfxx::adc::sampler mic({.pins = std::vector<idfxx::gpio>{idfxx::gpio_3}, .sample_rate = 20_kHz});
mic.start();
std::array<idfxx::adc::sampler::sample, 256> buf;
while (true) {
size_t n = mic.read(buf);
for (size_t i = 0; i < n; ++i) {
quanta::electro::millivolts v = mic.to_voltage(buf[i]);
// ...
}
}
```
For a single pin, read straight into calibrated voltages:
```cpp
std::array<quanta::electro::millivolts, 256> volts;
size_t n = mic.read(volts); // reads and converts in one call
```
### Result-based
```cpp
auto battery = idfxx::adc::input::make({.pin = idfxx::gpio_3});
if (!battery) { /* handle error */ }
auto v = battery->try_read_voltage();
if (!v) { /* v.error() */ }
```
```cpp
auto mic = idfxx::adc::sampler::make({
.pins = std::vector<idfxx::gpio>{idfxx::gpio_3},
.sample_rate = quanta::frequency::hertz{20'000},
});
if (!mic) { /* handle error */ }
if (auto r = mic->try_start(); !r) { /* r.error() */ }
std::array<idfxx::adc::sampler::sample, 256> buf;
auto n = mic->try_read(buf, std::chrono::milliseconds{100});
if (!n) { /* n.error() */ }
```
## API Overview
### `idfxx::adc::input`
| Method | Description |
| ------ | ----------- |
| `input(config)` / `make(config)` | Claim the pin's ADC unit and configure the channel. |
| `read_voltage()` / `try_read_voltage()` | Calibrated voltage, scaled by the configured divider (`quanta::electro::millivolts`). |
| `read_pin_voltage()` / `try_read_pin_voltage()` | Calibrated voltage at the pin, not scaled by the divider. |
| `read_raw()` / `try_read_raw()` | Raw conversion value. |
| `calibrated()` | Whether factory calibration is active. |
`config`: `pin` (required, ADC-capable), `attenuation` (default `db_12`, full range), `divider`
(external divider ratio, default 1:1 — `read_voltage` scales by it to report the source voltage;
`read_pin_voltage` and `read_raw` are unaffected). `divider_ratio::source_voltage(pin)` converts a
pin voltage to the source voltage.
### `idfxx::adc::sampler`
| Method | Description |
| ------ | ----------- |
| `sampler(config)` / `make(config)` | Claim ADC1 and configure round-robin conversion of the pins. |
| `start()` / `try_start()` | Begin conversion; resets the overrun counter. |
| `stop()` / `try_stop()` | Stop conversion (idempotent). |
| `read(out[, timeout])` / `try_read(out[, timeout])` | Block for at least one parsed sample (`out` a span of `sample`); returns the count written. |
| `read(mv[, timeout])` / `try_read(mv[, timeout])` | Single-pin convenience: read and convert to voltages in one call (`out` a span of `quanta::electro::millivolts`). |
| `to_voltage(sample)` / `try_to_voltage(sample)` | Calibrated voltage for one sample (`quanta::electro::millivolts`). |
| `to_voltage(raw)` / `try_to_voltage(raw)` | Calibrated voltage for a raw value (single-pin samplers only). |
| `to_voltage(in, out)` / `try_to_voltage(in, out)` | Convert a batch of samples to voltages, preserving pin association. |
| `pins()` / `sample_rate()` / `running()` | Configuration and state accessors. |
| `calibrated()` | Whether factory calibration is active for every pin. |
| `overruns()` | Dropped-data events since the last start. |
`config`: `pins` (required, ADC1-capable, no duplicates), `attenuation` (default `db_12`, uniform
across pins), `sample_rate` (default 20 kHz, total across pins), `frame_samples` (default 256, read
granularity), `buffer_samples` (default 1024, internal pool capacity).
## Error Handling
- `errc::invalid_arg` — pin not connected or not ADC-capable, or a non-positive divider ratio; for
the sampler also: empty/duplicate or non-ADC1 pins, bad frame/buffer sizes, non-positive sample
rate, empty read destination, a batch `try_to_voltage` output span smaller than its input, or
`try_to_voltage` with a pin the sampler was not configured with.
- `errc::invalid_state` — sampler operation in the wrong state (e.g. `try_read` before `try_start`,
double start).
- `errc::timeout` — no sample arrived within the sampler read timeout.
- `errc::not_supported` — voltage conversion with no usable factory calibration (fall back to raw
values; check `calibrated()`).
## Important Notes
- Each `input` claims its pin's entire ADC unit; two inputs on the same unit cannot currently
coexist. This component intentionally covers only the single-input case.
- **The sampler is ADC1 only.** The digital (continuous) controller serves only ADC1 on the
supported targets; pins that map to ADC2 are rejected.
- **One-shot and continuous reads exclude each other on ADC1.** While a sampler is running, `input`
reads on ADC1 fail with a timeout — the driver serializes access to the unit. Stop the sampler
first.
- **Sampler attenuation is uniform.** The hardware applies one attenuation per ADC unit in
continuous mode, so all pins share `config.attenuation`.
- **Sample-rate range is chip-specific.** ESP32: 20 kHz – 2 MHz; most other targets (S3/C3/C6/H2):
611 Hz – 83.3 kHz. Rates outside the range fail at construction. `sample_rate` is the *total*
conversion rate — each pin samples at `sample_rate / pins.size()`.
- **Overruns drop data, not errors.** If reads don't keep up and the sampler's internal pool
overflows, the driver discards samples; `try_read` still returns valid data and `overruns()`
counts the drop events. Size `buffer_samples` and read cadence so the pool never fills.
- **The sampler expects a single reader and is not ISR-safe.** Call `read`/`try_read` from one task
only, and never from an interrupt handler.
- ADC2 is shared with Wi-Fi on most chips — prefer ADC1 pins when Wi-Fi is active.
- For battery sensing above the input range, use a resistor divider and set `config::divider` so
`read_voltage` reports the source voltage.
## License
Apache-2.0
57caa7b2aabd577aa3ac24211bda868e980767b0
idf.py add-dependency "cleishm/idfxx_adc^2.1.0"