Homing subsystem with automatic settings caching. More...

#include <tmc51x0.hpp>

Collaboration diagram for tmc51x0::TMC51x0< CommType >::Homing:

Classes
struct	BoundsOptions

struct	BoundsResult

struct	HomeConfig

Public Types
enum class	BoundsMethod { StallGuard , Encoder , Switch }

enum class	HomePlacement { None , AtMin , AtMax , AtCenter , AtOffsetFromMin }

using	CancelCallback = bool (*)()

Public Member Functions
	Homing (TMC51x0 &driver) noexcept
	Construct homing subsystem.

Result< void >	PerformSensorlessHoming (bool direction, const BoundsOptions &opt, int32_t &final_position, CancelCallback should_cancel=nullptr) noexcept
	Perform sensorless homing using StallGuard2 (with settings caching)

Result< void >	PerformSwitchHoming (bool direction, const BoundsOptions &opt, int32_t &final_position, bool use_left_switch, CancelCallback should_cancel=nullptr) noexcept
	Perform homing using a reference switch (with settings caching)

Result< void >	PerformEncoderIndexHoming (bool direction, const BoundsOptions &opt, int32_t &final_position, CancelCallback should_cancel=nullptr) noexcept
	Perform homing using encoder index pulse (N-channel) with latch_x_act.

Result< BoundsResult >	FindBoundsStallGuard (const BoundsOptions &opt, const HomeConfig &home={}, CancelCallback should_cancel=nullptr) noexcept
	Find motion bounds using StallGuard2 (sensorless hard-stop detection).

Result< BoundsResult >	FindBoundsEncoder (const BoundsOptions &opt, const HomeConfig &home={}, CancelCallback should_cancel=nullptr) noexcept
	Find motion bounds using encoder feedback (detects "no further motion" via stalled encoder).

Result< BoundsResult >	FindBoundsSwitch (const BoundsOptions &opt, const HomeConfig &home={}, CancelCallback should_cancel=nullptr) noexcept
	Find motion bounds using reference switches (REFL/REFR stop events).

Result< BoundsResult >	FindBounds (BoundsMethod method, const BoundsOptions &opt, const HomeConfig &home={}, CancelCallback should_cancel=nullptr) noexcept
	Dispatch bounds finding by method.

Private Member Functions
Result< void >	CacheCurrentSettings () noexcept

Result< void >	RestoreCachedSettings () noexcept

Result< void >	EnsureSpreadCycleForStallGuard () noexcept

Result< void >	ApplyHomePlacement (BoundsResult &out, float raw_min, float raw_max, const HomeConfig &home, const BoundsOptions &opt) noexcept

Private Attributes
TMC51x0 &	driver_

HomingSettingsCache	cache_ {}

Detailed Description

template<typename CommType>
struct tmc51x0::TMC51x0< CommType >::Homing

Homing subsystem with automatic settings caching.

Provides homing methods that automatically cache and restore settings modified during homing operations.

Member Typedef Documentation

◆ CancelCallback

template<typename CommType >

using tmc51x0::TMC51x0< CommType >::Homing::CancelCallback = bool (*)()

Member Enumeration Documentation

◆ BoundsMethod

template<typename CommType >

enum class tmc51x0::TMC51x0::Homing::BoundsMethod

strong

Enumerator
StallGuard
Encoder
Switch

◆ HomePlacement

template<typename CommType >

enum class tmc51x0::TMC51x0::Homing::HomePlacement

strong

Enumerator
None
AtMin
AtMax
AtCenter
AtOffsetFromMin

Constructor & Destructor Documentation

◆ Homing()

template<typename CommType >

tmc51x0::TMC51x0< CommType >::Homing::Homing ( TMC51x0 & driver )

inlineexplicitnoexcept

Construct homing subsystem.

Parameters

driver Reference to parent TMC51x0 driver instance

Member Function Documentation

◆ ApplyHomePlacement()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Homing::ApplyHomePlacement	(	BoundsResult &	out,
		float	raw_min,
		float	raw_max,
		const HomeConfig &	home,
		const BoundsOptions &	opt )

privatenoexcept

◆ CacheCurrentSettings()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Homing::CacheCurrentSettings ( )

privatenoexcept

◆ EnsureSpreadCycleForStallGuard()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Homing::EnsureSpreadCycleForStallGuard ( )

privatenoexcept

◆ FindBounds()

