Motor configuration and control subsystem. More...

#include <tmc9660.hpp>

Collaboration diagram for tmc9660::TMC9660< CommType >::MotorConfig:

Classes
struct	MotorProfile
	Configuration structure for auto-configuring motor parameters. More...

Public Member Functions
bool	setType (tmc9660::tmcl::MotorType type, uint8_t polePairs=1) noexcept
	Configure the motor type (DC, BLDC, or stepper) and basic motor settings.

bool	setDirection (tmc9660::tmcl::MotorDirection direction) noexcept
	Set the motor direction inversion.

bool	setPWMFrequency (uint32_t frequency_hz) noexcept
	Set the PWM frequency for the motor driver.

bool	setCommutationMode (tmc9660::tmcl::CommutationMode mode) noexcept
	Configure the commutation mode for the motor.

bool	setOutputVoltageLimit (uint16_t limit) noexcept
	Set the output voltage limit for the FOC controller.

bool	getOutputVoltageLimit (uint16_t &limit) noexcept
	Read the output voltage limit for the FOC controller.

bool	setMaxTorqueCurrent (uint16_t milliamps) noexcept
	Set the maximum allowed motor current (torque limit).

bool	setMaxFluxCurrent (uint16_t milliamps) noexcept
	Set the maximum allowed flux current for BLDC/stepper motors.

bool	setPWMSwitchingScheme (tmc9660::tmcl::PwmSwitchingScheme scheme) noexcept
	Set the PWM switching scheme for the motor driver.

bool	setIdleMotorPWMBehavior (tmc9660::tmcl::IdleMotorPwmBehavior pwmOffWhenIdle=tmc9660::tmcl::IdleMotorPwmBehavior::PWM_OFF_WHEN_MOTOR_IDLE) noexcept
	Configure PWM behavior when the motor is idle (System Off mode).

bool	configureAuto (const MotorProfile &profile) noexcept
	Auto-configure motor parameters based on high-level motor characteristics.

Private Member Functions
	MotorConfig (TMC9660 &parent) noexcept

Private Attributes
TMC9660 &	driver

Friends
class	TMC9660

Detailed Description

template<typename CommType>
struct tmc9660::TMC9660< CommType >::MotorConfig

Motor configuration and control subsystem.

Provides high-level methods for configuring motor parameters such as motor type, pole pairs, PWM frequency, commutation mode, and control limits. This subsystem abstracts the low-level TMCL parameter access into intuitive, easy-to-use methods.

// Configure a BLDC motor
driver.motor.setType(tmc9660::tmcl::MotorType::BLDC, 7);  // 7 pole pairs
driver.motor.setPWMFrequency(20000);  // 20 kHz PWM
driver.motor.setCommutationMode(tmc9660::tmcl::CommutationMode::FOC_HALL);
driver.motor.setMaxTorqueCurrent(2000);  // 2A torque current limit
driver.motor.enable();  // Start motor control

Constructor & Destructor Documentation

◆ MotorConfig()

template<typename CommType >

tmc9660::TMC9660< CommType >::MotorConfig::MotorConfig ( TMC9660 & parent )

inlineexplicitprivatenoexcept

Member Function Documentation

◆ configureAuto()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::configureAuto ( const MotorProfile & profile )

noexcept

Auto-configure motor parameters based on high-level motor characteristics.

This method automatically configures motor-specific parameters including:

Motor type and pole pairs
Motor direction
PWM frequency and switching scheme
Maximum torque and flux current limits
Idle motor PWM behavior
Output voltage limit
Commutation mode (if specified, applied last after all configuration is complete)

Note: Current sensing configuration (CSA gain, current scaling factor) should be configured separately using CurrentSensing::configureAuto().; The function sets commutation mode to SYSTEM_OFF first (required for motor type changes), then configures all parameters, and finally applies the requested commutation mode if specified in the profile.

Parameters

profile Motor configuration profile (see MotorProfile)

Returns: true if all configurations succeeded, false otherwise

◆ getOutputVoltageLimit()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::getOutputVoltageLimit ( uint16_t & limit )

noexcept

Read the output voltage limit for the FOC controller.

Parameters

[out] limit Current output voltage limit value.

Returns: true if the parameter was read successfully.

◆ setCommutationMode()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setCommutationMode ( tmc9660::tmcl::CommutationMode mode )

noexcept

Configure the commutation mode for the motor.

