adc.hpp

Go to the documentation of this file.

/* SPDX-License-Identifier: Apache-2.0 */
/* Copyright 2017-2019 Peter A. Bigot */
 
#ifndef NRFCXX_SENSOR_ADC_HPP
#define NRFCXX_SENSOR_ADC_HPP
#pragma once
 
#include <cstring>
#include <initializer_list>
 
#include <nrfcxx/periph.hpp>
#include <nrfcxx/lpm.hpp>
 
namespace nrfcxx {
namespace sensor {
 
namespace adc {
 
class vdd : public periph::ADCClient
{
  using super = periph::ADCClient;
 
public:
  using vdd_callback_bi = std::function<void(unsigned int vdd_mV)>;
 
  vdd (vdd_callback_bi callback = nullptr) :
    super{},
    vdd_callback_{callback},
    vdd_adc16_{}
  { }
 
  int convert_adc16_mV (unsigned int vdd_adc16) const;
 
  unsigned int vdd_mV () const
  {
    return convert_adc16_mV(vdd_adc16_);
  }
 
private:
  int configure_bi_ () override;
  void complete_bi_ () override;
 
  vdd_callback_bi vdd_callback_;
  volatile uint16_t vdd_adc16_;
};
 
class voltage_divider : public nrfcxx::periph::ADCClient
{
  using super = nrfcxx::periph::ADCClient;
 
  using packed_type = uint32_t;
  static constexpr auto AIN_WIDTH = 4U;
  static constexpr packed_type AIN_MASK = (1U << AIN_WIDTH) - 1;
 
  static constexpr auto MAX_INTERNAL = 2;
 
  enum flags_enum : flags_type {
 
    FL_RAW_EXTERNAL = (FL_SUBCLASS_BASE << 0),
 
    FL_MEASURE_RESISTANCE = (FL_SUBCLASS_BASE << 1),
  };
 
  template <typename Iterator>
  int8_t pack_values (packed_type& dest,
                      Iterator begin,
                      Iterator end)
  {
    static constexpr int8_t max_count = (8 * sizeof(dest)) / AIN_WIDTH;
    int8_t count = 0;
    unsigned int shift = 0;
 
    dest = 0;
    while ((begin != end) && (count < max_count)) {
      dest |= (AIN_MASK & *begin) << shift;
      shift += AIN_WIDTH;
      ++begin;
      ++count;
    }
    if (begin != end) {
      count = -1;
    }
    return count;
  }
 
  volatile uint16_t* raw_adc16_ ()
  {
    if (FL_RAW_EXTERNAL & flags_) {
      return raw_.ptr;
    }
    return raw_.val;
  }
 
  volatile const uint16_t* raw_adc16_ () const
  {
    if (FL_RAW_EXTERNAL & flags_) {
      return raw_.ptr;
    }
    return raw_.val;
  }
 
  void configure_instance_ (int8_t channel_count,
                            volatile uint16_t* raw);
 
public:
 
  const unsigned int r1_Ohm;
 
  const unsigned int r2_Ohm;
 
  template <typename Iterator>
  voltage_divider (unsigned int r1_Ohm,
                   unsigned int r2_Ohm,
                   Iterator ains_begin,
                   Iterator ains_end,
                   volatile uint16_t* raw = nullptr) :
    r1_Ohm{r1_Ohm},
    r2_Ohm{r2_Ohm}
  {
    configure_instance_(pack_values(channel_ains_, ains_begin, ains_end), raw);
  }
 
  voltage_divider (unsigned int r1_Ohm,
                   unsigned int r2_Ohm,
                   uint8_t ain) :
    voltage_divider{r1_Ohm, r2_Ohm, &ain, 1 + &ain}
  { }
 
  voltage_divider (unsigned int r1_Ohm,
                   unsigned int r2_Ohm,
                   std::initializer_list<uint8_t> ains,
                   volatile uint16_t* raw = nullptr) :
    voltage_divider{r1_Ohm, r2_Ohm, ains.begin(), ains.end(), raw}
  { }
 
