Skip to content

Motion

The ramp generator, the two motion modes, the units of the ramp registers and the calls that move and stop the motor.

Datasheet sections this page relies on

From Analog Devices (Trinamic) TMC5160A-DS 1.18:

  • Velocity dependent control: 6.2 Velocity Dependent Driver Feature Control Register Set, p. 38
  • Ramp generator registers: 6.3 Ramp Generator Registers, p. 40
  • Reference switches and SW_MODE: 6.3 Ramp Generator Registers, p. 43
  • Ramp status and events: 6.3 Ramp Generator Registers, p. 44
  • Real world unit conversion: 12.1 Real World Unit Conversion, p. 81
  • Motion profiles and early ramp termination: 12.2 Motion Profiles, p. 82
  • Velocity thresholds: 12.3 Velocity Thresholds, p. 84
  • Reference switches: 12.4 Reference Switches, p. 85
  • STEP/DIR interface and MicroPlyer: 15 STEP/DIR Interface, p. 94
  • Emergency stop: 19 Emergency Stop, p. 106
  • Clock oscillator and input: 26 Clock Oscillator and Input, p. 119

All of them, with the driver API for each: Datasheet map.

Modes

Mode Config::mode Strap Moves by
Motion controller MotionController SD_MODE low The internal ramp generator: MoveTo(), MoveBy(), RunVelocity()
STEP/DIR StepDir SD_MODE high Pulses on STEP and DIR; MicroPlyer interpolates to 256 microsteps

EnsureInitialized() reads IOIN and compares the SD_MODE strap with Config::mode; a mismatch returns ModeMismatch and the chip is left with the driver off. In STEP/DIR mode the ramp calls return Unsupported.

The ramp profile

RampProfile holds the six-point ramp of the datasheet (section 6.3, page 40): VSTART, A1, V1, AMAX, VMAX, DMAX, D1, VSTOP and TZEROWAIT. SetRamp() writes all of them before any XTARGET, so a move never starts on half a profile. The defaults are the datasheet's quick-start values. Velocities are in the chip's own unit (microsteps per 2^24 clocks); acceleration in fCLK^2 / (512 * 256 * 2^24) per second.

// Position mode: the ramp generator moves to XTARGET. Poll PositionReached().
tmc5160::Error GoTo(Motor& motor, int32_t target) {
  if (auto r = motor.MoveTo(target); !r) {
    return r.error;
  }
  for (int i = 0; i < 1000; ++i) { // bounded: the caller decides how long a move may take
    const auto done = motor.PositionReached();
    if (!done) {
      return done.error;
    }
    if (done.value) {
      return tmc5160::Error::Ok;
    }
  }
  return tmc5160::Error::Timeout;
}

Units

units::VelocityRegFromHz(hz, fclk) and units::AccelRegFromHzPerS() convert real-world values to register values, with a 128-bit oracle in the tests. The relations (section 12.1, page 81): v[Hz] = v_reg * fCLK / 2^24, a[Hz/s] = a_reg * fCLK^2 / (512 * 256 * 2^24). With the internal 12 MHz clock one velocity count is 0.715 Hz. The clock is Config::clock: an external clock changes every value.

Calls

Call What it does
MoveTo(position) Position mode, XTARGET = position
MoveBy(delta) Position mode relative to XACTUAL; a target that overflows is LimitExceeded (after one read)
RunVelocity(v) Velocity mode; the sign picks the direction (write order and the run-back bound below)
SetMaxVelocity(v) VMAX while moving; above Config::max_velocity_reg it returns LimitExceeded, below VSTART (not 0) InvalidArgument; 0 writes VSTART 0 first (page 84)
Hold() RAMPMODE Hold: the present velocity stays (a stop event still ends it); use Stop() to slow down
Stop(kind) Ramp, Immediate, HoldTarget or Emergency (early ramp termination, section 12.2.4, page 83)
SetHomePosition(x) XACTUAL and XTARGET together; needs standstill
ReadPosition(), ReadVelocity(), ReadTarget(), PositionReached() The motion state

Emergency switches the driver off (DRV_ENN and TOFF 0): the motor is not held, and the ramp generator is told to stop (VMAX 0, velocity mode) so that a later Enable() does not resume the move; Enable() returns Busy until RAMP_STAT shows vzero set, no TZEROWAIT pause and, in position mode with VMAX not 0, position_reached. On UART the TOFF 0 write has no reply, so Disable() and Emergency read IFCNT afterwards (one extra transfer) and return VerifyFailed when the chip did not count the write; DRV_ENN, when wired, is already high by then. Without a DRV_ENN hook a lost write leaves the chopper on, which only the error tells. Writing XACTUAL in position mode starts a move, so SetHomePosition() writes the hold mode first.

Reference switches and homing

SetSwitches() programs SW_MODE: stop on the left or right switch, polarity, swap, and the latches. The latched position is ReadLatchedPosition(). Homing is not a driver call: the right speed, back-off and sequence depend on the machine. examples/host/homing_switch.cpp and homing_stall.cpp show both procedures with the driver's primitives. They home in velocity mode. A position move that a switch or a stall stops has not reached its target, so SetHomePosition() answers Busy for it until Stop() (any kind) or Hold() ends the move: a homing loop that polls SetHomePosition() after a position move must stop it first, or it waits forever. After a position move arrives, the chip waits TZEROWAIT before the next move (pages 41, 83), and the standstill check answers Busy during that pause too.

RunVelocity() called while a position stop pauses for TZEROWAIT or turns back after an overshoot: the ramp may start its run-back before the mode write arrives, by at most VSTARTt + at^2/2 + (VSTART + at)^2/(2AMAX) microsteps, t the time to the accepted mode write (one SPI datagram; one 8-byte UART frame, 80 bit times: 8.3 ms at 9600 baud, 0.7 ms at 115200) and a = max(A1, AMAX) when V1 > 0 and VSTART < V1, else AMAX (V1 = 0 disables A1, page 40). A TZEROWAIT longer than t avoids it (page 83 c). From position mode the motor also keeps, or speeds towards, the old VMAX for that one write before the new VMAX applies. The bound counts from the call: a run-back that already moves keeps its speed for that write too, and 8.3 ms is the least t at 9600 baud (the port and the line add to it).

A new MoveTo() (or MoveBy()) while a Stop(HoldTarget) pauses for TZEROWAIT retargets at once: the RAMPMODE write ends the pause (A51), and the ramp heads for the new target without the rest of the wait. SetMaxVelocity() during the pause changes only the speed of the run-back that follows. Wait for the pause to end (the standstill check is Busy until then) when the extra wait matters to the mechanics.

SetMaxVelocity(0) stops a position move (VSTART 0 first, page 84) and stays in force: MoveTo() and MoveBy() return Refused until SetMaxVelocity() or SetRamp() gives a speed again.

XACTUAL units

In the model and on the chip, XACTUAL counts microsteps at 256 per full step; MSCNT is XACTUAL & 1023 in the sequencer. TSTEP is fCLK / |v_hz| with 256 microsteps (section 6.2, page 38).

Limits

Config::max_velocity_reg is an optional ceiling for VMAX beyond the register limit of 2^23 - 512; a ramp above it is refused. A VSTOP below 10 gives a slow termination (section 12.5, page 86): this is documented advice, not a guard.