Unified handler for MAX22200 octal solenoid/motor driver. More...

#include <Max22200Handler.h>

Public Types
using	DriverType = max22200::MAX22200< HalSpiMax22200Comm >
	Underlying max22200::MAX22200 driver type.

Public Member Functions
	Max22200Handler (BaseSpi &spi, BaseGpio &enable, BaseGpio &cmd, BaseGpio *fault=nullptr) noexcept
	Construct MAX22200 handler.

	~Max22200Handler () noexcept

	Max22200Handler (const Max22200Handler &)=delete

Max22200Handler &	operator= (const Max22200Handler &)=delete

	Max22200Handler (Max22200Handler &&)=delete

Max22200Handler &	operator= (Max22200Handler &&)=delete

max22200::DriverStatus	Initialize () noexcept
	Initialize driver (ENABLE HIGH, read/clear STATUS, set ACTIVE).

bool	EnsureInitialized () noexcept
	Ensure driver is initialized (lazy init entrypoint).

max22200::DriverStatus	Initialize (const max22200::BoardConfig &board_config) noexcept
	Initialize with board configuration.

max22200::DriverStatus	Deinitialize () noexcept
	Deinitialize — disable all channels, ACTIVE=0, ENABLE LOW.

bool	IsInitialized () const noexcept
	Check if Initialize completed successfully.

uint8_t	GetLastFaultByte () const noexcept
	STATUS[7:0] captured on the last command-phase SPI byte.

max22200::DriverStatus	ConfigureChannel (uint8_t channel, const max22200::ChannelConfig &config) noexcept
	Configure a channel completely.

max22200::DriverStatus	SetupCdrChannel (uint8_t channel, uint16_t hit_ma, uint16_t hold_ma, float hit_time_ms) noexcept
	Quick CDR setup with milliamp values.

max22200::DriverStatus	SetupVdrChannel (uint8_t channel, float hit_duty_pct, float hold_duty_pct, float hit_time_ms) noexcept
	Quick VDR setup with duty cycle percentages.

max22200::DriverStatus	EnableChannel (uint8_t channel) noexcept
	Enable a channel (sets bit in STATUS channels_on_mask).

max22200::DriverStatus	DisableChannel (uint8_t channel) noexcept
	Disable a channel.

max22200::DriverStatus	EnableAllChannels () noexcept
	Enable all eight channels (writes full channels_on_mask).

max22200::DriverStatus	DisableAllChannels () noexcept
	Disable all channels.

bool	IsChannelEnabled (uint8_t channel) noexcept
	Check if a channel is enabled (reads STATUS channels_on_mask).

max22200::DriverStatus	SetChannelsMask (uint8_t mask) noexcept
	Set channels enabled by bitmask.

max22200::DriverStatus	GetStatus (max22200::StatusConfig &status) noexcept
	Read the STATUS register.

max22200::DriverStatus	GetChannelFaults (uint8_t channel, max22200::FaultStatus &faults) noexcept
	Read the device-wide FAULT register (channel param is range-checked only).

bool	HasFault () noexcept
	Check if any fault flag is set (reads STATUS fault summary).

max22200::DriverStatus	ClearFaults () noexcept
	Clear all latched fault flags (read-clear FAULT register).

max22200::DriverStatus	ReadFaultRegister (max22200::FaultStatus &faults) noexcept
	Read the FAULT register (OCP/OLF/HHF/DPM channel bitmasks).

template<typename Fn >
auto	WithDriver (Fn &&fn) noexcept
	Run `fn` against the raw driver with mutex_ held.

DriverType *	GetDriver () noexcept
	Get the underlying driver for advanced operations.

const DriverType *	GetDriver () const noexcept
	Const view of GetDriver (delegates via const_cast).

void	DumpDiagnostics () noexcept
	Log STATUS, FAULT register, and SPI transfer statistics.

Static Public Attributes
static constexpr uint8_t	kNumChannels = 8
	Number of MAX22200 output channels (0..7).

Private Member Functions
max22200::DriverStatus	InitializeLocked () noexcept
	Initialize while mutex_ is held (no board IFS).

bool	EnsureInitializedLocked () noexcept

bool	WaitForActiveAndDrainFaults () noexcept
	Post-init wake poll: poke ACTIVE=1, wait for latch or SPI-live fallback.

template<typename Fn >
auto	withDriver (Fn &&fn) noexcept
	Execute a lambda with a locked, initialized driver.

Private Attributes
bool	initialized_ {false}

RtosMutex	mutex_

std::unique_ptr< HalSpiMax22200Comm >	comm_

std::unique_ptr< DriverType >	driver_

uint8_t	last_fault_byte_ {0xFF}

Detailed Description

Unified handler for MAX22200 octal solenoid/motor driver.