  size_t count () const
  {
    return channel_count_;
  }
 
  int channel_ain (size_t ci) const
  {
    int rv = -1;
    if (ci < channel_count_) {
      rv = AIN_MASK & (channel_ains_ >> (ci * AIN_WIDTH));
    }
    return rv;
  }
 
  int sample_adc16 (size_t ci = 0) const
  {
    int rv = -1;
    if (ci < channel_count_) {
      rv = raw_adc16_()[ci];
    }
    return rv;
  }
 
  int sample_mV (size_t ci = 0,
                 bool truncate = false) const;
 
  int input_mV (size_t ci = 0) const;
 
  virtual int measurement_mV (uint16_t m16) const
  {
#if (NRF51 - 0)
    return (3 * peripheral::VBG_mV * m16) >> 16;
#else
    return (6 * peripheral::VBG_mV * m16) >> 16;
#endif
  }
 
  int measurement_Ohm (uint16_t m16) const
  {
    if (0 == m16) {
      return -1;
    }
    if (0 == r1_Ohm) {
      return r2_Ohm * ((uint64_t{1} << 16) - m16) / m16;
    }
    return r1_Ohm * static_cast<uint64_t>(m16) / ((1U << 16) - m16);
  }
 
  int sample_Ohm (size_t ci = 0,
                  bool filter_high_negative = false) const;
 
private:
 
  uint32_t channel_ains_ = 0;
 
  uint8_t channel_count_ = 0;
 
  uint8_t channel_idx_ = 0;
 
  uint32_t config_ = 0;
 
  union {
    volatile uint16_t* ptr;
    uint16_t volatile val[MAX_INTERNAL];
  } raw_ = {nullptr};
 
  int configure_bi_ () override;
  int nrf51_next_bi_ (size_t ci) override;
};
 
class SteinhartHart
{
public:
  constexpr SteinhartHart (float a = 1.19438315714902408e-03,
                           float b = 2.19852114398042317e-04,
                           float c = 1.72427510143621963e-07,
                           uint16_t open_adc16 = 2281,
                           uint16_t short_adc16 = 65133) :
    a{a},
    b{b},
    c{c},
    open_adc16{open_adc16},
    short_adc16{short_adc16}
  { }
 
  const float a;
 
  const float b;
 
  const float c;
 
  const uint16_t open_adc16;
 
  const uint16_t short_adc16;
 
  int temperature_cK (unsigned int therm_Ohm) const;
};
 
namespace steinhartHart {
extern const SteinhartHart adafruit372fullScale;
 
extern const SteinhartHart adafruit372hvac;
 
extern const SteinhartHart adafruit372refrigerator;
} // ns steinhartHart
 
class ntcThermistor : public voltage_divider
{
  using super = voltage_divider;
 
public:
  static constexpr int ABSOLUTE_ZERO_cCel = -27315;
 
  static constexpr int INVALID_cCel = 30000;
 
  static constexpr int SHORT_cCel = INVALID_cCel + 1;
 
  static constexpr int OPEN_cCel = - SHORT_cCel;
 
  template <typename Iterator>
  ntcThermistor(Iterator ains_begin,
                Iterator ains_end,
                volatile uint16_t*raw = nullptr,
                const SteinhartHart* coeff = &steinhartHart::adafruit372fullScale,
                unsigned int ref_Ohm = 10000) :
    super{0, ref_Ohm, ains_begin, ains_end, raw},
    steinhartHart{coeff}
  { }
 
  ntcThermistor(std::initializer_list<uint8_t> ains,
                volatile uint16_t*raw = nullptr,
                const SteinhartHart* coeff = &steinhartHart::adafruit372fullScale,
                unsigned int ref_Ohm = 10000) :
    ntcThermistor(ains.begin(), ains.end(), raw, coeff, ref_Ohm)
  { }
 
  int convert_adc16_cCel (unsigned int therm_adc16);
 
  int temperature_cCel (size_t ci = 0);
 
