Configure a TMC5072 motor

This 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 StallGuard2^TM.

Configuration

To configure a DC motor as a component of your robot, first configure the board to which the motor driver is wired.

Then assign your motor a name (to identify the motor), type (motor) and model (TMC5072), and fill in the attributes that apply to your particular hardware. Refer to your motor and motor driver data sheets for specifics.

An example configuration for a tmc5072 motor driver and the board it’s wired to:

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

{
  "components": [
    {
      "name": <board_name>,
      "type": "board",
      "model": <board_model>,
      "attributes": {},
      "depends_on": [],
    },
    {
      "name": <motor_name>,
      "type": "motor",
      "model": "TMC5072",
      "attributes": {
        "board": <board_name>,
        "spi_bus": <SPI bus name>,
        "chip_select": <pin number (string)>,
        "index": <SPI bus index>,
        "ticks_per_rotation": <int>,
        "max_acceleration_rpm_per_sec": <float>,
        "sg_thresh": <int32>,
        "home_rpm": <float>,
        "cal_factor": <float>,
        "run_current": <int32>,
        "hold_current": <int32>,
        "hold_delay": <int32>
      },
      "depends_on": []
    }
  ]
}

{
  "components": [
    {
      "name": "example-board",
      "type": "board",
      "model": "pi"
    },
    {
      "name": "my-tmc-motor",
      "type": "motor",
      "model": "TMC5072",
      "attributes": {
        "board": "example-board",
        "chip_select": "36",
        "index": 0,
        "max_acceleration": 10000,
        "max_rpm": 450,
        "spi_bus": "main",
        "ticks_per_rotation": 200
      }
    }
  ]
}

Required Attributes

Name	Type	Description
`board`	string	Should match name of board to which the motor controller is wired.
`spi_bus`	string	The board SPI bus over which the TMC chip communicates with the board.
`chip_select`	string	The pin number of the GPIO pin on the board wired to the TMC controller. The board sets this high or low to let the TMC chip know whether to listen for commands over SPI.
`index`	int	The index of the SPI bus. For example, on a Raspberry Pi a user could use SPI bus “0” or “1.”
`ticks_per_rotation`	integer	Number 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.

Optional Attributes

Name	Type	Description
`max_acceleration_rpm_per_sec`	float64	Set a limit on maximum acceleration in revolutions per minute per second.
`sg_thresh`	int32	Stallguard threshold; sets sensitivity of virtual endstop detection when homing.
`home_rpm`	float64	Speed in revolutions per minute that the motor will turn when executing a Home() command (through DoCommand()).
`cal_factor`	float64	Calibration factor for velocity and acceleration. Compensates for clock source drift when doing time-based calculations.
`run_current`	int32	Set current when motor is turning, from 1-32 as a percentage of rsense voltage. Defaults to 15 if omitted or set to 0.
`hold_current`	int32	Set 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_delay`	int32	How 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.

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 StallGuard^TM (a builtin feature of this controller).

Python
Go

Parameters:

None

Raises:

(error): An error, if one occurred.

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

Example usage:

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().

Example usage:

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.

Python
Go

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.

Example usage:

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.

Example usage:

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})