ODrive/docs/ascii-protocol.md

ASCII Protocol

How to send commands

• Via USB:
  • Windows: Use the Zadig utility to set the ODrive's driver to "usbser". Windows will then make the device available as COM port. You can 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 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 (GPIO1) to your host's RX. Connect your ODrive's RX (GPIO2) to your host's TX. The logic level of the ODrive is 3.3V.
  • 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.

Command format

The ASCII protocol is human-readable and line-oriented, with each line having the following 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.
• comments are supported for GCode compatibility
• the command is interpreted once the new-line character is encountered

Command Reference

Motor trajectory command

t motor destination

• t for trajectory
• motor is the motor number, 0 or 1.
• destination is the goal position, in encoder counts.

Example: t 0 -20000

For general moving around of the axis, this is the recommended command.

This command updates the watchdog timer for the motor.

Motor Position command

For basic use where you send one setpoint at at a time, use the q command. If you have a realtime controller that is streaming setpoints and tracking a trajectory, use the p command.

q motor position velocity_lim current_lim

• q for position
• motor is the motor number, 0 or 1.
• position is the desired position, in encoder counts.
• velocity_lim is the velocity limit, in counts/s (optional).
• current_lim is the current limit, in A (optional).

Example: q 0 -20000 10000 10

p motor position velocity_ff current_ff

• p for position
• motor is the motor number, 0 or 1.
• position is the desired position, in encoder counts.
• velocity_ff is the velocity feed-forward term, in counts/s (optional).
• current_ff is the current feed-forward term, in A (optional).

Example: p 0 -20000 0 0

Note that if you don't know what feed-forward is or what it's used for, simply omit it.

This command updates the watchdog timer for the motor.

Motor Velocity command

v motor velocity current_ff

• v for velocity
• motor is the motor number, 0 or 1.
• velocity is the desired velocity in counts/s.
• current_ff is the current feed-forward term, in A (optional).

Example: v 0 1000 0

Note that if you don't know what feed-forward is or what it's used for, simply omit it.

This command updates the watchdog timer for the motor.

Motor Current command

c motor current

• c for current
• motor is the motor number, 0 or 1.
• current is the desired current in A.

This command updates the watchdog timer for the motor.

Request feedback

f motor

response:
pos vel

• f for feedback
• pos is the encoder position in counts (float)
• vel is the encoder velocity in counts/s (float)

Update motor watchdog

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.

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:

  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:

  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.pos_setpoint -123.456

System commands:

• ss - Save config
• se - Erase config
• sr - Reboot