odrivetool

The odrivetool is the accompanying PC program for the ODrive. It’s main purpose is to provide an interactive shell to control the device manually, as well as some supporting functions like firmware update.

Installation

Refer to the Getting Started guide.

Type odrivetool --help to see what features are available.

Multiple ODrives

By default, odrivetool will connect to any ODrive it finds. If this is not what you want, you can select a specific ODrive.

To find the serial number of your ODrive, run odrivetool, connect exactly one ODrive and power it up. You should see this:

Connected to ODrive 306A396A3235 as odrv0
In [1]:

306A396A3235 is the serial number of this particular ODrive. If you want odrivetool to ignore all other devices you would close it and then run:

odrivetool --serial-number 306A396A3235

Commands and Objects

The ODrive Tool console provides aliases and wrappers for various entities in the odrive Python package. These are optimized for interactive use. When you write your own Python script that does import odrive, these wrappers are not available.

shell.odrv0: ODrive

First ODrive that is connected. The next ODrive is called odrv1 etc…

shell.dump_errors(odrv: ODrive)

Alias for odrive.utils.dump_errors()

shell.start_liveplotter(*args)

Alias for odrive.utils.start_liveplotter()

shell.status(config: odrive.config.MachineConfig)

Wrapper for config.show_status(odrives)

shell.apply(config: odrive.config.MachineConfig)

Wrapper for config.apply(odrives)

shell.calibrate(config: odrive.config.MachineConfig)

Wrapper for config.calibrate(odrives)

shell.odrives

Dictionary of all currently connected ODrives

Liveplotter

Liveplotter is used for the graphical plotting of ODrive parameters (i.e. position) in real time.

Note

This is an experimental feature. Please use the Web GUI for liveplotting instead.

Example 1

In this example we plot the position of two motors. They are both running in AxisState.CLOSED_LOOP_CONTROL while they are being forced off position by hand.

start_liveplotter(lambda: [
    odrv0.axis0.pos_vel_mapper.pos_rel,
    odrv1.axis0.pos_vel_mapper.pos_rel,
])
_images/liveplotter-pos-estimate.png

Example 2

In this example we plot the approximate motor torque [Nm] and the velocity [RPM] of axis0.

start_liveplotter(lambda: [
    ((odrv0.axis0.pos_vel_mapper.vel*60), # turns/s to rpm
    ((odrv0.axis0.foc.Iq_setpoint * my_odrive.axis0.config.motor.torque_constant), # Torque [Nm]
])

The motor is forced off axis by hand and held there. In response the motor controller increases the torque (orange line) to counteract this disturbance up to a peak of 500 N.cm at which point the motor current limit is reached. When the motor is released it returns back to its commanded position very quickly as can be seen by the spike in the motor velocity (blue line).

_images/liveplotter-iq-omega.png

Liveplotter Torque Velocity Plot

Liveplotter from Interactive odrivetool Instance

You can also run start_liveplotter(...) directly from the interactive odrivetool prompt. This is useful if you want to issue commands or otherwise keep interacting with the odrive while plotting.

For example you can type the following directly into the interactive prompt:

start_liveplotter(lambda: [odrv0.axis0.pos_vel_mapper.pos_rel])

Just like the examples above, you can list several parameters to plot separated by comma in the square brackets. In general, you can plot any variable that you are able to read like normal in odrivetool.

Configuration Backup

You can use odrivetool to back up and restore device configurations or transfer the configuration of one ODrive to another one.

  • To save the configuration to a file on the PC, run

    odrivetool backup-config my_config.json
    
  • To restore the configuration form such a file, run

    odrivetool restore-config my_config.json
    

Note

The encoder offset calibration is not restored because this would be dangerous if you transfer the calibration values of one axis to another axis.

Note

It is not recommened to transfer the configuration between different firmware versions because variables can get renamed or removed (in which case odrivetool will show warnings) or defaults changed between firmware versions. After firmware updates it is instead recommended to check the Changelog and manually transfer the settings.