8. Command reference

Overview

All of the Tic’s serial commands are available on its TTL serial, I²C, and USB interfaces, with the exception of a few commands that are unique to USB. Each command uses one of these four formats:

1. Quick command: no data
2. 7-bit write command: writes a 7-bit value to the Tic
3. 32-bit write command: writes a 32-bit value to the Tic
4. Block read command: reads a block of data from the Tic; the block starts from the specified offset and can have a variable length

Descriptions of how these command formats are encoded for each interface can be found in the following sections (Section 9 for TTL serial, Section 10 for I²C, and Section 11 for USB). (Note that the USB-only “set setting” command is a special case that uses its own unique format.)

List of commands

• Set target position
• Set target velocity
• Halt and set position
• Halt and hold
• Go home
• Reset command timeout
• De-energize
• Energize
• Exit safe start
• Enter safe start
• Reset
• Clear driver error
• Set max speed
• Set starting speed
• Set max acceleration
• Set max deceleration
• Set step mode
• Set current limit
• Set decay mode
• Set AGC option
• Get variable
• Get variable and clear errors occurred
• Get setting
• Set setting (USB only)
• Reinitialize (USB only)
• Start bootloader (USB only)

Set target position

Command	0xE0
Format	32-bit write
Data	target position, signed 32-bit Range: −2,147,483,648 to +2,147,483,647 = −0x8000 0000 to +0x7FFF FFFF Units: microsteps
ticcmd	ticcmd -p NUM ticcmd --position NUM
Arduino library	tic.setTargetPosition(int32_t position)

This command sets the target position of the Tic, in microsteps.

If the control mode is set to Serial / I²C / USB, the Tic will start moving the motor to reach the target position. If the control mode is something other than Serial / I²C / USB, this command will be silently ignored.

In the Tic Control Center, the controls in the “Set target” box can be used to set a target position. These controls are on the “Status” tab and are only available when the control mode is Serial / I²C / USB.

Set target velocity

Command	0xE3
Format	32-bit write
Data	target velocity, signed 32-bit Range: −500,000,000 to +500,000,000 Units: microsteps per 10,000 s
ticcmd	ticcmd -y NUM ticcmd --velocity NUM
Arduino lib	tic.setTargetVelocity(int32_t velocity)

This command sets the target velocity of the Tic, in microsteps per 10,000 seconds.

If the control mode is set to Serial / I²C / USB, the Tic will start accelerating or decelerating the motor to reach the target velocity. If the control mode is something other than Serial / I²C / USB, this command will be silently ignored.

In the Tic Control Center, the controls in the “Set target” box can be used to set a target velocity. These controls are on the “Status” tab and are only available when the control mode is Serial / I²C / USB.

Halt and set position

Command	0xEC
Format	32-bit write
Data	current position, signed 32-bit Range: −2,147,483,648 to +2,147,483,647 = −0x8000 0000 to +0x7FFF FFFF Units: microsteps
ticcmd	ticcmd --halt-and-set-position NUM
Arduino lib	tic.haltAndSetPosition(int32_t position)

This command stops the motor abruptly without respecting the deceleration limit and sets the “Current position” variable, which represents what position the Tic currently thinks the motor is in. Besides stopping the motor and setting the current position, this command also clears the “position uncertain” flag, sets the input state to “halt”, and clears the “input after scaling” variable.

If the control mode is something other than Serial / I²C / USB, this command will be silently ignored.

In the Tic Control Center, the “Set current position” button can be used to halt the motor and set the Tic’s current position to the specified value. This button is on the “Status” tab and is only available when the control mode is Serial / I²C / USB.

Halt and hold

Command	0x89
Format	Quick
Data	none
ticcmd	ticcmd --halt-and-hold
Arduino lib	tic.haltAndHold()

This command stops the motor abruptly without respecting the deceleration limit. Besides stopping the motor, this command also sets the “position uncertain” flag (because the abrupt stop might cause steps to be missed), sets the input state to “halt”, and clears the “input after scaling” variable.

If the control mode is something other than Serial / I²C / USB, this command will be silently ignored.

In the Tic Control Center, the “Halt motor” button can be used to halt the motor. This button is on the “Status” tab and is only available when the control mode is Serial / I²C / USB.

Go home

Command	0x97
Format	7-bit write
Data	0: Go home in the reverse direction 1: Go home in the forward direction
ticcmd	ticcmd --home rev or ticcmd --home fwd
Arduino lib	tic.goHomeReverse() or tic.goHomeForward()

Starts the Tic’s homing procedure as described in Section 5.6.

