DESCRIPTION

The Trinamic Motion Control Language (TMCL) motor controllers come in many models, as described at the Trinamic website. The controllers are supported by spec over serial (RS-232/RS-485), USB and CAN-bus interfaces. (The USB interface appears as a serial device to spec.)

All the models share a common syntax and protocol. The protocol includes up to 256 axis parameters and 256 global parameters, with different models supporting different subsets of the parameters. Some parameters having the same parameter number have different meanings depending on model. Firmware updates can add or subtract support for parameters or change the meaning of certain parameters. Support for a specific TMCM model requires accounting for the set of parameters that model uses. The current TMCL code in spec supports models that have been tested with the code and models that should work, but have not been tested. Fixes for supported models or support for new models will be added based on spec user feedback and requests.

The table below shows in which spec release support for particular TMCM models became available:

Release	TMCM models
6.02	1140 3110
6.09.01	6210
6.10.03	6214
6.10.07	1110 1141 1211 1240
6.12.05	1180 1260
6.12.05*	1021 1111 1160 1241 1290 3212 3214 3230 3351 6110 6212

*Code is in place for these models, but the code hasn't been tested with actual controllers.

CONFIGURATION

Configure the motor controllers on the Devices screen of the configuration editor as follows, choosing the CAN bus or serial/USB entry, as appropriate:

Motor and Counter Device Configuration (Not CAMAC)

MOTORS     DEVICE   ADDR <>MODE NUM                      <>TYPE
   YES /dev/tmcl0     <>   9600  10  Trinamic TMCL (Serial|USB)
   YES                 0         16     Trinamic TMCL (CAN bus)

The TMCL serial interface is RS-485, so requires use of an RS-232 to RS-485 converter to connect to the usual serial ports available on computers.

The TMCL USB interface identifies itself to the computer as a modem-type device. On Linux, the kernel driver will create special device nodes named /dev/ttyACM0, /dev/ttyACM1, etc. The spec udev rules (see /etc/udev/rules.d/10-spec_usb.rules) will automatically create links with corresponding names /dev/tmcl0, /dev/tmcl1, etc. Set the baud rate in the MODE column. The hardware default is 9600.

If using the CAN-bus interface, configure the CAN-bus controller in the field-bus section of the Interfaces screen of the configuration editor. spec allows multiple field-bus controllers to be configured with each assigned an index number starting from zero. The ADDR field for the TMCL device holds the index number of the field-bus controller to be used. One may need to use the USB interface temporarily to set the CAN bus parameters on the TMCL controller to other than the default (1M bit rate, ID 1).

On the Motor screen of the configuration editor, choose TMCL or TMCL_E as the controller type. TMCL_E indicates an encoder is used with the particular channel. The TMCL motor channels require unit/module/channel configuration. The unit numbers refer to the entries on the Devices screen for the controller configuration and start at zero for each type of controller. That is, the first TMCL controller is unit 0, even if other controller types appear before it in the listing. The module number is the configured module address. The channel numbers run from 0 to one minus the number of motor channels. Modules are available with 1, 3 and 6 axes.

The TMCL firmware includes over a hundred parameters. Some of them are standard parameters set by spec, but others are associated with special functions of the controller. The parameters can be set using motor_par() as described below. The parameters can also be configured as non-standard optional parameters using the configuration editor.

Parameters that can be stored in EEPROM (a feature available on some models) will be saved to EEPROM when set using motor_par() or when configured as nonstandard optional parameters in the config file. To prevent excessive writing to EEPROM, spec will always pre-read the value from EEPROM and only store values that are to be changed. EEPROM parameters are indicated in the output of the "dump" and "gdump" commands below with an E in the Access column. An A in the Access column indicates the parameters are automatically saved to EEPROM, a feature available for global parameters on some models of controller.

FUNCTIONS

Note, the second argument in all the following motor_par() commands is case insensitive.

motor_par(mne, "reset")

Restores all settings stored in the EEPROM to their factory defaults. After using this command, it may be necessary to execute a reconfig or restart spec to synchronize spec's settings with that of the TMCL.

motor_par(mne, "last_restore")

Returns the time in seconds since a power cycle was detected for the controller associated with motor mne, or if no power cycle detected, the time since the most recent hardware configuration. The value can be used to detect if there has been a power cycle which would have restored user programmed parameters.

motor_par(mne, "dump" [, pattern])

Displays the current values of the axis parameters for motor mne. The display includes the parameter number, description, value, access permissions and the allowed range of values. The permissions and range are taken from the Trinamic documentation. spec does not test values against the permissions or range. An attempt to set a write-only parameter or to set a value outside an allowed range will produce an error response from the TMCL controller.

