MCP9700 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, the variant table, configuration, presets and conversions. More...

Classes

struct  mcp9700::Result< T >
 The value of a call, or why there is none. More...
 
struct  mcp9700::Result< void >
 The result of a call that returns no value. More...
 
struct  mcp9700::CustomSpec
 What the user declares for Variant::Custom. Every field must be set (an all-zero declaration fails Validate()); every field must stay zero for a named variant. More...
 
struct  mcp9700::Config
 Everything EnsureInitialized() uses. Config{} is an MCP9700 on a 12 bit, 3.3 V ADC. More...
 
struct  mcp9700::AccuracyBand
 One accuracy limit of the datasheet: the error band guaranteed over a temperature span. More...
 
struct  mcp9700::VariantSpec
 One row of the variant table: the only place a coefficient, range, supply, accuracy band or package list lives. The code never branches on a variant name. More...
 
struct  mcp9700::AccuracyLimits
 The guaranteed error limits at one temperature, milli-C. More...
 
struct  mcp9700::Measurement
 The temperature and the voltage behind it, from one validated reading. More...
 

Enumerations

enum class  mcp9700::Error : uint8_t {
  mcp9700::Error::Ok = 0 , mcp9700::Error::NotInitialized = 1 , mcp9700::Error::InvalidArgument = 2 , mcp9700::Error::Bus = 3 ,
  mcp9700::Error::Timeout = 4 , mcp9700::Error::DeviceIdMismatch = 5 , mcp9700::Error::Crc = 6 , mcp9700::Error::Busy = 7 ,
  mcp9700::Error::DeviceFault = 8 , mcp9700::Error::Unsupported = 9 , mcp9700::Error::OutputLow = 16 , mcp9700::Error::OutputHigh = 17 ,
  mcp9700::Error::Saturated = 18 , mcp9700::Error::Unstable = 19
}
 Why a call failed. Values 0 to 9 are the shared base set; chip-specific values start at 16. More...
 
enum class  mcp9700::Variant : uint8_t {
  mcp9700::Variant::Mcp9700 = 0 , mcp9700::Variant::Mcp9700A = 1 , mcp9700::Variant::Mcp9700B = 2 , mcp9700::Variant::Mcp9701 = 3 ,
  mcp9700::Variant::Mcp9701A = 4 , mcp9700::Variant::Custom = 5
}
 Which part of the family is wired up: one of the five datasheet devices, or Custom. More...
 
enum class  mcp9700::TemperatureClass : uint8_t { mcp9700::TemperatureClass::Extended = 0 , mcp9700::TemperatureClass::High = 1 }
 The temperature class of the part: the upper end of its specified range. More...
 
