tmc9660::TMC9660< CommType >::PositionControl::PositionConfig Struct Reference

Configuration structure for position control auto-configuration. More...

#include <tmc9660.hpp>

Public Attributes
tmc9660::tmcl::PositionSensorSelection	sensorSelection
	Position feedback sensor selection (required)
std::optional< uint16_t >	positionP
	Position P gain [0-32767] (optional, default: 2000).
std::optional< uint16_t >	positionI
	Position I gain [0-32767] (optional, default: 100).
tmc9660::tmcl::VelocityPiNorm	pNormalization
tmc9660::tmcl::VelocityPiNorm	iNormalization
std::optional< uint16_t >	positionScalingFactor
std::optional< uint32_t >	encoderCountsPerRev
uint8_t	loopDownsampling = 1
	Position loop downsampling factor [0-127] (default: 1).
std::optional< int32_t >	positionLimitLow
	Low position limit (optional, disabled if not provided)
std::optional< int32_t >	positionLimitHigh
	High position limit (optional, disabled if not provided)
uint32_t	positionReachedThreshold = 100
	Position reached threshold (default: 100)
std::optional< uint32_t >	stopOnDeviationMaxError
bool	stopOnDeviationSoftStop
	Use soft stop (ramp down) for deviation stop (default: true)

Detailed Description

template<typename CommType>
struct tmc9660::TMC9660< CommType >::PositionControl::PositionConfig

Configuration structure for position control auto-configuration.

Member Data Documentation

encoderCountsPerRev

template<typename CommType >

std::optional<uint32_t> tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::encoderCountsPerRev

Encoder CPR for auto-calculating position scaling (optional, required if positionScalingFactor not provided)

iNormalization

template<typename CommType >

tmc9660::tmcl::VelocityPiNorm tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::iNormalization

Initial value:

=
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT

I-term normalization (default: SHIFT_16_BIT)

loopDownsampling

template<typename CommType >

uint8_t tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::loopDownsampling = 1

Position loop downsampling factor [0-127] (default: 1).

Clock Distribution (Cascading): The position control loop frequency is derived from the velocity loop frequency:

• Velocity loop frequency = PWM frequency / (VELOCITY_LOOP_DOWNSAMPLING + 1)
• Position loop frequency = Velocity loop frequency / (loop_downsampling + 1)
• Example: 25kHz PWM, velocity downsampling=5, position downsampling=1 → velocity loop = 25kHz/6 = 4.17kHz → position loop = 4.17kHz/2 = 2.08kHz

Effect on PI Gains: Lower loop frequencies (higher downsampling) require proportionally higher PI gains to maintain the same response. The integrator speed depends on the PWM frequency, velocity loop downsampling, and this position loop downsampling factor.

Typical Values:

• 0-1: Fast response (high-frequency position control, default: 1)
• 2-3: Standard (good balance for most applications)
• 4-6: Slower response (for heavy loads or stability)
• >6: Very slow (rarely needed)

Note: Position loop must be slower than velocity loop (typically 5-10× slower). Position loop downsampling factor [0-127] (default: 1)

pNormalization

template<typename CommType >

tmc9660::tmcl::VelocityPiNorm tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::pNormalization

Initial value:

=
          tmc9660::tmcl::VelocityPiNorm::SHIFT_16_BIT

P-term normalization (default: SHIFT_16_BIT)

positionI

template<typename CommType >

std::optional<uint16_t> tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::positionI

Position I gain [0-32767] (optional, default: 100).

Direct I gain for the position PI controller. Higher values = better steady-state accuracy but potentially more overshoot. Typical range: 50-200. Position I gain [0-32767] (optional, default: 100)

positionLimitHigh

template<typename CommType >

std::optional<int32_t> tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::positionLimitHigh

High position limit (optional, disabled if not provided)

positionLimitLow

template<typename CommType >

std::optional<int32_t> tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::positionLimitLow

Low position limit (optional, disabled if not provided)

positionP

template<typename CommType >

std::optional<uint16_t> tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::positionP

Position P gain [0-32767] (optional, default: 2000).

Direct P gain for the position PI controller. Higher values = faster response but potentially less stable. Typical range: 1000-4000 for most applications. Position P gain [0-32767] (optional, default: 2000)

positionReachedThreshold

template<typename CommType >

uint32_t tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::positionReachedThreshold = 100

Position reached threshold (default: 100)

positionScalingFactor

template<typename CommType >

std::optional<uint16_t> tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::positionScalingFactor

Position scaling factor [1-2047] (optional, auto-calculated from encoder CPR if not provided)

sensorSelection

template<typename CommType >

tmc9660::tmcl::PositionSensorSelection tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::sensorSelection

Position feedback sensor selection (required)

stopOnDeviationMaxError

template<typename CommType >

std::optional<uint32_t> tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::stopOnDeviationMaxError

Max allowed position deviation for stop condition (optional, disabled if not provided)

stopOnDeviationSoftStop

template<typename CommType >

bool tmc9660::TMC9660< CommType >::PositionControl::PositionConfig::stopOnDeviationSoftStop

Initial value:

=
          true

Use soft stop (ramp down) for deviation stop (default: true)

---

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

• tmc9660.hpp