ODrive Documentation

High performance motor control

View the Project on GitHub madcowswe/ODrive

Help improve these docs: submit edits using the link in the top right.

If you need help, please search or ask the ODrive Community.

ODrive Tool

The ODrive Tool 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.

Table of contents

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 ODrive Tool to ignore all other devices you would close it and then run 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 Linux you can find it by running:

$ (sudo lsusb -d 1209:0d32 -v; sudo lsusb -d 0483:df11 -v) 2>/dev/null | grep iSerial
  iSerial                 3 385F324D3037
  iSerial                 3 306A396A3235

Here, two ODrives are connected.

Configuration Backup

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

Device Firmware Update

ODrive v3.4 or earlier: DFU is not supported on these devices. You need to flash with the external programmer instead.

To update the ODrive to the newest firmware release, simply open up a terminal and run the following command:

~ $ odrivetool dfu
ODrive control utility v0.3.7.dev
Waiting for ODrive...
Found ODrive 308039673235 (v3.5-24V) with firmware v0.3.7-dev
Checking online for newest firmware... found v0.3.7
Downloading firmware...
Putting device 308039673235 into DFU mode...
Erasing... done            
Flashing... done            
Verifying... done            

Note that this command will connect to GitHub servers to retrieve the latest firmware.

If you have a non-default configuration saved on the device, ODrive Tool will try to carry over the configuration across the firmware update. If any of the settings are removed or renamed, you will get warning messages.

How to flash a custom firmware

If you want to flash a specific firmware file instead of automatically downloading one, you can run odrivetool dfu path/to/firmware/file.hex

You can download one of the officially released firmware files from here. You will need one of the .hex files (not the .elf file). Make sure you select the file that matches your board version.

To compile firmware from source, refer to the developer guide.

Troubleshooting

Upgrading firmware with a different DFU tool

Some people have had issues using the python dfu tool, so below is a guide on how to manually use a different tool.

Before starting the below steps, you need to get firmware binary. You can download one of the officially released firmware files from here. Make sure you select the file that matches your board version, and that you get the .hex file (not the .elf file).

To compile firmware from source, refer to the developer guide.

Windows

You can use the DfuSe app from ST.

  1. Download the tool here. Unfortunately they make you create a login to download. Sorry about that.
  2. After installing the tool, launch DfuFileMgr.exe which probably got added to the start menu as “Dfu file manager”.
  3. Select “I want to GENERATE a DFU file from S19, HEX or BIN files”, press OK.
  4. Click the button that says “S19 or Hex…”, find the ODriveFirmware.hex file you built or downloaded.
  5. Leave all the other settings as default and click the “Generate…” button.
  6. Save the output file as ODriveFirmware.dfu. Note that the success message has a warning sign for some reason…
  7. Launch DfuSeDemo.exe which probably got added to the start menu as “DfuSeDemo”.
  8. Force the ODrive into DFU mode, as per the instructions above “How to force DFU mode”.
  9. In the top left it should now be connected to “STM Device in DFU Mode”.
    1. If it doesn’t appear, it may be because the driver is set to libusb by Zadig. We need to set it back to the original driver. Follow these instructions.
  10. In the bottom right section called “Upgrade or Verify Action” click the button “Choose…”.
  11. Locate the ODriveFirmware.dfu we made before.
  12. Click button “Upgrade”.
  13. If you get a warning that it’s not possible to check that it’s the correct device type: click yes to continue.
  14. Congratulations your ODrive should now be flashed; you can now quit DfuSeDemo.
  15. Turn off the power to the ODrive and set the DIP switch back to RUN mode.

MacOS or Linux

This section needs more detail. Please consider adding detail if you got it to work. You may be able to use dfu-util to upgrade the firmware. You will need to convert the .hex file to a .dfu file. You may be able to do it with the python script dfu-convert or the c program hex2dfu.

You probably need to force DFU mode, as per the instructions above.

This procedure is only necessary for ODrive v3.4 or earlier. You will need an STLink/v2 or compatible programmer. You should have received one with your ODrive.

  1. Install OpenOCD
    • Windows: instructions (also follow the instructions on the ST-LINK/V2 drivers)
    • Linux: sudo apt-get install openocd
    • macOS: brew install openocd
  2. Download the latest firmware release form here. You will need the .elf file. Make sure you select the file that matches your board version.
  3. Wire up the ODrive and STLink/v2 programmer as shown in this picture:
    stlink-wiring Power up the ODrive.
  4. Open up a terminal and navigate to the directory where the firmware is.
  5. Run the following command (replace ODriveFirmware_v3.4-24V.elf with the name of your firmware file):
    openocd -f interface/stlink-v2.cfg -f target/stm32f4x.cfg -c init -c "reset halt" -c "flash write_image erase ODriveFirmware_v3.4-24V.elf" -c "reset run" -c exit
    

If everything worked correctly, you should see something similar to this towards the end of the printout:

wrote 262144 bytes from file ODriveFirmware_v3.4-24V.elf in 10.194110s (25.113 KiB/s)

If something doesn’t work, make sure openocd is in your PATH variable, check that the wires are connected properly and try with elevated privileges.

Liveplotter

Liveplotter is used for the graphical plotting of odrive parameters (i.e. position) in real time. To start liveplotter, close any other instances of liveplotter and run odrivetool liveplotter from a new anaconda prompt window. By defult two parameters are plotted on startup; the encoder positon of axis 1 and axis 2. In the below example the motors are running in closed_loop_control while they are being forced off position by hand.

Liveplotter position plot

To change what parameters are plotted open odrivetool (located in Anaconda3\Scripts or ODrive-master\tools) with a text editor and modify the liveplotter function:

        # If you want to plot different values, change them here.
        # You can plot any number of values concurrently.
        cancellation_token = start_liveplotter(lambda: [
            my_odrive.axis0.encoder.pos_estimate,
            my_odrive.axis1.encoder.pos_estimate,
        ])

For example, to plot the approximate motor torque [N.cm] and the velocity [RPM] of axis1 with a 150KV motor and an 8192 count per rotation econder you would modify the function to read:

        # If you want to plot different values, change them here.
        # You can plot any number of values concurrently.
        cancellation_token = start_liveplotter(lambda: [
            (((my_odrive.axis0.encoder.pll_vel)/8192)*60), # 8192 CPR encoder
            ((8.27*my_odrive.axis0.motor.current_control.Iq_setpoint/150) * 100), # Torque [N.cm] = (8.27 * Current [A] / KV) * 100
        ])

In the example below 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).

Liveplotter torque vel plot

To change the scale and sample rate of the plot modify the following parameters located at the beginning of utils.py (located in Anaconda3\Lib\site-packages\odrive):

data_rate = 100
plot_rate = 10
num_samples = 1000

For more examples on how to interact with the plotting functinality refer to the Matplotlib examples.

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.encoder.pos_estimate]). 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.