Handbook - Working with emcsh part 2

Adding new Tcl commands to emcsh and iosh is relatively straight forward if you are familiar with C and C++. All the Tcl/Tk functions can be called at a low level in C. For descriptions of each call, take a look at the man pages, copies of which can be found at
http://tcl.activestate.com/man/tcl8.0/ and http://www.elf.org.

Tcl command extensions for EMC

The following information has been extracted from emcsh.cc. For examples of the correct usage, look at the tcl scripts in emc/src/task/tkemc.tcl or emc/plat/nonrealtime/bin/tkemc.

To use the emcsh commands, use the following at the start of the script:

#!/bin/sh
# the next line restarts using emcsh \
exec plat/nonrealtime/bin/emcsh "$0" "$@"

Using emcsh:

emcsh {<filename>} {-- -ini <ini file>}

With filename, it opens NML buffers to the EMC, runs the script, closes the buffers, and quits.

With -- -ini <inifile>, uses inifile instead of emc.ini. Note that the two dashes prevents Tcl from looking at the remaining args, which would otherwise trigger a Tcl error that it doesn't understand what -ini means.

Without filename, it runs interactively.

The files (or manual input) are Tcl scripts, extended with EMC-specific commands. These commands are all prefixed with "emc_", which makes them somewhat inconvenient for typing but avoids name conflicts, e.g.,open.

Some commands take 0 or more arguments. 0 arguments means they return the associated value; the argument would be to set the value.

Commands are sent to the EMC, and control resumes immediately. You can call a timed wait until the command got there, or a timed wait until the command completed, or not wait at all.

EMC commands:

EMC_INIFILE
Exported values of the EMC global of the same name

emc_plat
Returns the platform for which this was compiled, e.g., linux_2_0_36

emc_ini <var> <section>
Returns the string value of <var> in section <section>, in EMC_INIFILE

emc_debug {<new value>}
With no arg, returns the integer value of EMC_DEBUG, in the EMC. Note that it may not be true that the local EMC_DEBUG variable here (in emcsh and the GUIs that use it) is the same as the EMC_DEBUG value in the EMC. This can happen if the EMC is started from one .ini file, and the GUI is started with another that has a different value for DEBUG.

With an arg, sends a command to the EMC to set the new debug level, and sets the EMC_DEBUG global here to the same value. This will make the two values the same, since they really ought to be the same.

emc_set_wait none | received | done
Set the wait for commands to return to be right away (none), after the command was sent and received (received), or after the command was done (done).

emc_wait received | done
Force a wait for the previous command to be received, or done. This lets you wait in the event that "emc_set_wait none" is in effect.

emc_set_timeout <timeout>
Set the timeout for commands to return to <timeout>, in seconds. Timeout is a real number. If it's <= 0.0, it means wait forever. Default is 0.0, wait forever.

emc_update (none) | none | auto
With no arg, forces an update of the EMC status. With "none", doesn't cause an automatic update of status with other emc_ words. With "auto", makes emc_ words automatically update status before they return values.

emc_error
Returns the current EMC error string, or "ok" if no error.

emc_operator_display
Returns the current EMC operator display string, or "ok" if none.

emc_operator_text
Returns the current EMC operator text string, or "ok" if none.

emc_time
Returns the time, in seconds, from the start of the epoch. This starting time depends on the platform.

emc_estop (none) | on | off
With no arg, returns the estop setting as "on" or "off". Otherwise, sends an estop on or off command.

emc_estop_in
Returns the estop input setting as "on" or "off".

emc_machine (none) | on | off
With no arg, returns the machine setting as "on" or "off". Otherwise, sends a machine on or off command.

emc_mode (none) | manual | auto | mdi
With no arg, returns the mode setting as "manual", "auto", or "mdi". Otherwise, sends a mode manual, auto, or mdi command.

emc_mist (none) | on | off
With no arg, returns the mist setting as "on" or "off". Otherwise, sends a mist on or off command.

emc_flood (none) | on | off
With no arg, returns the flood setting as "on" or "off". Otherwise, sends a flood on or off command.

emc_lube (none) | on | off
With no arg, returns the lubricant pump setting as "on" or "off". Otherwise, sends a lube on or off command.

emc_lube_level
Returns the lubricant level sensor reading as "ok" or "low".

emc_spindle (none) | forward | reverse | increase | decrease |constant | off
With no arg, returns the value of the spindle state as "forward", "reverse", "increase", "decrease", or "off". With arg, sends the spindle command. Note that "increase" and "decrease" will cause a speed change in the corresponding direction until a "constant" command is sent.

emc_brake (none) | on | off
With no arg, returns the brake setting. Otherwise sets the brake.

emc_tool
Returns the id of the currently loaded tool

emc_tool_offset
Returns the currently applied tool length offset

emc_load_tool_table <file>
Loads the tool table specified by <file>

emc_home 0 | 1 | 2 | ...
Homes the indicated axis.

emc_jog_stop 0 | 1 | 2 | ...
Stop the axis jog

emc_jog 0 | 1 | 2 | ... <speed>
Jog the indicated axis at <speed>; sign of speed is direction

emc_jog_incr 0 | 1 | 2 | ... <speed> <incr>
Jog the indicated axis by increment <incr> at the <speed>; sign of speed is direction

emc_feed_override {<percent>}
With no args, returns the current feed override, as a percent. With argument, set the feed override to be the percent value

emc_abs_cmd_pos 0 | 1 | ...
Returns double obj containing the XYZ-SXYZ commanded pos in abs coords, at given index, 0 = X, etc.

emc_abs_act_pos
Returns double objs containing the XYZ-SXYZ actual pos in abs coords