template<typename CommType >

Result< BoundsResult > tmc51x0::TMC51x0< CommType >::Homing::FindBounds	(	BoundsMethod	method,
		const BoundsOptions &	opt,
		const HomeConfig &	home = {},
		CancelCallback	should_cancel = nullptr )

noexcept

Dispatch bounds finding by method.

Convenience wrapper around:

FindBoundsStallGuard() when method == BoundsMethod::StallGuard
FindBoundsEncoder() when method == BoundsMethod::Encoder
FindBoundsSwitch() when method == BoundsMethod::Switch

Parameters

method	Bounds detection method to use.
opt	Bounds-search options.
home	Optional home placement policy (defaults to `AtCenter`).
should_cancel	Optional cancellation callback polled during motion.

Returns: Result<BoundsResult> on success, otherwise an error code (e.g. INVALID_STATE if an unknown method is provided).

◆ FindBoundsEncoder()

template<typename CommType >

Result< BoundsResult > tmc51x0::TMC51x0< CommType >::Homing::FindBoundsEncoder	(	const BoundsOptions &	opt,
		const HomeConfig &	home = {},
		CancelCallback	should_cancel = nullptr )

noexcept

Find motion bounds using encoder feedback (detects "no further motion" via stalled encoder).

This routine performs two span-capped searches (± opt.search_span). For each direction, it monitors the encoder position during motion and considers a bound detected when the encoder position stops changing for a short window while motion has already started.

Behavior

Requires internal ramp mode (SD_MODE=0).
Requires the encoder subsystem to be configured (otherwise returns INVALID_STATE).
Establishes a local coordinate frame by setting the current position to 0 in opt.position_unit.
For each direction:
- Command a relative move (± opt.search_span) using either opt.search_speed or cached VMAX, with optional accel/decel overrides.
- Detect a bound when the encoder position does not change by a minimum delta for a short time after motion begins.
- On detection, performs a physical backoff move of opt.backoff_distance away from the bound and records the post-backoff position as the bound.

Home placement After both directions complete, home is applied via the same policy as the StallGuard variant.

Parameters

opt	Bounds-search options (units, span/speed, backoff, timeouts, accel/decel overrides).
home	Optional home placement policy (defaults to `AtCenter`).
should_cancel	Optional cancellation callback polled during motion; when it returns true, motion is stopped and the function returns `CANCELLED`.

Returns: Result<BoundsResult> on success, otherwise an error code.

Warning: This function moves the motor. Ensure your encoder is correctly wired and configured; a missing/failed encoder can prevent detection and lead to large travel up to search_span.

Note: When a side does not "stall" within search_span, BoundsResult.bounded will be false and that side's bound is the final span endpoint (i.e., not a detected limit).

◆ FindBoundsStallGuard()

template<typename CommType >

Result< BoundsResult > tmc51x0::TMC51x0< CommType >::Homing::FindBoundsStallGuard	(	const BoundsOptions &	opt,
		const HomeConfig &	home = {},
		CancelCallback	should_cancel = nullptr )

noexcept

Find motion bounds using StallGuard2 (sensorless hard-stop detection).

This is a blocking routine that actively moves the motor to discover the reachable travel range around the current location, then optionally establishes a new coordinate frame via home.

High-level behavior

Requires internal ramp mode (SD_MODE=0). Returns INVALID_STATE otherwise.
Caches and restores driver settings that are modified during the procedure (ramp settings, SW_MODE, StealthChop/CoolStep, etc.).
Defines a local coordinate frame at the start by setting the current position to 0 in opt.position_unit.
Performs two span-capped searches (± opt.search_span) in the requested order (opt.search_positive_first), attempting to stop on a StallGuard2 stall.

StallGuard specifics

Ensures SpreadCycle is active (StallGuard2 is not reliable in StealthChop).
Disables CoolStep during the scan to avoid current modulation affecting detection.
Configures SW_MODE.sg_stop=1 and SW_MODE.en_softstop=0 (hard stop), and disables reference-switch stop/latch sources so StallGuard is the only stop cause.
If opt.stallguard_override is non-null, it is used temporarily and restored on exit.
StallGuardConfig.min_velocity must be > 0 (enforced), because StallGuard2 is only meaningful above a minimum velocity threshold.

Backoff semantics

Unlike switch/encoder methods, this routine does not physically back off after a stall hit.
After both sides complete, it applies opt.backoff_distance numerically to compute a "safe" interval (min increased, max decreased). If this would invert the interval, the function returns INVALID_VALUE.

