Vortex Class Reference

Unified API singleton for the HardFOC Vortex platform. More...

#include <Vortex.h>

Collaboration diagram for Vortex:

Public Member Functions
	Vortex (const Vortex &)=delete
Vortex &	operator= (const Vortex &)=delete
	Vortex (Vortex &&)=delete
Vortex &	operator= (Vortex &&)=delete
bool	EnsureInitialized () noexcept
	Bring the managers up in dependency order (idempotent).
ManagerError	GetLastError () const noexcept
	Why the last EnsureInitialized() failed (ManagerError::None after a success).
bool	CollectDiagnostics (VortexBoardDiagnostics &out) const noexcept
	Aggregated health of every manager, the buses and the device counts.
bool	IsInitialized () const noexcept
	Check if all Vortex systems are initialized.
bool	Shutdown () noexcept
	Shut down all subsystems in reverse initialization order.
bool	GetSystemDiagnostics (VortexSystemDiagnostics &diagnostics) const noexcept
	Get comprehensive system diagnostics.
std::array< bool, kVortexManagerCount >	GetComponentInitializationStatus () const noexcept
	Get initialization status for each component.
size_t	GetFailedComponents (const char *out_names[], size_t max_entries) const noexcept
	Get list of failed components during initialization.
size_t	GetSystemWarnings (const char *out_warnings[], size_t max_entries) const noexcept
	Get the warnings recorded by the last EnsureInitialized() (degraded subsystems and unusual conditions that did not fail initialisation).
bool	CollectManagerHealth (ManagerHealthSnapshot &snapshot) noexcept
	Collect per-manager error health into a unified snapshot.
uint64_t	GetSystemUptimeMs () const noexcept
	Get system uptime in milliseconds.
uint64_t	GetInitializationTimeMs () const noexcept
	Get initialization time in milliseconds.
void	DumpSystemStatistics () const noexcept
	Dump comprehensive system statistics.
bool	PerformHealthCheck () noexcept
	Perform system health check.
const char *	GetSystemVersion () const noexcept
	Get system version information.

Static Public Member Functions
static Vortex &	GetInstance () noexcept
	Get the singleton instance of Vortex API.
static void	SetOnboardTmc9660Transport (VortexOnboardTmc9660Transport transport) noexcept
	Select onboard TMC9660 transport before the first EnsureInitialized().
static VortexOnboardTmc9660Transport	GetOnboardTmc9660Transport () noexcept
	Effective transport for InitializeMotors() (default: Uart).

Public Attributes
CommChannelsManager &	comms
	Communication channels (SPI, I²C, UART, CAN). After NVS.
NvsManager &	nvs
	Non-volatile storage (vortex / vortex_cal / vortex_cfg). Init before comms.
GpioManager &	gpio
	ESP32 + I/O-expander GPIO pins. Depends on comms.
MotorController &	motors
	TMC9660 motor controllers. Depends on comms.
AdcManager &	adc
	ADC channels (Vortex: TMC9660-hosted path; see AdcManager). Depends on motors.
ImuManager &	imu
	BNO08x IMU sensors. Depends on comms and gpio.
EncoderManager &	encoders
	AS5047U rotary encoders. Depends on comms and gpio.
LedManager &	leds
	WS2812 status LED. Independent component.
TemperatureManager &	temp
	Temperature sensors (NTC, ESP32, TMC9660). Depends on ADC and motors.

Private Member Functions
	Vortex () noexcept
	Private constructor for singleton pattern.
	~Vortex ()=default
	Destructor for cleanup.
bool	InitializeAllComponents () noexcept
	Initialize all component handlers in proper order.
void	ShutdownComponentsLocked () noexcept
	Shut down every manager that is up, in reverse init order. Caller holds lifecycle_mutex_.
void	FailClosed (ManagerError why) noexcept
	Record why init failed and shut everything down again. Caller holds lifecycle_mutex_.
bool	InitializeNvs () noexcept
bool	InitializeComms () noexcept
	Initialize communication channels (step 2)
bool	InitializeGpio () noexcept
	Initialize GPIO management (step 3)
bool	InitializeMotors () noexcept
	Initialize motor controllers (step 5 — after GPIO + LEDs)