emc_rel_cmd_pos 0 | 1 | ...
Returns double obj containing the XYZ-SXYZ commanded pos in rel coords, at given index, 0 = X, etc., including tool length offset

emc_rel_act_pos
Returns double objs containing the XYZ-SXYZ actual pos in rel coords, including tool length offset

emc_joint_pos
Returns double objs containing the actual pos in absolute coords of individual joint/slider positions, excludes tool length offset

emc_pos_offset X | Y | Z | R | P | W
Returns the position offset associated with the world coordinate provided

emc_joint_limit 0 | 1 | ...
Returns "ok", "minsoft", "minhard", "maxsoft", "maxhard"

emc_joint_fault 0 | 1 | ...
Returns "ok" or "fault"

emc_joint_homed 0 | 1 | ...
Returns "homed", "not"

emc_mdi <string>
Sends the <string> as an MDI command

emc_task_plan_init
Initializes the program interpreter

emc_open <filename>
Opens the named file

emc_run {<start line>}
Without start line, runs the opened program from the beginning. With start line, runs from that line. A start line of -1 runs in verify mode.

emc_pause
Pause program execution

emc_resume
Resume program execution

emc_step
Step the program one line

emc_program
Returns the name of the currently opened program, or "none"

emc_program_line
Returns the currently executing line of the program

emc_program_status
Returns "idle", "running", or "paused"

emc_program_codes
Returns the string for the currently active program codes

emc_joint_type <joint>
Returns "linear", "angular", or "custom" for the type of the specified joint

emc_joint_units <joint>
Returns "inch", "mm", "cm", or "deg", "rad", "grad", or "custom", for the corresponding native units of the specified axis. The type of the axis (linear or angular) is used to resolve which type of units are returned. The units are obtained heuristically, based on the EMC_AXIS_STAT::units numerical value of user units per mm or deg. For linear joints, something close to 0.03937 is deemed "inch", 1.000 is "mm", 0.1 is "cm", otherwise it's "custom". For angular joints, something close to 1.000 is deemed "deg",PI/180 is "rad", 100/90 is "grad", otherwise it's "custom".

emc_program_units
emc_program_linear_units
Returns "inch", "mm", "cm", or "none", for the corresponding linear units that are active in the program interpreter.

emc_program_angular_units
Returns "deg", "rad", "grad", or "none" for the corresponding angular units that are active in the program interpreter.

emc_user_linear_units
Returns "inch", "mm", "cm", or "custom", for the corresponding native user linear units of the EMC trajectory level. This is obtained heuristically, based on the EMC_TRAJ_STAT::linearUnits numerical value of user units per mm. Something close to 0.03937 is deemed "inch", 1.000 is "mm", 0.1 is "cm", otherwise it's "custom".

emc_user_angular_units
Returns "deg", "rad", "grad", or "custom" for the corresponding native user angular units of the EMC trajectory level. Like with linear units,this is obtained heuristically.

emc_display_linear_units
emc_display_angular_units
Returns "inch", "mm", "cm", or "deg", "rad", "grad", or "custom", for the linear or angular units that are active in the display. This is effectively the value of linearUnitConversion or angularUnitConversion, resp.

emc_linear_unit_conversion {inch | mm | cm | auto}
With no args, returns the unit conversion active. With arg, sets the units to be displayed. If it's "auto", the units to be displayed match the program units.

emc_angular_unit_conversion {deg | rad | grad | auto}
With no args, returns the unit conversion active. With arg, sets the units to be displayed. If it's "auto", the units to be displayed match the program units.

emc_log_open <file> <type> <size> <skip>{<axis>}
Open a log into file named <file>. <type> is one of axis_pos, axes_inpos, axes_outpos, axis_vel, axes_ferror, traj_pos, traj_vel, traj_acc, pos_voltage. <size> is size in entries. <skip> is how many to skip. <axis> pertains only to axis_pos and axis_vel types.

emc_log_start
emc_log_stop
Starts or stops logging into the log, which must be already opened with emc_log_open.

emc_log_close
Close the log and dump contents to the file specified in emc_log_open.

emc_probe_index
Which wire is the probe on or which bit of digital IO to use? (No args gets it, one arg sets it.)

emc_probe_polarity
Value to look for for probe tripped? (0 args gets it, one arg sets it.)

emc_probe_clear
Clear the probe tripped flag.

emc_probe_tripped
Has the probe been tripped since the last clear.

emc_probe_value
Value of current probe signal. (read-only)

emc_probe
Move toward a certain location. If the probe is tripped on the way stop motion, record the position and raise the probe tripped flag.

emc_teleop_enable
Should motion run in teleop mode? (No args gets it, one arg sets it.)

emc_kinematics_type
returns the type of kinematics functions used identity=1, serial=2, parallel=3, custom=4

Additional Comments

Further on in emcsh.cc is some additional comments regarding units.

Unit conversion

Length and angle units in the EMC status buffer are in user units, as defined in the INI file in [TRAJ] LINEAR,ANGULAR_UNITS. These may differ from the program units, and when they are the display is confusing.

It may be desirable to synchronize the display units with the program units automatically, and also to break this sync and allow independent display of position values.

The global variable "linearUnitConversion" is set by the Tcl commands emc_linear_unit_conversion to correspond to either "inch", "mm", "cm", "auto", or "custom". This forces numbers to be returned in the units specified, in program units when "auto" is set, or not converted at all if "custom" is specified.

Ditto for "angularUnitConversion", set by emc_angular_unit_conversion to "deg", "rad", "grad", "auto", or "custom".

With no args, emc_linear/angular_unit_conversion return the setting.

The functions convertLinearUnits and convertAngularUnits take a length or angle value, typically from the emcStatus structure, and convert it as indicated by linearUnitConversion and angularUnitConversion, resp.