Home placement

If home.mode != HomePlacement::None, the routine may move to the selected home position (min/max/center/offset-from-min), then redefines that position as 0.
Center/offset placement requires both bounds; if only one side is detected, the placement is skipped and the origin remains at the start position.

Parameters

opt	Bounds-search options (units, span/speed, timeouts, optional current reduction, etc.).
home	Optional home placement policy (defaults to `AtCenter`).
should_cancel	Optional cancellation callback polled during motion; when it returns true, motion is stopped and the function returns `CANCELLED`.

Returns

Result<BoundsResult>:

On success (OK): returns BoundsResult containing bounds in opt.position_unit.
On error: returns an error code such as INVALID_STATE, INVALID_VALUE, TIMEOUT, CANCELLED, or a communication error.

Warning: This function moves the motor and can hit hard mechanical stops. Ensure your mechanism can tolerate this and use conservative speed/accel/current settings.

Note: BoundsResult.bounded is true only when a stall is detected on both sides. When a side does not stall within search_span, the corresponding bound value will be the final position reached at the end of the span-capped move.

◆ FindBoundsSwitch()

template<typename CommType >

Result< BoundsResult > tmc51x0::TMC51x0< CommType >::Homing::FindBoundsSwitch	(	const BoundsOptions &	opt,
		const HomeConfig &	home = {},
		CancelCallback	should_cancel = nullptr )

noexcept

Find motion bounds using reference switches (REFL/REFR stop events).

This routine configures the TMC51x0 reference-switch stop sources and performs two span-capped searches. A bound is detected when the corresponding stop event fires; the routine then backs off from the switch and records the post-backoff position as the bound.

Behavior

Requires internal ramp mode (SD_MODE=0).
Establishes a local coordinate frame by setting the current position to 0 in opt.position_unit.
Preflight handling: if a switch is already active at the start and opt.preflight_clear_active_switch is true, the routine attempts a bounded move away (using opt.backoff_distance) to clear it. If preflight is disabled or backoff_distance is not configured, returns INVALID_STATE.
During bounds finding, enables both SW_MODE.stop_l_enable and SW_MODE.stop_r_enable (hard stop), disables latching, and clears stale stop/latch state between passes.
On each direction search:
- Positive direction expects the right stop event; negative direction expects the left stop event.
- After a hit, performs a physical backoff move of opt.backoff_distance away from the switch.

Home placement After both directions complete, home is applied via the same policy as the other variants.

Parameters

opt	Bounds-search options (units, span/speed, backoff, timeouts, accel/decel overrides).
home	Optional home placement policy (defaults to `AtCenter`).
should_cancel	Optional cancellation callback polled during motion; when it returns true, motion is stopped and the function returns `CANCELLED`.

Returns: Result<BoundsResult> on success, otherwise an error code.

Warning: This function moves the motor and relies on correctly wired/functional limit switches.

Note: When a side does not trigger within search_span, BoundsResult.bounded will be false and that side's bound is the final span endpoint (i.e., not a detected limit).

◆ PerformEncoderIndexHoming()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Homing::PerformEncoderIndexHoming	(	bool	direction,
		const BoundsOptions &	opt,
		int32_t &	final_position,
		CancelCallback	should_cancel = nullptr )

noexcept

Perform homing using encoder index pulse (N-channel) with latch_x_act.

Parameters

direction	Direction to search (true = positive, false = negative)
opt	Homing options (unit-aware). Uses opt.search_speed, opt.search_span, opt.timeout_ms.
final_position	Reference to store final position after homing (in steps). This is the latched XACTUAL at the moment the N-event fired, providing precise motor position at index pulse detection.

Returns: Result<void> indicating success or error

This method uses the encoder's N-channel (index pulse) for high-precision homing:

Enables ENCMODE.latch_x_act so XACTUAL is latched to XLATCH on N-event
Clears N-event flag and searches for the index pulse
When N-event fires, reads XLATCH for the exact motor position at that instant
This provides microsecond-accurate position capture vs polling uncertainty

Prerequisites:

Encoder must be configured (Configure() or SetNChannelSensitivity())
Motor must have an encoder with index pulse (N channel)

Note: The latched position is typically more accurate than polling-based homing because it captures XACTUAL at the hardware level when N fires.

