Unified singleton for controlling all valve channels on the Flux board. More...

#include <ValveManager.h>

Collaboration diagram for ValveManager:

Public Member Functions
	ValveManager (const ValveManager &)=delete

ValveManager &	operator= (const ValveManager &)=delete

	ValveManager (ValveManager &&)=delete

ValveManager &	operator= (ValveManager &&)=delete

bool	EnsureInitialized () noexcept
	Ensure the valve manager system is initialized.

bool	IsInitialized () const noexcept
	Check whether the valve subsystem has been initialised.

bool	IsBankReady (ValveDriverType bank) const noexcept
	Whether one driver IC came up during the last bring-up attempt.

flux::hal::ManagerError	GetManagerError () const noexcept
	Lifecycle / bind error of the last `EnsureInitialized()` (shared catalog).

bool	Deinitialize () noexcept
	Turn every channel off, release both driver handlers and reset to uninitialised.

bool	DropEnablePins () noexcept
	Drive MAX22200 ENABLE and TLE92466ED EN low: both banks de-energised in hardware.

bool	RearmEnablePins () noexcept
	Leave SafeHold: full re-bring-up of both banks, which raises the enable pins again.

bool	IsOutputInhibited () const noexcept
	The enable pins were dropped and not re-armed since.

void	GetEnablePinStates (bool &max_enable, bool &tle_enable) const noexcept
	Read back the two enable outputs.

hf_valve_err_t	EnableChannel (ValveChannel channel) noexcept
	Enable a valve channel output.

hf_valve_err_t	DisableChannel (ValveChannel channel) noexcept
	Disable a valve channel output.

hf_valve_err_t	EnableChannelsMask (uint16_t mask) noexcept
	Enable multiple channels by bitmask.

hf_valve_err_t	DisableAllChannels () noexcept
	Disable all channels on both drivers.

bool	IsChannelEnabled (ValveChannel channel) const noexcept
	Check if a channel is currently enabled.

hf_valve_err_t	ConfigureSolenoidCdr (ValveChannel channel, uint16_t hit_ma, uint16_t hold_ma, float hit_time_ms) noexcept
	Configure a solenoid channel with CDR (current drive regulation).

hf_valve_err_t	ConfigureSolenoidVdr (ValveChannel channel, float hit_duty_pct, float hold_duty_pct, float hit_time_ms) noexcept
	Configure a solenoid channel with VDR (voltage drive regulation).

hf_valve_err_t	SetProportionalCurrent (ValveChannel channel, uint16_t current_ma) noexcept
	Set current setpoint for a proportional valve channel.

hf_valve_err_t	ConfigureProportionalPwm (ValveChannel channel, float frequency_hz) noexcept
	Configure PWM frequency for a proportional channel.

hf_valve_err_t	ConfigureProportionalDither (ValveChannel channel, float amplitude_ma, float frequency_hz) noexcept
	Configure dither for a proportional channel.

bool	HasFault () noexcept
	Check if any driver reports a fault.

hf_valve_err_t	ClearAllFaults () noexcept
	Clear faults on both drivers.

bool	HasSolenoidFault () noexcept
	Check for MAX22200-specific faults.

bool	HasProportionalFault () noexcept
	Check for TLE92466ED-specific faults.

hf_valve_err_t	GetSolenoidFaults (max22200::FaultStatus &faults) noexcept
	Retrieve the MAX22200 fault status.

hf_valve_err_t	GetProportionalFaults (tle92466ed::FaultReport &report) noexcept
	Retrieve the TLE92466ED fault report.

const ValveChannelState *	GetChannelState (ValveChannel channel) const noexcept
	Get channel runtime state by enum.

const ValveChannelInfo *	GetChannelInfo (std::string_view name) const noexcept
	Get channel info (driver type, hw channel, name) by string name.

ValveChannel	FindChannel (std::string_view name) const noexcept
	Find a channel enum by name.

Max22200Handler *	GetMax22200Handler () noexcept
	Get the MAX22200 handler for advanced solenoid operations.