If an argument is present, only axis parameters that have a description that matches the pattern are shown. The pattern search is case insensitive. As usual, the pattern may contain the *, ? and [] metacharacters. A * matches any string, while a ? matches any single character. With the [...] pattern, any string that contains the characters within the square brackets is matched. Two characters separated by a hyphen specify a range of characters that will match. An initial ^ negates the enclosed character set.

motor_par(mne, "gdump" [, pattern])

As "dump" above, but for global parameters for the controller associated with motor mne.

motor_par(mne, "par#" [, val])

Sets or returns the value of the axis parameter number specified by #. Parameter numbers range from 0 to 255, although not all numbers are used.

motor_par(mne, "gpar#" [, val])

Sets or returns the value of the global parameter number specified by #. Parameter numbers range from 0 to 255, although not all numbers are used.

motor_par(mne, "PeakCurrent" [, val])

Sets or returns the absolute maximum current value.

motor_par(mne, "PowerDownCurrent" [, val])

Sets or returns the standby current value.

motor_par(mne, "SE_current_min" [, val])

Sets or returns the smartEnergy minimum current value.

motor_par(mne, "SE_current_down" [, val])

Sets or returns the smartEnergy current down step value.

motor_par(mne, "SE_hysteresis" [, val])

Sets or returns the smartEnergy hysteresis value.

motor_par(mne, "SE_current_up" [, val])

Sets or returns the smartEnergy current up step value.

motor_par(mne, "stop_on_stall" [, val])

Sets or returns the stop-on-stall value.

motor_par(mne, "SE_threshold_speed" [, val])

Sets or returns the smartEnergy threshold speed.

motor_par(mne, "SE_current_slow" [, val])

Sets or returns the smartEnergy slow run current value.

motor_par(mne, "AccelerationCurrent" [, val])

Sets or returns the boost current value.

motor_par(mne, "PowerDownDelay" [, val])

Sets or returns the power-down delay time.

motor_par(mne, "set_pullup", 0|1)

Switches the pull-up resistors for all inputs off (0) or on (1).

motor_par(mne, "set_bit", val)

Set output port number val to high.

motor_par(mne, "clr_bit", val)

Set output port number val to low.

motor_par(mne, "put_bits"|"set_bits"|"put_byte", val)

Set output ports that correspond to bits set in val and clears output ports that correspond to bits not set in val.

motor_par(mne, "get_ain", val)

Returns the analog input from bank 1 associated with the command val.

motor_par(mne, "get_bit", val)

Returns 0 or 1 based on whether the input port corresponding to bit number val is high or low.

motor_par(mne, "get_bits"|"get_byte")

Returns an 8-bit value that reflects the setting of the input ports.

The following parameters are associated with the SixPoint motion profile feature available on some models. See the "SixPoint" Motion Profile section below.

motor_par(mne, "SixP_VelRatio" [, value])

Sets or returns the velocity point (V1) at which the second phase of the acceleration or deceleration profile kicks in. The value must be between zero and one, inclusive, and sets the value of V1 to value * ("velocity" - "base_rate"). The default value of zero eliminates the first acceleration phase and the second deceleration phase.

motor_par(mne, "SixP_AccRatio" [, value])

Sets or returns the first phase of the acceleration profile (A1), relative to the second phase (A2). The ratio is with respect to spec acceleration units, which are milliseconds. A ratio less than one will be a shorter time, a faster acceleration and a higher pulses per second per second value (the units used by the TMCM controller). The default value is 1.

motor_par(mne, "SixP_DecRatio" [, value])

Sets or returns the second phase of the acceleration profile (D1), relative to the first phase (D2). The ratio is with respect to spec acceleration units, which are milliseconds. A ratio greater than one will be a longer time, a slower deceleration and a smaller pulses per second per second value (the units used by the TMCM controller). The default value is 1.

motor_par(mne, "SixP_DecAccRatio" [, value])

If the standard optional parameter "deceleration" is not set, sets or returns the value that relates the deceleration to the acceleration. The ratio is with respect to spec acceleration units, which are milliseconds. A value greater than one means the deceleration is slower than the acceleration. The default value is 1.

motor_par(mne, "SixP_StopStartRatio" [, value])

Sets or returns the ratio of VSTOP to VSTART. VSTART is always set to the configured base rate. The default value is 1, which makes VSTOP equal to VSTART.

"SixPoint" MOTION PROFILE

Some TMCL motors implement a feature Trinamic calls a "SixPoint" motion profile. This features divides the speed ramps for acceleration and deceleration each into two regions, characterized by a number of parameters as shown below:

