EMC source code documentation, first cut

[Fred Proctor <frederick.proctor-at-nist.gov>]

EMC folks,

I've taken a first cut at documenting the EMC source code. I've appended
the contents of the file here, and checked it into SourceForge as
emc/doc/sourcecode.txt. I wanted to get something out as fast as
possible in response to a request I got a week or so ago. I'll spend
some more time on it but here's what I have so far.

--Fred

EMC Source Code Decription
==========================

emcnml
------

inivar
	A program that prints to stdout the .ini file result of a
variable-in-section search, useful for scripts that want to pick
things out of INI files, e.g.,

	you> plat/linux_2_2_14/bin/inivar -var CYCLE_TIME -sec TASK
-ini youremc.ini
	0.010

emcnmlsize
	A short program that prints the size of the EMC NML status
structures. Running this gets you something like this:

	...
	sizeof(EMC_STAT) = 6552

	which shows that the size of the top-level EMC status
structure is 6552 bytes.

canon.hh
	Declarations for the canonical interface functions called by
the NC code interpreter. This includes functions like STRAIGHT_FEED(),
which the interpreter calls when it sees a G1. The implementation of
these functions is in emc/src/emctask/emccanon.cc. In that file, the
functions are implemented to append NML messages onto the interp_list,
which are dequeued in emc/src/emctaskmain.cc and send to either the
motion or IO controller.

emc.cc
	Definitions for the NML message classes declared in
emc.hh. This file is automatically generated from emc.hh by the
CodeGen Java program, and shouldn't be edited. The class methods in
this file call the base class constructors, etc.

emc.gen
	A ad-hoc script that tells the CodeGen Java code generator
what to do when generating emc.cc from emc.hh.

emc.hh
	The declarations for all NML command and status classes. This
is the crux of the EMC messaging. NML messages are sent from the GUI
to the EMC task level, from the task level to the motion and IO
controllers, and are put onto the interp_list by the canonical
interface in emc/src/emctask/emccanon.cc. All the EMC status is
declared in the NML status structures.

emcargs.cc
	A short file containing the definition of the emcGetArgs()
function, which gets the common command line arguments like -ini and
-nml and sets the EMC global variables EMC_INIFILE, EMC_NMLFILE which
are declared in emcglb.h and defined in emcglb.h.

emccfg.h
emcglb.c
	Declarations and definitions for the default value of global
variables, e.g., DEFAULT_EMC_INIFILE, DEFAULT_EMC_NMLFILE,
DEFAULT_AXIS_MAX_VELOCITY.

emcglb.h
	Declarations of the EMC global variables, defined in emcglb.c,
e.g., EMC_INIFILE, EMC_NMLFILE, AXIS_MAX_VELOCITY.

emcnmlsize.cc
	A short program that prints the size of the EMC NML status
structures. Running this gets you something like this:

	...
	sizeof(EMC_STAT) = 6552

	which shows that the size of the top-level EMC status
structure is 6552 bytes.

emcops.cc
	Forced initializations of the EMC NML classes. This
complements the auto-generated emc.cc and lets you force
initializations to be what you want.

extintf.h
	Declarations for all the "External Interface" functions that
are called by the EMC motion and IO controllers, e.g.,
extEncoderRead(), extDacWrite(), extHomeSwitchRead(). Implementations
of these functions dispatch the calls to the actual hardware, like the
Servo To Go board or the parallel port. These dispatchers are files
such as emc/src/emcmot/{extstgmot.c,extsmmot.c}, for the Servo To Go
and parallel port stepper motion functions, respectively.

extppt.c
	Dispatcher of the external interface functions for
general-purpose IO declared in emc/src/emcnml/extintf.h, for the
parallel port.

getinput.c
getinput.h
	Utility function for getting terminal input in a portable
way. Used by the terminal-based diagnostics programs emcpanel and
usrmot.