Tle92466edHandler *	GetTle92466Handler () noexcept
	Get the TLE92466ED handler for advanced proportional operations.

hf_valve_err_t	GetLastError () const noexcept
	Get the most recent failed valve operation's error code.

hf_valve_err_t	GetSystemDiagnostics (ValveSystemDiagnostics &diag) const noexcept
	Populate a ValveSystemDiagnostics snapshot.

void	DumpStatistics () const noexcept
	Log valve channel statistics and driver health to the console.

Static Public Member Functions
static ValveManager &	GetInstance () noexcept
	Return the singleton ValveManager instance.

Private Member Functions
	ValveManager () noexcept

	~ValveManager ()=default

hf_valve_err_t	Initialize () noexcept

flux::hal::ManagerError	InitializeMax22200 () noexcept

flux::hal::ManagerError	InitializeTle92466 () noexcept

hf_valve_err_t	DisableAllLocked () noexcept
	Disable every channel on every bank that is up (mutex held by the caller).

void	ReleaseDriversLocked () noexcept
	Destroy both handlers and clear the bank flags (mutex held by the caller).

hf_valve_err_t	Record (hf_valve_err_t result) const noexcept
	Remember a failed operation result for GetLastError(); pass the result through.

Static Private Member Functions
static bool	ResolveChannel (ValveChannel channel, ValveDriverType &driver_type, uint8_t &hw_channel) noexcept
	Resolve channel enum to hw channel index and driver type.

Private Attributes
std::optional< Max22200Handler >	max22200_

bool	max22200_valid_ {false}

std::optional< Tle92466edHandler >	tle92466_

bool	tle92466_valid_ {false}

std::array< ValveChannelState, static_cast< size_t >(ValveChannel::CHANNEL_COUNT)>	channel_states_ {}

std::atomic< bool >	initialized_ {false}

std::atomic< bool >	outputs_inhibited_ {false}
	DropEnablePins() latched, until re-armed.

std::atomic< flux::hal::ManagerError >	manager_error_ {flux::hal::ManagerError::NotInitialized}

std::atomic< hf_valve_err_t >	last_error_ {hf_valve_err_t::VALVE_SUCCESS}

RtosMutex	mutex_

Detailed Description

Unified singleton for controlling all valve channels on the Flux board.

Provides a single API surface for both solenoid (MAX22200) and proportional (TLE92466ED) valve channels. The manager owns both handler instances and resolves channel requests to the correct backend automatically.

Constructor & Destructor Documentation

◆ ValveManager() [1/3]

ValveManager::ValveManager ( const ValveManager & )

delete

◆ ValveManager() [2/3]

ValveManager::ValveManager ( ValveManager && )

delete

◆ ValveManager() [3/3]

ValveManager::ValveManager ( )

privatenoexcept

◆ ~ValveManager()

ValveManager::~ValveManager ( )

privatedefault

Member Function Documentation

◆ ClearAllFaults()

hf_valve_err_t ValveManager::ClearAllFaults ( )

noexcept

Clear faults on both drivers.

Returns: VALVE_SUCCESS on success.

Here is the call graph for this function:

◆ ConfigureProportionalDither()

hf_valve_err_t ValveManager::ConfigureProportionalDither	(	ValveChannel	channel,
		float	amplitude_ma,
		float	frequency_hz
	)

noexcept

Configure dither for a proportional channel.

Dither superimposes a small oscillation on the current setpoint to reduce valve stiction and improve proportional control linearity.

Parameters

channel	Must be PROP_CH0..PROP_CH5
amplitude_ma	Peak-to-peak dither amplitude in milliamps
frequency_hz	Dither oscillation frequency in Hz

Returns: VALVE_SUCCESS on success, specific error code on failure

Here is the call graph for this function:

◆ ConfigureProportionalPwm()

hf_valve_err_t ValveManager::ConfigureProportionalPwm	(	ValveChannel	channel,
		float	frequency_hz
	)