Serialises all driver access behind an internal mutex. Production callers should use WithDriver for multi-register sequences; GetDriver does not protect subsequent use of the returned pointer.

Provides thread-safe access to all MAX22200 driver features:

8-channel output control (enable/disable)
CDR (Current Drive Regulation) and VDR (Voltage Drive Regulation) modes
HIT/HOLD current and timing configuration
Channel-pair modes (independent, parallel, half-bridge, full-bridge)
Fault monitoring and diagnostics
DPM (Detect Plunger Movement) configuration
Convenience APIs with real-unit parameters (mA, %, ms)

Note: Bench carrier: only channel 0 is wired (Parker C21, 500 mA HIT / 250 mA HOLD). Unpopulated channels 1..7 must keep OL detection off.

Member Typedef Documentation

◆ DriverType

using Max22200Handler::DriverType = max22200::MAX22200<HalSpiMax22200Comm>

Underlying max22200::MAX22200 driver type.

Constructor & Destructor Documentation

◆ Max22200Handler() [1/3]

Max22200Handler::Max22200Handler	(	BaseSpi &	spi,
		BaseGpio &	enable,
		BaseGpio &	cmd,
		BaseGpio *	fault = `nullptr`
	)

noexcept

Construct MAX22200 handler.

Parameters

spi	Reference to pre-configured BaseSpi (Mode 0).
enable	BaseGpio for ENABLE pin (active HIGH).
cmd	BaseGpio for CMD pin.
fault	Optional BaseGpio for nFAULT (active LOW).

◆ ~Max22200Handler()

Max22200Handler::~Max22200Handler ( )

noexcept

◆ Max22200Handler() [2/3]

Max22200Handler::Max22200Handler ( const Max22200Handler & )

delete

◆ Max22200Handler() [3/3]

Max22200Handler::Max22200Handler ( Max22200Handler && )

delete

Member Function Documentation

◆ ClearFaults()

max22200::DriverStatus Max22200Handler::ClearFaults ( )

noexcept

Clear all latched fault flags (read-clear FAULT register).

◆ ConfigureChannel()

max22200::DriverStatus Max22200Handler::ConfigureChannel	(	uint8_t	channel,
		const max22200::ChannelConfig &	config
	)

noexcept

Configure a channel completely.

Parameters

channel	Channel number (0-7).
config	Full channel configuration.

Returns: DriverStatus::OK on success, specific error code on failure.

◆ Deinitialize()

max22200::DriverStatus Max22200Handler::Deinitialize ( )

noexcept

Deinitialize — disable all channels, ACTIVE=0, ENABLE LOW.

Returns: DriverStatus::OK (always succeeds when not initialized).

◆ DisableAllChannels()

max22200::DriverStatus Max22200Handler::DisableAllChannels ( )

noexcept

Disable all channels.

◆ DisableChannel()

max22200::DriverStatus Max22200Handler::DisableChannel ( uint8_t channel )

noexcept

Disable a channel.

Parameters

channel Channel number (0-7).

Returns: DriverStatus::INVALID_PARAMETER if channel out of range.

◆ DumpDiagnostics()

void Max22200Handler::DumpDiagnostics ( )

noexcept

Log STATUS, FAULT register, and SPI transfer statistics.

Note: No-op with warning if not initialized. Holds mutex_ for the duration of the dump.

◆ EnableAllChannels()

max22200::DriverStatus Max22200Handler::EnableAllChannels ( )

noexcept

Enable all eight channels (writes full channels_on_mask).

◆ EnableChannel()

max22200::DriverStatus Max22200Handler::EnableChannel ( uint8_t channel )

noexcept

Enable a channel (sets bit in STATUS channels_on_mask).

Parameters

channel Channel number (0-7).

Returns: DriverStatus::INVALID_PARAMETER if channel out of range.

◆ EnsureInitialized()

bool Max22200Handler::EnsureInitialized ( )

noexcept

Ensure driver is initialized (lazy init entrypoint).

Returns: true if initialized and ready.

Note: Thread-safe; acquires mutex_ internally.

◆ EnsureInitializedLocked()

bool Max22200Handler::EnsureInitializedLocked ( )

privatenoexcept

◆ GetChannelFaults()

max22200::DriverStatus Max22200Handler::GetChannelFaults	(	uint8_t	channel,
		max22200::FaultStatus &	faults
	)

noexcept

Read the device-wide FAULT register (channel param is range-checked only).

Parameters

	channel	Channel number (0-7); validated but not used — FaultStatus carries per-channel bitmasks for all eight outputs.
[out]	faults	Populated fault register snapshot.

Returns: DriverStatus::INVALID_PARAMETER if channel out of range.

