Firmware Update

Note

This page describes the new ODrive DFU system that is use since Q2 2024. Migration instructions can be found here. See also: Legacy Firmware Update.

Quick Summary

Updating the firmware on your ODrive is easy and safe and works directly from your browser via USB or a USB-CAN Adapter. Head over to the Web GUI > Firmware Update and press Install Firmware.

Firmware update from GUI

Alternatively, you can install updates from the command line.

Specifications

  • Supported firmware:

    • 0.6.7 or newer when using GUI

    • 0.6.5 or newer when using odrivetool (use the legacy DFU system to install older firmware)

    • 0.6.11 or newer for updates over CAN

  • Supported interfaces: USB, CAN

  • Supported host programs:

    • Web GUI (USB and CAN via USB-CAN Adapter)

    • odrivetool 0.6.9 or newer (USB)

    • odrivetool 0.6.11 or newer (CAN)

  • Recoverable even without physical access, see Recovering from a failed update and Recovering from unbootable firmware.

  • CAN specifications:

    • The DFU-over-CAN protocol uses extended (29-bit) IDs. It is not currently guaranteed to work with other 29bit ID CAN messages on the bus. If you wish to use other vendor’s 29bit CAN protocols on the same bus, please contact us and let us know what vendor and messages you are looking to use, so we can work towards ensuring compatibility.

    • Up to 62 devices that speak the DFU protocol (ODrives in DFU mode + updater hosts) are allowed on one bus. The bus can have additional devices that use other protocols (ODrives in run mode, third party devices), as long as they don’t conflict with the other points listed here.

    • Supported baudrates (autodetected): 1Mbps, 500kbps, 250kbps, 125kbps, 40kbps

    • The ODrive bootloader does not send any CAN-FD messages but is ok with other CAN-FD messages going on the same bus (sent by other devices).

Updating firmware from the command line

Warning

Your configuration will be erased during a firmware update. See Configuration Backup if you want to keep it.

  1. Install (or update) odrivetool on your computer:

    Command Line
    python3 -m pip install odrive --upgrade

    For more detailed installation instructions, see odrivetool Installation.

  2. Run the following command to install the latest firmware on your ODrive:

    Command Line
    odrivetool new-dfu

This will connect to the first ODrive it finds, put it into DFU mode, and install the latest firmware. The ODrive’s status LED will pulsate purple during the update and return to the normal pattern (blue / cyan) when done.

ODrives are by default discovered over USB or, on Windows and macOS, also via a USB-CAN Adapter. For Linux, see Using odrivetool via CAN.

For more options, see odrivetool new-dfu --help or next section.

Other Options

  • Install firmware from our semi-stable development channel (see Firmware Channels):

    odrivetool new-dfu --channel devel

  • Install a specific firmware version (0.6.9 in this example):

    odrivetool new-dfu --version 0.6.9

  • Install a local firmware file:

    odrivetool new-dfu firmware.elf

    You can manually download firmware files from here.

  • Install firmware over a SocketCAN interface (Linux only, can0 in this example):

    odrivetool --can=can0 new-dfu

    See Using odrivetool via CAN for more details.

Note

If you need to run firmware updates on a system where Python is not available and the Web GUI cannot be used, please contact us.

Troubleshooting

SSL Certificate Issues

Example error message:

SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1002)

odrivetool is unable to establish an SSL connection with our firmware release server. This usually means that its Python environment is missing the necessary certificate bundle.

  • macOS: In odrivetool, run the following command to check which Python environment is used:

    odrivetool
    import sys; print(sys.executable)

    If this prints a path in /Library, such as /Library/Frameworks/Python.framework/Versions/3.11/bin/python3.11, it means you probably installed Python using the installer from Python.org. In this case, you need to install the certificates by running this command (replace 3.11 with your version):

    Command Line
    '/Applications/Python 3.11/Install Certificates.command'

See also: USB Connectivity Issues

Updating firmware over CAN

⇒ Requires firmware 0.6.11 or newer

Both the Web GUI and odrivetool can update firmware over CAN. See Using odrivetool via CAN and Connecting over CAN for details on how to connect. After connecting, the update process is the same as over USB.

Limitations

  • When updating firmware over CAN, the device does currently not recognize when the host disconnects after enumeration or during the update. That means in case of a failed/cancelled DFU attempt, or if the device was interrogated while updating another device, it needs to be restarted to correctly handle a new DFU attempt.

  • The bootloader does not reject simultaneous update attempts from two separate hosts. The result of such a situation is undefined.

Recovering from a failed update

If the firmware update is interrupted (e.g. due to power loss), the ODrive will automatically start into DFU mode on the next power up and you can restart the DFU process. No physical access is required for this.

Note

The hardware “DFU” DIP switch on ODrive Pro and ODrive S1 is deprecated and should be left in “RUN” state when the new DFU system is used.

Recovering from unbootable firmware

In rare corner cases, the ODrive might get into a state where there’s valid looking firmware installed but the firmware fails to start correctly so that the ODrive cannot accept an “enter DFU mode” command. This should never happen during normal usage and is only expected in these cases:

  • Installing untested development or custom firmware builds that happen to be broken

  • Setting special untested configuration that is not correctly handled by the firmware

  • Unexpected hardware damage that is not properly handled by the firmware