  unsigned int therm_adc16 (size_t ci = 0) const;
 
  unsigned int therm_Ohm (size_t ci = 0) const;
 
  const SteinhartHart* const steinhartHart;
};
 
class lpsm_wrapper : public lpm::lpsm_capable
{
  using super_lpsm = lpm::lpsm_capable;
 
  /* State transitions:
   *
   * * ENTRY_START transitions to IDLE.
   *
   * * ENTRY_CALIBRATE claims the ADC, invokes sample_setup_(), and
   *   transitions to CALIBRATE (after a setup delay if necessary).
   *
   * * CALIBRATE queues an ADC calibration and falls into
   *   EXIT_CALIBRATE.
   *
   * * EXIT_CALIBRATE loops until calibration resolved, then records
   *   state of calibration and transitions to either IDLE (invoking
   *   sample_teardown_() and releasing the ADC) or ENTRY_SAMPLE
   *   depending on the source of the calibration request.
   *
   * * ENTRY_SAMPLE if not calibrated jumps to ENTRY_CALIBRATE.
   *   Otherwise it claims the ADC, invokes sample_setup_(), and
   *   transitions to SAMPLE (after a setup delay if necessary).
   *
   * * SAMPLE queues an ADC collection and transitions to EXIT_SAMPLE.
   *
   * * EXIT_SAMPLE is blocked until the ADC completes, then it invokes
   *   sample_teardown_() and processes the sample, emitting
   *   #PF_OBSERVATION if the collection was valid.  It then release
   *   the ADC and transitions to IDLE.
   *
   * Calibration and sampling are queued ADCClient operations.
   * Failure to successfully initiate the queued operation translates
   * to a machine error.
   *
   * NOTE: The design of this machine is influenced by the inability
   * to queue multiple operations on the same client.  As a result the
   * calibrate and sample operations cannot be made to occur within
   * the same claim session.  This is a problem only when multiple
   * clients are managed with distinct LPSM wrappers, and calibration
   * may be performed with both single-ended and differential sampling
   * configurations producing different offsets, as documented in the
   * devzone posting below.
   *
   * See: https://devzone.nordicsemi.com/f/nordic-q-a/43316/nrf52832-saadc-configuration-effects-on-calibration */
  static constexpr auto MS_ENTRY_CALIBRATE = lpm::state_machine::MS_ENTRY_SAMPLE + 1;
  static constexpr auto MS_CALIBRATE = lpm::state_machine::MS_SAMPLE + 1;
  static constexpr auto MS_EXIT_CALIBRATE = lpm::state_machine::MS_EXIT_SAMPLE + 1;
 
  using flags_type = uint8_t;
 
  enum flags_enum : flags_type
  {
    FL_CALIBRATING = 0x01,
 
    FL_SAMPLING = 0x02,
 
    FL_PENDING = 0x08,
 
    FL_CALIBRATED = 0x10,
 
    FL_THEN_SAMPLE = 0x20,
  };
 
public:
  using mutex_type = periph::ADCClient::mutex_type;
 
  static constexpr auto PF_CALIBRATED = lpm::state_machine::PF_APP_BASE << 0;
 
  lpsm_wrapper (notifier_type notify,
                periph::ADCClient& client) :
    super_lpsm{notify},
    client_{client}
  { }
 
  template <typename Client = periph::ADCClient>
  Client& client () const
  {
    return reinterpret_cast<Client&>(client_);
  }
 
  int lpsm_calibrate ();
 
  int lpsm_bypass_calibration ();
 
private:
  void lpsm_reset_ () override
  {
    mutex_type mutex;
    flags_bi_ = 0;
  }
 
  int lpsm_process_ (int& delay,
                     process_flags_type& lpf) override;
 
  periph::ADCClient& client_;
  int queue_rc_ = 0;
  flags_type flags_bi_ = 0;
};
 
} // ns adc
} // ns sensor
} // ns nrfcxx
 
#endif /* NRFCXX_SENSOR_ADC_HPP */