Thermal Meter

Overview

RTL8721F provides an on-chip thermal sensor for measuring die temperature. The Rust driver ameba_hal::thermal wraps the PAC register block directly — no raw bit-masking or C FFI is involved.

Features

  • Single instance Thermal, obtained via Thermal::steal()

  • Configurable down-sample rate from DownSampRate::Dsr1 to DownSampRate::Dsr512 and ADC clock divider via AdcClkDiv::Div64 / AdcClkDiv::Div128

  • Periodic auto-sampling driven by an internal timer, with the period set via ThermalInitParams::time_period

  • High-temperature over-protect threshold, high-temperature warning threshold, and low-temperature warning threshold, each independently configurable and maskable via ThermalInt::HIGH_WARN / ThermalInt::LOW_WARN

  • Max/min recorded temperature tracking via get_max_temp / get_min_temp, resettable with clear_max_temp / clear_min_temp

  • Factory gain/offset calibration applied automatically during init on chip version A

  • Raw-to-temperature conversion via raw_to_celsius / raw_to_fahrenheit, pure math with no register access

Note

The driver does not yet expose the high/low warning interrupts as an async or ISR callback path, and get_interrupt / clear_interrupt must be polled manually.

Operating Modes

Thermal exposes a single usage pattern: periodic polling.

Polling Mode

After init, the peripheral samples continuously in the background at the configured period. The CPU reads the latest result at any time via get_temp_result, which internally spin-waits on the data-latch flag until the current sample completes or a timeout elapses, then returns the raw 19-bit value. raw_to_celsius converts it to a signed floating-point temperature.

use ameba_hal::{
    println,
    thermal::{TM_INVALID_VALUE, Thermal, ThermalInitParams, raw_to_celsius},
};
...
let thermal = unsafe { Thermal::steal() };
thermal.init(&ThermalInitParams::default());
...
let raw = thermal.get_temp_result();
if raw == TM_INVALID_VALUE {
    println!("[THERMAL] sensor not ready");
    all_pass = false;
    continue;
}

let temp_c = raw_to_celsius(raw);

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

There is no interrupt-driven or async variant yet. Applications that need periodic readings without blocking the current task should call get_temp_result from an Embassy task on a timer, as the bundled example does.

Application Examples

The Rust SDK provides one example project under examples/thermal/:

  • thermal

    Samples the on-chip sensor once per second for 5 rounds, converts each raw result to Celsius, and prints it. Fails if any reading falls outside -10-110 °C.

    Wiring: none — the sensor is on-chip.

    [THERMAL] start
    [THERMAL] Temp: 35.2 C
    ...
    [PASS] thermal: OK
    

Note

Build any example with cargo xtask build example --name thermal.

API Reference

Quick Usage

use ameba_hal::thermal::{TM_INVALID_VALUE, Thermal, ThermalInitParams, raw_to_celsius};

let thermal = unsafe { Thermal::steal() };
thermal.init(&ThermalInitParams::default());

let raw = thermal.get_temp_result();
if raw != TM_INVALID_VALUE {
    let temp_c = raw_to_celsius(raw);
}

Thermal also tracks historical extremes via get_max_temp / get_min_temp and exposes high/low warning thresholds through set_high_warn_threshold / set_low_warn_threshold.