You can recover from such a state by power-cycling the ODrive and sending a “Force DFU” message during one second after power-up. This can be done without physical access as long as the ODrive’s power supply can be controlled independently from the power supply of the update host (e.g. robot’s on-board computer).

  • Force DFU via USB: When the ODrive boots, for a brief period of 1 second, it presents itself to the USB host as “ODrive Pro/S1/Micro Bootloader”. During this period, the host can send a Vendor Setup Request with bRequest = 0x0D and wValue = 0x0001 to force the ODrive to stay in DFU mode.

    Example Script

    The following Python script polls for ODrives in DFU mode as fast as possible and sends the “Force DFU” command each time one is found.

    Python
    import usb.core
import usb.util

while True:
    print(f"scanning...")
    devices = list(usb.core.find(find_all=True, idVendor=0x1209, idProduct=0x0D32))
    print(f"found {len(devices)} ODrives...")

    bootloader_odrives = []
    for device in devices:
        try:
            if usb.util.get_string(device, device.iProduct).endswith(" Bootloader"):
                bootloader_odrives.append(device)
        except ValueError:
            pass
        except usb.core.USBError as e:
            print(f"USBError: {str(e)}")

    if len(bootloader_odrives) > 0:
        print(f"sending FORCE DFU command to {len(bootloader_odrives)} devices...")
    for device in bootloader_odrives:
        try:
            # Send a vendor setup request
            request_type = usb.util.build_request_type(
                usb.util.CTRL_OUT,
                usb.util.CTRL_TYPE_VENDOR,
                usb.util.CTRL_RECIPIENT_DEVICE,
            )
            request = 0x0D # vendor code: ODrive
            value = 0x0001 # command: force DFU
            index = 0x00

            device.ctrl_transfer(request_type, request, value, index)
        except usb.core.USBError as e:
            print(f"USBError: {str(e)}")

    Start the script, and while it is running, reboot the ODrive (e.g. power cycle). Shortly after power-on (<1 second), the ODrive LED should start pulsating purple, and you can exit the script with Ctrl+C.

  • Force DFU via CAN: Send a message with the data 0xa8, 0x94, 0x18, 0x5c, 0xa8, 0xe6, 0x0c, 0x56 at an interval <100ms while the ODrive is rebooting.

    Any message ID can be used as long as it does not conflict with any other protocols that may be running on the bus. Any supported baudrate can be used.

    Example Script

    In this example we’re using message ID 0 to ensure that our message gets through even on high bus load.

    python
    import can
import time
with can.interface.Bus("can0", interface="socketcan") as bus:
    while True:
        bus.send(can.Message(arbitration_id=0, data=[0xa8, 0x94, 0x18, 0x5c, 0xa8, 0xe6, 0x0c, 0x56], is_extended_id=False))
        time.sleep(0.02)

    Start the script, and while it is running, reboot the ODrive (e.g. power cycle). Shortly after power-on (<1 second), the ODrive LED should start pulsating purple, and you can exit the script with Ctrl+C.

If successful, the status LED should be pulsating purple, indicating that the ODrive is in DFU mode. The ODrive will stay in DFU mode until the next power cycle unless told otherwise. At this point you can run a normal firmware update using your preferred method.

Firmware Channels

Firmware updates are made available on two channels: master and devel.

The master channel is considered stable and recommended for most users and production use. The devel channel is our internal development channel and contains the latest features and bug fixes, however it may not always be stable.

The effective differences are:

  • Firmware on master is guaranteed to have fully passed our internal hardware-in-the-loop test suite. Firmware on devel is usually tested with the same test suite, however it is not guaranteed to have passed it (e.g. due to mainenance).

  • After larger changes, devel firmware is more likely to contain bugs that are not covered by our test suite. master firmware is only released if enough time has passed since the last larger change.

  • devel firmware may not be fully supported by the Web GUI.

  • Some features or changes on devel may be refined before reaching master. On master we try to do incompatible changes only when necessary.

  • Firmware on master carries version names (X.Y.Z) that equal the version number reported by the firmware itself. Firmware on devel uses 40-digit hashes as version names.

  • Updates on master happen more sparsely, thus avoiding to distract users for whom the updates may not be relevant.

Users are advised to back up configuration files and test firmware upgrades thoroughly prior to fleet deployment, as ODrive endpoints or behavior may change. For a full list of changes for each version, please see the Changelog.

How to migrate from the legacy DFU system

If your ODrive was purchased before Q3 2024, you need to run a one-time migration step to use the new DFU system.

Note

Your configuration will be erased during this migration. See Configuration Backup if you want to keep it.

First, make sure the ODrive Web GUI is closed before you continue. Then run:

Command Line
python3 -m pip install odrive --upgrade
odrivetool install-bootloader

For troubleshooting, see odrivetool Installation and Legacy Firmware Update.

Why migrate?

If you’re previously used the legacy DFU system on the ODrive, the new DFU system will get you these benefits:

  • Support for DFU via CAN

  • Recoverable without physical access (on-board “DFU” DIP switch deprecated)

  • Requires no driver setup, no Zadig, no libusb installation

  • Supports multiple update methods:

    • From the browser (ODrive Web GUI)

    • As before with odrivetool new-dfu - works almost identically to odrivetool dfu that you might be familiar with.

  • Faster and safer than the legacy system

Should you ever want to disable the new DFU system, you can do so with odrv0.disable_bootloader() or by running odrivetool legacy-dfu.