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. 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. Experimental support for firmware updates via CAN is also available.

Specifications

  • Supported firmware:

    • 0.6.7 or newer when using GUI

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

  • Supported interfaces: USB (stable), CAN (experimental)

  • 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, 10kbps

    • 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
    

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.

  • If you want to avoid insalling Python, you can use the standalone utility odriveupdater instead of odrivetool. This requires manually downloading the files and manually commanding the ODrive into DFU mode.

Updating firmware over CAN

Warning

DFU over CAN is currently under beta testing and not intended for production use yet. During the beta phase, USB or physical access to the ODrive may be required to recover from unexpected issues.

You will need a Linux device with a CAN interface for this.

We assume that your CAN interface is called can0, but this may differ on your system.

  1. Download ODrive Updater. (The GUI and odrivetool can only perform firmware updates via USB.)

  2. Obtain the firmware that you want to install from the firmware release page.

  3. If you have set a custom baudrate on the ODrive before, make sure to revert to the firmware default of 250k on all devices on the bus.

    odrv0.can.config.baud_rate = 250000

    If you haven’t touched this value before, you can ignore this step.

    Note

    While the DFU process itself supports other baudrates too, we recommend a baudrate of 250kbps because the user configuration is currently not preserved during the firmware update. That means when the update completes, the ODrive will default to a baudrate of 250kbps, which would crash the CAN bus if any devices (including the update host) use a different baudrate.

  4. Configure and enable the host computer’s CAN interface.

    sudo ip link set dev can0 type can bitrate 250000
    sudo ip link set dev can0 txqueuelen 256
    sudo ip link set dev can0 up
    
  5. Make sure your host computer and ODrive are connected via CAN.

  6. If the ODrive’s LED isn’t already pulsating purple, put it into DFU mode:

    If the ODrive’s default CAN Protocol is enabled, you can send a CAN message with the message ID (node_id << 5 | 0x16) and payload 0x03 to enter DFU mode (see Reboot). You can use the broadcast node_id of 0x3f to put all ODrives into DFU mode at once.

    For example using Python:

    Python
    import can
    node_id = 0x3f # broadcast address
    with can.interface.Bus("can0", bustype="socketcan") as bus:
      bus.send(can.Message(arbitration_id=(node_id << 5 | 0x16), data=[0x03], is_extended_id=False))
    

    This method won’t work if you manually disabled the CAN Protocol. In that case, see Recovering from unbootable firmware instead.

  7. Install the new firmware via CAN.

    The following command will update the first ODrive in DFU mode that’s found on the bus (see odriveupdater --help for more options):

    /path/to/odriveupdater --can can0 firmware.elf
    

    After successful completion, the status LED will go back to the normal pattern (blue / cyan), indicating that the main firmware is running.

    Note

    The odriveupdater utility does currently not terminate when the update is done. Press Ctrl+C to exit.

  8. Configuration and calibration is erased during a firmware update. You can re-apply it by following the instructions here: Setting up the ODrive (CAN only).

Limitations

  • When updating firmware over CAN, odriveupdater will not exit automatically once complete or when the device is disconnected. Press Ctrl+C to exit.

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

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

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.

ODrive Updater

odriveupdater is a standalone command line utility that serves as a light-weight alternative to odrivetool new-dfu when Python is not available and the GUI cannot be used (on headless systems or for automation).

Currently it is also the only way to run updates over CAN (experimental).

Unpack the downloaded zip file, and then run:

chmod +x /path/to/odriveupdater

Run ./path/to/odriveupdater --help for general usage hints or proceed with the instructions on this page.

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.

As with all software, despite thorough internal testing, it is still possible that firmware on master contains bugs or regressions. For commercial customers that plan to push updates to their end users, it is therefore recommended to do acceptance tests of new firmware integrated into your system before pushing it out to your fleet.

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.

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