Configure a TMC5072-Controlled Stepper Motor

The TMC5072 model supports stepper motors controlled by the TMC5072 chip.

Whereas a basic low-level stepper driver supported by the gpiostepper model sends power to a stepper motor based on PWM signals from GPIO pins, the TMC5072 chip uses SPI bus to communicate with the board, does some processing on the chip itself, and provides convenient features including StallGuard2TM.

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Component. Select the motor type, then select the TMC5072 model. Enter a name or use the suggested name for your motor and click Create.

Config panel for a TMC5072 motor with attributes filled in according to the JSON tab.

Edit and fill in the attributes as applicable.

{
  "components": [
    {
      "name": "<your-board-name>",
      "model": "<your-board-model>",
      "type": "board",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": [],
    },
    {
      "name": "<your-motor-name>",
      "model": "TMC5072",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "spi_bus": "<your-spi-bus-index>",
        "chip_select": "<pin-number>",
        "index": "<your-terminal-index>",
        "pins": {
          "en_low": "<int>",
        },
        "ticks_per_rotation": <int>,
        "max_acceleration_rpm_per_sec": <float>,
        "sg_thresh": <int>,
        "home_rpm": <float>,
        "cal_factor": <float>,
        "run_current": <int>,
        "hold_current": <int>,
        "hold_delay": <int>
      },
      "depends_on": []
    }
  ]
}

{
  "components": [
    {
      "name": "my-tmc-motor",
      "model": "TMC5072",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "chip_select": "0",
        "index": 1,
        "pins": {
          "en_low": "17"
        },
        "max_acceleration": 10000,
        "max_rpm": 450,
        "spi_bus": "0",
        "ticks_per_rotation": 200
      }
    }
  ]
}

The following attributes are available for TMC5072 motors:

NameTypeInclusionDescription
spi_busstringRequiredThe index of the SPI bus over which the TMC chip communicates with the board.
chip_selectstringRequiredThe chip select number (CSN) that the TMC5072 is wired to. For Raspberry Pis, use "0" if the CSN is wired to pin number 24 (GPIO 8) on the Pi, or use "1" if you wire the CSN to pin 26. The board sets this high or low to let the TMC chip know whether to listen for commands over SPI.
pinsobjectRequiredA structure that holds the pin number you are using for "en_low", the enable pin for the driver chip.
indexintRequiredThe index of the part of the chip the motor is wired to. Either 1 or 2, depending on whether the motor is wired to the “MOTOR1” terminals or the “MOTOR2” terminals, respectively.
ticks_per_rotationintRequiredNumber of full steps in a rotation. 200 (equivalent to 1.8 degrees per step) is very common. If your data sheet specifies this in terms of degrees per step, divide 360 by that number to get ticks per rotation.
max_acceleration_rpm_per_secfloatOptionalSet a limit on maximum acceleration in revolutions per minute per second.
sg_threshintOptionalStallguard threshold; sets sensitivity of virtual endstop detection when homing.
home_rpmfloatOptionalSpeed in revolutions per minute that the motor will turn when executing a Home() command (through DoCommand()).
cal_factorfloatOptionalCalibration factor for velocity and acceleration. Compensates for clock source drift when doing time-based calculations.
run_currentintOptionalSet current when motor is turning, from 1-32 as a percentage of rsense voltage. Defaults to 15 if omitted or set to 0.
hold_currentintOptionalSet current when motor is holding a position, from 1-32 as a percentage of rsense voltage. Defaults to 8 if omitted or set to 0.
hold_delayintOptionalHow long to hold full power at a set position before ramping down to hold_current. 0=instant powerdown, 1-15=delay * 2^18 clocks, 6 is the default.

Refer to your motor and motor driver data sheets for specifics.

Extended API

The TMC5072 model supports additional methods that are not part of the standard Viam motor API (passed through DoCommand()):

Home

Home the motor using TMC’s StallGuardTM (a builtin feature of this controller).

Parameters:

  • None

Raises:

  • (error): An error, if one occurred.

For more information on do_command, see the Python SDK Docs.

myMotor = Motor.from_robot(robot=robot, name='my_motor')

# Home the motor
home_dict = {
  "command": "home"
}
await myMotor.do_command(home_dict)

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK docs on Home() and on DoCommand().

myMotor, err := motor.FromRobot(robot, "motor1")

// Home the motor
resp, err := myMotor.DoCommand(ctx, map[string]interface{}{"command": "home"})

Jog

Move the motor indefinitely at the specified RPM.

Parameters:

  • rpm (float64): The revolutions per minute at which the motor will turn indefinitely.

Raises:

  • (error): An error, if one occurred.

For more information on do_command, see the Python SDK Docs.

myMotor = Motor.from_robot(robot=robot, name='my_motor')

# Run the motor indefinitely at 70 rpm
jog_dict = {
  "command": "jog",
  "rpm": 70
}
await myMotor.do_command(jog_dict)

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • rpm (float64): The revolutions per minute at which the motor will turn indefinitely.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK Docs on Jog and on DoCommand.

myMotor, err := motor.FromRobot(robot, "motor1")

// Run the motor indefinitely at 70 rpm
resp, err := myMotor.DoCommand(ctx, map[string]interface{}{"command": "jog", "rpm": 70})

Test the motor

Once your motor is configured and connected, go to the CONTROL tab and click on the motor’s dropdown panel. Use the buttons to try turning your motor forwards or backwards at different power levels and check whether it moves as expected.

Motor control panel.

If the motor does not appear on the CONTROL tab, or if you notice unexpected behavior, check your machine’s LOGS tab for errors, and review the configuration.



Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.