ASCII Protocol

Sending Commands

  • Via USB:

    • Windows: Use PuTTY to manually send commands or open the COM port using your favorite programming language

    • Linux/macOS: Run /dev/tty* to list all serial ports. The ODrive will show up as /dev/ttyACM0 (or similar) on Linux and /dev/tty.usbmodem[...] on macOS. Once you know the name, you can use screen /dev/ttyACM0 (with the correct name) to send commands manually or open the device using your favorite programming language. Serial ports on Unix can be opened, written to and read from like a normal file.

  • Via UART: Connect the ODrive’s TX to your host’s RX, and the ODrive’s RX to your host’s TX. See UART for more info.

    • Arduino: You can use the ODrive Arduino library to talk to the ODrive.

    • Windows/Linux/macOS: You can use an FTDI USB-UART cable to connect to the ODrive.

The ODrive does not echo commands. That means that when you type commands into a program like screen, the characters you type won’t show up in the console.

Arduino

There is an Arduino library that gives some examples on how to use the ASCII protocol to communicate with the ODrive. Check it out here <../Arduino/ODriveArduino>.

Command Format

The ASCII protocol is human-readable and line-oriented, with each line having the following format:

Format: command *42 ; comment [new line character]

  • *42 stands for a GCode compatible checksum and can be omitted. If and only if a checksum is provided, the device will also include a checksum in the response, if any. If the checksum is provided but is not valid, the line is ignored. The checksum is calculated as the bitwise xor of all characters before the asterisk (*). Example of a valid checksum: r vbus_voltage *93.

  • Comments are supported for GCode compatibility.

  • The command is interpreted once the new-line character is encountered.

  • If the command yields a response but the ODrive hasn’t finished sending the previous response yet, the new response is silently discarded.

  • Supported new-line characters are carriage return (\r), line feed (\n), CR/LF (\r\n), and !.

  • The ODrive will always use CR/LF (\r\n) as the new-line termination sequence

Command Reference

Motor Trajectory

For moving the axis from point to point, this is the recommended command and mode. Make sure to set up the trapezoidal trajectory parameters first.

Format: t motor destination

  • t for trajectory.

  • motor is the motor number, 0 or 1.

  • destination is the goal position, in [turns].

Example:

t 0 -2

This command sets the control mode to CONTROL_MODE_POSITION_CONTROL and the input mode to INPUT_MODE_TRAP_TRAJ This command updates the watchdog timer for the motor.

Motor Position

For basic use where you send position setpoints, use the q command, recommended together with filtered position input mode for general use.

Format: q motor position velocity_lim torque_lim

  • q for position.

  • motor is the motor number, 0 or 1.

  • position is the desired position, in [turns].

  • velocity_lim is the velocity limit, in [turns/s] (optional).

  • torque_lim is the torque limit, in [Nm] (optional).

Example:

q 0 -2 1 0.1

This command sets the control mode to CONTROL_MODE_POSITION_CONTROL This command updates the watchdog timer for the motor.

Motor Position with feed-forward

If you have a realtime controller that is streaming setpoints and tracking a trajectory, use the p command.

Format: p motor position velocity_ff torque_ff

  • p for position

  • motor is the motor number, 0 or 1.

  • position is the desired position, in [turns].

  • velocity_ff is the velocity feed-forward term, in [turns/s] (optional).

  • torque_ff is the torque feed-forward term, in [Nm] (optional).

Example:

p 0 -2 0 0

This command sets the control mode to CONTROL_MODE_POSITION_CONTROL This command updates the watchdog timer for the motor.

Note

If you don’t know what feed-forward is or what it’s used for, simply omit it.

Motor Velocity

Format: v motor velocity torque_ff

  • v for velocity

  • motor is the motor number, 0 or 1.

  • velocity is the desired velocity in [turns/s].

  • torque_ff is the torque feed-forward term, in [Nm] (optional).

Example:

v 0 1 0

This command sets the control mode to CONTROL_MODE_VELOCITY_CONTROL This command updates the watchdog timer for the motor.

Motor Torque

Format: c motor torque

  • c for torque

  • motor is the motor number, 0 or 1.

  • torque is the desired torque in [Nm].

This command sets the control mode to CONTROL_MODE_TORQUE_CONTROL This command updates the watchdog timer for the motor.

Request Feedback

input format: f motor

response format: pos vel

  • f for feedback.

  • pos is the encoder position in [turns] (float).

  • vel is the encoder velocity in [turns/s] (float).

Update Motor Watchdog

Format: u motor

  • u for /u/pdate.

  • motor is the motor number, 0 or 1.

This command updates the watchdog timer for the motor, without changing any setpoints.

Set Absolute Position

Format: es motor abs_pos

  • esl for encoder set (abs pos).

  • motor is the motor number, 0 or 1.

  • abs_pos the absolute position to set the current position to.

Sets the absolute position of the axis

Parameter Reading/Writing

Not all parameters can be accessed via the ASCII protocol but at least all parameters with float and integer type are supported.

  • Reading format: r [property]

    • property name of the property, as seen in ODrive Tool

    • response: text representation of the requested value

    • Example: r vbus_voltage => response: 24.087744

  • Writing format: w [property] [value]

    • property name of the property, as seen in ODrive Tool

    • value text representation of the value to be written

    • Example:

      w axis0.controller.input_pos -123.456

System Commands

  • ss - Save config

  • se - Erase config

  • sr - Reboot

  • sc - Clear errors