enum class  mcp9700::LogLevel : uint8_t { mcp9700::LogLevel::Error = 0 , mcp9700::LogLevel::Warning , mcp9700::LogLevel::Info , mcp9700::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 

Functions

constexpr const char * mcp9700::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr Error mcp9700::Validate (const Config &config) noexcept
 Check a configuration without touching the hardware.
 
constexpr Result< VariantSpec > mcp9700::ResolveSpec (const Config &config) noexcept
 The effective variant row of a configuration: a table row, or the row built from the Custom declaration. No I/O.
 
constexpr int32_t mcp9700::OutputMvToMilliC (const VariantSpec &spec, uint32_t output_mv) noexcept
 The temperature of an output voltage, from the row's V0 and TC; rounded half away from zero. No window check, no calibration.
 
constexpr uint32_t mcp9700::MilliCToOutputMv (const VariantSpec &spec, int32_t temperature_mc) noexcept
 The output voltage of a temperature: the inverse of OutputMvToMilliC(), rounded to the nearest millivolt.
 
constexpr Result< AccuracyLimits > mcp9700::AccuracyLimitsFor (const VariantSpec &spec, TemperatureClass range, int32_t temperature_mc) noexcept
 The error limits the datasheet guarantees at a temperature (first band that contains it, narrowest first). With High only the High-option rows (-40 to +150 C) apply over the whole range: the datasheet does not say that an H part also meets the tighter Extended rows. For a named variant they hold at its tested supply; the driver never applies them to a reading.
 
constexpr float mcp9700::ToCelsius (int32_t milli_c) noexcept
 A temperature as float degrees Celsius, for printing and for callers that want it. The only floating-point in the driver.
 
constexpr Config mcp9700::ConfigFor (Variant variant) noexcept
 The configuration of a named part: Config{} with that variant.
 
constexpr Config mcp9700::FastPreset () noexcept
 One conversion per reading: lowest latency, no noise rejection.
 
constexpr Config mcp9700::LowNoisePreset () noexcept
 32 conversions 200 us apart: averages ADC noise and mains pickup.
 
constexpr Config mcp9700::Mcp9701Preset () noexcept
 The MCP9701 transfer function and range.
 
constexpr Config mcp9700::HighTemperaturePreset () noexcept
 An MCP9700 with the High temperature option (to +150 C).
 
constexpr const char * mcp9700::GetDriverVersion () noexcept
 
constexpr uint32_t mcp9700::GetDriverVersionMajor () noexcept
 
constexpr uint32_t mcp9700::GetDriverVersionMinor () noexcept
 
constexpr uint32_t mcp9700::GetDriverVersionPatch () noexcept
 

Variables

constexpr uint16_t mcp9700::kMaxSamples = 64U
 Largest number of conversions one reading averages.
 
constexpr uint32_t mcp9700::kMaxSampleIntervalUs = 100'000U
 Largest wait between two conversions, microseconds.
 
constexpr uint8_t mcp9700::kMaxDiscard = 4U
 Largest number of dummy conversions before a reading.
 
constexpr uint32_t mcp9700::kMaxPowerOnSettleUs = 1'000'000U
 Largest power-on wait, microseconds.
 
constexpr uint64_t mcp9700::kMaxAveragingWindowUs = 1'000'000ULL
 Longest span of one reading, (discard + samples - 1) x interval, microseconds: below the 1.3 s thermal response (t_RES, p.4), so an average is never staler than the sensor (design decision).
 
constexpr uint32_t mcp9700::kMaxSpreadLimitMv = 1000U
 Largest max_spread_mv.
 
constexpr int32_t mcp9700::kMaxOffsetCalMc = 20'000
 Largest absolute offset_cal_mc, milli-degrees.
 
constexpr int32_t mcp9700::kMaxRangeMarginMc = 20'000
 Largest range_margin_mc, milli-degrees.
 
constexpr uint32_t mcp9700::kMinAdcFullScaleMv = 100U
 Smallest declarable ADC full scale, millivolts.
 
constexpr uint32_t mcp9700::kMaxAdcFullScaleMv = 10'000U
 Largest declarable ADC full scale, millivolts.
 
constexpr uint8_t mcp9700::kMinAdcResolutionBits = 8U
 Smallest declarable ADC resolution, bits.
 
constexpr uint8_t mcp9700::kMaxAdcResolutionBits = 16U
 Largest declarable ADC resolution, bits.
 
constexpr uint32_t mcp9700::kCustomMinTcUvPerC = 1000U
 Custom: smallest slope, microvolts per degree.
 
constexpr uint32_t mcp9700::kCustomMaxTcUvPerC = 100'000U
 Custom: largest slope, microvolts per degree.
 
constexpr uint32_t mcp9700::kCustomMaxV0Mv = 5000U
 Custom: largest output at 0 C, millivolts.
 
constexpr int32_t mcp9700::kCustomMaxTemperatureMc = 200'000
 Custom: largest absolute temperature limit, milli-degrees.
 
constexpr uint32_t mcp9700::kCustomMaxOutputMv = 20'000U
 Custom: largest output voltage anywhere in the declared range, millivolts.
 
constexpr int32_t mcp9700::kCustomMaxAccuracyMc = 20'000
 Custom: largest absolute accuracy limit, milli-degrees.
 
constexpr uint8_t mcp9700::kPackageSot23 = 1U
 Package bit: SOT-23-3 (/TT).
 
constexpr uint8_t mcp9700::kPackageSc70 = 2U
 Package bit: SC70-5 (/LT).
 
constexpr uint8_t mcp9700::kPackageTo92 = 4U
 Package bit: TO-92-3 (/TO).
 
constexpr uint8_t mcp9700::kPackagesAll
 Every package: SOT-23-3, SC70-5 and TO-92-3.
 
constexpr uint8_t mcp9700::kPackagesNoTo92 = static_cast<uint8_t>(kPackageSot23 + kPackageSc70)
 The packages without TO-92-3 (the MCP9700B, and the High option of every part).
 
constexpr std::size_t mcp9700::kMaxBands = 4U
 Most accuracy bands one row holds.
 
constexpr std::array< VariantSpec, 5 > mcp9700::kVariantTable
 The five datasheet devices (DS20001942L), indexed by Variant. Every value is cited in docs/hardware.md: coefficients p.3 and p.4, supply p.3, ranges p.4, accuracy p.3, packages p.12 and p.23.
 

Detailed Description

Errors, results, the variant table, configuration, presets and conversions.

Enumeration Type Documentation

◆ Error

enum class mcp9700::Error : uint8_t
strong

Why a call failed. Values 0 to 9 are the shared base set; chip-specific values start at 16.

An analog sensor has no bus protocol and no fault register: Timeout, Crc, Busy and DeviceFault are never returned; its faults are OutputLow, OutputHigh, Saturated and Unstable.

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize()/Sleep() ran since.

InvalidArgument 

Validate() failed (at EnsureInitialized()); nothing was sent.

Bus 

The port's ADC bring-up, a conversion or a pin write failed.

Timeout 

Not returned by this driver.

DeviceIdMismatch 

Start-up found no plausible, stable output on the channel.

Crc 

Not returned by this driver.

Busy 

Not returned by this driver.

DeviceFault 

Not returned by this driver.

Unsupported 

Sleep() needs the optional GpioSet() hook and the port has none.

OutputLow 

The output is below the specified range minus the margin.

OutputHigh 

The output is above the specified range plus the margin.

Saturated 

A conversion is within one LSB of the declared full scale, or above it.

Unstable 

The conversions of one reading differ by more than max_spread_mv.

◆ LogLevel

enum class mcp9700::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected the driver continued from.

Info 

Lifecycle events.

Debug 

Detail for bring-up.

◆ TemperatureClass

enum class mcp9700::TemperatureClass : uint8_t
strong

The temperature class of the part: the upper end of its specified range.

Enumerator
Extended 

-40 (MCP9701: -10) to +125 C, every part.

High 

-40 to +150 C: ordering code H, MCP9700 and MCP9700B in SOT-23-3 and SC70-5 only.

◆ Variant

enum class mcp9700::Variant : uint8_t
strong

Which part of the family is wired up: one of the five datasheet devices, or Custom.

The parts cannot be told apart at run time (they differ in accuracy grade, not in transfer function, except the MCP9701 family), so this is a declaration by the user, never detected.

Enumerator
Mcp9700 

500 mV at 0 C, 10.0 mV/C, -40 to +125 C (High: +150 C), accuracy +-4 C.

Mcp9700A 

As the MCP9700 with the +-2 C grade (0 to +70 C).

Mcp9700B 

As the MCP9700 with the +-1 C grade (+20 to +70 C); High option to +150 C.

Mcp9701 

400 mV at 0 C, 19.5 mV/C, -10 to +125 C, accuracy +-4 C.

Mcp9701A 

As the MCP9701 with the +-2 C grade (0 to +70 C).

Custom 

Another first-order linear sensor, fully declared in Config::custom.

Function Documentation

◆ AccuracyLimitsFor()

constexpr Result< AccuracyLimits > mcp9700::AccuracyLimitsFor ( const VariantSpec &  spec,
TemperatureClass  range,
int32_t  temperature_mc 
)
constexprnoexcept

The error limits the datasheet guarantees at a temperature (first band that contains it, narrowest first). With High only the High-option rows (-40 to +150 C) apply over the whole range: the datasheet does not say that an H part also meets the tighter Extended rows. For a named variant they hold at its tested supply; the driver never applies them to a reading.

Parameters
specThe variant row.
rangeThe temperature class.
temperature_mcTemperature in milli-degrees Celsius.
Returns
The limits, or InvalidArgument outside the specified range (or High on a row without that class).

◆ ConfigFor()

constexpr Config mcp9700::ConfigFor ( Variant  variant)
constexprnoexcept

The configuration of a named part: Config{} with that variant.

Parameters
variantOne of the five named variants (and Custom, which still needs its declaration).
Returns
The configuration.

◆ FastPreset()

constexpr Config mcp9700::FastPreset ( )
constexprnoexcept

One conversion per reading: lowest latency, no noise rejection.

Returns
The preset (an MCP9700).

◆ GetDriverVersion()

constexpr const char * mcp9700::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0". No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t mcp9700::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t mcp9700::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t mcp9700::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ HighTemperaturePreset()

constexpr Config mcp9700::HighTemperaturePreset ( )
constexprnoexcept

An MCP9700 with the High temperature option (to +150 C).

Returns
The preset.

◆ LowNoisePreset()

constexpr Config mcp9700::LowNoisePreset ( )
constexprnoexcept

32 conversions 200 us apart: averages ADC noise and mains pickup.

Returns
The preset (an MCP9700).

◆ Mcp9701Preset()

constexpr Config mcp9700::Mcp9701Preset ( )
constexprnoexcept

The MCP9701 transfer function and range.

Returns
The preset.

◆ MilliCToOutputMv()

constexpr uint32_t mcp9700::MilliCToOutputMv ( const VariantSpec &  spec,
int32_t  temperature_mc 
)
constexprnoexcept

The output voltage of a temperature: the inverse of OutputMvToMilliC(), rounded to the nearest millivolt.

Parameters
specThe variant row.
temperature_mcTemperature in milli-degrees Celsius.
Returns
Millivolts; 0 for a temperature whose output would be negative.

◆ OutputMvToMilliC()

constexpr int32_t mcp9700::OutputMvToMilliC ( const VariantSpec &  spec,
uint32_t  output_mv 
)
constexprnoexcept

The temperature of an output voltage, from the row's V0 and TC; rounded half away from zero. No window check, no calibration.

Parameters
specThe variant row.
output_mvOutput voltage in millivolts; values above 65535 are treated as 65535.
Returns
Milli-degrees Celsius.

◆ ResolveSpec()

constexpr Result< VariantSpec > mcp9700::ResolveSpec ( const Config &  config)
constexprnoexcept

The effective variant row of a configuration: a table row, or the row built from the Custom declaration. No I/O.

Parameters
configThe configuration.
Returns
The row, or InvalidArgument when Validate(config) fails.

◆ ToCelsius()

constexpr float mcp9700::ToCelsius ( int32_t  milli_c)
constexprnoexcept

A temperature as float degrees Celsius, for printing and for callers that want it. The only floating-point in the driver.

Parameters
milli_cMilli-degrees Celsius.
Returns
Degrees Celsius.

◆ ToString()

constexpr const char * mcp9700::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error mcp9700::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the hardware.

Parameters
configThe configuration.
Returns
Error::Ok or Error::InvalidArgument: a variant or range that is no enumerator, a named variant with a non-zero custom field, an incomplete or inconsistent Custom declaration, range = High where the part has none, or any field outside its documented range.

Variable Documentation

◆ kPackagesAll

constexpr uint8_t mcp9700::kPackagesAll
inlineconstexpr
Initial value:
=
static_cast<uint8_t>(kPackageSot23 + kPackageSc70 + kPackageTo92)
constexpr uint8_t kPackageSc70
Package bit: SC70-5 (/LT).
Definition mcp9700_types.hpp:307
constexpr uint8_t kPackageTo92
Package bit: TO-92-3 (/TO).
Definition mcp9700_types.hpp:309
constexpr uint8_t kPackageSot23
Package bit: SOT-23-3 (/TT).
Definition mcp9700_types.hpp:305

Every package: SOT-23-3, SC70-5 and TO-92-3.