Skip to content

Porting

Run the driver on a new MCU by writing one class: the port. It moves one millivolt value from your ADC and waits; the driver does everything else.

Datasheet sections this page relies on

From Microchip Technology Inc. DS20001942 L:

  • Absolute maximum ratings: 1.0 Electrical Characteristics, p. 3
  • Output current, impedance and load capacitance: DC Electrical Characteristics (I_OUT, Z_OUT, C_LOAD), p. 4
  • Shutdown from an I/O pin: 4.2 Shutdown Using Microcontroller I/O Pin, p. 11

All of them, with the driver API for each: Datasheet map.

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

What you implement

Method Required Contract
bool EnsureInitialized() noexcept yes Bring the ADC up (unit, channel attenuation, calibration) on the first call; true at once afterwards
bool ReadVoltageMv(uint8_t channel, uint32_t& voltage_mv) noexcept yes One conversion of channel, calibrated, in millivolts at the ADC pin; false on any failure, leaving voltage_mv untouched
void DelayUs(uint32_t us) noexcept yes, for every wait Wait at least us microseconds
bool GpioSet(CtrlPin, GpioSignal) noexcept no Power the sensor from an MCU pin; without it Sleep() returns Unsupported
void Log(LogLevel, const char* message) noexcept no Print one line; message is plain text, never a format string

ReadVoltageMv() is the standard millivolt hook of the Kokeb Labs driver contract, so one ADC port serves every analog-input driver. The driver asks for no raw counts and no reference voltage: you tell it the full scale and the resolution of your port in Config (Configuration).

The port

my_port.hpp
class MyPort : public mcp9700::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`, calibrated to millivolts.
  bool ReadVoltageMv(uint8_t channel, uint32_t& voltage_mv) noexcept {
    return platform_adc_read_mv(channel, voltage_mv);
  }

  // Wait at least `us` microseconds: power-up and sample spacing depend on it.
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

private:
  bool ready_ = false;
};

A port with every hook:

class FullPort : public mcp9700::AdcInterface<FullPort> {
public:
  bool EnsureInitialized() noexcept {
    return platform_adc_init();
  }
  bool ReadVoltageMv(uint8_t channel, uint32_t& voltage_mv) noexcept {
    return platform_adc_read_mv(channel, voltage_mv);
  }
  void DelayUs(uint32_t us) noexcept {
    platform_delay_us(us);
  }

  // Optional: the sensor's supply from an MCU pin (DS20001942L Section 4.2). ACTIVE means
  // "powered". The pin idles INACTIVE until the driver enables it.
  bool GpioSet(mcp9700::CtrlPin pin, mcp9700::GpioSignal signal) noexcept {
    if (pin != mcp9700::CtrlPin::Enable) {
      return false;
    }
    return platform_gpio_write(kSupplyGpio, signal == mcp9700::GpioSignal::ACTIVE);
  }

  // Optional: one line per failure. The driver never formats; the port does.
  void Log(mcp9700::LogLevel level, const char* message) noexcept {
    (void)level;
    platform_log(message); // plain text: never use it as a format string
  }

private:
  static constexpr int kSupplyGpio = 7;
};

What the ADC must do

Limit Value Why
Input current 100 µA at most (kMaxOutputCurrentUa) The sensor sources and sinks at most that (IOUT, p. 4)
Source impedance of the sensor 20 Ω typical (kOutputImpedanceOhm) An ADC with a large sample capacitor sees a small error after a switch
Load capacitance 1000 pF (kMaxLoadCapacitancePf) The family is characterised and production tested with that (p. 4)
Series resistor in VOUT none It adds an error with the input current; filter in the supply line instead (section 4.3)
  • Return calibrated millivolts. If the SDK has a calibration (a curve fit for the ESP32, a factory gain and offset elsewhere), apply it in the port. If it has none, fail EnsureInitialized() rather than scale by a guess: a count scaled by a guess looks like a voltage and is not one.
  • Declare the ceiling. On some MCUs the calibrated range at the attenuation you use ends below the supply (about 3.1 V at 12 dB on ESP32 parts). Put that value in Config::adc_full_scale_mv, not the supply: the clip check compares conversions with it. The ESP32 port keeps it as a constant next to the attenuation and asserts both at compile time.
  • Multiplexed ADCs. The sample capacitor holds the last channel for a moment after a switch; that is what the driver's dummy conversion is for. If you give the sensor an ADC of its own, set discard_conversions to 0.
  • Wait in DelayUs(). Power-up and sample spacing depend on it. A busy-wait is fine for the microseconds the driver asks; it never asks for more than a second at a time.

Control pins

The sensor may be powered from an MCU pin (section 4.2, p. 11), with 200 Ω in the supply line and 1 µF at the sensor (section 4.3; see Hardware). Each control pin has a defined idle level, and the port drives it there before it enables the pin's output (handbook KB-HW-018): configuring a pin as an output first and setting its level afterwards can glitch the supply.

CtrlPin Package pin Polarity Idle (INACTIVE) level Before the first read
Enable VDD, through 200 Ω ACTIVE = powered (pin high) low: sensor off Set low, then enable the output; EnsureInitialized() powers it

GpioSignal::ACTIVE always means "function asserted"; the port maps it to the electrical level. With an enable pin the driver gains Sleep(), and a failed start-up switches the sensor off again.

Ports in this repository

Port Where
ESP-IDF: adc_oneshot with curve-fitting calibration, an optional enable GPIO, esp_rom_delay_us esp32_mcp9700_port.hpp
Host: the simulated sensor and ADC host_mcp9700_port.hpp

Threads

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