Add an ODrive motor as a Modular Resource

The Viam GitHub provides an implementation of ODrive Robotics’ ODrive S1 motor driver as module defining two modular resources extending the motor API as new motor types.

Install requirements, prepare your ODrive, and configure the module to configure an serial or canbus motor resource on your robot.

Requirements

On your robot’s computer, clone the Viam ODrive module:

git clone https://github.com/viamrobotics/odrive.git

Install python-can, cantools, and the Python viam-sdk:

pip3 install python-can cantools viam-sdk

Follow these instructions to install odrivetool.

Find and copy the path (either absolute, or relative to the working directory) to the executable module file run.sh on your robot’s computer to provide when configuring the module.

cd <your/path/to/odrive/odrive-motor>
pwd

Prepare your ODrive

1. Read through the ODrive documentation to wire, calibrate, and configure your ODrive natively.

   Tip

   This configuration remains on the same ODrive motor controller across reboots, and only changes when you go through the configuration of the ODrive again.

   If you wish to set the native configuration dynamically, use odrivetool to find and copy the path to the motor’s config.json file. Provide this in configuration as the optional attribute odrive_config_file. See add an odrive_config_file for more information.

   This option is not recommend for the canbus model.

   Note that iq_msg_rate_ms in the odrive_config_file defaults to 0, and you must set this to or around 100 to use the motor API’s SetPower method.

2. Follow this guide to tune your ODrive motor.

3. See the ODrive CAN documentation for detailed information on how to set up CAN on your ODrive.

   Tip

   If you are using a Raspberry Pi as your board, you must run sudo ip link set can0 up type can bitrate <baud_rate> in your terminal to receive CAN messages. See “Troubleshooting: CAN Link Issues” for more information.

   Additionally, make sure you have enabled SPI communication on your Pi to use several common CANHats.

4. Make sure your ODrive is connected to your board as follows, depending on your preferred connection method:

   
   serial
   		
   canbus
   
   	
   Plug the USB Isolator for Odrive into a USB port on your board.
   Plug a USB-C to USB-A cable from the isolator to the ODrive.
   
   
   	
   Wire the CANH and CANL pins from your board to your ODrive.
   Refer to your board and the ODrive’s pinout diagrams for the location of these pins.
   You must make a serial connection to set up your ODrive.
   If CAN chains together multiple ODrives, only one at a time must have this serial connection for reconfiguration
   After setting up the ODrive, if you wish to use the canbus model, you can either leave the serial connection plugged in or remove it and leave only the CANH and CANL pins wired.
   Note that if you want to only use the CAN pins, you cannot specify an "odrive_config_file" in your Viam configuration.
   The ODrive would not be able to make the serial connection it needs to perform reconfiguration.
   
   
   

   After preparing your ODrive, configure the module to configure serial or canbus model motors on your robot.

Configuration

{
    "width_px": <int>,
    "height_px": <int>,
    "frame_rate": <int>,
    "debug": "<boolean>"
}

{
  "name": "odrive",
  "executable_path": "<your/path/to/odrive/odrive-motor/run.sh>"
}

{
  "model": "viam:odrive:serial",
  "namespace": "rdk",
  "attributes": {},
  "depends_on": [],
  "type": "motor",
  "name": "<your-odrive-motor>"
}

{
    "model": "viam:odrive:canbus",
    "namespace": "rdk",
    "attributes": {
      "canbus_node_id": <int>,
    },
    "depends_on": [],
    "type": "motor",
    "name": "<your-odrive-motor>"
}

{
  "modules": [
    {
      "name": "odrive",
      "executable_path": "/path/to/odrive/odrive-motor/run.sh"
    }
  ],
  "components": [
    {
      "model": "viam:odrive:canbus",
      "namespace": "rdk",
      "attributes": {
        "canbus_node_id": 0,
        "odrive_config_file": "/path/to/first/config.json",
        "serial_number": "NUM0001"
      },
      "depends_on": [],
      "type": "motor",
      "name": "odrive-motor"
    },
    {
      "model": "viam:odrive:canbus",
      "namespace": "rdk",
      "attributes": {
        "canbus_node_id": 2,
        "odrive_config_file": "/path/to/second/config.json",
        "serial_number": "NUM0002"
      },
      "depends_on": [],
      "type": "motor",
      "name": "odrive-motor-2"
    }
  ]
}

Edit and fill in the attributes as applicable to your model of ODrive.

The following attributes are available for the motor resources available in the Viam ODrive module:

Save the config. Check the Logs tab of your robot in the Viam app to make sure your ODrive motor has connected and no errors are being raised.

Add an odrive_config_file

To add an odrive_config_file and reconfigure your ODrive natively each time the motor is initialized on the robot, use odrivetool to extract your configuration from your ODrive:

1. Run odrivetool backup-config config.json to extract your configs to a file called config.json. See the ODrive documentation for more info.
2. iq_msg_rate_ms in the config defaults to 0. You must set this to or around 100 to use the motor API’s SetPower method.
3. If you add an odrive_config_file to an canbus motor, you will have to leave the serial connection established with your ODrive plugged in to the USB port, in addition to wiring the CANH and CANL pins.

An alternative to adding an odrive_config_file is running the command odrivetool restore-config /path/to/config.json in your terminal.

Troubleshooting

See the Viam Github for help with common issues.

You can also ask questions in the Community Discord and we will be happy to help.