Controller Modes

The dev_motor_controller main controller offers a user selectable closed loop current controller, or open loop voltage controller. The main controller also offers tests for aligning the rotor to the encoder and deriving the motor phase inductances and resistances.

Controller modes

Set the controller mode by writing an enum to controller_mode:

Control mode	Description
`current_dq`	Closed loop D/Q axis current controller.
`voltage_dq`	Open loop D/Q axis voltage controller.
`test_align`	Ramp and dwell alignment controller.
`test_dq_l`	D/Q axis inductance test controller.
`test_dq_r`	D/Q axis resistance test controller.
`test_dq_step_response`	D/Q axis step response controller.
`safety_active_damper`	Active damper safety controller.
`safety_active_passive_damper`	Active and passive damper safety controller.
`safety_control_off`	No-action safety controller.

Note: Also see Health for configuration for estop and safety controllers.

Controller mode: current_dq

The closed loop controller implements field oriented control to control the motor phase currents in the D/Q axis. The control action is provided by two PI controllers - one for each axis.

Requirements to start:

Motor commutation source configured.
Aligned rotor.
JCS command signals i_q or i_d (either or both) connected.

Note: For general motor operation the signal i_d may be left unconnected.

Configuration parameters

PI current controllers

Configure the current controllers with the following parameters:

Commands	Type	Required	Description
`i_d_kp`	float32	Required	D axis current controller proportional gain (A).
`i_d_ki`	float32	Required	D axis current controller integral gain (A.s).
`i_d_out_lim_h`	float32	Optional	D axis current controller output and integrator upper limit (V).
`i_d_out_lim_l`	float32	Optional	D axis current controller output and integrator lower limit (V).
`i_q_kp`	float32	Required	Q axis current controller proportional gain (A).
`i_q_ki`	float32	Required	Q axis current controller integral gain (A.s).
`i_q_out_lim_h`	float32	Optional	Q axis current controller output and integrator upper limit (V).
`i_q_out_lim_l`	float32	Optional	Q axis current controller output and integrator lower limit (V).

Note: If the PI controller output limits are left unconfigured, then the PI controller outputs and integrators will be clamped to the maximum device voltage. It may be useful to set the limits during testing.

Motor torque constant

Setting the motor torque constant converts the incoming command signal from a torque into a current.

If configuring motor_Kt it is advisable to rename JCS command signali_q to something that shows that the command signal is now a torque. This removes confusion and ensure users are aware that the incoming signal is a torque command, rather than a current command.

Command	Type	Required	Description
`motor_Kt`	float32	Optional	Motor torque constant (Nm/A). Default: 1.0 (effectively disabled) Must be greater than zero.

Invert incoming current command

Setting the parameter invert_incoming_command inverts the incoming D and Q axis current commands. This is useful for ensuring the commanded current results in the expected rotational direction, which is dependent on the encoder configuration.

Commands	Type	Description
`invert_incoming_command`	boolean	True: Inverts the incoming D and Q axis current commands. Default: False

DQ axis current measurement and command filters

The D and Q axis current measurements and commands may be filtered before use. The measurement and command filters are separately configurable, however the D and Q components are jointly configured.

Configure the DQ measurement filters with:

Command	Type	Required	Description
`i_dq_measurement_filter`	enum	Optional	D/Q axis measurement filter type
`i_dq_measurement_filter_fc_hz`	float32	Optional	D/Q axis measurement filter cutoff (Hz) Default: 1000Hz

Configure the DQ command filters with:

Command	Type	Required	Description
`i_dq_command_filter`	enum	Optional	D/Q axis command filter type
`i_dq_command_filter_fc_hz`	float32	Optional	D/Q axis command filter cutoff (Hz) Default: 500Hz

Set the measurement filter type by writing an enum to i_dq_measurement_filter and set the command filter type by writing an enum to i_dq_command_filter:

Filter type	Description
`dq_filter_none`	No filter configured - pass through.
`dq_filter_lp1`	First order low pass filter.

Notes:

Command noise may come from sources such as higher level controllers that take feedback from other sources. For example, a higher level PD controller may rely on a noisy velocity measurement, which may turn into a noisy current command. Configure the command filter bandwidth in relation to your higher level controller bandwidth.
Measurement noise is typically a product of the current sensors themselves, however configure the measurement filter cutoff to be at, or a a bit above the current controller bandwidth.

Current controller decoupling

Performs decoupling of the D and Q axis.

Commands	Type	Description
`using_vdq_decouple`	boolean	True: Enables D/Q axis decoupling. Default: False