Parameter Name	Number	spec treatment
Start velocity (VSTART)	19	base rate
Stop velocity (VSTOP)	20	VSTART * SixP_StopStartRatio
Maximum velocity (VMAX)	4	slew rate
Velocity (V1)	16	(VMAX - VSTART) * SixP_VelRatio
Acceleration Phase 1 (A1)	15	acceleration (in msec)
Acceleration Phase 2 (A2)	5	acceleration * SixP_AccRatio
Deceleration Phase 1 (D2)	17	deceleration * SixP_DecRatio
Deceleration Phase 2 (D1)	18	deceleration (in msec)
Wait time - WAIT	21	not set

Allowed values for SixP_VelRatio are from zero to one. A value of zero disables the first acceleration phase and the second deceleration phase (A1 and D1).

spec units for acceleration and deceleration are the number of milliseconds over which the acceleration occurs. The TMCL units are pulses per second per second. The ratios for setting the second phase accelerations are with respect to spec units. A ratio less than one will decrease the acceleration time, but increases the number of pulses per second per second.

"deceleration" is a standard optional motor parameter that can be set on the second optional motor parameter screen of the configuration editor. If not set, the parameter is set to acceleration * SixP_DecAccRatio.

The acceleration and deceleration values are converted from spec units of milliseconds to TMCL units of pulses per second per second by dividing the difference between the start and end velocity of the associated phase by the acceleration time in seconds.

The WAIT parameter specifies how long to wait until the next movement can start. A value could be specified via motor_par() or in the config file. Otherwise spec leaves the parameter untouched.

The "SixPoint" support was added in spec release 6.10.03.

RESTORING PARAMETERS ON POWER CYCLE

Motor position and parameters related to motor speed are stored in volatile registers on the TMCL controllers. These registers get reset to zero when the power to the controller is cycled. When initializing a TMCL controller, spec writes a signature value to general purpose register 255. When that register is read back as zero, it is an indication that the power has been cycled.

As of release 6.08.03, spec will (by default) automatically restore motor positions and the other registers if it detects the TMCL controller power has been cycled. The check is performed whenever spec reads the position register and gets a zero. If the signature register value is zero, spec will restore the controller position registers using the values spec has saved in memory (or from the settings file if spec is just starting up). spec will also restore any parameters set in the config file. Note, any volatile parameter values that may have been set with motor_par() from the command line will not be restored, as spec does not keep a record of those values.

A custom controller parameter "check_interval" is available to configure checks on the signature register. These checks are performed before moving, reading positions or changing the dial position, on the sync command, and before changing parameters with motor_par(), but no more often than the specified interval. The "check_interval" parameter can be configured to add the additional checks beyond the new automatic checking triggered when the position register is zero.

To set the custom controller parameter "check_interval", go to the controller configuration line on the Devices screen of the configuration editor and type p to enter the parameter:

Custom Parameters for "Trinamic TMCL (Serial|USB)"

NAME                      VALUE
check_interval            2

The above example configures the checking at no more often than every two seconds. The parameter needs to be separately configured for each controller for which checks are to be enabled.

As of release 6.08.03, if "check_interval" is set to a negative number, both the interval checking and the automatic checking are disabled. Note, though, it is not necessary to create and set the "check_interval" parameter at all, as the default behavior should suffice for most applications.

ENCODERS

spec release 6.03.10 includes encoder support for TMCL motors. Select controller type TMCL_E on the Motor screen for channels with encoders. For such channels, spec will take the current position from axis register 209 "Encoder Position".

As a default, spec will use relative rather than absolute moves for positioning for motors configured as TMCL_E. Absolute positioning can be selected by setting the nonstandard optional motor parameter "encoder_move_mode" to the string "absolute" (as of spec release 6.04.01). To set the parameter, go the associated motor column on the Motor screen of the configuration editor and type p to reach the custom parameter screen. Then enter strings for the parameter name and value:

Custom Parameters for Motor 10 "TMCL" (tmcl)

NAME                      VALUE
encoder_move_mode         absolute

If the standard optional motor parameter "encoder_step_size" is set, spec will use that parameter instead of the standard "step_size" to scale the readings. The chg_dial() function (used by the set_dial macro) will modify register 209 in addition to the commanded position registers 0 and 1, again, scaling by "encoder_step_size", if set. Note, as always, the units of "step_size" and "encoder_step_size" are actually the number of steps per degree, not the size of a step.

Currently, spec does not set the encoder prescaler register (number 210) or the encoder mode register (number 201), available on some models. Use motor_par(), as described above, to set the numbered parameters, if needed. Include the numbered parameters in the config file as nonstandard optional motor parameters if desired.

The encoder support will be refined based on user feedback received at CSS HQ.