This sets how the motor is driven: e.g., open-loop or closed-loop FOC with various sensor feedback options. Typically used for BLDC or stepper motors. For DC motors, commutation modes are not applicable except for sensor feedback in velocity/position control modes.

Parameters

mode

A CommutationMode value defining the motor control strategy:

SYSTEM_OFF: Motor disabled (default state after power-on/reset)
SYSTEM_OFF_LOW_SIDE_FETS_ON: All low-side FETs ON (brake)
SYSTEM_OFF_HIGH_SIDE_FETS_ON: All high-side FETs ON
FOC_OPENLOOP_VOLTAGE: Constant duty cycle (voltage) control without feedback
FOC_OPENLOOP_CURRENT: Constant current control without position feedback
FOC_ENCODER: Field-oriented control with ABN encoder feedback
FOC_HALL: Field-oriented control with Hall sensor feedback
FOC_SPI_ENCODER: Field-oriented control with SPI encoder feedback

Returns: true if the mode was applied successfully.

Note: When using SYSTEM_OFF, the behavior is controlled by IDLE_MOTOR_PWM_BEHAVIOR parameter. For open-loop modes, additional parameters must be set (OPENLOOP_VOLTAGE or OPENLOOP_CURRENT). For sensor-based modes, the appropriate sensor must be configured before enabling this mode.

◆ setDirection()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setDirection ( tmc9660::tmcl::MotorDirection direction )

noexcept

Set the motor direction inversion.

This configures the MOTOR_DIRECTION parameter which inverts the meaning of "forward" direction for the motor.

Parameters

direction MotorDirection (FORWARD or REVERSE).

Returns: true if successfully set.

◆ setIdleMotorPWMBehavior()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setIdleMotorPWMBehavior ( tmc9660::tmcl::IdleMotorPwmBehavior pwmOffWhenIdle = tmc9660::tmcl::IdleMotorPwmBehavior::PWM_OFF_WHEN_MOTOR_IDLE )

noexcept

Configure PWM behavior when the motor is idle (System Off mode).

Controls whether motor phases are driven or left floating (high-impedance) when commutation is disabled.

Parameters

pwm_off_when_idle True → high-Z / disconnected phases False → all phases driven equally (same PWM output)

Returns: true if the parameter was set successfully.

Note: Motor-type idle mode selection guide:

Motor Type	Idle Goal	Best Setting	Notes
Stepper	Hold shaft position	PWM on	• Energizing both windings
			provides full static torque
			• Prevents back-driving by load
			or gravity
			• Always draws current at idle
			• Causes heat and power waste—
			disable if holding isn't needed

----------—	--------------------------—	-------------—	-------------------------------—
BLDC	Coast freely (no braking)	PWM off	• With PWM off (high-Z), stator
(3-phase)		(high-Z)	phases are floating—not
			connected to power or ground
			• No current flows from battery,
			eliminating idle power & heat
			• Rotor coasts with only
			mechanical friction
			• No braking torque (this is
			pure coasting, not braking)
			• For passive braking (eddy-
			current braking), use
			SYSTEM_OFF_LOW_SIDE_FETS_ON
			or SYSTEM_OFF_HIGH_SIDE_FETS_ON
			instead (phases shorted)
			• If holding torque is needed
			(rare for sensorless BLDC),
			enable PWM or use active brake

----------—	--------------------------—	-------------—	-------------------------------—
Brushed	Coast freely (no braking)	PWM off	• With PWM off (high-Z), H-bridge
DC Motor		(high-Z)	terminals float—not connected
			• No current flows from battery,
			eliminating idle power & heat
			• Rotor coasts with only
			mechanical friction
			• No braking torque (this is
			pure coasting, not braking)
			• PWM on = short-circuit braking
			(both terminals at same
			voltage) → motor generates
			back-EMF, creating braking
			torque and regenerative
			currents flowing back
			• Regenerative currents can
			charge battery or damage
			system if not handled—use with
			caution

There is no universal best setting—choose based on your application needs:

• PWM_OFF_WHEN_MOTOR_IDLE: All phases set to high-Z. Motor is electrically disconnected. • PWM_ON_WHEN_MOTOR_IDLE: All bridge outputs actively driven to same potential.

Quick Decision Tree

Do you need the shaft locked at idle? → Yes: PWM on → No: Continue
Is battery life, idle power, or heat a concern? → Yes: PWM off
Do you want the rotor to coast freely? → Yes: PWM off (high-Z) → No, you want braking: leave PWM on or use a dedicated brake feature