See also: SetLatchXactualEnabled(), IsNEventDetected(), Switches::GetLatchedPosition()

◆ PerformSensorlessHoming()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Homing::PerformSensorlessHoming	(	bool	direction,
		const BoundsOptions &	opt,
		int32_t &	final_position,
		CancelCallback	should_cancel = nullptr )

noexcept

Perform sensorless homing using StallGuard2 (with settings caching)

Parameters

direction	Direction to search (true = positive, false = negative)
opt	Homing options (unit-aware). Uses opt.search_speed, opt.search_span, opt.timeout_ms.
final_position	Reference to store final position after homing (in steps). Note: if `opt.backoff_distance > 0`, the motor backs off and the post-backoff point becomes home (XACTUAL=0).

Returns: Result<void> indicating success or error

This is a blocking function that automatically:

Caches current settings (StealthChop, SW_MODE, ramp settings)
Disables StealthChop if enabled (StallGuard requires SpreadCycle)
Uses existing StallGuard configuration (SGT threshold from motor config)
Enables sg_stop and waits for stall event
Restores cached settings after homing completes

Note: StallGuard threshold (SGT) should be configured via Initialize() or ConfigureStallGuard() before calling this method. The method uses the existing SGT configuration (or opt.stallguard_override if provided).

Perform sensorless homing using StallGuard2 (span-capped, unit-aware)

Uses BoundsOptions.search_speed (in speed_unit) and BoundsOptions.search_span (in position_unit) to perform a single-direction homing move. If StallGuard stop triggers, the current position is defined as home (XACTUAL=0).

final_position returns the pre-zero position in steps (i.e., the position at the moment homing finished, after any optional backoff, before XACTUAL is reset to 0).

Note: search_span is a hard cap on travel; this prevents excessive motion even if timeout_ms is large.

◆ PerformSwitchHoming()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Homing::PerformSwitchHoming	(	bool	direction,
		const BoundsOptions &	opt,
		int32_t &	final_position,
		bool	use_left_switch,
		CancelCallback	should_cancel = nullptr )

noexcept

Perform homing using a reference switch (with settings caching)

Parameters

direction	Direction to search (true = positive, false = negative)
opt	Homing options (unit-aware). Uses opt.search_speed, opt.search_span, opt.timeout_ms.
final_position	Reference to store final position after homing (in steps). Note: if `opt.backoff_distance > 0`, the motor backs off and the post-backoff point becomes home (XACTUAL=0).
use_left_switch	true to use REFL, false to use REFR

Returns: Result<void> indicating success or error

This is a blocking function that automatically:

Caches current settings (SW_MODE, ramp settings)
Configures switches and performs homing
Restores cached settings after homing completes

Perform homing using a reference switch (span-capped, unit-aware)

Uses BoundsOptions.search_speed and BoundsOptions.search_span to perform a single-direction homing move. When the selected switch triggers, the current position is defined as home (XACTUAL=0).

final_position returns the pre-zero position in steps (i.e., the position at the moment homing finished, after any optional backoff, before XACTUAL is reset to 0).

BoundsOptions.search_span is the max relative travel cap. StallGuard-only fields in BoundsOptions are ignored.

◆ RestoreCachedSettings()

template<typename CommType >

Result< void > tmc51x0::TMC51x0< CommType >::Homing::RestoreCachedSettings ( )

privatenoexcept

Member Data Documentation

◆ cache_

template<typename CommType >

HomingSettingsCache tmc51x0::TMC51x0< CommType >::Homing::cache_ {}

private

◆ driver_

template<typename CommType >

TMC51x0& tmc51x0::TMC51x0< CommType >::Homing::driver_

private

The documentation for this struct was generated from the following file:

tmc51x0.hpp

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ CancelCallback

Member Enumeration Documentation

◆ BoundsMethod

◆ HomePlacement

Constructor & Destructor Documentation

◆ Homing()

Member Function Documentation

◆ ApplyHomePlacement()

◆ CacheCurrentSettings()

◆ EnsureSpreadCycleForStallGuard()

◆ FindBounds()

◆ FindBoundsEncoder()

◆ FindBoundsStallGuard()

◆ FindBoundsSwitch()

◆ PerformEncoderIndexHoming()

◆ PerformSensorlessHoming()

◆ PerformSwitchHoming()

◆ RestoreCachedSettings()

Member Data Documentation

◆ cache_

◆ driver_