noexcept

Configure PWM frequency for a proportional channel.

Accepts a frequency in Hz and internally converts to the TLE92466ED register encoding (mantissa, exponent, low-freq-range bit).

Valid range: ~30 Hz to 8 MHz.

Standard range (≥ 245 Hz): T = MANT × 2^EXP × 0.125 µs
Low-freq range (< 245 Hz): T = MANT × 2^EXP × 1.0 µs

Parameters

channel	Must be PROP_CH0..PROP_CH5
frequency_hz	Desired PWM frequency in Hz

Returns: VALVE_SUCCESS on success, specific error code on failure

Here is the call graph for this function:

◆ ConfigureSolenoidCdr()

hf_valve_err_t ValveManager::ConfigureSolenoidCdr	(	ValveChannel	channel,
		uint16_t	hit_ma,
		uint16_t	hold_ma,
		float	hit_time_ms
	)

noexcept

Configure a solenoid channel with CDR (current drive regulation).

Parameters

channel	Must be SOL_CH0..SOL_CH7
hit_ma	HIT (inrush) current in milliamps
hold_ma	HOLD (sustain) current in milliamps
hit_time_ms	Duration of HIT phase in milliseconds

Returns: VALVE_SUCCESS on success, specific error code on failure

Here is the call graph for this function:

◆ ConfigureSolenoidVdr()

hf_valve_err_t ValveManager::ConfigureSolenoidVdr	(	ValveChannel	channel,
		float	hit_duty_pct,
		float	hold_duty_pct,
		float	hit_time_ms
	)

noexcept

Configure a solenoid channel with VDR (voltage drive regulation).

Parameters

channel	Must be SOL_CH0..SOL_CH7
hit_duty_pct	HIT duty cycle percentage (0-100)
hold_duty_pct	HOLD duty cycle percentage (0-100)
hit_time_ms	Duration of HIT phase in milliseconds

Returns: VALVE_SUCCESS on success, specific error code on failure

Here is the call graph for this function:

◆ Deinitialize()

bool ValveManager::Deinitialize ( )

noexcept

Turn every channel off, release both driver handlers and reset to uninitialised.

Safe to call when not initialised. Channels are disabled before the handlers are destroyed, so a shutdown never leaves an output energised by a stale command.

Returns: true on success

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DisableAllChannels()

hf_valve_err_t ValveManager::DisableAllChannels ( )

noexcept

Disable all channels on both drivers.

Returns: VALVE_SUCCESS on success.

Here is the call graph for this function:

◆ DisableAllLocked()

hf_valve_err_t ValveManager::DisableAllLocked ( )

privatenoexcept

Disable every channel on every bank that is up (mutex held by the caller).

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DisableChannel()

hf_valve_err_t ValveManager::DisableChannel ( ValveChannel channel )

noexcept

Disable a valve channel output.

Parameters

channel Valve channel to disable.

Returns: VALVE_SUCCESS on success.

Here is the call graph for this function:

◆ DropEnablePins()

bool ValveManager::DropEnablePins ( )

noexcept

Drive MAX22200 ENABLE and TLE92466ED EN low: both banks de-energised in hardware.

The hardware half of SafeHold (architecture-port design §3.4, §3.8). Writes the two enable GPIOs directly: no SPI transfer, no mutex, no allocation, no logging, so it is safe from the safety thread at any priority while another thread is mid-transfer on the valve bus. It works whether or not the manager is initialised (the pins exist as soon as GpioManager is up).

After a drop the manager refuses every channel-energising call (EnableChannel, EnableChannelsMask) with VALVE_ERR_WRONG_MODE, so software never believes a valve is on while its bank is gated off. De-energising calls still work. The drop holds until RearmEnablePins.

This does not decide when to drop the pins or whether to vent first: that is the caller's policy (the product's safety arbiter; vent-then-hold is owner question Q2).