Rule of Thumb

• Steppers: Keep coils energized only when holding torque is required. • BLDC & Brushed DC: Default to PWM off; only energize if braking or holding is needed.

Final guidance: • Holding torque needed → PWM on • Coasting, low idle power → PWM off

◆ setMaxFluxCurrent()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setMaxFluxCurrent ( uint16_t milliamps )

noexcept

Set the maximum allowed flux current for BLDC/stepper motors.

This sets the MAX_FLUX parameter which limits the flux-producing current component. Important for field-weakening operation and stepper motor control.

Parameters

milliamps Maximum flux current in milliamps.

Returns: true on success, false on error.

Note: This value can be temporarily exceeded marginally due to the operation of the current regulator.

◆ setMaxTorqueCurrent()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setMaxTorqueCurrent ( uint16_t milliamps )

noexcept

Set the maximum allowed motor current (torque limit).

This sets the MAX_TORQUE parameter which limits the peak current/torque that the controller will deliver to the motor.

Parameters

milliamps Maximum current in milliamps.

Returns: true on success, false on error.

Note: This value can be temporarily exceeded marginally due to the operation of the current regulator.

◆ setOutputVoltageLimit()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setOutputVoltageLimit ( uint16_t limit )

noexcept

Set the output voltage limit for the FOC controller.

This parameter limits the maximum Uq/ Ud output of the FOC controller (PID output circular limiter).

Parameters

limit Output voltage limit (0 ... 32767, default 8000).

Returns: true if the parameter was set successfully.

◆ setPWMFrequency()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setPWMFrequency ( uint32_t frequency_hz )

noexcept

Set the PWM frequency for the motor driver.

Parameters

frequency_hz PWM frequency in Hertz (allowed range 10kHz to 100kHz).

Returns: true if set successfully, false if an error occurred.

◆ setPWMSwitchingScheme()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setPWMSwitchingScheme ( tmc9660::tmcl::PwmSwitchingScheme scheme )

noexcept

Set the PWM switching scheme for the motor driver.

This configures how the PWM signals are generated for driving the motor phases. Different schemes offer varying trade-offs between voltage utilization, switching losses, and current measurement windows.

Parameters

scheme PWM switching scheme: 0: STANDARD - Standard PWM modulation (86% max voltage for BLDC) 1: SVPWM - Space Vector PWM (100% max voltage for BLDC, balanced load on FETs) 2: FLAT_BOTTOM - Flat bottom PWM (100% max voltage for BLDC, extended current measurement window)

Returns: true if set successfully, false if an error occurred.

Note: For BLDC motors, SVPWM and Flat Bottom schemes allow full voltage utilization. For Stepper/DC motors, only standard and flat bottom modes are available with 100% duty cycle.

◆ setType()

template<typename CommType >

bool tmc9660::TMC9660< CommType >::MotorConfig::setType	(	tmc9660::tmcl::MotorType	type,
		uint8_t	polePairs = 1 )

noexcept

Configure the motor type (DC, BLDC, or stepper) and basic motor settings.

This sets the MOTOR_TYPE parameter and optionally related parameters like pole pairs for BLDC or microstep settings for steppers. Note that the BLDC option also covers PMSM motors since they use the same three-phase commutation scheme.

Parameters

type	MotorType (DC, BLDC/PMSM, STEPPER).
polePairs	For BLDC motors, number of pole pairs. For stepper or DC, this can be set to 1.

Returns: true if the motor type was set successfully, false if communication or device error.

Friends And Related Symbol Documentation

◆ TMC9660

template<typename CommType >

friend class TMC9660

friend

Member Data Documentation

◆ driver

template<typename CommType >

TMC9660& tmc9660::TMC9660< CommType >::MotorConfig::driver

private

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

tmc9660.hpp

Classes

Public Member Functions

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ MotorConfig()

Member Function Documentation

◆ configureAuto()

◆ getOutputVoltageLimit()

◆ setCommutationMode()

◆ setDirection()

◆ setIdleMotorPWMBehavior()

Quick Decision Tree

Rule of Thumb

◆ setMaxFluxCurrent()

◆ setMaxTorqueCurrent()

◆ setOutputVoltageLimit()

◆ setPWMFrequency()

◆ setPWMSwitchingScheme()

◆ setType()

Friends And Related Symbol Documentation

◆ TMC9660

Member Data Documentation

◆ driver