max22200.hpp

Go to the documentation of this file.

 
#pragma once
#include "max22200_registers.hpp"
#include "max22200_types.hpp"
#include "max22200_spi_interface.hpp"
#include "max22200_version.h"
#include <cstdint>
 
namespace max22200 {
 
template <typename SpiType> class MAX22200 {
public:
  explicit MAX22200(SpiType &spi_interface);
 
  MAX22200(SpiType &spi_interface, const BoardConfig &board_config);
 
  ~MAX22200();
 
  // Disable copy
  MAX22200(const MAX22200 &) = delete;
  MAX22200 &operator=(const MAX22200 &) = delete;
  MAX22200(MAX22200 &&) = default;
  MAX22200 &operator=(MAX22200 &&) = delete;
 
  // =========================================================================
  // Initialization
  // =========================================================================
 
  DriverStatus Initialize();
 
  DriverStatus Deinitialize();
 
  bool IsInitialized() const;
 
  // =========================================================================
  // STATUS Register Operations
  // =========================================================================
 
  DriverStatus ReadStatus(StatusConfig &status) const;
 
  DriverStatus WriteStatus(const StatusConfig &status);
 
  // =========================================================================
  // Channel Configuration (CFG_CHx)
  // =========================================================================
 
  DriverStatus ConfigureChannel(uint8_t channel, const ChannelConfig &config);
 
  DriverStatus GetChannelConfig(uint8_t channel, ChannelConfig &config) const;
 
  DriverStatus ConfigureAllChannels(const ChannelConfigArray &configs);
 
  DriverStatus GetAllChannelConfigs(ChannelConfigArray &configs) const;
 
  // =========================================================================
  // Channel Enable/Disable (ONCH bits in STATUS register)
  // =========================================================================
 
  DriverStatus EnableChannel(uint8_t channel);
 
  DriverStatus DisableChannel(uint8_t channel);
 
  DriverStatus SetChannelEnabled(uint8_t channel, bool enable);
 
  DriverStatus EnableAllChannels();
 
  DriverStatus DisableAllChannels();
 
  DriverStatus SetAllChannelsEnabled(bool enable);
 
  DriverStatus SetChannelsOn(uint8_t channel_mask);
 
  DriverStatus SetFullBridgeState(uint8_t pair_index, FullBridgeState state);
 
  // =========================================================================
  // Fault Operations
  // =========================================================================
 
  DriverStatus ReadFaultRegister(FaultStatus &faults) const;
 
  DriverStatus ClearAllFaults();
 
  DriverStatus ClearChannelFaults(uint8_t channel_mask, FaultStatus *out_faults = nullptr) const;
 
  DriverStatus ReadFaultRegisterSelectiveClear(uint8_t ocp_mask,
                                              uint8_t hhf_mask,
                                              uint8_t olf_mask,
                                              uint8_t dpm_mask,
                                              FaultStatus &faults) const;
 
  DriverStatus ReadFaultFlags(StatusConfig &status) const;
 
  DriverStatus ClearFaultFlags();
 
  // =========================================================================
  // DPM Configuration (CFG_DPM, 0x0A)
  // =========================================================================
 
  DriverStatus ConfigureDpm(float start_current_ma, float dip_threshold_ma,
                           float debounce_ms);
 
  DriverStatus ConfigureDpm(float start_current_ma, float dip_threshold_ma,
                           float debounce_ms, ChopFreq chop_freq);
 
  DriverStatus ReadDpmConfig(DpmConfig &config) const;
 
  DriverStatus WriteDpmConfig(const DpmConfig &config);
 
  DriverStatus SetDpmEnabledChannels(uint8_t channel_mask);
 
  // =========================================================================
  // Device Control
  // =========================================================================
 
  DriverStatus EnableDevice();
 
  DriverStatus DisableDevice();
 
  DriverStatus SetDeviceEnable(bool enable);
 
  DriverStatus GetFaultPinState(bool &fault_active) const;
 
  // =========================================================================
  // Raw Register Access (for debug)
  // =========================================================================
 
  DriverStatus ReadRegister32(uint8_t bank, uint32_t &value) const;
 
  DriverStatus WriteRegister32(uint8_t bank, uint32_t value);
 
  DriverStatus ReadRegister8(uint8_t bank, uint8_t &value) const;
 
  DriverStatus WriteRegister8(uint8_t bank, uint8_t value);
 
  uint8_t GetLastFaultByte() const;
 
  // =========================================================================
  // Statistics
  // =========================================================================
 
  DriverStatistics GetStatistics() const;
 
  void ResetStatistics();
 
  // =========================================================================
  // Callbacks
  // =========================================================================
 
  void SetFaultCallback(FaultCallback callback, void *user_data);
 
  void SetStateChangeCallback(StateChangeCallback callback, void *user_data);
 
  // =========================================================================
  // Board/Scale Configuration (for unit-based APIs)
  // =========================================================================
 
  void SetBoardConfig(const BoardConfig &config);
 
  BoardConfig GetBoardConfig() const;
 
  // =========================================================================
  // Convenience APIs: Current in Real Units (CDR Mode)
  // =========================================================================
 
  DriverStatus SetHitCurrentMa(uint8_t channel, uint32_t ma);
 
  DriverStatus SetHoldCurrentMa(uint8_t channel, uint32_t ma);
 
  DriverStatus SetHitCurrentA(uint8_t channel, float amps);
 
  DriverStatus SetHoldCurrentA(uint8_t channel, float amps);
 
  DriverStatus SetHitCurrentPercent(uint8_t channel, float percent);
 
  DriverStatus SetHoldCurrentPercent(uint8_t channel, float percent);
 
  DriverStatus GetHitCurrentMa(uint8_t channel, uint32_t &ma) const;
 
  DriverStatus GetHoldCurrentMa(uint8_t channel, uint32_t &ma) const;
 
  DriverStatus GetHitCurrentPercent(uint8_t channel, float &percent) const;
 
  DriverStatus GetHoldCurrentPercent(uint8_t channel, float &percent) const;
 
  // =========================================================================
  // Convenience APIs: Duty Cycle in Percent (VDR Mode)
  // =========================================================================
 
  DriverStatus SetHitDutyPercent(uint8_t channel, float percent);
 
  DriverStatus SetHoldDutyPercent(uint8_t channel, float percent);
 
  DriverStatus GetHitDutyPercent(uint8_t channel, float &percent) const;
 
  DriverStatus GetHoldDutyPercent(uint8_t channel, float &percent) const;
 
  static DriverStatus GetDutyLimits(bool master_clock_80khz, ChopFreq chop_freq,
                                    bool slew_rate_control_enabled, DutyLimits &limits);
 
  DriverStatus GetDutyLimits(uint8_t channel, DutyLimits &limits) const;
 
  // =========================================================================
  // Convenience APIs: HIT Time in Milliseconds
  // =========================================================================
 
  DriverStatus SetHitTimeMs(uint8_t channel, float ms);
 
  DriverStatus GetHitTimeMs(uint8_t channel, float &ms) const;
 
  // =========================================================================
  // Convenience APIs: One-Shot Channel Configuration
  // =========================================================================
 
  DriverStatus ConfigureChannelCdr(uint8_t channel, uint32_t hit_ma,
                                   uint32_t hold_ma, float hit_time_ms,
                                   SideMode side_mode = SideMode::LOW_SIDE,
                                   ChopFreq chop_freq = ChopFreq::FMAIN_DIV4,
                                   bool slew_rate_control_enabled = false,
                                   bool open_load_detection_enabled = false,
                                   bool plunger_movement_detection_enabled = false,
                                   bool hit_current_check_enabled = false);
 
  DriverStatus ConfigureChannelVdr(uint8_t channel, float hit_duty_percent,
                                   float hold_duty_percent, float hit_time_ms,
                                   SideMode side_mode = SideMode::LOW_SIDE,
                                   ChopFreq chop_freq = ChopFreq::FMAIN_DIV4,
                                   bool slew_rate_control_enabled = false,
                                   bool open_load_detection_enabled = false,
                                   bool plunger_movement_detection_enabled = false,
                                   bool hit_current_check_enabled = false);
 
  // =========================================================================
  // Validation
  // =========================================================================
 
  static bool IsValidChannel(uint8_t channel) { return channel < NUM_CHANNELS_; }
 
  // ===========================================================================
  // Driver Version
  // ===========================================================================
 
  static constexpr const char* GetDriverVersion() noexcept {
    return HF_MAX22200_VERSION_STRING;
  }
 
  static constexpr uint8_t GetDriverVersionMajor() noexcept {
    return HF_MAX22200_VERSION_MAJOR;
  }
 
  static constexpr uint8_t GetDriverVersionMinor() noexcept {
    return HF_MAX22200_VERSION_MINOR;
  }
 
  static constexpr uint8_t GetDriverVersionPatch() noexcept {
    return HF_MAX22200_VERSION_PATCH;
  }
 
private:
  SpiType &spi_interface_;
  bool initialized_;
  mutable DriverStatistics statistics_;
  mutable uint8_t last_fault_byte_;  
  mutable StatusConfig cached_status_;  
  BoardConfig board_config_;         
 
  FaultCallback fault_callback_;
  void *fault_user_data_;
  StateChangeCallback state_callback_;
  void *state_user_data_;
 
  void notifyFaults(const FaultStatus &faults) const;
  void notifyStatusFaults(const StatusConfig &status) const;
 
  // ── Core SPI protocol (two-phase) ──────────────────────────────────────
 
  DriverStatus writeCommandRegister(uint8_t bank, bool is_write,
                                    bool mode8 = false) const;
 
  DriverStatus writeData32(uint32_t value) const;
 
  DriverStatus readData32(uint32_t &value) const;
 
  DriverStatus readData32WithTx(const uint8_t tx[4], uint32_t &value) const;
 
  DriverStatus writeData8(uint8_t value) const;
 
  DriverStatus readData8(uint8_t &value) const;
 
  // ── Convenience wrappers ───────────────────────────────────────────────
 
  DriverStatus writeReg32(uint8_t bank, uint32_t value) const;
 
  DriverStatus readReg32(uint8_t bank, uint32_t &value) const;
 
  DriverStatus writeReg8(uint8_t bank, uint8_t value) const;
 
  DriverStatus readReg8(uint8_t bank, uint8_t &value) const;
 
  void updateStatistics(bool success) const;
};
 
inline const char* GetDriverVersion() noexcept {
  return HF_MAX22200_VERSION_STRING;
}
 
} // namespace max22200
 
// Include implementation: from the source tree (inc/ next to src/), or from an installed tree where
// `cmake --install` puts max22200.ipp next to this header.
#if __has_include("../src/max22200.ipp")
#include "../src/max22200.ipp"
#else
#include "max22200.ipp"
#endif