Ensure the following motor parameters are configured: Good estimates of these parameters are required for satisfactory decoupling performance

Command	Type	Required	Description
`motor_Rd`	float32	Optional	D axis motor winding resistance (Ohm).
`motor_Rq`	float32	Optional	Q axis motor winding resistance (Ohm).
`motor_Ld`	float32	Optional	D axis motor winding inductance (Henry).
`motor_Lq`	float32	Optional	Q axis motor winding inductance (Henry).
`motor_Ym`	float32	Optional	Flux linkage.
`motor_Kt`	float32	Optional	Motor torque constant.

Cogging torque compensation

The current controller features a motor cogging torque compensation mechanism that applies a feedforward current command to the Q axis current controller. The feedforward current is derived from a table of coefficients that map the rotor position to the current required to overcome cogging torque at that position.

The coefficients are generated by an external tool that rotates the rotor under a stiff position control loop, while recording the Q axis current required to hold that position. The motor should be un-loaded and free to spin when generating the coefficients.

As the absolute motor speed increases, torque due to cogging decreases. An envelope may be applied to reduce the cogging torque compensator contribution based on the rotor speed.

An upper envelope region may be defined that reduces the cogging torque feed forward current from full contribution, linearly down to zero contribution. cogging_compensator_upper_w_m_low defines where the feedforward term begins to reduce its contribution and cogging_compensator_upper_w_m_high defines where the contribution is fully reduced to zero.

Commands	Type	Required	Description
`cogging_compensator_coeffs`	float32	Optional	Array of 1024 compensation coefficients. The compensator will be enabled if any value is non-zero.
`cogging_compensator_upper_w_m_low`	float32	Required	Start of upper motor speed envelope region, where the cogging torque feedforward contribution starts to be reduced (Rad/s).
`cogging_compensator_upper_w_m_high`	float32	Required	End of upper motor speed envelope region, where the cogging torque feedforward contribution is fully reduced to zero (Rad/s).
`cogging_compensator_lower_w_m_high`	float32	Optional	End of lower motor speed envelope region, where the cogging torque feedforward contribution is fully enabled (Rad/s). Set to 0.0f to disable this feature. (default) Experimental: May cause some hunting of the rotor at zero speed.

Cogging compensation is enabled when any of the cogging_compensator_coeffs are non zero. If cogging compensation is required then cogging_compensator_upper_w_m_low and cogging_compensator_upper_w_m_high must be configured.

NOTE:

Controller commands and limits may be affected by other health limiting processes. See Health.

D-Axis flux braking

The current controller has D-axis flux braking capability for dissipating excess energy into the motor windings. Flux braking may be used to manage DC bus voltage spikes when the motor regenerates and the voltage source is not capable of sinking the excess energy.

When the flux brake is enabled, once the DC bus voltage passes over flux_brake_v_threshold, flux braking activates and a computed current is added to the D-axis current command as:

\[ \begin{align} V_{error} &= V_{dc} - (V_{warning-h} - V_{threshold})\\ i_{d} &\mathrel{{+}{=}} {V_{error} \over R}\\ \end{align} \]

Where \(R\) is the braking resistance, which may be calculated from Ohms law as:

\[R = {V_{threshold} \over I_{braking}}\]

Here \(I_{braking}\) is the maximum braking current, which is initially defined as \(70\%\) of the maximum device current.

Commands	Type	Required	Description
`flux_brake_v_threshold`	float32	Optional	The voltage under `v_dc_limit_warning_h`, where braking action begins Default: \(3.0V\)
`flux_brake_resistance`	float32	Optional	Braking resistance that defines the braking current Default: 70% maximum device current
`flux_brake_enabled`	bool	Optional	Set to true to enable the flux brake Default: False

Flux brake considerations:

D-axis flux braking dumps excess energy into the motor windings as heat. The motor must be able to withstand this. Under continuous activation of the flux brake the motor may heat up significantly. The user should monitor the motor temperature.
Dumping energy into the D-axis can result in torque ripple if not actually braking. For example, setting the threshold too close to the nominal DC bus voltage could cause the flux brake to activate (due to noise) when no braking action is required.
Since v_dc_limit_warning_h defines the upper limit of the flux brake activation region, the user must consider the effects of using v_dc_error_on_warning setting. If the flux brake saturates and the DC bus voltage rises above v_dc_limit_warning_h an estop may be generated if v_dc_error_on_warning is set to true. See Health.
The user must evaluate whether the flux brake will be capable of sinking all excess energy, such that any DC bus voltage supplies will not be damaged if the flux brake saturates. Braking choppers or other energy storage mechanisms might be considered. For example, large inertial loads decelerating to quickly may saturate the flux brake.