Reset command timeout

Command	0x8C
Format	Quick
Data	none
ticcmd	ticcmd --reset-command-timeout
Arduino lib	tic.resetCommandTimeout()

If the command timeout is enabled, this command resets it and prevents the “command timeout” error from happening for some time. See Section 5.4 for more information about the command timeout.

The Tic Control Center constantly sends this command while it is connected to a Tic.

De-energize

Command	0x86
Format	Quick
Data	none
ticcmd	ticcmd --deenergize
Arduino lib	tic.deenergize()

This command causes the Tic to de-energize the stepper motor coils by disabling its stepper motor driver. The motor will stop moving and consuming power. This command sets the “position uncertain” flag (because the Tic is no longer in control of the motor’s position); the Tic will also set the “intentionally de-energized” error bit, turn on its red LED, and drive its ERR line high.

The “energize” command will undo the effect of this command (except it will leave the “position uncertain” flag set) and could make the system start up again.

In the Tic Control Center, the red “De-energize” button in the lower left can be used to de-energize the motor.

Energize

Command	0x85
Format	Quick
Data	none
ticcmd	ticcmd --energize
Arduino lib	tic.energize()

This command is a request for the Tic to energize the stepper motor coils by enabling its stepper motor driver. The Tic will clear the “intentionally de-energized” error bit. If there are no other errors, this allows the system to start up.

In the Tic Control Center, the green “Resume” button in the lower left can be used to attempt to energize the motor.

Exit safe start

Command	0x83
Format	Quick
Data	none
ticcmd	ticcmd --exit-safe-start
Arduino lib	tic.exitSafeStart()

In Serial / I²C / USB control mode, this command causes the “safe start violation” error to be cleared for 200 ms. If there are no other errors, this allows the system to start up.

In the Tic Control Center, the green “Resume” button in the lower left will additionally exit safe start if the control mode is Serial / I²C / USB.

Enter safe start

Command	0x8F
Format	Quick
Data	none
ticcmd	ticcmd --enter-safe-start
Arduino lib	tic.enterSafeStart()

If safe start is enabled and the control mode is Serial / I²C / USB, RC speed, analog speed, or encoder speed, this command causes the Tic to stop the motor (using the configured soft error response behavior) and set its “safe start violation” error bit. If safe start is disabled, or if the Tic is not in one of the listed modes, this command will cause a brief interruption in motor control (during which the soft error response behavior will be triggered) but otherwise have no effect.

In Serial mode, an “exit safe start” command is required before the Tic will move the motor again. In the speed control modes, the input must be moved to a neutral position before the Tic will exit safe start and move the motor again. See Section 5.4 for more information about safe start.

Reset

Command	0xB0
Format	Quick
Data	none
ticcmd	ticcmd --reset
Arduino lib	tic.reset()

This command makes the Tic forget most parts of its current state. Specifically, it does the following:

• Reloads all settings from the Tic’s non-volatile memory and discards any temporary changes to the settings previously made with serial commands (this applies to the step mode, current limit, decay mode, max speed, starting speed, max acceleration, and max deceleration settings)
• Abruptly halts the motor
• Resets the motor driver
• Sets the Tic’s operation state to “reset”
• Clears the last movement command and the current position
• Clears the encoder position
• Clears the serial and “command timeout” errors and the “errors occurred” bits
• Enters safe start if configured to do so

The Tic’s serial and I²C interfaces will be unreliable for a brief period after the Tic receives the Reset command, so we recommend waiting at least 10 ms after sending a Reset command before sending additional I²C or serial commands.

This command does not modify the “intentionally de-energized” error bit. Since this command does not trigger a full microcontroller reset, it does not affect the “up time” variable (which indicates the time elapsed since the Tic’s last full microcontroller reset) or the “device reset” variable (which indicates the cause of the Tic’s last full microcontroller reset).

Clear driver error

Command	0x8A
Format	Quick
Data	none
ticcmd	ticcmd --clear-driver-error
Arduino lib	tic.clearDriverError()

This command attempts to clear a motor driver error, which is an over-current or over-temperature fault reported by the Tic’s motor driver. If the “Automatically clear driver errors” setting is enabled (the default), the Tic will automatically clear a driver error and it is not necessary to send this command. Otherwise, this command must be sent to clear the driver error before the Tic can continue controlling the motor. See Section 5.4 for more information about driver errors.

Set max speed

Command	0xE6
Format	32-bit write
Data	max speed, unsigned 32-bit Range: 0 to 500,000,000 Units: microsteps per 10,000 s
ticcmd	ticcmd --max-speed NUM
Arduino lib	tic.setMaxSpeed(uint32_t speed)

