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
ori_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:
Where \(R\) is the braking resistance, which may be calculated from Ohms law as:
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 beginsDefault: \(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 usingv_dc_error_on_warning
setting. If the flux brake saturates and the DC bus voltage rises abovev_dc_limit_warning_h
an estop may be generated ifv_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
orv_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
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:
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.