ODrive Overview

We will use the <odrv> as a placeholder for any ODrive object. Every ODrive controller is an ODrive object. In odrivetool and the Web GUI this is usually odrv0. Furthermore we use <axis> as a placeholder for any axis, which is an attribute of an ODrive object (for example odrv0.axis0). An axis represents where the motors are connected.

System Status LED

The current status of the ODrive can be observed by the color the LED:

• blue/teal: The ODrive is idle. It will not move, and has no errors.

• green: The ODrive is active and running.

• red: An error has occurred and the ODrive is disabled. Please refer to the troublshooting page for more information.

Per-Axis Commands

For the most part, both axes on the ODrive can be controlled independently.

State Machine

The current state of an axis is indicated by <axis>.current_state. The user can request a new state by assigning a new value to <axis>.requested_state. The default state after startup is AxisState.IDLE. A description of all states can be found here.

Startup Procedure

By default, the ODrive takes no action at startup and goes to idle immediately. In order to change what startup procedures are used, set the startup procedures you want to True. The ODrive will sequence all enabled startup actions selected in the order shown below.

• <axis>.config.startup_motor_calibration

• <axis>.config.startup_encoder_index_search

• <axis>.config.startup_encoder_offset_calibration

• <axis>.config.startup_closed_loop_control

See here for a description of each state.

Control Mode

The default control mode is position control. ControlMode.POSITION_CONTROL If you want a different mode, you can change <axis>.controller.config.control_mode. Possible values are listed here.

Control Commands

• <axis>.controller.input_pos = <turn>

• <axis>.controller.input_vel = <turn/s>

• <axis>.controller.input_torque = <torque in Nm>

Modes can be selected by changing <axis>.controller.config.input_mode. The default input mode is InputMode.PASSTHROUGH. Possible values are listed here.

System Monitoring Commands

Encoder Position and Velocity

• View the position with <axis>.pos_estimate [turns] (See also Position Reference Frame)

• View rotational velocity with <axis>.vel_estimate [turn/s]

Motor Current and Torque Estimation

• View the commanded motor current with <axis>.foc.Iq_setpoint [A]

• View the measured motor current with <axis>.foc.Iq_measured [A].

Noisy Iq_measured

If you find that this returns noisy data then use the command motor current instead. The two values should be close so long as you are not approaching the maximum achievable rotational velocity of your motor for a given supply voltage, in which case the commanded current may become larger than the measured current.

Using the motor current and the known KV of your motor you can estimate the motors torque using the following relationship:

Torque [N.m] = 8.27 * Current [A] / KV

General System Commands

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 also reboots the device.

Diagnostics

• <odrv>.serial_number: A number that uniquely identifies your device. When printed in upper case hexadecimal (hex(<odrv>.serial_number).upper()), this is identical to the serial number indicated by the USB descriptor.

• <odrv>.fw_version_major, <odrv>.fw_version_minor, <odrv>.fw_version_revision: The firmware version that is currently running.

• <odrv>.hw_version_major, <odrv>.hw_version_minor, <odrv>.hw_version_revision: The hardware version of your ODrive.

User Storage

The variables config.user_config_0, config.user_config_1, etc. allow storing a small amount of non-volatile user data on the ODrive for arbitrary user-defined purposes.

An example where this is useful is when you have integrated ODrive + Motor units which are assembled or handled separately from the rest of the robot, and you need to attach some user-defined calibration or identification data to each drive unit individually.

Like any other config values, these variables are saved and erased using save_configuration() and erase_configuration().

Note that the ODrive only supports a limited amount of config write cycles, so it is not recommened to use this for dynamic data.

For larger data or dynamic data, consider using storage on the host side.