This command temporarily sets the Tic’s maximum allowed motor speed in units of steps per 10,000 seconds. The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset.

Set starting speed

Command	0xE5
Format	32-bit write
Data	starting speed, unsigned 32-bit Range: 0 to 500,000,000 Units: microsteps per 10,000 s
ticcmd	ticcmd --starting-speed NUM
Arduino lib	tic.setStartingSpeed(uint32_t speed)

This command temporarily sets the Tic’s starting speed in units of steps per 10,000 seconds. This is the maximum speed at which instant acceleration and deceleration are allowed; see Section 5.1 for more information. The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset.

Set max acceleration

Command	0xEA
Format	32-bit write
Data	max accel, unsigned 32-bit Range: 100 to 2,147,483,647 = 0x64 to 0x7FFF FFFF Units: microsteps per 100 s²
ticcmd	ticcmd --max-accel NUM
Arduino lib	tic.setMaxAccel(uint32_t accel)

This command temporarily sets the Tic’s maximum allowed motor acceleration in units of steps per second per 100 seconds. The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset.

If the provided value is between 0 and 99, it is treated as 100.

This command does not affect the max deceleration, even if the “Use max acceleration limit for deceleration” checkbox in the Tic Control Center is checked. See the set max deceleration command.

Set max deceleration

Command	0xE9
Format	32-bit write
Data	max decel, unsigned 32-bit Range: 100 to 2,147,483,647 = 0x64 to 0x7FFF FFFF Units: microsteps per 100 s²
ticcmd	ticcmd --max-decel NUM
Arduino lib	tic.setMaxDecel(uint32_t decel)

This command temporarily sets the Tic’s maximum allowed motor deceleration in units of steps per second per 100 seconds. The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset.

If the provided value is 0, then the max deceleration will be set equal to the current max acceleration value. If the provided value is between 1 and 99, it is treated as 100.

Set step mode

Command	0x94
Format	7-bit write
Data	step mode, unsigned 7-bit 0: Full step 1: 1/2 step 2: 1/4 step 3: 1/8 step 4: 1/16 step (Tic T834, Tic T825, and Tic 36v4 only) 5: 1/32 step (Tic T834, Tic T825, and Tic 36v4 only) 6: 1/2 step 100% (Tic T249 only) 7: 1/64 step (Tic 36v4 only) 8: 1/128 step (Tic 36v4 only) 9: 1/256 step (Tic 36v4 only)
ticcmd	ticcmd --step-mode MODE (full, half, 1, 2, 2_100p, 4, 8, 16, 32, 64, 128, 256)
Arduino lib	tic.setStepMode(TicStepMode mode) (TicStepMode::Full, TicStepMode::Half, TicStepMode::Microstep1, …, TicStepMode::Microstep256, TicStepMode::Microstep2_100p)

This command temporarily sets the step mode (also known as microstepping mode) of the driver on the Tic, which defines how many microsteps correspond to one full step. The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset.

Set current limit

Command	0x91
Format	7-bit write
Data	current limit, unsigned 7-bit
ticcmd	ticcmd --current NUM (in mA)
Arduino lib	tic.setCurrentLimit(uint16_t limit) (in mA)

This command temporarily sets the stepper motor coil current limit of the driver on the Tic. The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset.

See the description of the “Current limit” setting in Section 6 for information about the units and allowed ranges for the 7-bit current limit argument for each different type of Tic.

Note that the Tic Command-line Utility and the Tic Arduino library use units of milliamps instead.

Tic 36v4 warning: The Tic 36v4 has no meaningful over-temperature shut-off (while the gate driver IC has over-temperature protection, it is the external MOSFETs that will overheat first). An over-temperature condition can cause permanent damage to the motor driver. We strongly recommend you do not increase the current limit setting beyond 4000 mA (or lower in applications with reduced heat dissipation) unless you can first confirm that the temperature of the MOSFETs will stay under 140°C. By default, the Tic will prevent you from setting a current limit above 4000 mA, but you can override this if you use the “Enable unrestricted current limits” setting.

Set decay mode

Command	0x92
Format	7-bit write
Data	decay mode, unsigned 7-bit Tic T500: 0: Automatic Tic T834: 0: Mixed 50% 1: Slow 2: Fast 3: Mixed 25% 4: Mixed 75% Tic T825: 0: Mixed 1: Slow 2: Fast Tic T249: 0: Mixed
ticcmd	ticcmd --decay MODE (mixed, slow, fast, mixed25, mixed50, mixed75)
Arduino lib	tic.setDecayMode(TicDecayMode mode) (TicDecayMode::Mixed, TicDecayMode::Slow, TicDecayMode::Fast, TicDecayMode::Mixed25, TicDecayMode::Mixed50, TicDecayMode::Mixed75)