Note: Callable from task context of any priority. From an ISR only if the binding's GPIO write is ISR-safe; on the ESP32-S3 prefer waking the safety thread (gpio_set_level is not in IRAM).

Returns: true when every enable pin that exists was driven low.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ DumpStatistics()

void ValveManager::DumpStatistics ( ) const

noexcept

Log valve channel statistics and driver health to the console.

Here is the caller graph for this function:

◆ EnableChannel()

hf_valve_err_t ValveManager::EnableChannel ( ValveChannel channel )

noexcept

Enable a valve channel output.

Parameters

channel Valve channel to enable.

Returns: VALVE_SUCCESS on success.

Here is the call graph for this function:

◆ EnableChannelsMask()

hf_valve_err_t ValveManager::EnableChannelsMask ( uint16_t mask )

noexcept

Enable multiple channels by bitmask.

Parameters

mask	Lower 8 bits → MAX22200 channels, upper 6 bits → TLE92466ED.

Returns: VALVE_SUCCESS on success.

Here is the call graph for this function:

◆ EnsureInitialized()

bool ValveManager::EnsureInitialized ( )

noexcept

Ensure the valve manager system is initialized.

Returns: true if initialization successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

◆ FindChannel()

ValveChannel ValveManager::FindChannel ( std::string_view name ) const

noexcept

Find a channel enum by name.

Parameters

name	Channel name to look up.

Returns: Matching ValveChannel, or CHANNEL_COUNT if not found.

◆ GetChannelInfo()

const ValveChannelInfo * ValveManager::GetChannelInfo ( std::string_view name ) const

noexcept

Get channel info (driver type, hw channel, name) by string name.

Parameters

name	Human-readable channel name (e.g. "SOL_CH0").

Returns: Pointer to ValveChannelInfo, or nullptr if not found.

◆ GetChannelState()

const ValveChannelState * ValveManager::GetChannelState ( ValveChannel channel ) const

noexcept

Get channel runtime state by enum.

Parameters

channel Valve channel to query.

Returns: Pointer to ValveChannelState, or nullptr if invalid.

◆ GetEnablePinStates()

void ValveManager::GetEnablePinStates	(	bool &	max_enable,
		bool &	tle_enable
	)		const

noexcept

Read back the two enable outputs.

Parameters

[out]	max_enable	MAX22200 ENABLE is driven high (false if the pin does not exist).
[out]	tle_enable	TLE92466ED EN is driven high (false if the pin does not exist).

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetInstance()

ValveManager & ValveManager::GetInstance ( )

staticnoexcept

Return the singleton ValveManager instance.

Here is the caller graph for this function:

◆ GetLastError()

hf_valve_err_t ValveManager::GetLastError ( ) const

inlinenoexcept

Get the most recent failed valve operation's error code.

Operation lane (per call). Set by every channel, configuration and fault call that fails, and by a failed bring-up; never cleared by a later success. The lifecycle lane is GetManagerError().

Returns: Last hf_valve_err_t recorded, or VALVE_SUCCESS if nothing has failed.

◆ GetManagerError()

flux::hal::ManagerError ValveManager::GetManagerError ( ) const

inlinenoexcept

Lifecycle / bind error of the last EnsureInitialized() (shared catalog).

Returns: ManagerError::None when initialised; otherwise why bring-up failed.

◆ GetMax22200Handler()

Max22200Handler * ValveManager::GetMax22200Handler ( )

noexcept

Get the MAX22200 handler for advanced solenoid operations.

Returns: Pointer to Max22200Handler, or nullptr if not initialised.

◆ GetProportionalFaults()

hf_valve_err_t ValveManager::GetProportionalFaults ( tle92466ed::FaultReport & report )

noexcept

Retrieve the TLE92466ED fault report.

Parameters

[out] report Fault report structure to fill.

Returns: VALVE_SUCCESS on success.

Here is the call graph for this function:

◆ GetSolenoidFaults()

hf_valve_err_t ValveManager::GetSolenoidFaults ( max22200::FaultStatus & faults )

