Skip to content

Porting

Run the driver on a new MCU by writing one class: the port.

The driver calls hooks on a class you derive from ntc_thermistor::AdcInterface<Self> (in inc/ntc_thermistor_adc_interface.hpp). The base declares no hook; the driver template is constrained by the ntc_thermistor::AdcPort concept, so a missing or misdeclared hook is a compile error with a message that names it.

What you implement

Method Required Contract
bool EnsureInitialized() noexcept yes Bring the ADC up on the first call; true at once afterwards
bool ReadRaw(uint8_t channel, uint32_t& code) noexcept yes One conversion of channel: the raw count, 0 to 2^adc_bits - 1; no averaging, no volts; false on any failure
void DelayUs(uint32_t us) noexcept only if the configuration waits Wait at least us microseconds (sample_delay_us, settle_us)
bool SetBias(bool on) noexcept no Power the divider only while sampling; false when the pin could not be driven

Optional hooks are found by name at compile time and must have exactly these signatures; a hook with the right name and a wrong signature (a narrowed parameter, a missing noexcept, a void return) does not compile. The driver refuses at EnsureInitialized() a configuration that waits for something the port cannot do: a sample_delay_us or settle_us without DelayUs(), or a settle_us without SetBias().

The port

my_port.hpp
class MyPort : public ntc_thermistor::AdcInterface<MyPort> {
public:
  // Bring the ADC up once; later calls return true at once.
  bool EnsureInitialized() noexcept {
    if (!ready_) {
      ready_ = platform_adc_init();
    }
    return ready_;
  }

  // One conversion of `channel`: the raw count, as many bits as
  // Config::adc_bits says. No averaging.
  bool ReadRaw(uint8_t channel, uint32_t& code) noexcept {
    return platform_adc_read_raw(channel, code);
  }

  // Optional: wait at least `us` microseconds (sample_delay_us, settle_us).
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

A port with every hook, powering the divider from a GPIO only while it is read (which also removes the self-heating between readings):

// A port with both optional hooks: the divider is powered from a GPIO only
// while sampling.
class FullPort : public ntc_thermistor::AdcInterface<FullPort> {
public:
  bool EnsureInitialized() noexcept {
    return platform_adc_init();
  }
  bool ReadRaw(uint8_t channel, uint32_t& code) noexcept {
    return platform_adc_read_raw(channel, code);
  }
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }
  // true when the pin was driven; the driver treats false as Bus and still
  // switches the divider off.
  bool SetBias(bool on) noexcept {
    platform_gpio_write(kBiasPin, on);
    return true;
  }

private:
  static constexpr int kBiasPin = 4;
};

Bias

When the port has SetBias(), every Read() runs this order: on, settle, samples, off, convert. The divider is switched off on every path, including a failed switch-on, a failed sample, an out-of-scale code and Unstable. EnsureInitialized() also switches it off once, so the first reading starts from a known state. A failed switch-off after a good read is Bus: a divider left on is a fault. There are no retries.

The pin's idle level is "off": set it before the output is enabled (handbook KB-HW-018), or the divider glitches on at start-up. A port for a board where the divider is always powered either leaves SetBias() out (then settle_us must be 0) or provides it as a successful no-op, as the ESP32 example does when no GPIO is set: a SetBias() that returns false is a Bus error at EnsureInitialized().

Codes and millivolts

Return the raw count. If your SDK gives only calibrated millivolts, map them back to a code of adc_bits bits over the full scale and declare that full scale (see Reference, range and supplies):

// A port that only has calibrated millivolts: map them back to a code of
// `adc_bits` bits.
bool platform_adc_read_mv(uint8_t channel, uint32_t& millivolts) noexcept;

class MillivoltPort : public ntc_thermistor::AdcInterface<MillivoltPort> {
public:
  bool EnsureInitialized() noexcept {
    return true;
  }
  bool ReadRaw(uint8_t channel, uint32_t& code) noexcept {
    uint32_t mv = 0;
    if (!platform_adc_read_mv(channel, mv)) {
      return false;
    }
    code = (mv * 4096U) / 3300U; // 12 bits over the 3.3 V full scale: loses under one code
    code = (code > 4095U) ? 4095U : code;
    return true;
  }
};

The ESP32 example, esp32_ntc_thermistor_port.hpp, uses the one-shot ADC and an optional GPIO.

Describing your part and your hardware

Porting also covers the documentation of a board: Hardware has the recipe for adapting hardware.yml and the chip card to your thermistor, and Presets how to declare the part as data.

Threads

The driver is not thread-safe. Give each driver object one owner task, or guard every call with one mutex.