This command temporarily sets the decay mode of the driver on the Tic. For more information about the decay mode, see Section 6 and the driver datasheet. The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset. If the command contains an unrecognized decay mode, the Tic will use decay mode 0. Although the decay mode on the Tic T500 and Tic T249 is not configurable, those Tics still accept this command.

Set AGC option

Command	0x98
Format	7-bit write
Data	Upper 3 bits specify which AGC option to temporarily change: 0: AGC mode 1: AGC bottom current limit 2: AGC current boost steps 3: AGC frequency limit The lower 4 bits specify the new value of that option. See the documentation of the corresponding settings in Section 6.
ticcmd	ticcmd --agc-mode MODE (on, off, active_off) ticcmd --agc-bottom-current-limit LIMIT (45, 50, 55, 60, 65, 70, 75, 80) ticcmd --agc-current-boost-steps STEPS (5, 7, 9, 11) ticcmd --agc-frequency-limit LIMIT (off, 225, 450, 675)
Arduino lib	tic.setAgcMode(TicAgcMode mode) tic.setAgcBottomCurrentLimit(TicAgcBottomCurrentLimit limit) tic.setAgcCurrentBoostSteps(TicAgcCurrentBoostSteps steps) tic.setAgcFrequencyLimit(TicAgcFrequencyLimit limit) (see Tic.h for allowed enum values)

This command is only valid for the Tic T249. It temporarily changes one of the configuration options of the Active Gain Control (AGC). The provided value will override the corresponding setting from the Tic’s non-volatile memory until the next Reset (or Reinitialize) command or full microcontroller reset.

Get variable

Command	0xA1
Format	Block read
Returns	block of data from variables
ticcmd	ticcmd -s ticcmd --status (shows info with important variables)
	ticcmd -s --full ticcmd --status --full (shows info with all variables)
Arduino lib	(see the tic.get____() functions)

This command reads a block of data from the Tic’s variables; the block starts from the specified offset and can have a variable length. See Section 7 for the offset and type of each variable.

Get variable and clear errors occurred

Command	0xA2
Format	Block read
Returns	block of data from variables
Arduino lib	(see tic.getErrorsOccurred())

This command is identical to the Get variable command, except that it also clears the “Errors occurred” variable at the same time. The intended use of this command is to both read and clear the “errors occurred” variable so that whenever you see a bit set in that variable, you know it indicates an error that occurred since the last “Get variable and clear errors occurred” command.

Get setting

Command	0xA8
Format	Block read
Returns	block of data from settings
ticcmd	ticcmd --get-settings FILE (reads all settings from device to file)
Arduino lib	tic.getSetting(uint8_t offset, uint8_t length, uint8_t * buffer)

This command reads a block of data from the Tic’s settings (stored in non-volatile memory); the block starts from the specified offset and can have a variable length. While some of the Tic’s settings can be overridden temporarily using other commands documented in this section, the settings that this command accesses are stored in non-volatile memory and can only be changed using the Set setting USB command. See Section 6 for the offset and type of each setting.

Set setting (USB only)

Command	0x13
Format	special (see Section 11)
Data	setting data, 8-bit
ticcmd	ticcmd --settings FILE (writes all settings from file to device)

This command writes a byte of data to the Tic’s settings (stored in non-volatile memory) at the specified offset. It is not available on the TTL serial and I²C interfaces. The Tic Control Center software uses this command when you click the “Apply settings” button.

Be careful not to call this command in a fast loop to avoid wearing out the Tic’s EEPROM, which is rated for only 100,000 write cycles.

Reinitialize (USB only)

Command	0x10
Format	Quick
Data	none

This command reloads all settings from the Tic’s non-volatile memory and discards any temporary changes to the settings previously made with serial commands (this applies to the step mode, current limit, decay mode, max speed, starting speed, max acceleration, and max deceleration settings). It does not have any of the other effects of the Reset command, instead applying the new settings seamlessly if possible. This command is not available on the TTL serial and I²C interfaces.

Start bootloader (USB only)

Command	0xFF
Format	Quick
Data	none

This command causes the Tic to start its bootloader in preparation for receiving a firmware upgrade over USB. It is not available on the TTL serial and I²C interfaces.