noexcept

Retrieve the MAX22200 fault status.

Parameters

[out] faults Fault status structure to fill.

Returns: VALVE_SUCCESS on success.

Here is the call graph for this function:

◆ GetSystemDiagnostics()

hf_valve_err_t ValveManager::GetSystemDiagnostics ( ValveSystemDiagnostics & diag ) const

noexcept

Populate a ValveSystemDiagnostics snapshot.

Parameters

[out] diag Diagnostics structure to fill.

Returns: VALVE_SUCCESS on success.

◆ GetTle92466Handler()

Tle92466edHandler * ValveManager::GetTle92466Handler ( )

noexcept

Get the TLE92466ED handler for advanced proportional operations.

Returns: Pointer to Tle92466edHandler, or nullptr if not initialised.

◆ HasFault()

bool ValveManager::HasFault ( )

noexcept

Check if any driver reports a fault.

Returns: true if a fault is active on either driver.

Here is the call graph for this function:

◆ HasProportionalFault()

bool ValveManager::HasProportionalFault ( )

noexcept

Check for TLE92466ED-specific faults.

Returns: true if a proportional-driver fault is active.

Here is the caller graph for this function:

◆ HasSolenoidFault()

bool ValveManager::HasSolenoidFault ( )

noexcept

Check for MAX22200-specific faults.

Returns: true if a solenoid-driver fault is active.

Here is the caller graph for this function:

◆ Initialize()

hf_valve_err_t ValveManager::Initialize ( )

privatenoexcept

Here is the call graph for this function:

Here is the caller graph for this function:

◆ InitializeMax22200()

ManagerError ValveManager::InitializeMax22200 ( )

privatenoexcept

Here is the call graph for this function:

Here is the caller graph for this function:

◆ InitializeTle92466()

ManagerError ValveManager::InitializeTle92466 ( )

privatenoexcept

< UV trip: 24 V − 21 % (flag true supply loss)

< OV trip: 24 V + 21 % (flag regulator runaway)

Here is the call graph for this function:

Here is the caller graph for this function:

◆ IsBankReady()

bool ValveManager::IsBankReady ( ValveDriverType bank ) const

noexcept

Whether one driver IC came up during the last bring-up attempt.

True for a bank even when the manager as a whole failed (fail-closed) because the other bank did not come up; used for diagnosis (which part is missing).

Parameters

bank	`ValveDriverType::MAX22200` or `ValveDriverType::TLE92466`.

◆ IsChannelEnabled()

bool ValveManager::IsChannelEnabled ( ValveChannel channel ) const

noexcept

Check if a channel is currently enabled.

Parameters

channel Valve channel to query.

Returns: true if the channel output is active.

◆ IsInitialized()

bool ValveManager::IsInitialized ( ) const

inlinenoexcept

Check whether the valve subsystem has been initialised.

Returns: true if initialised.

◆ IsOutputInhibited()

bool ValveManager::IsOutputInhibited ( ) const

inlinenoexcept

The enable pins were dropped and not re-armed since.

Here is the caller graph for this function:

◆ operator=() [1/2]

ValveManager & ValveManager::operator= ( const ValveManager & )

delete

◆ operator=() [2/2]

ValveManager & ValveManager::operator= ( ValveManager && )

delete

◆ RearmEnablePins()

bool ValveManager::RearmEnablePins ( )

noexcept

Leave SafeHold: full re-bring-up of both banks, which raises the enable pins again.

The MAX22200 is not guaranteed to keep its configuration across an ENABLE low period, so re-arming is Deinitialize() followed by EnsureInitialized(): every channel off, handlers rebuilt, chips re-initialised, pins raised by their drivers. Takes the manager mutex and uses SPI; never call it from the safety path.

Returns: true when the manager is initialised again with both pins high.

Here is the call graph for this function:

◆ Record()

hf_valve_err_t ValveManager::Record ( hf_valve_err_t result ) const

inlineprivatenoexcept

