API guide¶
The driver's API by task, with code that compiles.
Datasheet sections this page relies on
From Microchip Technology Inc. DS20001942 L:
- 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.
| Group | Calls |
|---|---|
| Lifecycle | EnsureInitialized(), IsInitialized(), Deinitialize(), Sleep() |
| Measurement | ReadMeasurement(), ReadTemperatureMilliC(), ReadOutputMv() |
| Bring-up | ReadRawPortMv(), GetLastRawPortMv() |
| Information | GetConfig(), GetSpec(), ResolutionMilliC() |
| Free functions | Validate(), ResolveSpec(), OutputMvToMilliC(), MilliCToOutputMv(), AccuracyLimitsFor(), ToCelsius(), ToString() |
| Presets | ConfigFor(), FastPreset(), LowNoisePreset(), Mcp9701Preset(), HighTemperaturePreset() |
The constructor stores the port and the configuration (Config{} unless you pass one) and does no I/O.
EnsureInitialized() is the one way to start the sensor: its first call checks the configuration, then starts it as the
Contract page describes; once it has succeeded, later calls return Ok at once with no I/O, and after a
failure the next call starts again from the beginning. No other call starts the sensor: before EnsureInitialized()
succeeds every read returns NotInitialized. Deinitialize(), then EnsureInitialized(), is the recovery after a
fault.
Read the temperature¶
#include "mcp9700.hpp"
int read_board_temperature(MyPort& port, int32_t& milli_celsius) {
mcp9700::MCP9700<MyPort> sensor(port); // no I/O yet: an MCP9700 on a 12 bit, 3.3 V ADC
if (auto r = sensor.EnsureInitialized(); !r) { // 1. ADC up, settle, one validated reading
return static_cast<int>(r.error); // DeviceIdMismatch: wrong channel or no sensor
}
const auto t = sensor.ReadTemperatureMilliC(); // 2. discard 1, average 8, check, convert
if (!t) {
return static_cast<int>(t.error); // OutputLow, OutputHigh, Saturated, Unstable or Bus
}
milli_celsius = t.value; // 3. 25000 is 25.000 C
return 0;
}
ReadTemperatureMilliC() returns milli-degrees Celsius (25000 is 25.000 °C), after the calibration offset. The
result is an int32_t; print it with integer arithmetic, or call ToCelsius() once if a float suits you.
The whole measurement¶
ReadMeasurement() returns the temperature, the mean voltage at VOUT and the spread of the conversions in one call.
That is the call to use when you log the voltage next to the temperature or watch the noise:
bool PrintableTemperature(MyPort& port, int32_t& whole, int32_t& thousandths) {
Sensor sensor(port);
if (!sensor.EnsureInitialized().ok()) {
return false;
}
const auto m = sensor.ReadMeasurement(); // temperature, mean VOUT and spread in one call
if (!m.ok()) {
return false;
}
const int32_t mc = m.value.temperature_mc;
whole = mc / 1000; // integer maths: no float needed
thousandths = ((mc < 0) ? -mc : mc) % 1000;
return true;
}
Calibrate¶
mcp9700::Config CalibratedConfig() {
mcp9700::Config c = mcp9700::LowNoisePreset();
c.channel = 2;
c.variant = mcp9700::Variant::Mcp9700B; // the part on the board
c.offset_cal_mc = -1200; // measured +1.2 C high at +25 C on this board
return c;
}
mcp9700::Error StartCalibrated(MyPort& port) {
static Sensor sensor(port, CalibratedConfig()); // stored, no I/O
return sensor.EnsureInitialized().error; // InvalidArgument if the config is out of range
}
Compare a reading with the datasheet¶
AccuracyLimitsFor() returns the error the datasheet guarantees for your part at a temperature. The driver never
applies it to a reading; it is for your own check, such as a production test against a reference:
bool WithinDatasheetLimits(const mcp9700::Config& c, int32_t reference_mc, int32_t reading_mc) {
const auto spec = mcp9700::ResolveSpec(c);
if (!spec.ok()) {
return false;
}
const auto lim = mcp9700::AccuracyLimitsFor(spec.value, c.range, reference_mc);
const int32_t error_mc = reading_mc - reference_mc;
return lim.ok() && (error_mc >= lim.value.min_mc) && (error_mc <= lim.value.max_mc);
}
Switch the sensor off¶
With an enable pin in the port, Sleep() powers the sensor down (a few µA less) and the next EnsureInitialized()
powers it up again and waits for it. Without the pin, Sleep() returns Unsupported. Deinitialize() does the same
and is also the recovery after a fault.
If Sleep() or Deinitialize() returns Bus, the pin write failed: the sensor may still be powered, and the driver is
uninitialised either way, so a second Deinitialize() does nothing. To retry the switch-off, call EnsureInitialized()
(which switches the sensor on and checks it) and then Sleep() again; the order is covered by test_faults.
Look at the raw ADC¶
ReadRawPortMv() makes one conversion and returns the millivolts the port reported: no discard, no averaging, no
check. Use it at bring-up to see what your ADC does; GetLastRawPortMv() returns the last conversion any read made.
Handle errors¶
const char* Describe(mcp9700::Error e) {
switch (e) {
case mcp9700::Error::DeviceIdMismatch:
return "no plausible, stable output on this channel";
case mcp9700::Error::OutputLow:
return "grounded or open input, unpowered sensor, wrong channel";
case mcp9700::Error::OutputHigh:
return "shorted to the supply, or the ADC scale is wrong";
case mcp9700::Error::Saturated:
return "the ADC clipped: declare its real full scale";
case mcp9700::Error::Unstable:
return "floating or disturbed line";
default:
return mcp9700::ToString(e);
}
}
This analog driver never returns Timeout, Crc, Busy or DeviceFault: it has no bus protocol and no fault
register. Its faults are OutputLow, OutputHigh, Saturated and Unstable. A failed reading does not
uninitialise the driver, and no call retries: the next call is a new reading. Every value it returns is on the
Contract page, and the causes are in Troubleshooting.