Controller mode: voltage_dq

Open loop voltage controller that outputs a voltage command in the D/Q axis.

Requirements to start:

Motor commutation source configured.
Aligned rotor.
JCS command signals v_q or v_d (either or both) connected.

NOTE:

Controller commands and limits may be affected by other health limiting processes. See Health.

Invert incoming voltage command

Setting the parameter invert_incoming_command inverts the incoming D and Q axis voltage commands. This is useful for ensuring the commanded voltage results in the expected rotational direction, which is dependent on the encoder configuration.

Commands	Type	Description
`invert_incoming_command`	boolean	True: Inverts the incoming D and Q axis voltage commands. Default: False

Controller mode: test_align

This mode runs the rotor/encoder alignment procedure by energising the D axis current. Please see Rotor Position Alignment.

Controller mode: test_dq_l

This controller mode attempts to determine either the D or Q axis inductance (H) via frequency injection.

Parameters:

Command	Type	Required	Description
`test_ls_dq_test_axis`	enum	Required	Selects either the D or Q axis to apply the test voltage. Options are: `measure_test_axis_d` `measure_test_axis_q`
`test_ls_v_dq_bias`	float32	Required	Bias voltage (V). Should be large enough to lock the rotor, but low enough to avoid over current and over temperatures.
`test_ls_v_dq_amplitude`	float32	Required	Test square wave amplitude (V), centred around the bias voltage.
`test_ls_test_freq_hz`	float32	Required	Test square wave frequency (Hz).
`test_ls_test_time_ms`	uint16	Required	Test duration (ms).

Once the parameters are written, set controller_mode to test_dq_l to select the D/Q inductance test, then start the test with a write to controller_start. Poll the status of the test with a boolean read to command controller_is_running. The boolean value will be true if the controller is running (ie, the test is still running) and false if the controller is in any other state. Exit the test early with a write to command controller_stop.

Upon test completion read float32 from command motor_Ld or motor_Lq depending on the axis selected by test_ls_dq_test_axis. The test failed if the return values is 0.0f.

Note: Parameters test_ls_v_dq_bias and test_ls_v_dq_amplitude form the voltage applied to the windings of the motor. Due to the typically low winding resistances of the motors, large currents may develop for seemingly small voltages. Either estimate the winding resistance (or measure with a multimeter) to select a reasonable bias voltage or start with small bias voltages (e.g. 1V) and work up.

Controller mode: test_dq_r

This controller mode attempts to determine the D or Q axis resistance (Ohms) via Ohms law.

Parameters:

Command	Type	Required	Description
`test_rs_dq_test_axis`	enum	Required	Selects either the D or Q axis to apply the test voltage. Options are: `measure_test_axis_d` `measure_test_axis_q`
`test_rs_v_dq_test_amplitude`	float32	Required	Vd test voltage (V). Should be large enough to lock the rotor, but low enough to avoid over current and over temperatures.
`test_rs_test_time_ms`	uint16	Required	Test duration (ms).

Once the parameters are written, set controller_mode to test_dq_r to select the D/Q resistance test, then start the test with a write to controller_start. Poll the status of the test with a boolean read to command controller_is_running. The boolean value will be true if the controller is running (ie, the test is still running) and false if the controller is in any other state. Exit the test early with a write to command controller_stop.

Upon test completion read float32 from command motor_Rd or motor_Rq depending on the axis selected by test_rs_dq_test_axis. The test failed if the return values is 0.0f.

Note: Parameter test_rs_v_dq_test_amplitude is the voltage applied to the windings of the motor. Due to the typically low winding resistances of the motors, large currents may develop for seemingly small voltages. Either estimate the winding resistance (or measure with a multimeter) to select a reasonable bias voltage or start with small bias voltages (e.g. 1V) and work up.

Controller mode: test_dq_step_response

This controller mode applies a step current to the configured D or Q axis for some time, then stops.

Parameters:

Command	Type	Required	Description
`test_step_response_amplitude`	float32	Required	Step response test current (A).
`test_step_response_time_ms`	uint16	Required	Test duration (ms).
`test_step_response_dq_test_axis`	enum	Required	Selects either the D or Q axis to apply the test current. Options are: `measure_test_axis_d` `measure_test_axis_q`

Safety controllers

These controllers are used as part of the estop and safety components of the motor controller.

When parameter controller_estop_safe_mode is configured with one of these controllers, in the event of a safe estop the active controller will attempt to transition to the configured safety controller in an effort to place the motor controller (an in turn, the robot) in to a safe state.

