Controller
Structure
The motor controller is a cascaded style position, velocity and current control loop, as per the diagram below. When the control mode is set to position control, the whole loop runs. When running in velocity control mode, the position control part is removed and the velocity command is fed directly in to the second stage input. In torque control mode, only the current controller is used.

Cascaded position and velocity I loops
Each stage of the control loop is a variation on a PID controller. A PID controller is a mathematical model that can be adapted to control a wide variety of systems. This flexibility is essential as it allows the ODrive to be used to control all kinds of mechanical systems.
Note
The controller has been updated to use torque in Newton-meters instead of current at the “system” level.
There is a torque_constant
parameter which converts between torque and current, after which the rest of this explanation still holds.
Position Control loop
The position controller is a P loop with a single proportional gain,
pos_error = pos_setpoint - pos_feedback, vel_cmd = pos_error * pos_gain + vel_feedforward.
Velocity Control Loop
The velocity controller is a PI loop where
vel_error = vel_cmd - vel_feedback, current_integral += vel_error * vel_integrator gain, current_cmd = vel_error * vel_gain + current_integral + current_feedforward.
Current Control Loop
The current controller is also a PI loop,
current_error = current_cmd - current_feedback, voltage_integral += current_error * current_integrator gain, voltage_cmd = current_error * current_gain + voltage_integral + ... ... + voltage_feedforward (when we have motor model).
Note
current_gain and current_integrator_gain are automatically set according to config.motor.current_control_bandwidth
Control Modes
Filtered Position Control
Asking the ODrive controller to go as hard as it can to raw setpoints may result in jerky movement. Even if you are using a planned trajectory generated from an external source, if that is sent at a modest frequency, the ODrive may chase each stair in the incoming staircase in a jerky way. In this case, a good starting point for tuning the filter bandwidth is to set it to one half of your setpoint command rate.
You can use the second order position filter in these cases.
odrv0.axis0.controller.config.input_filter_bandwidth = 2.0 # Set the filter bandwidth [1/s]
odrv0.axis0.controller.config.input_mode = InputMode.POS_FILTER # Activate the setpoint filter
odrv0.axis0.controller.input_pos = 1 # control the position [turns]
Step response of a 1000 to 0 position input with a filter bandwidth of 1.0 [/sec].
Trajectory Control
See the :usage section for details. This mode lets you smoothly accelerate, coast, and decelerate the axis from one position to another. With raw position control, the controller simply tries to go to the setpoint as quickly as possible. Using a trajectory lets you tune the feedback gains more aggressively to reject disturbance, while keeping smooth motion.
Position (blue) and velocity (orange) vs. time using trajectory control.
Note
Trajectory control is not compatible with circular mode
(<axis>.controller.config.circular_setpoints
).
Parameters
odrv0.axis0.trap_traj.config.vel_limit = <Float>
odrv0.axis0.trap_traj.config.accel_limit = <Float>
odrv0.axis0.trap_traj.config.decel_limit = <Float>
odrv0.axis0.controller.config.inertia = <Float>
vel_limit
is the maximum planned trajectory speed. This sets your coasting speed.accel_limit
is the maximum acceleration in turns / sec^2decel_limit
is the maximum deceleration in turns / sec^2controller.config.inertia
is a value which correlates acceleration (in turns / sec^2) and motor torque. It is 0 by default. It is optional, but can improve response of your system if correctly tuned. Keep in mind this will need to change with the load / mass of your system.
Note
All values should be strictly positive (>= 0).
Keep in mind that you must still set your safety limits as before. It is recommended you set these a little higher ( > 10%) than the planner values, to give the controller enough control authority.
odrv0.axis0.config.motor.current_soft_max = <Float>
odrv0.axis0.controller.config.vel_limit = <Float>
Usage
Make sure you are in position control mode. To activate the trajectory module, set the input mode to trajectory:
odrv0.axis0.controller.config.input_mode = InputMode.TRAP_TRAJ
Simply send a position command to execute the move:
odrv0.axis0.controller.input_pos = <Float>
Use the move_incremental
function to move to a relative position.
odrv0.axis0.controller.move_incremental(pos_increment, from_goal_point)
To set the goal relative to the current actual position, use from_goal_point = False
To set the goal relative to the previous destination, use from_goal_point = True
You can also execute a move with the appropriate ascii command.
Circular Position Control
To enable Circular position control, set
odrv0.axis0.controller.config.circular_setpoints = True
This mode is useful for continuous incremental position movement.
For example a robot rolling indefinitely, or an extruder motor or conveyor belt moving with controlled increments indefinitely.
In the regular position mode, the input_pos
would grow to a very large value and would lose precision due to floating point rounding.
In this mode, the controller will try to track the position within only one turn of the motor. Specifically, input_pos
is expected in the range [0, 1).
If the input_pos
is incremented to outside this range (say via step/dir input), it is automatically wrapped around into the correct value.
Note that in this mode encoder.pos_circular
is used for feedback instead of encoder.pos_estimate
.
If you try to increment the axis with a large step in one go that exceeds 1 turn, the motor will go to the same angle around the wrong way. This is also the case if there is a large disturbance. If you have an application where you would like to handle larger steps, you can use a larger circular range. Set
odrv0.axis0.controller.config.circular_setpoints_range = <N>
Choose N to give you an appropriate circular space for your application.
Absolute Position Control
The ODrive, by default, interprets position commands relative to its startup position.
If you prefer to issue position commands with respect to an absolute reference frame for your machine,
you can activate this by setting <axis>.controller.config.absolute_setpoints
to True
.
Note that this usually necessitates a homing procedure each time the ODrive starts up before you can switch to position control. This is regardless of whether you’re using a relative or absolute encoder.
However, you can avoid homing under two circumstances:
If you can ensure that the physical position of the axis is always within +/- 0.5 turns of a predefined center position. More on this below.
If you are only concerned with the absolute angle but not the total turn count. Again, see below for more details. Alternatively, this can be achieved using Circular Position Control with an absolute encoder (or an incremental encoder with index signal).
Using a Well-known Startup Position
If you’re using an absolute encoder, even though the ODrive knows the encoder angle immediately at startup, it can in general not know the absolute position on a multi-turn axis. For example, if your axis has a motion range of five turns, there are five possible axis positions that any known encoder angle can correspond to.
However if the user is able to guarantee the approximate startup position within +- half of an encoder turn, the ODrive can combine this information with the measured encoder angle to determine the exact absolute axis position at startup without homing.
The following example shows how to configure this feature. The example assumes that your ODrive is already configured for (relative) position control.
odrv0.axis0.pos_vel_mapper.config.offset
= 0.0 # change this if you want the meaning of "position setpoint zero" to differ from the encoder's zeroodrv0.axis0.pos_vel_mapper.config.offset_valid
= Trueodrv0.axis0.pos_vel_mapper.config.approx_init_pos
= 0.0 # change this if the guaranteed startup range is different from [-0.5, +0.5].odrv0.axis0.pos_vel_mapper.config.approx_init_pos_valid
= Trueodrv0.axis0.controller.config.absolute_setpoints
= True
This example sets both offset
and approx_init_pos
to 0.0. While this might not represent your final configuration, it’s generally easier to begin with these settings. After executing odrv0.save_configuration()
, the position estimate odrv0.axis0.pos_vel_mapper.pos_abs
will be immediately available without needing a homing procedure.
At this point, you can examine the pos_abs
output to better understand if you need to adjust the offset
(should you wish to shift the setpoint zero position) or alter the approx_init_pos
(if the center of the startup range needs refining).
Velocity Control
Set the control mode
odrv0.axis0.controller.config.control_mode = ControlMode.VELOCITY_CONTROL
You can now control the velocity [turn/s] with
odrv0.axis0.controller.input_vel = 1
Ramped Velocity Control
Set the control mode
odrv0.axis0.controller.config.control_mode = ControlMode.VELOCITY_CONTROL
Set the velocity ramp rate (acceleration in turn/s^2):
odrv0.axis0.controller.config.vel_ramp_rate = 0.5
Activate the ramped velocity mode:
odrv0.axis0.controller.config.input_mode = InputMode.VEL_RAMP
You can now control the velocity (turn/s) with
odrv0.axis0.controller.input_vel = 1
Torque Control
Set the control mode
odrv0.axis0.controller.config.control_mode = ControlMode.TORQUE_CONTROL
Set the torque constant, e.g.:
# Approximately 8.23 / Kv where Kv is in the units [rpm / V]
odrv0.axis0.config.motor.torque_constant = 8.23 / 150
You can now control the torque (Nm) with e.g.
odrv0.axis0.controller.input_torque = 0.1
Note
For safety reasons, the torque mode velocity limiter is enabled by default.
This works by reducing the torque of the motor according to vel_limit
and vel_gain
, as shown below.
Please note that with the default settings, torque will be limited even at 0 rpm.

The torque mode velocity limiter can be completely disabled by setting:
odrv0.axis0.controller.enable_torque_mode_vel_limit = False