bool	InitializeAdc () noexcept
	Initialize ADC management (step 6)
bool	InitializeImu () noexcept
	Initialize IMU management (step 7)
bool	InitializeEncoders () noexcept
	Initialize encoder management (step 8)
bool	InitializeLeds () noexcept
	Initialize LED management (step 4 — early for LED-only benches)
bool	InitializeTemperature () noexcept
	Initialize temperature management (step 9)
void	UpdateSystemDiagnostics () noexcept
	Update system diagnostics.
void	AddSystemWarning (const char *warning) noexcept
	Add warning message to system warnings.

Private Attributes
std::atomic< bool >	initialized_
	Overall initialization status.
std::atomic< uint64_t >	initialization_start_time_
	Initialization start timestamp.
std::atomic< uint64_t >	initialization_end_time_
	Initialization end timestamp.
std::atomic< bool >	nvs_initialized_
std::atomic< bool >	comms_initialized_
std::atomic< bool >	gpio_initialized_
std::atomic< bool >	motors_initialized_
std::atomic< bool >	adc_initialized_
std::atomic< bool >	imu_initialized_
std::atomic< bool >	encoders_initialized_
std::atomic< bool >	leds_initialized_
std::atomic< bool >	temp_initialized_
VortexSystemDiagnostics	diagnostics_
VortexBootReport	report_ {}
	Failed components and warnings of the last init attempt.
std::atomic< ManagerError >	last_error_ {ManagerError::None}
	Why the last init attempt failed.
RtosMutex	lifecycle_mutex_
	Serialises EnsureInitialized(), Shutdown() and the diagnostics readers (recursive).

Static Private Attributes
static std::atomic< std::uint8_t >	onboard_tmc9660_transport_

Detailed Description

Unified API singleton for the HardFOC Vortex platform.

Constructor & Destructor Documentation

Vortex() [1/3]

Vortex::Vortex ( const Vortex &  )

delete

Vortex() [2/3]

Vortex::Vortex ( Vortex &&  )

delete

Vortex() [3/3]

Vortex::Vortex ( )

privatenoexcept

Private constructor for singleton pattern.

~Vortex()

Vortex::~Vortex ( )

privatedefault

Destructor for cleanup.

Member Function Documentation

AddSystemWarning()

void Vortex::AddSystemWarning ( const char *  warning )

privatenoexcept

Add warning message to system warnings.

Parameters

warning

Warning message to add

Here is the caller graph for this function:

CollectDiagnostics()

bool Vortex::CollectDiagnostics ( VortexBoardDiagnostics &  out ) const

noexcept

Aggregated health of every manager, the buses and the device counts.

Reads counters the managers already hold: no bus transfer, no allocation. Works before and after initialisation (a manager that is down reports NotInitialized).

Parameters

out	Filled completely.

Returns

The value of IsInitialized().

Here is the call graph for this function:

CollectManagerHealth()

bool Vortex::CollectManagerHealth ( ManagerHealthSnapshot &  snapshot )

noexcept

Collect per-manager error health into a unified snapshot.

Parameters

snapshot

Reference to snapshot structure to fill

Returns

true if snapshot collected successfully, false if not initialized

Note

Error codes are manager-specific uint8_t values (0 = success)

Here is the caller graph for this function:

DumpSystemStatistics()

void Vortex::DumpSystemStatistics ( ) const

noexcept

Dump comprehensive system statistics.

Note

This will dump statistics from all component handlers

Here is the call graph for this function:

EnsureInitialized()

bool Vortex::EnsureInitialized ( )

noexcept

Bring the managers up in dependency order (idempotent).

Fail-closed: if a required manager (NVS, comms, GPIO, LEDs) fails, every manager that did come up is shut down again in reverse order, GetLastError() says why, and the call returns false; nothing is left half-initialised. Best-effort managers (motors, ADC, IMU, encoders, temperature) that fail become warnings (GetSystemWarnings()). If the motor controller does not come up, the TMC9660 driver-enable line is driven inactive.

Returns

true when every required manager is up.

Here is the call graph for this function:

FailClosed()

void Vortex::FailClosed ( ManagerError  why )

privatenoexcept

Record why init failed and shut everything down again. Caller holds lifecycle_mutex_.