An example of this action may be a loss of DC bus voltage. Without external mechanical brakes, in this event a robot may simply collapse and fall to the ground. With a safety controller configured, the motor controller may attempt to actively brake the motor as the DC bus voltage collapses, then transition to passive damping when the DC bus voltage falls so low that active braking is not achievable.

Notes:

Safety controllers are typically used in estop events, however they still may be configured and used as normal controllers for experimentation.
Some safety controllers are robust to DC bus voltage collapse, however the 12V rail must remain valid for control to be possible.

Configuration

Configure the required safety controller by writing an enum to parameter controller_estop_safe_mode.

`controller_estop_safe_mode`	Description
`safety_active_damper`	Active damper safety controller.
`safety_active_passive_damper`	Active and passive damper safety controller.
`safety_control_off`	No-action safety controller.

Note, that while the standard controllers are selectable in controller_estop_safe_mode, they will not start in safety mode.

Controller mode: safety_active_damper

When active safety_active_damper applies a Q axis current command of the form

\[i_{q} = -b\omega_{m}\]

where \(b\) is the damping coefficient configured with parameter safe_active_damper_coeff and \(\omega_{m}\) is the mechanical velocity (Rad/s).

The effect of this controller is to provide a damping action to reduce the velocity of the motor in a safe manner.

Parameter safe_active_damper_active_time_ms defines the time that once started, the safety_active_damper will remain active for. Once this timer expires the motor controller will transition to standby and all control action will be disabled. The motor will freewheel.

Write 0 to safe_active_damper_active_time_ms to disable the timer expiry. When the timer expiry is disabled safety_active_damper will remain active until the user disables it.

Parameters:

Command	Type	Required	Description
`safe_active_damper_coeff`	float32	Required	Damping coefficient. Units are dependent on parameter 'motor_Kt'.
`safe_active_damper_active_time_ms`	uint32	Required	Controller active time (ms). Default: 10000ms

safety_active_damper relies on current_dq being configured correctly as it relies on current_dq for the underlying current control.

The active damper safety controller is robust to most safe-shutdown estops. It is robust to DC bus voltage collapse until v_dc_limit_error_l is reached, upon which a critical estop is generated and the drive will shutdown. The motor will freewheel.

Controller mode: safety_active_passive_damper

The active-passive damper safety controller performs the same damping action as safety_active_damper, however once the the mechanical velocity of the commutation encoder drops below safe_active_passive_w_threshold all control action is disabled and the bottom three MOSFETs of the bridge are enabled. This is the passive component of the controller.

Enabling the bottom three MOSFETs effectively shorts the three motor phases and causes the motor winding currents to recirculate. The effect is a braking action that does not require full current control. The passive controller action is robust to DC bus voltage collapse past v_dc_limit_error_l, where safety_active_damper is not.

Consideration of the active-to-passive safe_active_passive_w_threshold parameter is required as the passive damping component is either on or off. No variable damping is available. If the motor speed is too high at the transition then huge phase currents can be generated and a critical estop may be generated if the phase currents reach the hard limits. The drive will free-wheel the motor and negate any passive damping attempts.

Controller operation

Active phase

When started, safety_active_passive_damper begins active damping according to the control law:

\[i_{q} = -b\omega_{m}\]

where \(b\) is the damping coefficient configured with parameter safe_active_damper_coeff and \(\omega_{m}\) is the mechanical velocity (Rad/s).

The intent here is that motor begins to slow down.

If parameter safe_active_damper_active_time_ms is set to zero then the controller will remain in the active phase until the velocity is below safe_active_passive_w_threshold, or until the user stops the controller. If parameter safe_active_damper_active_time_ms is greater than zero, then the controller will remain in the active phase until the timer expires. Once the timer expires the controller will attempt to transition to the passive phase if the velocity is below safe_active_passive_w_threshold, or it will force transition to the passive phase if safe_active_passive_force_passive is set to true. If the controller can not transition to the passive state when the timer expires then the controller will disable all outputs and transition to the standby state. The motor will freewheel.

Passive phase

When the controller transitions to the passive phase all active control action stops and the motor phases are shorted together by means of enabling the bottom three MOSFETs of the power electronics. Current recirculation in the motor windings begins and an uncontrolled braking action on the motor takes place.

If parameter safe_active_passive_passive_time_ms is set to zero then the controller will remain in the passive phase until the user stops the controller. if parameter safe_active_passive_passive_time_ms is greater than zero, them the controller will remain in the passive phase until the timer expires. Once the timer expires the controller will disable all outputs and transition to standby state. The motor will freewheel, however ideally the motor will be stopped when this timer expires.

