Skip to content

Quickstart

Read a temperature from a thermistor on your MCU: wire a divider, write a small port class, call two driver functions.

1. Wire it

MCU Divider Notes
ADC input Node between the series resistor and the thermistor The thermistor goes to ground (low side)
3.3 V Series resistor, 10 k as a start The same rail as the ADC reference, so the reading is ratiometric
GND Thermistor Same ground as the ADC

The Hardware page says how to choose the series resistor and what to do about the ADC input.

2. Add the driver

git submodule add https://github.com/kokeb-labs-drivers/driver-ntc-thermistor.git external/driver-ntc-thermistor

3. Write the port

Two functions, one optional: bring the ADC up, and read one raw count of one channel.

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;
};

4. Read the temperature

main.cpp
#include "ntc_thermistor.hpp"
#include "ntc_thermistor_presets.hpp"

// A 10 kOhm / B 3950 thermistor low-side in a 10 kOhm divider on a 12-bit ADC,
// valid from -40 to +125 degC.
constexpr ntc_thermistor::Config kConfig{.curve = ntc_thermistor::presets::kGeneric10kB3950,
                                         .min_temperature_mc = -40'000,
                                         .max_temperature_mc = 125'000};

int read_temperature_mc(MyPort& port, int32_t& milli_celsius) {
  ntc_thermistor::NtcThermistor<MyPort> sensor(port, kConfig); // no I/O yet

  if (auto r = sensor.EnsureInitialized(); !r) { // 1. check the config, bring the ADC up
    return static_cast<int>(r.error);            //    InvalidArgument or Bus
  }
  const auto t = sensor.Read(); // 2. sample, divider to ohms, curve to temperature
  if (!t) {
    return static_cast<int>(t.error); //    OpenCircuit, ShortCircuit, BelowRange, ...
  }
  milli_celsius = t.value.temperature_mc; // 3. milli-degrees Celsius;
                                          // t.value.uncertainty_mc bounds it
  return 0;
}
  1. Config has no default part: you name one. The preset is a 10 kOhm, B 3950 thermistor, the common class sold as probes and beads (typical values, not a datasheet claim). Read the datasheet of yours and replace it: see Presets.
  2. A beta curve needs the range the part is rated for (min_temperature_mc, max_temperature_mc): the equation extrapolates, so the driver will not guess one. A table carries its own range.
  3. EnsureInitialized() checks the configuration (no I/O), brings the ADC up and switches the divider off. It is the only call that starts anything.
  4. Read() takes sample_count conversions, averages them, finds the resistance and the temperature, and returns a Reading: temperature_mc, resistance_ohm, code and uncertainty_mc.

An error means something specific: a cut wire is OpenCircuit, a short is ShortCircuit. The table is in Troubleshooting.

Next: API guide.