Here is the caller graph for this function:

GetComponentInitializationStatus()

std::array< bool, kVortexManagerCount > Vortex::GetComponentInitializationStatus ( ) const

noexcept

Get initialization status for each component.

Returns

Array of initialization status (true/false) for each component

GetFailedComponents()

size_t Vortex::GetFailedComponents ( const char *  out_names[], size_t  max_entries  ) const

noexcept

Get list of failed components during initialization.

Parameters

out_names	Array to receive failed component name pointers
max_entries	Maximum entries the array can hold

Returns

Number of failed components written

GetInitializationTimeMs()

uint64_t Vortex::GetInitializationTimeMs ( ) const

noexcept

Get initialization time in milliseconds.

Returns

Time taken for initialization in milliseconds

Here is the caller graph for this function:

GetInstance()

Vortex & Vortex::GetInstance ( )

staticnoexcept

Get the singleton instance of Vortex API.

Returns

Reference to the singleton Vortex instance

Note

Uses Meyer's singleton for thread-safe initialization

Here is the caller graph for this function:

GetLastError()

ManagerError Vortex::GetLastError ( ) const

inlinenoexcept

Why the last EnsureInitialized() failed (ManagerError::None after a success).

GetOnboardTmc9660Transport()

VortexOnboardTmc9660Transport Vortex::GetOnboardTmc9660Transport ( )

staticnoexcept

Effective transport for InitializeMotors() (default: Uart).

Here is the caller graph for this function:

GetSystemDiagnostics()

bool Vortex::GetSystemDiagnostics ( VortexSystemDiagnostics &  diagnostics ) const

noexcept

Get comprehensive system diagnostics.

Parameters

diagnostics

Reference to diagnostics structure to fill

Returns

true if diagnostics retrieved successfully, false otherwise

GetSystemUptimeMs()

uint64_t Vortex::GetSystemUptimeMs ( ) const

noexcept

Get system uptime in milliseconds.

Returns

System uptime in milliseconds

Here is the caller graph for this function:

GetSystemVersion()

const char * Vortex::GetSystemVersion ( ) const

noexcept

Get system version information.

Returns

System version string

GetSystemWarnings()

size_t Vortex::GetSystemWarnings ( const char *  out_warnings[], size_t  max_entries  ) const

noexcept

Get the warnings recorded by the last EnsureInitialized() (degraded subsystems and unusual conditions that did not fail initialisation).

Parameters

out_warnings	Array to receive warning string pointers (static storage)
max_entries	Maximum entries the array can hold

Returns

Number of warnings written

InitializeAdc()

bool Vortex::InitializeAdc ( )

privatenoexcept

Initialize ADC management (step 6)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeAllComponents()

bool Vortex::InitializeAllComponents ( )

privatenoexcept

Initialize all component handlers in proper order.

Returns

true if all components initialized successfully, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeComms()

bool Vortex::InitializeComms ( )

privatenoexcept

Initialize communication channels (step 2)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeEncoders()

bool Vortex::InitializeEncoders ( )

privatenoexcept

Initialize encoder management (step 8)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeGpio()

bool Vortex::InitializeGpio ( )

privatenoexcept

Initialize GPIO management (step 3)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeImu()

bool Vortex::InitializeImu ( )

privatenoexcept

Initialize IMU management (step 7)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeLeds()

bool Vortex::InitializeLeds ( )

privatenoexcept

Initialize LED management (step 4 — early for LED-only benches)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeMotors()

bool Vortex::InitializeMotors ( )

privatenoexcept

Initialize motor controllers (step 5 — after GPIO + LEDs)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeNvs()

bool Vortex::InitializeNvs ( )

privatenoexcept

Here is the call graph for this function:

Here is the caller graph for this function:

InitializeTemperature()

bool Vortex::InitializeTemperature ( )

privatenoexcept

Initialize temperature management (step 9)

Returns

true if successful, false otherwise

Here is the call graph for this function:

Here is the caller graph for this function:

IsInitialized()

bool Vortex::IsInitialized ( ) const

inlinenoexcept

Check if all Vortex systems are initialized.

Returns

true if all systems are initialized, false otherwise

operator=() [1/2]

Vortex & Vortex::operator= ( const Vortex &  )

