odrivetool Setup

GUI Wizard

Checkout our GUI Wizard for an enhanced graphical setup experience.

Important

Make sure you have odrivetool installed before continuing (pip install --upgrade odrive)

Configure Power Supply

AC/DC Power SupplyBattery

Use this configuration if you’re powering the ODrive from a power supply that plugs into the grid.

Note

Most AC/DC power supplies do not accept reverse current, make sure any regenerated power is effectively dissipated.

Please adapt the ??? placeholders below. dc_bus_overvoltage_trip_level is the overvoltage fault level and should be set to a value that will protect it from overvoltage damage. For instance if your power supply outputs 24V a reasonable value is 30. dc_max_positive_current is the overcurrent fault level and should be set to a value that will protect your power source from overcurrent damage. dc_max_negative_current is the regenerated current fault level, it is a negative value.

odrv0.config.dc_bus_overvoltage_trip_level = ???
odrv0.config.dc_max_positive_current = ???
odrv0.config.dc_max_negative_current = -0.01

Additionally, on ODrive S1 if you have a brake resistor connected:

odrv0.config.brake_resistor0.resistance = ??? # resistance in Ohms
odrv0.config.brake_resistor0.enable = True
odrv0.clear_errors()

Motor Configuration

We only list configurations for the most commonly used motors here. If you’re using a different motor, you can use these scenarios as reference and read up on the documentation of the settings to adapt them for your motor.

D5065 270KVD6374 150KVBotWheelGimbal MotorOther

odrv0.axis0.config.motor.motor_type = MotorType.HIGH_CURRENT
odrv0.axis0.config.motor.pole_pairs = 7
odrv0.axis0.config.motor.torque_constant = 8.27 / 270
odrv0.axis0.requested_state = AxisState.MOTOR_CALIBRATION
# [wait for end of motor beep]
odrv0.save_configuration()

set_motor_thermistor_coeffs(odrv0.axis0, Rload=1000, R_25=10000, Beta=3435, Tmin=-10, Tmax=150, thermistor_bottom=True)
# thermistor must be connected
odrv0.axis0.motor_thermistor.config.enabled = True
odrv0.save_configuration()

Warning

If you change the motor, make sure to re-run the motor calibration.

What’s the point of motor calibration?

Motor calibration measures your motor’s electrical properties (namely phase resistance and phase inductance). It uses this information to set its current controller gains.

If using motor thermistor Please see the Thermistors page for setup.

Setting the Limits

Current limit

odrv0.axis0.config.motor.current_soft_max = 10 # [A] (adapt this to your motor)
odrv0.axis0.config.motor.current_hard_max = 18 # [A] (should be more than soft max)

It is recommended to set the soft max to something quite weak to start with, but strong enough to overcome friction in your system with a decent margin. Once you have built confidence in the stability of the control and strength of your mechanical setup, you can increase these. For high current motors you need to turn this up to get high performance, and for low current motors such as the BotWheel you need to use something that’s lower than the examples shown above.

The recommended maximum for current_soft_max is the continuous current rating of your motor if you are not using motor thermistor temperature feedback, and the peak current rating of your motor if you are using it. The value for current_hard_max is a fault trip level and should be set to a level above current_soft_max. The appropriate level is a tradeoff between getting nuisance faults especially during high accelerations, and ability to catch unstable current control situations. The recommended maximum is the current your motor can handle for 50ms.

Note

The motor current and the current drawn from the power supply is not the same in general. You should not look at the power supply current to see what is going on with the motor current.

Ok, so tell me how it actually works then…

The current in the motor is only connected to the current in the power supply sometimes and other times it just cycles out of one phase and back in the other. This is what the modulation magnitude is (sometimes people call this duty cycle, but that’s a bit confusing because we use SVM not straight PWM). When the modulation magnitude is 0, the average voltage seen across the motor phases is 0, and the motor current is never connected to the power supply. When the magnitude is 100%, it is always connected, and at 50% it’s connected half the time, and cycled in just the motor half the time.

The largest effect on modulation magnitude is speed. There are other smaller factors, but in general: if the motor is still it’s not unreasonable to have 50A in the motor from 5A on the power supply. When the motor is spinning close to top speed, the power supply current and the motor current will be somewhat close to each other.

