ads7952.ipp

Go to the documentation of this file.

 
#pragma once
 
namespace ads7952 {
 
// =============================================================================
// Construction
// =============================================================================
 
template <typename SpiType>
ADS7952<SpiType>::ADS7952(SpiType &spi, float vref, float va, Range initial_range) noexcept
    : spi_(spi),
      vref_((std::max)(ADS7952_CFG::MIN_VREF, (std::min)(vref, ADS7952_CFG::MAX_VREF))),
      va_((std::max)(ADS7952_CFG::MIN_VA, (std::min)(va, ADS7952_CFG::MAX_VA))),
      two_vref_(2.0f * vref_),
  active_vref_((initial_range == Range::TwoVref) ? two_vref_ : vref_),
  range_(initial_range) {}
 
// =============================================================================
// Runtime Calibration
// =============================================================================
 
template <typename SpiType>
void ADS7952<SpiType>::SetVref(float vref) noexcept {
  vref_ = (std::max)(ADS7952_CFG::MIN_VREF, (std::min)(vref, ADS7952_CFG::MAX_VREF));
  two_vref_ = 2.0f * vref_;
  // Update active_vref_ based on current range setting
  active_vref_ = (range_ == Range::TwoVref) ? two_vref_ : vref_;
}
 
template <typename SpiType>
void ADS7952<SpiType>::SetVA(float va) noexcept {
  va_ = (std::max)(ADS7952_CFG::MIN_VA, (std::min)(va, ADS7952_CFG::MAX_VA));
}
 
// =============================================================================
// Initialization
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::EnsureInitialized(bool force) noexcept {
  if (initialized_ && !force) {
    return true;
  }
  initialized_ = false;
  return Initialize();
}
 
template <typename SpiType>
bool ADS7952<SpiType>::Initialize() noexcept {
  // Datasheet: first conversion after power-up is invalid — discard it
  if (!spiTransfer16(reg::Mode::CONTINUE)) {
    return false;
  }
 
  // Program Auto-1 with default channel mask
  if (!ProgramAuto1Channels(auto1_mask_)) {
    return false;
  }
 
  // Program Auto-2 with default last channel
  if (!ProgramAuto2LastChannel(auto2_last_ch_)) {
    return false;
  }
 
  // Enter Auto-1 mode as default operating mode
  if (!EnterAuto1Mode(true)) {
    return false;
  }
 
  initialized_ = true;
  return true;
}
 
// =============================================================================
// Channel Reading
// =============================================================================
 
template <typename SpiType>
ReadResult ADS7952<SpiType>::ReadChannel(uint8_t channel) noexcept {
  ReadResult result{};
 
  if (!initialized_) {
    result.error = Error::NotInitialized;
    return result;
  }
  if (channel >= reg::NUM_CHANNELS) {
    result.error = Error::InvalidChannel;
    return result;
  }
 
  const uint16_t ctrl = commonControlBits();
 
  // Frame N: MANUAL mode with the target channel. SLAS605C Figure 51: the
  // command written in frame N is parsed on the rising edge of CS ending
  // frame N, the MUX switches on the 2nd SCLK of frame N+1, the input is
  // acquired through frame N+1 and sampled on the CS falling edge that
  // opens frame N+2 — so the conversion for this channel is clocked out in
  // frame N+2, not N+1. Frame N+1 still carries the channel selected two
  // frames ago. Rather than count frames, clock CONTINUE until the 4-bit
  // channel address in DO15:12 is the one requested (the Airseal/Moonshine
  // port's ProcessFrame contract); anything else is attributed to the wrong
  // tap.
  uint16_t cmd = reg::Mode::MANUAL | reg::PROGRAM_RETAIN
               | reg::ChannelSelect(channel) | ctrl;
  result.channel = channel;
  if (!spiTransfer16(cmd)) {
    result.error = Error::SpiError;
    return result;
  }
  mode_ = Mode::Manual;
  manual_channel_ = channel;
 
  const uint16_t cont = reg::Mode::CONTINUE | ctrl;
  for (uint8_t i = 0; i < ADS7952_CFG::MANUAL_READ_MAX_FRAMES; ++i) {
    uint16_t resp = 0;
    if (!spiTransfer16(cont, &resp)) {
      result.error = Error::SpiError;
      return result;
    }
    const uint8_t  ch   = reg::Response::GetChannel(resp);
    if (ch == channel) {
      result.channel = ch;
      result.count   = reg::Response::GetData(resp);
      result.voltage = CountToVoltage(result.count);
      result.error   = Error::Ok;
      return result;
    }
  }
 
  result.channel = channel;
  result.error   = Error::Timeout;
  return result;
}
 
template <typename SpiType>
ChannelReadings ADS7952<SpiType>::ReadAllChannels() noexcept {
  ChannelReadings result{};
 
  if (!initialized_) {
    result.error = Error::NotInitialized;
    return result;
  }
 
  const uint16_t ctrl = commonControlBits();
  const uint16_t target_mask = auto1_mask_ & 0x0FFF;
  const uint8_t  num_enabled = popcount16(target_mask);
 
  if (num_enabled == 0) {
    result.error = Error::Ok;
    return result;
  }
 
  // Enter Auto-1 with the channel counter reset. Table 2: in Auto-1 the
  // DI11 programming bit gates DI10..DI00 as a block, so RESET_COUNTER
  // (DI10) is ignored unless DI11 = PROGRAM_ENABLE — the earlier
  // PROGRAM_RETAIN | RESET_COUNTER frame never reset the sequence. The
  // range / power / GPIO bits in `ctrl` are what the device already runs
  // with, so re-programming them here is a no-op. Response from this frame
  // is stale — discard.
  uint16_t cmd = reg::Mode::AUTO_1 | reg::PROGRAM_ENABLE
               | reg::RESET_COUNTER | ctrl;
  if (!spiTransfer16(cmd)) {
    result.error = Error::SpiError;
    return result;
  }
  mode_ = Mode::Auto1;
 
  // Read until all programmed channels are received (with safety margin).
  const uint16_t cont = reg::Mode::CONTINUE | ctrl;
  const uint8_t  max_frames =
      num_enabled + ADS7952_CFG::READ_ALL_MAX_EXTRA_FRAMES;
 
  for (uint8_t i = 0; i < max_frames; ++i) {
    uint16_t resp = 0;
    if (!spiTransfer16(cont, &resp)) {
      result.error = Error::SpiError;
      return result;
    }
    uint8_t  ch   = reg::Response::GetChannel(resp);
    uint16_t data = reg::Response::GetData(resp);
 
    if (ch < ChannelReadings::MAX_CHANNELS && (target_mask & (1U << ch))) {
      result.count[ch]   = data;
      result.voltage[ch] = CountToVoltage(data);
      result.valid_mask |= static_cast<uint16_t>(1U << ch);
    }
 
    if (result.valid_mask == target_mask) {
      result.error = Error::Ok;
      return result;
    }
  }
 
  // Not all channels arrived within the allowed frame budget.
  result.error = Error::Timeout;
  return result;
}
 
// =============================================================================
// Voltage Conversion
// =============================================================================
 
template <typename SpiType>
float ADS7952<SpiType>::CountToVoltage(uint16_t count) const noexcept {
  return (static_cast<float>(count) * active_vref_)
       / static_cast<float>(reg::MAX_COUNT);
}
 
template <typename SpiType>
uint16_t ADS7952<SpiType>::VoltageToCount(float voltage) const noexcept {
  if (voltage <= 0.0f) return 0;
  float raw = (voltage / active_vref_) * static_cast<float>(reg::MAX_COUNT);
  if (raw > static_cast<float>(reg::MAX_COUNT)) return reg::MAX_COUNT;
  return static_cast<uint16_t>(raw);
}
 
// =============================================================================
// Mode Control
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::EnterManualMode(uint8_t channel) noexcept {
  if (channel >= reg::NUM_CHANNELS) return false;
 
  uint16_t cmd = reg::Mode::MANUAL | reg::PROGRAM_ENABLE
               | reg::ChannelSelect(channel) | commonControlBits();
  if (!spiTransfer16(cmd)) {
    return false;
  }
  mode_ = Mode::Manual;
  manual_channel_ = channel;
  return true;
}
 
template <typename SpiType>
bool ADS7952<SpiType>::EnterAuto1Mode(bool reset_counter) noexcept {
  uint16_t cmd = reg::Mode::AUTO_1 | reg::PROGRAM_ENABLE
               | (reset_counter ? reg::RESET_COUNTER : reg::NO_RESET_COUNTER)
               | commonControlBits();
  if (!spiTransfer16(cmd)) {
    return false;
  }
  mode_ = Mode::Auto1;
  return true;
}
 
template <typename SpiType>
bool ADS7952<SpiType>::EnterAuto2Mode(bool reset_counter) noexcept {
  uint16_t cmd = reg::Mode::AUTO_2 | reg::PROGRAM_ENABLE
               | (reset_counter ? reg::RESET_COUNTER : reg::NO_RESET_COUNTER)
               | commonControlBits();
  if (!spiTransfer16(cmd)) {
    return false;
  }
  mode_ = Mode::Auto2;
  return true;
}
 
// =============================================================================
// Programming — Auto-1 Channel Mask
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::ProgramAuto1Channels(uint16_t channel_mask) noexcept {
  // Frame 1: Enter Auto-1 programming mode
  if (!spiTransfer16(reg::Mode::AUTO_1_PROG)) {
    return false;
  }
 
  // Frame 2: Channel enable mask in bits [11:0]
  // (bits [15:12] are "don't care" per datasheet Table 3)
  if (!spiTransfer16(channel_mask & 0x0FFF)) {
    return false;
  }
 
  auto1_mask_ = channel_mask & 0x0FFF;
  return true;
}
 
// =============================================================================
// Programming — Auto-2 Last Channel
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::ProgramAuto2LastChannel(uint8_t last_channel) noexcept {
  if (last_channel >= reg::NUM_CHANNELS) return false;
 
  // Single frame: mode + last channel address in bits [9:6]
  if (!spiTransfer16(reg::Mode::AUTO_2_PROG | reg::Auto2LastChannel(last_channel))) {
    return false;
  }
 
  auto2_last_ch_ = last_channel;
  return true;
}
 
// =============================================================================
// Programming — GPIO Configuration
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::ProgramGPIO(const GPIOConfig &config) noexcept {
  uint16_t frame = reg::Mode::GPIO_PROG;
 
  // Reset control (bit 9)
  if (config.reset_all_registers) {
    frame |= reg::GPIOProg::RESET_ALL_REGS;
  }
 
  // GPIO3 function (bit 8)
  if (config.gpio3_as_powerdown_input) {
    frame |= reg::GPIOProg::GPIO3_PWRDOWN_IN;
  }
 
  // GPIO2 function (bit 7)
  if (config.gpio2_as_range_input) {
    frame |= reg::GPIOProg::GPIO2_RANGE_IN;
  }
 
  // GPIO0/1 alarm mode (bits [6:4])
  switch (config.alarm_mode) {
    case GPIO01AlarmMode::GPIO:
      break;
    case GPIO01AlarmMode::GPIO0_HighAndLowAlarm:
      frame |= reg::GPIOProg::GPIO0_HI_LO_ALARM;
      break;
    case GPIO01AlarmMode::GPIO0_HighAlarm:
      frame |= reg::GPIOProg::GPIO0_HI_ALARM;
      break;
    case GPIO01AlarmMode::GPIO1_LowAlarm:
      frame |= reg::GPIOProg::GPIO1_LO_ALARM;
      break;
    case GPIO01AlarmMode::GPIO1_LowAlarm_GPIO0_HighAlarm:
      frame |= reg::GPIOProg::GPIO1_LO_GPIO0_HI_ALARM;
      break;
  }
 
  // Direction mask (bits [3:0])
  frame |= static_cast<uint16_t>(config.direction_mask & 0x0F);
 
  return spiTransfer16(frame);
}
 
// =============================================================================
// Programming — Alarm Thresholds
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::ProgramAlarm(uint8_t channel, AlarmBound bound,
                                    uint16_t threshold_12bit) noexcept {
  if (channel >= reg::NUM_CHANNELS) return false;
 
  // Determine alarm group (3 groups × 4 channels)
  const uint8_t group      = channel / reg::CHANNELS_PER_ALARM_GROUP;
  const uint8_t ch_in_grp  = channel % reg::CHANNELS_PER_ALARM_GROUP;
 
  // Select the correct alarm group mode code
  uint16_t group_mode;
  switch (group) {
    case 0: group_mode = reg::Mode::ALARM_GROUP_0; break;
    case 1: group_mode = reg::Mode::ALARM_GROUP_1; break;
    case 2: group_mode = reg::Mode::ALARM_GROUP_2; break;
    default: return false;
  }
 
  // Frame 1: Enter alarm group programming mode
  if (!spiTransfer16(group_mode)) {
    return false;
  }
 
  // Frame 2: Alarm data — channel in group, hi/lo select, exit, threshold
  uint16_t alarm_frame = reg::Alarm::ChannelInGroup(ch_in_grp);
 
  if (bound == AlarmBound::High) {
    alarm_frame |= reg::Alarm::HIGH_REGISTER;
  }
 
  // Exit programming after this alarm (single-alarm API)
  alarm_frame |= reg::Alarm::EXIT_NEXT_FRAME;
  alarm_frame |= reg::Alarm::Threshold12To10(threshold_12bit);
 
  if (!spiTransfer16(alarm_frame)) {
    return false;
  }
 
  // Frame 3: Any frame to complete the exit (continue mode)
  return spiTransfer16(reg::Mode::CONTINUE | commonControlBits());
}
 
template <typename SpiType>
bool ADS7952<SpiType>::ProgramAlarmVoltage(uint8_t channel, AlarmBound bound,
                                           float voltage) noexcept {
  return ProgramAlarm(channel, bound, VoltageToCount(voltage));
}
 
// =============================================================================
// Range & Power
// =============================================================================
 
template <typename SpiType>
template <typename Commit>
bool ADS7952<SpiType>::programControlBits(uint16_t ctrl, Commit commit) noexcept {
  // SLAS605C Tables 1, 2, 5: DI06:00 are taken only from a mode frame with
  // DI11 = 1 (DI11 = 0 retains the previous values). A CONTINUE frame
  // ignores DI11:00 entirely (Table 7), so it cannot carry a new setting.
  // Re-issue the current mode: Manual re-selects the current channel,
  // Auto-1/Auto-2 keep counting (DI10 = 0, no counter reset).
  uint16_t cmd = reg::PROGRAM_ENABLE | ctrl;
  switch (mode_) {
  case Mode::Auto1:
    cmd |= reg::Mode::AUTO_1 | reg::NO_RESET_COUNTER;
    break;
  case Mode::Auto2:
    cmd |= reg::Mode::AUTO_2 | reg::NO_RESET_COUNTER;
    break;
  case Mode::Manual:
  default:
    cmd |= reg::Mode::MANUAL | reg::ChannelSelect(manual_channel_);
    break;
  }
  if (!spiTransfer16(cmd)) {
    return false; // not sent: chip and driver keep the old setting
  }
  commit(); // the chip latched DI06:00 at the CS rising edge of that frame
 
  // One more frame makes the setting effective before returning
  // (Figure 50: the range written in frame N applies to the input acquired
  // in frame N+1; section 8.1: GPO pins update on the CS falling edge of
  // frame N+1; 8.3.2: DI05 = 1 powers down at the 16th SCLK of frame N+1).
  // Its reply is the last conversion made with the old range: discarded.
  return spiTransfer16(reg::Mode::CONTINUE);
}
 
template <typename SpiType>
bool ADS7952<SpiType>::SetRange(Range range) noexcept {
  const uint16_t ctrl = (commonControlBits() & ~reg::RANGE_2VREF) |
                        (range == Range::TwoVref ? reg::RANGE_2VREF : reg::RANGE_VREF);
  return programControlBits(ctrl, [&] {
    range_ = range;
    active_vref_ = (range == Range::TwoVref) ? two_vref_ : vref_;
  });
}
 
template <typename SpiType>
bool ADS7952<SpiType>::SetPowerDown(PowerDown pd) noexcept {
  const uint16_t ctrl = (commonControlBits() & ~reg::POWER_DOWN) |
                        (pd == PowerDown::PowerDown ? reg::POWER_DOWN : reg::POWER_NORMAL);
  return programControlBits(ctrl, [&] { power_down_ = pd; });
}
 
// =============================================================================
// GPIO Output Control
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::SetGPIOOutputs(uint8_t gpio_state) noexcept {
  const uint8_t state = gpio_state & 0x0F;
  const uint16_t ctrl = static_cast<uint16_t>((commonControlBits() & ~0x000Fu) | state);
  return programControlBits(ctrl, [&] { gpio_output_state_ = state; });
}
 
// =============================================================================
// Raw frame trace
// =============================================================================
 
template <typename SpiType>
uint8_t ADS7952<SpiType>::RawManualFrames(uint8_t channel, uint16_t* out,
                                          uint8_t n) noexcept {
  if (!initialized_ || out == nullptr || n == 0 ||
      channel >= reg::NUM_CHANNELS) {
    return 0;
  }
  const uint16_t ctrl = commonControlBits();
  if (!spiTransfer16(reg::Mode::MANUAL | reg::PROGRAM_RETAIN | reg::ChannelSelect(channel) | ctrl,
                     &out[0])) {
    return 0;
  }
  mode_ = Mode::Manual;
  manual_channel_ = channel;
  const uint16_t cont = reg::Mode::CONTINUE | ctrl;
  for (uint8_t i = 1; i < n; ++i) {
    if (!spiTransfer16(cont, &out[i])) {
      return i; // words 0..i-1 are valid
    }
  }
  return n;
}
 
// =============================================================================
// Internal Helpers
// =============================================================================
 
template <typename SpiType>
bool ADS7952<SpiType>::spiTransfer16(uint16_t command, uint16_t* response) noexcept {
  uint8_t tx[2] = {
      static_cast<uint8_t>((command >> 8) & 0xFF),  // MSB first
      static_cast<uint8_t>(command & 0xFF)};
  uint8_t rx[2] = {0, 0};
 
  // detail::Transfer: a bool-returning port reports bus errors; a legacy
  // void-returning port is treated as always successful.
  const bool ok = detail::Transfer(spi_, tx, rx, 2);
 
  if (response != nullptr) {
    *response = ok ? static_cast<uint16_t>((static_cast<uint16_t>(rx[0]) << 8) | rx[1]) : 0;
  }
  return ok;
}
 
template <typename SpiType>
uint16_t ADS7952<SpiType>::commonControlBits() const noexcept {
  uint16_t bits = 0;
 
  if (range_ == Range::TwoVref) {
    bits |= reg::RANGE_2VREF;
  }
 
  if (power_down_ == PowerDown::PowerDown) {
    bits |= reg::POWER_DOWN;
  }
 
  bits |= static_cast<uint16_t>(gpio_output_state_ & 0x0F);
 
  return bits;
}
 
template <typename SpiType>
constexpr uint8_t ADS7952<SpiType>::popcount16(uint16_t x) noexcept {
  x = x - ((x >> 1) & 0x5555);
  x = (x & 0x3333) + ((x >> 2) & 0x3333);
  return static_cast<uint8_t>((((x + (x >> 4)) & 0x0F0F) * 0x0101) >> 8);
}
 
} // namespace ads7952