Analog-to-Digital Converter (ADC)

Overview

RTL8721F provides a 16-bit, 11-channel ADC. The Rust driver ameba_hal::adc wraps the PAC register block directly — no raw bit-masking or C FFI is involved.

Features

  • 11 regular channels, AdcChannel::Ch0–Ch10, plus a dedicated dummy-cycle slot AdcChannel::DummyCycle

  • 16-bit conversion resolution, 4 MHz core clock

  • Four operating modes selected via AdcOpMode: Software Trigger, Automatic, Timer-Trigger, and Comparator-Assist

  • Configurable channel conversion list, per-channel sample period, and FIFO-full interrupt threshold via AdcInitParams

  • EFuse-calibrated raw-to-millivolt conversion through Adc::get_voltage, using a per-chip Vref trim and voltage curve read from OTP on first use

  • Oversampling engine with configurable ratio, right-shift, and staggered/regular sequencing via OsRatio / OsShift / OsMode

  • Per-channel threshold comparator via Adc::set_comp, with level or edge interrupt detection selectable through CompDetMode

  • FIFO-based sample retrieval through Adc::readable / Adc::read / Adc::read_raw, plus batch collection in Automatic mode via Adc::receive_buf

  • Single peripheral instance, accessed through the zero-sized Adc handle obtained via unsafe { Adc::steal() }

Note

The Adc driver does not implement any embedded-hal traits, its public API is entirely bespoke, and there is no async or DMA-backed transfer path.

Operating Modes

ADC supports four operating modes, selected via AdcInitParams::op_mode: Software Trigger Mode, Automatic Mode, Timer-Trigger Mode, and Comparator-Assist Mode.

Software Trigger Mode

Each conversion is started explicitly by calling Adc::sw_trig_cmd(true), then waiting for Adc::readable before popping the result and stopping the trigger with sw_trig_cmd(false). This is the default mode and suits one-shot or manually-paced sampling.

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};
...
const ADC_CH: u8 = 3;
...
let adc = unsafe { Adc::steal() };
let mut cvlist = [0u8; 16];
cvlist[0] = ADC_CH;
let params = AdcInitParams {
    op_mode: AdcOpMode::SoftwareTrigger,
    rx_threshold_level: 0,
    cvlist,
    cvlist_len: 1,
    special_ch: 0xFF,
    sample_period_us: 6,
};
adc.init(&params);
adc.set_ch_list(&[ADC_CH]);
adc.cmd(true);
...
adc.clear_fifo();
adc.sw_trig_cmd(true);
while !adc.readable() {}
adc.sw_trig_cmd(false);

let raw = adc.read().data;
// EFuse-calibrated raw -> millivolts (per-chip curve, read once by the driver).
let mv = adc.get_voltage(raw as u32);

Full example: examples/adc/src/main.rs.

Automatic Mode

Adc::auto_csw_cmd(true) starts a continuous scan across the whole channel list without further software intervention, and each channel’s result lands in the FIFO in turn. Adc::receive_buf wraps this into a simple blocking bulk read: it clears the FIFO, starts the scan, polls until the buffer is full, then stops the scan.

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};

let adc = unsafe { Adc::steal() };
let params = AdcInitParams {
    op_mode: AdcOpMode::Automatic,
    ..AdcInitParams::default()
};
adc.init(&params);
adc.cmd(true);

let mut buf = [0u32; 12];
adc.receive_buf(&mut buf);

No example under examples/adc/ exercises Automatic Mode. The calls above are real Adc API but this snippet is not sourced from an example file.

Timer-Trigger Mode

Adc::timer_trig_cmd configures one of the basic RTIMs (index 0–7) as a periodic trigger source and starts or stops it, and each timer period fires one conversion into the FIFO without CPU involvement in between.

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};
...
use ameba_hal::{
    pinmux::{self, Pin, PinFunction, Pull},
    rcc,
};
...
rcc::enable(rcc::Peripheral::LTIM0);

adc.cmd(false);
let tt_params = AdcInitParams { op_mode: AdcOpMode::TimerTrigger, ..params };
adc.init(&tt_params);
adc.set_ch_list(&[ADC_CH]);
adc.cmd(true);
adc.clear_fifo();

// Basic timer 0 fires a conversion every 100 ms.
adc.timer_trig_cmd(0, 100, true);
...
if adc.readable() {
    let raw = adc.read().data;
    let mv = adc.get_voltage(raw as u32);
    ...
}
...
adc.timer_trig_cmd(0, 100, false);

Full example: examples/adc/src/main.rs.

Comparator-Assist Mode

Adc::set_comp programs the high/low thresholds and match criterion for a channel and enables that channel’s comparator interrupt, and Adc::set_comp_mode selects whether the interrupt fires continuously while the criterion holds (level) or once per match (edge). Adc::get_comp_status reads back the current comparison result for a channel.

use ameba_hal::adc::{Adc, AdcChannel, AdcInt, CompCriteria, CompDetMode};

let adc = unsafe { Adc::steal() };
adc.set_comp_mode(CompDetMode::Edge);
adc.set_comp(AdcChannel::Ch3, 3600, 2800, CompCriteria::OutsideThlAndThh);

if adc.get_isr().contains(AdcInt::COMP_CH3) {
    adc.int_clear_pending(AdcInt::COMP_CH3);
    let status = adc.get_comp_status(AdcChannel::Ch3);
}

No example under examples/adc/ exercises Comparator-Assist Mode. The calls above are real Adc API but this snippet is not sourced from an example file.

Application Examples

The Rust SDK provides one example project at examples/adc, which exercises both Software Trigger and Timer-Trigger mode:

  • Software Trigger: samples channel 3 (PA17) five times at a 200 ms interval, converts each raw reading to millivolts via the EFuse-calibrated curve, and checks that the result falls within the 2800–3600 mV window.

  • Timer-Trigger: reconfigures the same channel for RTIM0-driven triggering at a 100 ms period and waits up to about 1 s for a sample to land in the FIFO.

Wiring: tie PA17 (ADC channel 3) to 3.3V or GND. The voltage window is 2.8–3.6V, so tying it to GND reports [FAIL].

[ADC] start
[ADC] raw: NNNN voltage: 3.30V
[ADC] raw: NNNN voltage: 3.30V
...
[PASS] ADC: voltage OK
[ADC] timer-trig raw: NNNN voltage: 3.30V
[PASS] ADC: timer-trigger OK

Note

Build the example with cargo xtask build example --name adc.

API Reference

Quick Usage

use ameba_hal::adc::{Adc, AdcInitParams, AdcOpMode};

let adc = unsafe { Adc::steal() };
let params = AdcInitParams {
    op_mode: AdcOpMode::SoftwareTrigger,
    cvlist_len: 1,
    cvlist: { let mut l = [0u8; 16]; l[0] = 3; l },
    ..AdcInitParams::default()
};
adc.init(&params);
adc.set_ch_list(&[3]);
adc.cmd(true);

adc.clear_fifo();
adc.sw_trig_cmd(true);
while !adc.readable() {}
adc.sw_trig_cmd(false);

let mv = adc.get_voltage(adc.read().data as u32);

Adc also exposes Automatic, Timer-Trigger, and Comparator-Assist modes, please see the Operating Modes section above.