Remember a failed operation result for GetLastError(); pass the result through.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ReleaseDriversLocked()

void ValveManager::ReleaseDriversLocked ( )

privatenoexcept

Destroy both handlers and clear the bank flags (mutex held by the caller).

Here is the caller graph for this function:

◆ ResolveChannel()

bool ValveManager::ResolveChannel	(	ValveChannel	channel,
		ValveDriverType &	driver_type,
		uint8_t &	hw_channel
	)

staticprivatenoexcept

Resolve channel enum to hw channel index and driver type.

◆ SetProportionalCurrent()

hf_valve_err_t ValveManager::SetProportionalCurrent	(	ValveChannel	channel,
		uint16_t	current_ma
	)

noexcept

Set current setpoint for a proportional valve channel.

Parameters

channel	Must be PROP_CH0..PROP_CH5
current_ma	Target current in milliamps (0–2000 single, 0–4000 parallel)

Returns: VALVE_SUCCESS on success, specific error code on failure

Here is the call graph for this function:

Member Data Documentation

◆ channel_states_

std::array<ValveChannelState, static_cast<size_t>(ValveChannel::CHANNEL_COUNT)> ValveManager::channel_states_ {}

private

◆ initialized_

std::atomic<bool> ValveManager::initialized_ {false}

private

◆ last_error_

std::atomic<hf_valve_err_t> ValveManager::last_error_ {hf_valve_err_t::VALVE_SUCCESS}

mutableprivate

◆ manager_error_

std::atomic<flux::hal::ManagerError> ValveManager::manager_error_ {flux::hal::ManagerError::NotInitialized}

private

◆ max22200_

std::optional<Max22200Handler> ValveManager::max22200_

private

◆ max22200_valid_

bool ValveManager::max22200_valid_ {false}

private

◆ mutex_

RtosMutex ValveManager::mutex_

mutableprivate

◆ outputs_inhibited_

std::atomic<bool> ValveManager::outputs_inhibited_ {false}

private

DropEnablePins() latched, until re-armed.

◆ tle92466_

std::optional<Tle92466edHandler> ValveManager::tle92466_

private

◆ tle92466_valid_

bool ValveManager::tle92466_valid_ {false}

private

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

Public Member Functions

Static Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ValveManager() [1/3]

◆ ValveManager() [2/3]

◆ ValveManager() [3/3]

◆ ~ValveManager()

Member Function Documentation

◆ ClearAllFaults()

◆ ConfigureProportionalDither()

◆ ConfigureProportionalPwm()

◆ ConfigureSolenoidCdr()

◆ ConfigureSolenoidVdr()

◆ Deinitialize()

◆ DisableAllChannels()

◆ DisableAllLocked()

◆ DisableChannel()

◆ DropEnablePins()

◆ DumpStatistics()

◆ EnableChannel()

◆ EnableChannelsMask()

◆ EnsureInitialized()

◆ FindChannel()

◆ GetChannelInfo()

◆ GetChannelState()

◆ GetEnablePinStates()

◆ GetInstance()

◆ GetLastError()

◆ GetManagerError()

◆ GetMax22200Handler()

◆ GetProportionalFaults()

◆ GetSolenoidFaults()

◆ GetSystemDiagnostics()

◆ GetTle92466Handler()

◆ HasFault()

◆ HasProportionalFault()

◆ HasSolenoidFault()

◆ Initialize()

◆ InitializeMax22200()

◆ InitializeTle92466()

◆ IsBankReady()

◆ IsChannelEnabled()

◆ IsInitialized()

◆ IsOutputInhibited()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ RearmEnablePins()

◆ Record()

◆ ReleaseDriversLocked()

◆ ResolveChannel()

◆ SetProportionalCurrent()

Member Data Documentation

◆ channel_states_

◆ initialized_

◆ last_error_

◆ manager_error_

◆ max22200_

◆ max22200_valid_

◆ mutex_

◆ outputs_inhibited_

◆ tle92466_

◆ tle92466_valid_