Controller configuration

The following parameters are available for configuration

Command	Type	Required	Description
`safe_active_damper_coeff`	float32	Required	Damping coefficient. Units are dependent on parameter 'motor_Kt'.
`safe_active_damper_active_time_ms`	uint32	Optional	Controller active time (ms). Default: 10000ms
`safe_active_passive_w_threshold`	float32	Optional	Mechanical velocity active to passive transition threshold. Default: 20Rad/s
`safe_active_passive_passive_time_ms`	uint32	Optional	Controller passive time (ms). Default: 10000ms
`safe_active_passive_force_passive`	bool	Optional	Controller force passive mode at active timeout Default: false

safety_active_passive_damper relies on current_dq being configured correctly as it relies on current_dq for the underlying current control.

Choosing `safe_active_damper_coeff`

Parameter safe_active_damper_coeff sets the \(i_{q}\) current during the active damping phase.

Choose a value of safe_active_damper_coeff that ensures the motor slows down fast enough that the safe_active_passive_w_threshold threshold is reached before safe_active_damper_active_time_ms times out.

Note: \(i_{q}\) is clamped to 90% of the maximum phase current.

Special consideration for DC bus voltage loss

safety_active_passive_damper controller is particularly useful for mitigating against DC bus voltage loss and is robust to DC bus collapse past v_dc_limit_error_l, however some configuration is required.

Set the DC bus voltage low warning parameter v_dc_limit_warning_l to some voltage above v_dc_limit_error_l (see specifications - typically around 20V). Parameter v_dc_error_on_warning should be set to true, so that a safe estop is generated as the DC bus voltage falls. The safety controller will be enabled when the safe estop is generated.

See Health for further information.

Example

A motor controller is connected to a 56V DC bus. We expect the DC bus voltage to vary from 40V to 56V during normal operation. The controller has a 20V minimum DC bus voltage and will shut down if this voltage is reached.

We have a safety switch between the batteries and the motor controllers. If the safety switch is triggered, the DC bus voltage to the motors will be shut off and the robot will fall on the ground. We want to enable the active-passive damper to "catch" the robot if this happens, and allow it to slowly drop to the ground so it does not break. We set v_dc_limit_warning_l to 30V to allow enough time for the safety controller to activate and begin to function as the DC bus collapses.

  ########################################################################
  # Safety configuration
  # On event of network e-stop we want to swap to a safe controller
  network_estop_config: estop_safe_controller

  # The safe controller is the active-passive damper
  controller_estop_safe_mode: safety_active_passive_damper

  # Configuration
  safe_active_damper_coeff: 0.1
  # The active time will be left as default, but we want the controller
  # to shut down after 20secs as our robot will take a while to slowly 
  # collapse to the ground
  safe_active_passive_passive_time_ms: 200000

  # We want to generate a safe estop
  v_dc_error_on_warning: true
  # When the DC bus voltage hits the low warning level
  v_dc_limit_warning_l: 30.0

  # We want to generate a safe estop
  temperature_error_on_warning: true
  # If the board temperature hits the high warning level
  temperature_limit_warning_h: 90.0

Controller mode: safety_control_off

The safety_control_off outputs no control action.

Controller Timing Statistics

The main controller executes within an interrupt routine. The following timing statistics are available to examine the performance of the controller:

Command	Type	Required	Description
`ctl_timing_step_max_us`	uint32	Optional	The maximum ISR execution time (us).
`ctl_timing_step_ave_us`	uint32	Optional	The average ISR execution time (us)
`ctl_timing_interval_us`	uint32	Optional	The time interval between ISR calls (us)
`ctl_timing_overrun_count`	uint32	Optional	Number of ISR overruns

Write a zero to any of these parameters to reset them.

Controller Modes

Controller modes

Controller mode: current_dq

Configuration parameters

PI current controllers

Motor torque constant

Invert incoming current command

DQ axis current measurement and command filters

Current controller decoupling

Cogging torque compensation

D-Axis flux braking

Controller mode: voltage_dq

Invert incoming voltage command

Controller mode: test_align

Controller mode: test_dq_l

Controller mode: test_dq_r

Controller mode: test_dq_step_response

Safety controllers

Configuration

Controller mode: safety_active_damper

Controller mode: safety_active_passive_damper

Controller operation

Active phase

Passive phase

Controller configuration

Choosing safe_active_damper_coeff

Special consideration for DC bus voltage loss

Example

Controller mode: safety_control_off

Controller Timing Statistics

Choosing `safe_active_damper_coeff`