delete

operator=() [2/2]

Vortex & Vortex::operator= ( Vortex &&  )

delete

PerformHealthCheck()

bool Vortex::PerformHealthCheck ( )

noexcept

Perform system health check.

Returns

true if system is healthy, false otherwise

Here is the call graph for this function:

SetOnboardTmc9660Transport()

void Vortex::SetOnboardTmc9660Transport ( VortexOnboardTmc9660Transport  transport )

staticnoexcept

Select onboard TMC9660 transport before the first EnsureInitialized().

Note

If EnsureInitialized() has already completed, the call is ignored and a warning is logged.

Shutdown()

bool Vortex::Shutdown ( )

noexcept

Shut down all subsystems in reverse initialization order.

Returns

true if all subsystems shut down cleanly

Here is the call graph for this function:

ShutdownComponentsLocked()

void Vortex::ShutdownComponentsLocked ( )

privatenoexcept

Shut down every manager that is up, in reverse init order. Caller holds lifecycle_mutex_.

Here is the call graph for this function:

Here is the caller graph for this function:

UpdateSystemDiagnostics()

void Vortex::UpdateSystemDiagnostics ( )

privatenoexcept

Update system diagnostics.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

adc

AdcManager& Vortex::adc

ADC channels (Vortex: TMC9660-hosted path; see AdcManager). Depends on motors.

adc_initialized_

std::atomic<bool> Vortex::adc_initialized_

private

comms

CommChannelsManager& Vortex::comms

Communication channels (SPI, I²C, UART, CAN). After NVS.

comms_initialized_

std::atomic<bool> Vortex::comms_initialized_

private

diagnostics_

VortexSystemDiagnostics Vortex::diagnostics_

mutableprivate

encoders

EncoderManager& Vortex::encoders

AS5047U rotary encoders. Depends on comms and gpio.

encoders_initialized_

std::atomic<bool> Vortex::encoders_initialized_

private

gpio

GpioManager& Vortex::gpio

ESP32 + I/O-expander GPIO pins. Depends on comms.

gpio_initialized_

std::atomic<bool> Vortex::gpio_initialized_

private

imu

ImuManager& Vortex::imu

BNO08x IMU sensors. Depends on comms and gpio.

imu_initialized_

std::atomic<bool> Vortex::imu_initialized_

private

initialization_end_time_

std::atomic<uint64_t> Vortex::initialization_end_time_

private

Initialization end timestamp.

initialization_start_time_

std::atomic<uint64_t> Vortex::initialization_start_time_

private

Initialization start timestamp.

initialized_

std::atomic<bool> Vortex::initialized_

private

Overall initialization status.

last_error_

std::atomic<ManagerError> Vortex::last_error_ {ManagerError::None}

private

Why the last init attempt failed.

leds

LedManager& Vortex::leds

WS2812 status LED. Independent component.

leds_initialized_

std::atomic<bool> Vortex::leds_initialized_

private

lifecycle_mutex_

RtosMutex Vortex::lifecycle_mutex_

mutableprivate

Serialises EnsureInitialized(), Shutdown() and the diagnostics readers (recursive).

motors

MotorController& Vortex::motors

TMC9660 motor controllers. Depends on comms.

motors_initialized_

std::atomic<bool> Vortex::motors_initialized_

private

nvs

NvsManager& Vortex::nvs

Non-volatile storage (vortex / vortex_cal / vortex_cfg). Init before comms.

nvs_initialized_

std::atomic<bool> Vortex::nvs_initialized_

private

onboard_tmc9660_transport_

std::atomic< std::uint8_t > Vortex::onboard_tmc9660_transport_

staticprivate

Initial value:

{
    static_cast<std::uint8_t>(VortexOnboardTmc9660Transport::Uart)}

0 = Spi, 1 = Uart — must match VortexOnboardTmc9660Transport enumerators.

report_

VortexBootReport Vortex::report_ {}

private

Failed components and warnings of the last init attempt.

temp

TemperatureManager& Vortex::temp

Temperature sensors (NTC, ESP32, TMC9660). Depends on ADC and motors.

temp_initialized_

std::atomic<bool> Vortex::temp_initialized_

private

---

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

• Vortex.h
• Vortex.cpp