odrivetool

odrivetool is the command line tool accompanying the ODrive. Its main purpose is to provide an interactive shell to control the device using text-based input, as well as some supporting functions like firmware update.

If you prefer a graphical user interface instead, consider using the Web GUI.

System Requirements

⇒ See Python Package

Installation

WindowsmacOSLinux

1. Install Python 3: Download the installer for Latest Python 3 Release from here. Execute the downloaded file and follow the instructions. In the installer, make sure to check “Add python.exe to PATH”.

2. Launch the command prompt: In the start menu, type cmd Enter. The instructions in the next steps are commands to be typed into the command prompt.

3. Optional: Install matplotlib (only needed if you’re going to use the Liveplotter).

   Command Line

   python3 -m pip install matplotlib
   

4. Install odrivetool.

   Command Line

   python3 -m pip install --upgrade odrive
   

Troubleshooting

• If you get 'python3' not recognized as an internal or external command, Python might not be in your PATH environment variable. Python comes with a small script that can fix this. Navigate to the Python install folder (usually C:\Program Files\Python<version>\ or C:\Users\<YourUsername>\AppData\Local\Programs\Python\Python<version>\) and double-click “win_add2path.py” to run it.

• See this walkthrough for more tips if the Python installation doesn’t work as expected.

Start odrivetool

After installation is complete, you can launch the interactive console with

Command Line

odrivetool

Connect your ODrive and wait for the tool to find it. If it doesn’t connect after a few seconds, refer to the troubleshooting page. Now you can, for instance, type odrv0.vbus_voltage Enter to display the board’s main supply voltage. It should look something like this:

odrivetool

ODrive control utility v0.5.1
Please connect your ODrive.
Type help() for help.

Connected to ODrive 306A396A3235 as odrv0
In [1]: odrv0.vbus_voltage
Out[1]: 11.97055721282959

The tool you’re looking at is a fully capable Python command prompt, so you can type any valid python code.

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

Using odrivetool via CAN

⇒ New in odrivetool 0.6.11. Requires Firmware 0.6.11 or newer (See Firmware Update)

Note

ODrivetool-over-CAN requires the latest Python package (v0.6.11.post0).

To upgrade, run python3 -m pip install --upgrade odrive.

Please let us know any feedback or issues via the forums, Discord, or email.

For general advice on CAN wiring, see CAN hardware setup.

Windows, macOSLinux

You will need a supported USB-CAN adapter (e.g. ODrive USB-CAN Adapter). Once the adapter is connected to the ODrive and the computer, run odrivetool as usual without any arguments. odrivetool will automatically detect the adapter and connect to all ODrives on the bus. By default, it will connect using a baudrate of 1Mbps. To use a different baudrate, run odrivetool --usbcan 500000 (replace with your desired baudrate). See also Which baudrate to select?.

Which baudrate to select?

In the default configuration, the ODrive automatically detects the baudrate of the CAN bus once there is regular bus activity. This means you can select any compatible baudrate on the host side, and the ODrive will adapt to it. For optimal performance, we recommend using a baudrate of 1Mbps. If other (non-ODrive) devices are on the bus or if you have very long cables, you may need to use a lower baudrate.

Commands and Objects

See also: Python Package.

The odrivetool console is a Python console (more precisely: IPython) with a few extras. The following commands and functions are available:

• All built-in Python commands and functions.

• ODrives are accessible via odrv0, odrv1, etc. The attributes on these ODrive objects are defined by the API that the ODrive exposes and can change when you update the ODrive’s firmware. The full API is documented in the API Reference.

• Additional helper functions, such as dump_errors(odrv0) are available. More precisely, all members of the module odrive.utils are available.

Below is a quick summary of helper functions. Click on a name to show more details, or visit odrive.utils for a complete list.

dump_errors(odrv[, clear])	Prints a summary of the error status of the device on stdout.
start_liveplotter(properties[, layout, ...])	Starts the liveplotter.
stop_liveplotter()	Stops the currently running liveplotter.
request_state(axis, state)	Requests an axis to enter the specified state.
backup_config(device)	Returns a dict of the form {path: value} containing all properties on the ODrive that have "config" in their path.
restore_config(device, config[, ...])	Restores the configuration of the ODrive from a dictionary.
high_rate_capture(odrv, properties[, ...])	Captures a short window of data from the ODrive at its native control loop rate.

HighRateCapturer

Facility to capture variables from the ODrive at its native control loop rate.

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:

odrivetool

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:

Command Line

odrivetool --serial-number 306A396A3235

My ODrive is stuck in DFU mode, can I still find the serial number?

Yes, the serial number is part of the USB descriptors. In Windows you can find it in the Device Manager. In Linux you can find it by running:

(sudo lsusb -d 1209:0d32 -v; sudo lsusb -d 0483:df11 -v) 2>/dev/null | grep iSerial

This should output something like:

iSerial                 3 385F324D3037
iSerial                 3 306A396A3235

Here, two ODrives are connected.

Liveplotter

start_liveplotter() can be used for graphical plotting of ODrive parameters (e.g. position) in real time. Any variable can be plotted that you are otherwise able to read like normal in odrivetool. The plot will open in a new window and you can run other commands while it is open. matplotlib must be installed to use this feature.

Note

For a better plotting experience, consider using the Web GUI instead.

Note

Some Linux distros (especially Arch Linux) require starting ODrivetool with an additional environment variable for Liveplotter to work properly. If liveplotter crashes for you, try starting odrivetool via: MPLBACKEND=TkAgg odrivetool and then starting liveplotter.

Example

In this example we plot the position of two motors.

To read the position, you would usually type odrv0.axis0.pos_estimate. However this returns the value itself. When starting the liveplotter, we need to pass in a reference to the property, not its value. We do this by replacing it with _[...]_property.

odrivetool

start_liveplotter(properties=[
    odrv0.axis0._pos_estimate_property,
    odrv1.axis0._pos_estimate_property,
])

Liveplotter Position Plot

Here, both motors are running in AxisState.CLOSED_LOOP_CONTROL while they are being forced off position by hand.

High Rate Capture

To get the best possible performance out of your system, it is important to see what it is doing at a high time resolution.

The ODrive can record a limted window of data at its native control frequency (8kHz) into a circular buffer. Once a capture is triggered, the ODrive stops recording and the buffer can be downloaded and plotted.

In odrivetool, this function is available via high_rate_capture_start() and HighRateCapturer.

Example

Assume we want to see how the axis responds to a step in input velocity. Assume the ODrive is already configured for basic velocity control.

1. Enter CLOSED_LOOP_CONTROL mode.

odrivetool

odrv0.axis0.requested_state = AxisState.CLOSED_LOOP_CONTROL

2. Send an input step while running a high rate recording.

The input step (odrv0.axis0.controller.input_vel = 10.0) and the triggering (trigger_and_download_sync()) must happen in quick succession, otherwise the capture window might not contain the time frame that’s of interest anymore. To ensure this, paste the following snippet as a single block into odrivetool and press enter.

odrivetool

odrv0.axis0.controller.input_vel = 0.0
capturer = high_rate_capture_start(odrv0, ['axis0.controller.vel_setpoint', 'axis0.vel_estimate', 'axis0.motor.foc.Iq_setpoint', 'axis0.motor.foc.Iq_measured'])
time.sleep(0.5)

odrv0.axis0.controller.input_vel = 10.0
data = capturer.trigger_and_download_sync(return_as=np.recarray, t_fmt=TimestampFmt.NANOSECONDS)

3. Plot the result.

odrivetool

import matplotlib.pyplot as plt
for key in list(data.dtype.fields.keys())[1:]:
    plt.plot(data['timestamps'] / 1e6, data[key], '.-', label=key)
plt.xlabel('Time [ms]')
plt.legend()
plt.grid()
plt.show()

High rate capture of a velocity step response. Click to enlarge.

Close-up of the high rate capture. The time 0ms corresponds to the call to trigger_and_download_sync(), so it is shortly after the input step.

For more options, such as moving the trigger point, changing the timestamp format etc., check out the reference documentation: high_rate_capture_start().

Things to know

• For now, this feature requires pre-release firmware. Select the devel channel when updating the firmware.

• When the ODrive enters IDLE, the capture is triggered automatically with a trigger point of 0.98.

• A maximum of 9 variables can be recorded in one go.

• The length of the recording window is determined by a fixed size buffer in the ODrive and depends on how many variables are being captured. For firmware 0.6.12 on ODrive Pro, S1 and Micro:

  Number of Variables	Window Length
  1 variable	2048 ms
  2 variables	1024 ms
  9 variables	228 ms

Firmware Update

See Updating firmware from the command line.

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

Command Line

odrivetool backup-config my_config.json

• To restore the configuration form such a file, run

Command Line

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 recommended 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.

Changelog

⇒ See Python Package Changelog