Velocity limit

odrv0.axis0.controller.config.vel_limit = 2 # [turn/s]

The motor will be limited to this speed. Again the default value is quite slow.

Temperature limits

odrv0.axis0.motor_thermistor.config.temp_limit_lower = 100 # °C (adapt this to your motor)
odrv0.axis0.motor_thermistor.config.temp_limit_upper = 120 # °C (adapt this to your motor)

Please see Over Temperature Current Limiting for more information.

Encoder Configuration

Note

The rotor must be allowed to rotate without any biased load during encoder calibration. That means mass and weak friction loads are fine, but gravity or spring loads are not okay. Heavier loads are not advised, it is recommended that you lift any wheeled robot off the ground.

AMT102AMT102 with indexAMT21ODrive OA1 encoderHall Effect SensorsBotWheelOnboard EncoderSPI EncoderSensorless Mode

The following commands assume you have the encoder connected to the Motor I/O connector.

Connecting the A, B phases is mandatory, the Z (index pulse) is optional.

odrv0.inc_encoder0.config.cpr = 8192
odrv0.inc_encoder0.config.enabled = True
odrv0.axis0.config.load_encoder = EncoderId.INC_ENCODER0
odrv0.axis0.config.commutation_encoder = EncoderId.INC_ENCODER0
odrv0.save_configuration()
# [wait for ODrive to reboot]
odrv0.axis0.requested_state = AxisState.ENCODER_OFFSET_CALIBRATION
# [wait for motor to stop]

After each subsequent reboot you need to re-run odrv0.axis0.requested_state = AxisState.ENCODER_OFFSET_CALIBRATION before you can activate position/velocity control.

What’s the point of encoder calibration?

Encoder offset calibration measures the offset between the motor’s electrical phase and the encoder position. This is needed so the ODrive knows in which orientation to generate a stator magnetic field depending on rotor orientation.

Help, something isn’t working!

Check the encoder wiring and that the encoder is firmly connected to the motor. Check the value of dump_errors(odrv0) and then refer to the error code documentation for details.

Once you understand the error and have fixed its cause, you may clear the error state with odrv0.clear_errors() Enter and retry.

Motor doesn’t move?

This could be because of high inertia or strong friction or cogging torque. Try increasing odrv0.axis0.config.motor.calibration_current [A] in steps of around 50%. Do not go higher than half of the maximum continuous current rating of your motor. If the motor still doesn’t move you may need to change something mechanically to reduce load torque.

Viewing Encoder Feedback

Position and velocity feedback from the load_encoder can be found by entering

odrv0.axis0.pos_estimate
# or
odrv0.axis0.vel_estimate

Position Control

Warning

Make sure you have a good mechanical connection between the encoder and the motor, slip can cause disastrous oscillations or runaway.

1. Enter closed loop control mode by setting odrv0.axis0.requested_state to AxisState.CLOSED_LOOP_CONTROL.

   From now on the ODrive will try to hold the motor’s position. If you try to turn it by hand, it will fight you gently. That is unless you bump up odrv0.axis0.config.motor.current_soft_max, in which case it will fight you more fiercely. If the motor begins to vibrate either immediately or after being disturbed you will need to lower the controller gains.

2. Send the motor a new position setpoint by setting odrv0.axis0.controller.input_pos to 1.

   The units are in turns.

3. At this point you will probably want to properly tune the motor controller in order to maximize system performance.

Other Control Modes

The default control mode is unfiltered position control relative to the startup position of the axis. You may wish to use a controlled trajectory instead. Or you may wish to control position in a circular frame to allow continuous rotation forever without growing the numeric value of the setpoint too large.

You may also wish to control velocity (directly or with a ramping filter). You can also directly control the torque of the motor.

For this and more, refer to Control Modes.

What’s Next?

You can now:

• Properly tune the motor controller to unlock the full potential of the ODrive.

• See what other commands and parameters are available, in order to better control the ODrive.

• Control the ODrive from your own program or hook it up to an existing system through one of it’s interfaces.

• See how you can improve the behavior during the startup procedure.

If you have any issues or any questions please get in touch. The ODrive Community warmly welcomes you.