iniaux.cc
iniaux.hh
iniaxis.cc
iniaxis.hh
inicool.cc
inicool.hh
inilube.cc
inilube.hh
inispin.cc
inispin.hh
initool.cc
initool.hh
initraj.cc
initraj.hh
	Declarations and definitions for the functions called by the
EMC task level to set parameters corresponding to .ini file
parameters. These functions are called by
emc/src/emctask/{bridgeporttaskintf.cc,minimilltaskintf.cc}, and do
such things as compose and send NML messages to the motion and IO
systems.
	The letters after the "ini" signify:
	aux -- parameters from the [EMCIO] section related to estop
	axis -- parameters from the [AXIS_#] section
	cool -- parameters from the [EMCIO] section related to coolant
	lube -- parameters from the [EMCIO] section related to lube
	spin -- parameters from the [EMCIO] section related to the spindle
	tool -- parameters from the [EMCIO] section related to tools
	traj -- parameters from the [TRAJ] section

inivar.c
	Definition of the 'inivar' program, which prints to stdout the
.ini file result of a variable-in-section search, useful for scripts
that want to pick things out of INI files.

interpl.cc
interpl.hh
	Declarations and definitions for the NML_INTERP_LIST class,
for which there is one instance, 'interp_list'. The interp_list is
appended to by the NC interpreter via the canonical interface
functions in emc/src/emctask/emccanon.cc, and dequeued by the task
controller in emc/src/emctask/emctaskmain.cc using the methods such as
get(), clear(), and len().

parport.c
parport.h
	Declarations and definitions for the parallel port IO
functions, e.g., pptDioByteRead(), pptDioShortWrite(),
pptDioWordCheck().

emcmot
------

usrmot
	A terminal-based diagnostics program that connects to the EMC
motion controller, not the top-level EMC, and lets you type in motion
commands and view status. It only requires that the motion controller
be running.

stgmod.o
	RT Linux motion controller based on the 4-axis Servo To Go
Model I board.

stg8mod.o
	RT Linux motion controller based on the 8-axis Servo To Go
Model I board.

stg2mod.o
	RT Linux motion controller based on the 4-axis Servo To Go
Model II board.

stg_v2_8axis_mod.o
	RT Linux motion controller based on the 8-axis Servo To Go
Model II board.

steppermod.o
	RT Linux motion controller for parallel port stepping, using
the "binning" algorithm for allocating pulses that causes resonance in
some systems. This links in the stepper algorithm from emcstepmot.c,
compiled with the -DSTEPPER_MOTORS flag, which generates emcstepmot.o.

freqmod.o
	RT Linux motion controller for parallel port stepping, using
the "servo" algorithm for allocating pulses that improves the
resonance problem from steppermod.o. This uses PID "servoing" to feed
a pulse generator. You need to set at least the P gain to run
this. This links in the stepper algorithm from emcmot.c, compiled with
the -DSTEPPER_MOTORS flag, which generates emcfreqmot.o.

smdromod.o
	A variation of freqmod.o, that uses feedback from Dan Mauch's
DRO board to get real position measurements rather than simply
accumulating output pulses.

simmod.o
	A simulated system using physics-based modeling of DC
servomotors. It's effectively a servo system with a loopback of DAC
output through motor simulators and back through encoder
simulators. This will exhibit overshoot, etc. if you don't have the
PIDs tuned right. It uses the .ini file parameters

	[AXIS_#]
	TORQUE_UNITS =			OZ_IN
	ARMATURE_RESISTANCE =		1.10
	ARMATURE_INDUCTANCE =		0.0120
	BACK_EMF_CONSTANT =		0.0254
	ROTOR_INERTIA =			0.0104
	DAMPING_FRICTION_COEFFICIENT =	0.083
	SHAFT_OFFSET =			0
	REVS_PER_UNIT =			10
	AMPLIFIER_GAIN =		1
	MAX_OUTPUT_CURRENT =		10
	LOAD_RESISTANCE =		1
	COUNTS_PER_REV =		4096

	This is good for running the EMC if you don't have a real
machine tool or Servo To Go board, but do have RT Linux up and
running.

minitetra.o
	A controller for the mini-tetra cable-based Stewart Platform
(hexapod) machine. This replaces the trivial kinematics for machine
tools (trivins.o) with the hexapod kinematics (genhexkins.o), and uses
frequency stepping (emcmot.c, compiled with -DSTEPPER_MOTORS, which
generates emcfreqmot.o).

cubic.c
cubic.h
	Declarations and definitions for the cubic interpolator, which
interpolates trajectory points from the slower trajectory rate (.ini
file parameter [TRAJ] CYCLE_TIME) to the faster axis rate (.ini file
parameter [AXIS_#] CYCLE_TIME). Typically this is 10:1. Cubic
interpolation matches the end points of each section, and the slopes
as well, connecting them with a 3rd-order polynomial. Linear
interpolation matches just the end points, connecting them with a line
(a first-order polynomial). You could write a quintic interpolator,
which would match the end points, slopes, and curvature with a
fifth-order polynomial. This would eliminate any jerk impulses caused
by cubic (and linear) interpolation.

dro.c
dro.h
	Functions for handling Dan Mauch's digital readout board, used
for encoder feedback in the smdromod.o "stepper motor DRO module"
real-time motion control module.

emcmot.c
emcmot.h
	Declarations and definitions for the EMC motion
controller. emcmot.h contains the commands to emcmot, and the status 
data structure. These are put into the Linux/RT Linux shared memory
buffer. This is not NML, since the shared memory buffer didn't support
semaphores for mutual exclusion and we had to use an ad hoc method
using head/tail counts to detect collisions.
	emcmot.h also declares the kinematics functions
kinematicsForward() and kinematicsInverse(), which are implemented in
such files as trivkins.c, puma560kins.c, and genhexkins.c, for machine
tools, the PUMA 560 robot, and hexapods, respectively.
	emc/src/emctask/{bridgeporttaskintf.cc,minimilltaskintf.cc}
convert the NML messages resulting from either the GUI (jogs, homes,
etc.) or the interp_list (G0, G1, F60, etc.) into emcmot commands and
write them to the shared memory buffer.
	emcmot.c is the crux of the EMC motion control. In this file
is the sequence from start to finish for the motion cycle. There are
two parts: trajectory planning and axis control. These run in a single
executable, but since the trajectory planning is done at a slower rate
([TRAJ] CYCLE_TIME in the .ini file) than the axis control ([AXIS_#]
CYCLE_TIME), the trajectory planning cycle is called every nth cycle
of the motion controller, where n is the ratio of the traj/axis cycle
times.
	The motion cycle starts by latching the input positions of
the axes through a call to the external interface function
extEncoderReadAll(). For servos this reads the encoders, going through
the dispatcher function (e.g., extstgmot.c for the Servo To Go
board). For steppers this function just returns the accumulated pulses
that have gone out.
	Trajectory planning means accepting commands for motions onto
the motion queue; planning the accel/cruise/decel for the motion;
blending two successive motions together by starting the second when
the first begins its final decel; handling feed rate override, pause,
and resume; calling the inverse kinematics to convert XYZ to axis
positions (trivial on a machine tool, complicated on a robot); and
appending them on the cubic interpolator so that they can be smoothly
interpolated at the faster axis rate.
	Axis planning means taking the interpolated points off the
cubic interpolators, one for each axis; and running PID servo
compensation for servos, or computing the number of pulses or
frequency needed for the binning (emcstepmot.c) or frequency generator
(emcmot.c) stepper motor algorithms.
	Finally the output is written, and the motion task goes to
sleep until the next timer interrupt wakes it up. Note that the motion
task is not connected to any board interrupt. It uses the native RTOS
timer tasking. This makes it more portable between boards.
	There are two distinct modes in emcmot: free mode and
coordinated mode. In free mode, each of the axes operates
independently of the others. This is the mode used for jogging and
homing, and corresponds to the manual mode of the EMC task level. In
coordinated mode, the axes are run together using the machine's
kinematics. This corresponds to the auto or MDI modes of the EMC task
level.
	Emcmot also handles aborting, enabling/disabling control
(machine on/estop reset, respectively, in the task level), homing,
latching probe triggers, and logging of various data types.

emcmotcfg.h
	Declarations for compile time defaults for the EMC motion
globals. These are distinct from the EMC globals, and are specifically
targeted toward the motion system. They include such things as
EMCMOT_MAX_AXIS (currently 6), DEFAULT_TRAJ_CYCLE_TIME. Many of these
have analogous EMC globals, but some, such as
DEFAULT_SHMEM_BASE_ADDRESS, are specific to the motion controller.
	When the compile-time flag STEPPER_MOTORS is defined, which
you'll see in the Makefiles as "-DSTEPPER_MOTORS", it includes the
code for stepper motors.

emcmotglb.c
emcmotglb.h
	Declarations and definitions for the EMC motion globals. There
default values are declared in emcmotcfg.h. This includes such things
as TRAJ_CYCLE_TIME, SHMEM_BASE_ADDRESS.

emcmotlog.c
emcmotlog.h
	Declarations and definitions for the EMC motion logging data
structure, types of data that can be logged, and functions to
manipulate the log (e.g., open, start, stop, close).

emcmotutil.c
	Functions for manipulating the emcmot error log. Declarations
for these are in emcmot.h. These functions are separated from emcmot.c
so that they can be shared with other programs that want to access the
error log in shared memory.

emcsegmot.c
	A probably obsolete alternative to the emcmot.c motion
planning, based on work done by Rogier Blom of the U of Twente in the
Netherlands while he was at NIST as a guest researcher. This fixes the
problem in emcmot.c where performance degrades as more, smaller
segments are blended together. With emcsegmot.c, we were able to run
the huge contouring NC program from MasterCAM for the race car. Rogier
had a few more things to work on when he left, and it's not complete
yet.

emcstepmot.c
	A version of emcmot.c that uses the "binning" algorithm for
allocating pulses that causes resonance in some systems. This was the
original stepper motor algorithm added to the servo-only emcmot.c,
using the STEPPER_MOTORS compile time flag. This creates a second task
that runs faster than the motion controller, typically 10 cycles for
every motion cycle. During these cycles, the pulses resulting from the
motion cycle's calculated position increment are spread out as best as
possible. The trouble comes when, say, 3 or 7 pulses need to be sent
out in 10 cycles. There are always some leftover time slots, and the
result is erratic pulsing that causes resonance. In many systems this
is not a problem. On a stepper motor Bridgeport machine that Matt
Shaver hooked up, the inertia caused resonance. This was the genesis
for the frequency stepping algorithm, which is part of emcmot.c if you
define STEPPER_MOTORS.

extsmdromot.c
	Implementation of external interface motion functions for
stepper motors, using Dan Mauch's DRO board for encoder feedback.

extsmmot.c
	Implementation of external interface motion functions for
stepper motors, using accumulated pulses as the measure of axis
position.

extstgmot.c
	Implementation of external interface motion functions for
the Servo To Go board.

genhexkins.c
genhexkins.h
	Declarations and definitions for the general hexapod
kinematics. These are the kinematics for Stewart Platform parallel
kinematic machines. They're used in the minitetra.o motion controller,
for the small cable-driven platform.

lsutil.c
lsutil.h
	Least-squares best fit code, not used for anything other than
to build the testlsutil binary and do some least-squares fitting. This
was useful for taking DAC outputs and linearizing them for the .ini
file. You can do this with a good calculator, which we were too lazy
to get so we wrote this.

mmxavg.c
mmxavg.h
	Min-max-average routines for building a window of points in a
ring buffer, and picking out the minimum, maximum, and average
value. A new point added to the ring buffer drops off the oldest
point. These stats are accumulated for three spots in emcmot.c, for
the case when no control is done (in disabled mode, same as estop
reset), when axis control is done, and when axis control plus
trajectory calculations are done.
	These aren't converted into the NML status structure and hence
are not visible from any GUI. You can see them using the "usrmot"
utility for motion diagnostics, by typing "show times" at the
prompt. We should put at least the trajectory stats in the NML
trajectory status structure, so you can do some sort of perfmeter-like
display and see how much CPU time you're soaking.

pid.c
pid.h
	Declarations and definitions for PID servo control. In pid.c,
the important function is pidRunCycle(). If we were to substitute
another servo algorithm, we would have to change the explicit call of
pidRunCycle() in emcmot.c to something like runControlCycle(), and
have a dispatcher that implements this as a call to the new servo
algorithm (and have one for PID too). The problem is that the
runControlCycle() function needs to be generic enough to handle both
cases. There are also the other functions, like pidSetGains(), that
would have to be generalized into a controlSetGains() that has enough
args for both PID and the other algorithms. There is also the problem
of .ini file params. If anyone has another algorithm they want to run,
please chime in.

puma560kins.c
puma560kins.h
	Declarations and definitions for the kinematics for the PUMA
560 robot. This implements kinematicsForward() and
kinematicsInverse(), which are declared in emcmot.h and called in
emcmot.c. This lets us switch kinematics in emcmot by linking in
different ones, without having to recode emcmot.c.

segmentqueue.c
segmentqueue.h
	An alternative to the trajectory planning algorithms in tp.c,
tc.c that fixes their problem with blending more than two motions, as
is done in contouring programs with lots of short motion segments.

stg.h
stg.c
stg2.c
stg2.h
stg_v2_axis8.c
stgdiag.c
	Servo To Go board functions. These are taken from the DOS
drivers that accompany the board, and are Linux-ized.
* stg.h contains the declarations for Model I boards.
* stg.c contains the functions for 4- and 8-axis axis Model I boards,
selectable with the -DSTG_8_AXES compiler flag. 
* stg2.h contains the declarations for Model II boards.
* stg2.c contains the functions for 4-axis Model II boards.
* stg_v2_axis8.c contains the functions for 8-axis Model II
boards. Blame Will for the hideous name.

tc.c
tc.h
	Motion planning algorithms used by emcmot.c for planning
trapezoidal velocity profiles for accel, cruising, and decel.  It
handles linear and circular (with helical) motions. Together with
tp.c, it forms the basis for emcmot trajectory planning.

testlsutil.c
	A testing wrapper for the lsutil.c,h files for least-squares
best fitting. Not used in emcmot, but only as a command-line utility.

testtp.c
tp.c
tp.h
	Blending algorithms used in conjunction with tc.c for blending
two adjacent motions. This could use some serious work due to the
problem blending more than two motions. There's no lookahead for
slowdown of tight corners, etc. Rogier Blom's segment queue algorithm
fixed this, but that code is about 90% there and still needs some
work, according to Rogier. Perhaps some enterprising programmer will
take Rogier's paper and look into this.

trivkins.c
	Trivial implementations of the kinematicsForward() and
kinematicsInverse() functions, for machine tools in which X = axis 1,
Y = axis 2, and Z = axis 3.

usrmot.c
	Command-line diagnostics program that peeks into emcmot, and
sends commands and prints status. An analogy of the full-blown EMC
diagnostics program emcpanel.c, but for motion only.

usrmotintf.c
usrmotintf.h
	Functions to handle the interface between the EMC motion
controller and its supervisor, the EMC task level. This handles the
gory details of connecting between user-level Linux processes (like
the EMC task level) and RT-Linux processes (like the EMC motion
controller). In here you'll see all sorts of communication goodies,
like the original RT-Linux FIFOs that aren't used anymore, mapping of
physical memory set aside by LILO at boot time, etc.

emcsim
------

amplifier.c
amplifier.h
	Declarations and definitions for a simulated
amplifier. Parameters that can be set include load resistance, max
output current, etc. Running a cycle of the simulation with
amplifierRunCycle() will generate the amplifier's output, which can be
used to drive a DC servomotor simulator. It checks for current limits
and will trip if they're exceeded. Linked into simmod.o (the realtime
simulator) and emcmotsim (the non-realtime simulator).

dcmotor.c
dcmotor.h
	Declarations and definitions for a simulated DC servomotor,
using the model from Benjamin C. Kuo, "Automatic Control Systems,"
Fourth Edition,  pp. 176-186. You set motor parameters such as
armature resistance, armature inductance, back emf constant, motor
rotor inertia, and viscous friction coefficient. Running a cycle of
the simulation with dcmotorRunCycle() will generate the motor's next
output position, given an input voltage. Linked into simmod.o (the
realtime simulator) and emcmotsim (the non-realtime simulator).

encoder.c
encoder.h
	Declarations and definitions for a simulated
encoder. Converts motor revolutions from the dcmotor simulator to
encoder counts. Generates an index pulse on a revolution
boundary. Linked into simmod.o (the realtime simulator) and emcmotsim
(the non-realtime simulator). 

extsimaio.c
extsimdio.c
extsimmot.c
	Dispatcher code for the simulated external interfaces to
analog, digital, and motion-related IO. Uses internal variables to
save output state. For environments that support it, uses the presence
of files to cause changes in input state. So, you can "touch di3" in
the directory in which the simulator is running, and it registers
digital input 3 as being on. "rm di3" removes the file, and the
simulator will register digital input 3 as off.

inisim.cc
	A program for initializing the parameters for dcmotors,
encoders, amplifiers, etc. from .ini file params.

sim.h
simaio.c
simdio.c
simmot.c
	Declarations and definitions for the implementations of
simulated external interface functions, e.g., simEncoderRead(),
simDacWrite(). These are called by the dispatchers in extsimaio.c,
extsimdio.c, and extsimmot.c to give them the extEncoderRead(),
etc. function names expected in the generic motion and IO controllers.

simmot_n.cc
simmot_n.gen
simmot_n.h
	NML-ization of simulator commands, for sending these to
controllers via a .ini file. The idea here is to send messages to load
the simulation parameters, rather than have the simulator read them
from .ini files. This is for RT Linux, which doesn't have access to
files.

emcio
-----

emcio.hh
	Declarations for the main C++-based EMC IO controller defined in
bridgeportiomain.cc amd minimilliomain.cc.

bridgeportaux.cc
bridgeportcool.cc
bridgeportlube.cc
bridgeportspin.cc
bridgeporttool.cc
	Controllers for the estop (aux), coolant, lubricant, spindle,
and tooling for Bridgeport-style machines. These contain the logic for
handling spindle brake and actuation interlocks, time delays,
etc. They can be thought of as a collection of state machines written
in C++ that are equivalent to a PLC program. A big win would be to
replace these with a Linux-based PLC that lets you program in the
IEC-1131 suite of PLC languages. Supposedly Puffin PLC is an
open-source effort to do this.

minimillaux.cc
minimilltool.cc
	Same as above, for the smaller set of controllers required to
run the minimill, which doesn't have automatic coolant, lube, or
spindle control.

bridgeportiomain.cc
minimilliomain.cc
	Main controller that reads the NML buffers for the EMC IO
controller and runs through the Bridgeport-specific controllers in
bridgeport{aux,cool,lube,spin,tool}.cc, or the minimill-specific
controllers in minimill{aux,tool}.cc.

extbridgeportio.c
extminimillio.c
	Dispatchers for the IO functions called in the bridgeportio*.cc
and minimillio*.cc controllers. For the Bridgeport, they call parallel
port functions. For the minimill, most of them stub out to the
simulated functions, since there's no coolant, lube, etc. on the
minimill.

iosh.cc
	A Tcl/Tk wrapper for general-purpose IO, the windowing "IO
shell". It contains functions for reading and writing IO points that
can be called from a Tcl/Tk script, e.g., inb, outb, and also to read
and write NML commands and status. You use this to build a full-blown
PLC in a Tcl/Tk script, giving it graphical LEDs, etc. An example of
this is in tkio.tcl.

tkio.tcl
	A Tcl/Tk script that uses the functions in the windowing IO
shell iosh.cc to build a controller for Bridgeport-style IO control.

rs274ngc
--------

canon_stand_alone.cc
	Implementations of the canonical functions, prototyped in
emc/src/emcnml/canon.hh, that just print their names instead of doing
any work. Used by the standalone interpreter for testing purposes.

driver.cc
	Functions necessary to build the standalone interpreter used
for testing purposes.

rs274ngc.cc
rs274ngc.hh
	Declarations and definitions for the RS-274/NGC
interpreter. This is a set of functions called by the EMC task level
controller to open, read, and execute NC code in the dialect specified
by Rockwell Automation in their report for the National Center for
Manufacturing Sciences (NCMS), "The Next Generation Controller Part
Programming Functional Specification (RS-274/NGC)." The Next
Generation Controller was an Air Force-sponsored program to define an
standard CNC.

rs274ngc.var
	Template file for the EMC .var file, used to save and restore
interpreter variables. Variables are named by number, and range from 1
to 5399. Some are reserved, e.g., axes offsets for G92 are 5211-5213,
offsets for G54 are 5221-5223, and latched probe positions are
5061-5063. Those variables you list in the .var file are saved and
restored each time the EMC is run.

emctask
-------

emcpanel (built in emc/src/emctask)
	A terminal-based diagnostics program that connects to the EMC
as does a typical GUI, and lets you type in commands and view
status. emcpanel provides all you need to bring up and run your
machine, but your fingers will tire quickly. Usually the full EMC
(task, io, motion) should be running, but emcpanel can be used with
the IO controller by itself for debugging.

inimot (built in emc/src/emctask)
	A program that reads a .ini file and sends the motion-specific
values from the [TRAJ] and [AXIS_#] sections to the EMC motion
controller. It is intended to be used to initialize the motion
controller for subsequent debugging with usrmot, e.g.,

	you> insmod plat/rtlinux_2_2/lib/stgmod.o
	...
	you> plat/linux_2_2_14/bin/inimot -ini youremc.ini
	...
	you> plat/linux_2_2_14/bin/usrmot -ini youremc.ini
	...

bridgeporttaskintf.cc
minimilltaskintf.cc
	Implementations of the EMC NML functions that send motion and
IO commands to the subsystems. These include such things as
emcAxisJog, emcSpindleOn, etc. The functions compose and send NML or
emcmot commands to the IO or motion subsystem. There are two of these,
one for Bridgeport-style machines and one for the minimill, since
there is some difference in how each handles IO. Specifically, spindle
commands can be routed to the unused 4th axis on a Servo To Go board
to be used for analog spindle control on the minimill. In this case,
the spindle commands that the bridgeporttaskintf.cc routes to the EMC
IO controller are instead routed to the EMC motion controller as raw
DAC commands by minimilltaskintf.cc.

debug.cc
	As Will modestly describes it, "a pathetic copy of the DOS
debug program. OK for testing io ports."

tkemc.tcl
	AKA TkEMC, the main EMC GUI, which replaces the X windows and
earlier interfaces. It's written in Tcl/Tk, a scripting language. The
default windowing shell "wish" used for regular Tcl/Tk scripts won't
work for EMC since it lacks commands for sending and reading NML
commands and status. We wrote emcsh.cc, the windowing "EMC shell"
which extends wish with EMC commands.
	The same sort of thing can be done for Perl/Tk and
Python/Tk. Someone should look into this.

genedit.tcl
	A general-purpose editor written in Tcl/Tk. This is used to
edit NC programs from the TkEMC GUI, rather than having to open
another editor window.

tkbackplot.tcl
	A nifty tool path drawing application that reads the machine
position from the EMC and draws the tool path. It has buttons that
duplicate those on the tkemc.tcl GUI script so you can bring programs
up and run them in the same application.

emccalib.tcl
emclog.tcl
emctesting.tcl
emctuning.tcl
	Scripts that can be called from the TkEMC Tcl/Tk-based GUI for
calibrating PID settings, logging, testing and system
identification. There are likely to be more of these now that TkEMC
automatically builds a menu of all .tcl scripts it finds in the
tcl/scripts directory.

emccanon.cc
	Implementation of the canonical functions, called by the NC
interpreter in emc/src/rs274ngc/rs275ngc.cc, that put messages on the
interp_list queue for the EMC task controller in emctaskmain.cc to
pull off and handle. Everything that happens in the interpreter has to
go through here.

emcdummy.cc
	A dummy version of the EMC, that creates the NML communication
buffers, reads commands, and says it's done with the commands right
away regardless of what they are. It's useful as an EMC stub for
testing handshaking of external applications that send EMC
commands. It's not useful for anything more than testing handshaking,
since it doesn't fake much of the EMC status. You can't really use it
for GUI development. Run the EMC simulator "emcmotsim" in conjuction
with the EMC task and IO controllers for this sort of thing.

emcpanel.cc
	A text-based interface to the EMC. You can type in commands
and read status from the command line. One could build a GUI from this
using a program like "expect" and Tcl/Tk, but it's slower than
building EMC commands into a the "wish" windowing shell, which is what
we did with emcsh.cc.

emcsh.cc
	An extension of the Tcl/Tk windowing shell "wish" that adds
EMC commands, hence the name "emcsh" for "EMC shell." emcsh connects
to the EMC using NML, and provides all the Tcl string commands you
need to send EMC commands and check status. It's meant to be the first
line in Tcl/Tk scripts, namely the tkemc.tcl GUI script, so you don't
invoke it manually. You can, however, and use it to type commands and
view status similar to emcpanel.

emcsvr.cc
	A network server for the EMC command and status buffers. This
needs to be running for processes to connect remotely across the
network. If you uncomment

	[EMCSVR]
	EMCSERVER = emcsvr

in the .ini file, it will be run. Then, in the .nml file, you can
specify that a process like xemc (which is what the GUIs call
themselves) should connect remotely, e.g.,

	P xemc emcCommand REMOTE localhost W 0 10.0 0 10
	P xemc emcStatus REMOTE localhost R 0 10.0 0 10
	P xemc emcError REMOTE localhost R 0 10.0 0 10
	P xemc toolCmd  REMOTE localhost W 0 10.0 0 10
	P xemc toolSts  REMOTE localhost R 0 10.0 0 10

where "localhost" is replaced with the hostname of the computer that
the EMC is actually running on.

emctask.cc
	Implementation of the EMC task level functions, e.g.,
emcTaskSetMode() for manual, auto, MDI; emcTaskSetState() for off, on,
estop, estop reset; and emcTaskPlanOpen(), emcTaskPlanRun() for running
NC
files.

emctaskmain.cc
	The main control loop for the EMC task level. It reads the NML
buffers; handles commands from the GUI or other external source;
calls the interpreter functions if a program is running; looks at the
interp_list and checks to see what's next to send out and when it
should go out; and writes the EMC status.

inimot.cc
	A short program that reads the .ini file and sends the
motion-specific values to the EMC motion controller. If you run the
motion controller manually, without the task and IO controllers, you
can use this to force .ini parameters into the motion system so that
it's configured properly for subsequent testing with the usrmot utility.

keystick.cc
	An ancient character-graphics "GUI". Uses the curses terminal
control library to draw characters at various X-Y coordinates on the
screen. This was done in advance of a full X Windows GUI, which was
then made obsolete by the TkEMC.

xemc.cc
yemc.cc
	X Windows-based GUIs, written using the Xt toolkit. It's
another example of how one can, but should not, write a GUI. xemc is
the original; yemc is a successor that gives 6-axis status for use
with the minitetra cable-based Stewart Platform.
	Use TkEMC instead. Others may be looking into a Motif/Lesstif
version of this, and can use this source code as an example of how to
connect to the EMC.