`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 

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”.
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.
Optional: Install matplotlib (only needed if you’re going to use the Liveplotter).
Command Line
```
python3 -m pip install matplotlib
```

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.

We are going to run the following commands for installation in Terminal.

Install homebrew. You can skip this step if brew doctor already returns something like Your system is ready to brew..

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
echo 'export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"' >> ~/.zshrc
source ~/.zshrc

Install Python 3. You can skip this step if python3 --version already returns something like Python 3.7.0 or newer.
```
brew install python3
```
Optional: Install libusb (only needed for Legacy Device Firmware Updates).
```
brew install libusb
```
Optional: Install matplotlib (only needed if you’re going to use the Liveplotter).
```
pip3 install matplotlib
```

Install odrivetool.

pip3 install --upgrade pip
pip3 install --upgrade odrive
echo 'export PATH="'$(python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))")':$PATH"' >> ~/.zshrc
source ~/.zshrc

Troubleshooting

Permission Errors: Just run the previous command in sudo
```
sudo pip3 install --upgrade odrive
```
Dependency Errors: If the installer doesn’t complete, and you get a dependency error (Ex. “No module…” or “module_name not found”)
```
sudo pip3 install module_name
```
Try step 5 again.
Other Install Errors: If the installer fails at installing dependencies, try
```
sudo pip3 install odrive --no-deps
```
If you do this, brace yourself for runtime errors when you run odrivetool (the basic functionality should work though).

Install Python 3. You can skip this step if python3 --version already returns something like Python 3.7.0 or newer. The installation command depends on your Linux distribution. For example on Ubuntu:
```
sudo apt install python3 python3-pip
```
If this doesn’t work, see the official download page.
Optional: Install matplotlib (only needed if you’re going to use the Liveplotter).
```
pip3 install matplotlib
```
Install odrivetool.
```
pip3 install --upgrade odrive
```

Set up USB device permissions.

sudo bash -c "curl https://cdn.odriverobotics.com/files/odrive-udev-rules.rules > /etc/udev/rules.d/91-odrive.rules && udevadm control --reload-rules && udevadm trigger"

Ubuntu, Raspbian: If you can’t invoke odrivetool at this point, try adding ~/.local/bin to your $PATH (see related bug). This is done for example by running nano ~/.bashrc, scrolling to the bottom, pasting export PATH=$PATH:~/.local/bin, and then saving and closing, and close and reopen the terminal window.

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.

Commands and Objects 

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

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,
 ])

../_images/liveplotter-pos-estimate.png — Liveplotter Position Plot

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

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.

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