Note: Prefer ReadFaultRegister when the channel argument is not needed.

◆ GetDriver() [1/2]

const Max22200Handler::DriverType * Max22200Handler::GetDriver ( ) const

noexcept

Const view of GetDriver (delegates via const_cast).

Returns: Pointer to driver, or nullptr if lazy init fails.

Warning: Same thread-safety constraints as GetDriver.

◆ GetDriver() [2/2]

Max22200Handler::DriverType * Max22200Handler::GetDriver ( )

noexcept

Get the underlying driver for advanced operations.

Returns: Pointer to driver, or nullptr if lazy init fails.

Warning: The returned pointer is not protected: the mutex is released when this call returns. Production code must use WithDriver; this accessor remains for single-threaded bring-up and bench example programs.

◆ GetLastFaultByte()

uint8_t Max22200Handler::GetLastFaultByte ( ) const

noexcept

STATUS[7:0] captured on the last command-phase SPI byte.

Returns: 0xFF if the driver object was reset after failed init; 0x04 indicates COMER (communication error).

Note: Retained in last_fault_byte_ when init fails and driver_ is destroyed — safe to call without holding mutex_.

◆ GetStatus()

max22200::DriverStatus Max22200Handler::GetStatus ( max22200::StatusConfig & status )

noexcept

Read the STATUS register.

Parameters

[out] status Status structure to fill.

Returns: DriverStatus::OK on success.

◆ HasFault()

bool Max22200Handler::HasFault ( )

noexcept

Check if any fault flag is set (reads STATUS fault summary).

Returns: false if STATUS read fails.

◆ Initialize() [1/2]

max22200::DriverStatus Max22200Handler::Initialize ( )

noexcept

Initialize driver (ENABLE HIGH, read/clear STATUS, set ACTIVE).

Returns: DriverStatus::OK on success, specific error code on failure.

Note: Does not set board IFS. CDR current APIs require Initialize(const max22200::BoardConfig&) or a subsequent WithDriver call to SetBoardConfig().

◆ Initialize() [2/2]

max22200::DriverStatus Max22200Handler::Initialize ( const max22200::BoardConfig & board_config )

noexcept

Initialize with board configuration.

Parameters

board_config Board-specific IFS (from RREF) and max-current limits.

Returns: DriverStatus::OK on success, specific error code on failure.

Note: Preferred production entrypoint — live bench uses BoardConfig(15.0f, false) before CDR setup.

◆ InitializeLocked()

max22200::DriverStatus Max22200Handler::InitializeLocked ( )

privatenoexcept

Initialize while mutex_ is held (no board IFS).

◆ IsChannelEnabled()

bool Max22200Handler::IsChannelEnabled ( uint8_t channel )

noexcept

Check if a channel is enabled (reads STATUS channels_on_mask).

Parameters

channel Channel number (0-7).

Returns: false if channel invalid, STATUS read fails, or bit clear.

◆ IsInitialized()

bool Max22200Handler::IsInitialized ( ) const

inlinenoexcept

Check if Initialize completed successfully.

◆ operator=() [1/2]

Max22200Handler & Max22200Handler::operator= ( const Max22200Handler & )

delete

◆ operator=() [2/2]

Max22200Handler & Max22200Handler::operator= ( Max22200Handler && )

delete

◆ ReadFaultRegister()

max22200::DriverStatus Max22200Handler::ReadFaultRegister ( max22200::FaultStatus & faults )

noexcept

Read the FAULT register (OCP/OLF/HHF/DPM channel bitmasks).

Parameters

[out] faults Device-wide fault snapshot.

Returns: DriverStatus::OK on success.

See also: GetChannelFaults

◆ SetChannelsMask()

max22200::DriverStatus Max22200Handler::SetChannelsMask ( uint8_t mask )

noexcept

Set channels enabled by bitmask.

Parameters

mask	Bitmask of channels to enable (bit 0 = CH0, bit 7 = CH7).

Returns: DriverStatus from underlying SetChannelsOn().

◆ SetupCdrChannel()

max22200::DriverStatus Max22200Handler::SetupCdrChannel	(	uint8_t	channel,
		uint16_t	hit_ma,
		uint16_t	hold_ma,
		float	hit_time_ms
	)

noexcept

Quick CDR setup with milliamp values.

Parameters

channel	Channel number (0-7).
hit_ma	HIT current in milliamps (bench CH0: 500 mA).
hold_ma	HOLD current in milliamps (bench CH0: 250 mA).
hit_time_ms	HIT phase duration in milliseconds.

Returns: DriverStatus::OK on success, first failing operation's error code.

