ODrive/docs/commands.md

Parameters & Commands

Each axis can be controlled independently. Most parameters can be set per axis. They are referred to as ``

State Machine

Each axis has an independent state machine. The default state after startup is AXIS_STATE_IDLE. The current state is indicated by .current_state. The user can request a new state by assigning a new value to .requested_state.

1. AXIS_STATE_IDLE Disable motor PWM and do nothing.
2. AXIS_STATE_STARTUP_SEQUENCE Run the startup procedure.
3. AXIS_STATE_FULL_CALIBRATION_SEQUENCE Run motor calibration and then encoder offset calibration (or encoder index search if .encoder.use_index is True).
4. AXIS_STATE_MOTOR_CALIBRATION Measure phase resistance and phase inductance.
   • To store the results set .motor.config.pre_calibrated to True and save the configuration. After that you don't have to run the motor calibration on the next start up.
   • This modifies the variables .motor.config.phase_resistance and .motor.config.phase_inductance.
5. AXIS_STATE_SENSORLESS_CONTROL Run sensorless control.
   • The motor must be calibrated (.motor.is_calibrated)
   • .controller.control_mode must be True.
6. AXIS_STATE_ENCODER_INDEX_SEARCH Turn the motor in one direction until the encoder index is traversed. This state can only be entered if .encoder.config.use_index is True.
7. AXIS_STATE_ENCODER_OFFSET_CALIBRATION Turn the motor in one direction for a few seconds and then back to measure the offset between the encoder position and the electrical phase.
   • Can only be entered if the motor is calibrated (.motor.is_calibrated).
   • A successful encoder calibration will make the .encoder.is_ready go to true.
8. AXIS_STATE_CLOSED_LOOP_CONTROL Run closed loop control.
   • The action depends on the control mode.
   • Can only be entered if the motor is calibrated (.motor.is_calibrated) and the encoder is ready (.encoder.is_ready).

Startup Procedure

By default the ODrive takes no action at startup and goes to idle immediately. This behavior can be changed by modifying the following parameters:

• .config.startup_motor_calibration
• .config.startup_encoder_index_search
• .config.startup_encoder_offset_calibration
• .config.startup_closed_loop_control
• .config.startup_sensorless_control

See state machine for a description of each state.

Control Mode

By default both motors are enabled, and the default control mode is position control. If you want a different mode, you can change odrv0.motorN.config.control_mode. Possible values are:

• CTRL_MODE_POSITION_CONTROL
• CTRL_MODE_VELOCITY_CONTROL
• CTRL_MODE_CURRENT_CONTROL
• CTRL_MODE_VOLTAGE_CONTROL - this one is not normally used.

To disable a motor at startup, set odrv0.axisN.config.enable_control and odrv0.axisN.config.do_calibration to False.

Tuning parameters

The motion control gains are currently manually tuned:

• odrv0.motorN.config.pos_gain = 20.0f [(counts/s) / counts]
• odrv0.motorN.config.vel_gain = 15.0f / 10000.0f [A/(counts/s)]
• odrv0.motorN.config.vel_integrator_gain = 10.0f / 10000.0f [A/((counts/s) * s)]

An upcoming feature will enable automatic tuning. Until then, here is a rough tuning procedure:

• Set the integrator gain to 0
• Make sure you have a stable system. If it is not, decrease all gains until you have one.
• Increase vel_gain by around 30% per iteration until the motor exhibits some vibration.
• Back down vel_gain to 50% of the vibrating value.
• Increase pos_gain by around 30% per iteration until you see some overshoot.
• Back down pos_gain until you do not have overshoot anymore.
• The integrator is not easily tuned, nor is it strictly required. Tune at your own discression.

Saving the configuration

All variables that are part of a [...].config object can be saved to non-volatile memory on the ODrive so they persist after you remove power. The relevant commands are:

• odrv.save_configuration(): Stores the configuration to persistent memory on the ODrive.
• odrv.erase_configuration(): Resets the configuration variables to their factory defaults. This only has an effect after a reboot. A side effect of this command is that motor control stops (in case it was running) and the USB communication breaks out temporarily. This is because erasing flash pages hangs the microcontroller for several seconds.