Switches the channel to CDR first if it is in VDR (the driver's current setters no longer do), keeping its other CFG_CHx fields. The chip ignores that switch while any channel is on or a TRIG pin is high.

Note: Requires board IFS via Initialize(const max22200::BoardConfig&).

◆ SetupVdrChannel()

max22200::DriverStatus Max22200Handler::SetupVdrChannel	(	uint8_t	channel,
		float	hit_duty_pct,
		float	hold_duty_pct,
		float	hit_time_ms
	)

noexcept

Quick VDR setup with duty cycle percentages.

Parameters

channel	Channel number (0-7).
hit_duty_pct	HIT duty cycle (0..100 %).
hold_duty_pct	HOLD duty cycle (0..100 %).
hit_time_ms	HIT phase duration in milliseconds.

Returns: DriverStatus::OK on success, first failing operation's error code.

Switches the channel to VDR first if it is in CDR, keeping its other CFG_CHx fields. The duty is written as percent (HIT[6:0] = 40 for 40 %).

◆ WaitForActiveAndDrainFaults()

bool Max22200Handler::WaitForActiveAndDrainFaults ( )

privatenoexcept

Post-init wake poll: poke ACTIVE=1, wait for latch or SPI-live fallback.

Must be called with mutex_ held and driver_ constructed.

The driver's Initialize() returns OK as soon as its STATUS write transaction completes, but the chip's t_WU = 2.5 ms (per datasheet) and the V18 LDO can take dozens of ms to settle on real boards. Polls STATUS while re-issuing a bare ACTIVE=1 write each iteration. UVM may remain set on soft-rail setups — logged but not fatal. If ACTIVE never latches, accepts SPI-live after >=3 OK STATUS polls, then read-clears FAULT so nFAULT releases.

Returns: true when faults are drained and either ACTIVE=1 latched or SPI is live (>=3 consecutive OK STATUS polls without ACTIVE); false if STATUS never reads OK within the timeout.

◆ WithDriver()

template<typename Fn >

auto Max22200Handler::WithDriver ( Fn && fn )

inlinenoexcept

Run fn against the raw driver with mutex_ held.

Preferred over GetDriver for any multi-register sequence: the MAX22200 uses a two-phase CMD-pin protocol (command byte, then data), so a peer transaction landing between the phases desynchronizes the device. Holding the handler mutex across the whole callback keeps the sequence coherent.

Template Parameters

Fn	Callable taking `DriverType&`.

Returns: fn's result, or INITIALIZATION_ERROR / a value-initialized result when the driver is unavailable. When fn returns void, this returns bool (true when fn actually ran).

◆ withDriver()

template<typename Fn >

auto Max22200Handler::withDriver ( Fn && fn )

inlineprivatenoexcept

Execute a lambda with a locked, initialized driver.

Acquires the mutex, ensures initialization, and invokes fn(*driver_). Returns a default-constructed R on failure.

Member Data Documentation

◆ comm_

std::unique_ptr<HalSpiMax22200Comm> Max22200Handler::comm_

private

◆ driver_

std::unique_ptr<DriverType> Max22200Handler::driver_

private

◆ initialized_

bool Max22200Handler::initialized_ {false}

private

◆ kNumChannels

constexpr uint8_t Max22200Handler::kNumChannels = 8

staticconstexpr

Number of MAX22200 output channels (0..7).

◆ last_fault_byte_

uint8_t Max22200Handler::last_fault_byte_ {0xFF}

private

Retained after failed init when driver_ is reset (CDC max_fault).

◆ mutex_

RtosMutex Max22200Handler::mutex_

mutableprivate

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ DriverType

Constructor & Destructor Documentation

◆ Max22200Handler() [1/3]

◆ ~Max22200Handler()

◆ Max22200Handler() [2/3]

◆ Max22200Handler() [3/3]

Member Function Documentation

◆ ClearFaults()

◆ ConfigureChannel()

◆ Deinitialize()

◆ DisableAllChannels()

◆ DisableChannel()

◆ DumpDiagnostics()

◆ EnableAllChannels()

◆ EnableChannel()

◆ EnsureInitialized()

◆ EnsureInitializedLocked()

◆ GetChannelFaults()

◆ GetDriver() [1/2]

◆ GetDriver() [2/2]

◆ GetLastFaultByte()

◆ GetStatus()

◆ HasFault()

◆ Initialize() [1/2]

◆ Initialize() [2/2]

◆ InitializeLocked()

◆ IsChannelEnabled()

◆ IsInitialized()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ReadFaultRegister()

◆ SetChannelsMask()

◆ SetupCdrChannel()

◆ SetupVdrChannel()

◆ WaitForActiveAndDrainFaults()

◆ WithDriver()

◆ withDriver()

Member Data Documentation

◆ comm_

◆ driver_

◆ initialized_

◆ kNumChannels

◆ last_fault_byte_

◆ mutex_