The EMC is configured with human readable text files. All of these
files can be read and edited in any of the common text file editors
available with most any Linux distribution.1.1 You'll need to be a bit careful when you edit these files. Some mistakes
will cause the startup to fail. These files are read whenever the
software starts up. Some of them are read repeatedly while the CNC
Configuration files include;
This chapter describes the EMC2's INI file in just enough detail so
that the reader can understand which variable values might need to
be edited in order to make a stock configuration conform to a real
- The ini file overrides defaults that are compiled
into the EMC code. It also provides sections that are read directly
by the Hardware Abstraction Layer.
- The hal files start up process modules and provide
linkages between EMC signals and specific hardware pins.
- The var file provide a set of numbered variables
for use by the interpreter. These values are saved from one run to
- The tbl file saves tool information.
- The nml file configures the communication channels
used by the EMC. It is normally setup to run all of the communication
within a single computer but can be modified to communicate between
- This file saves user specific information
and is created to save the name of the directory when the user first
selects an EMC configuration.1.2
A typical INI file follows a rather simple layout that includes;
Each of these elements is separated on single lines. Each end of line
or newline character creates a new element.
A comment line is started with a ; or a # mark. When the ini reader
sees either of these marks at the start a line, the rest of the line
is ignored by the software. Comments can be used to describe what
some INI element will do.
Comments can also be used to select between several values of a single
- ; This is my little mill configuration file.
; I set it up on January 12, 2006
In this list, the DISPLAY variable will be set to
axis because all of the others are commented out. If someone carelessly
edits a list like this and leaves two of the lines uncommented, the
first one encountered will be used.
- # DISPLAY = tkemc
DISPLAY = axis
# DISPLAY = mini
# DISPLAY = keystick
Sections in an INI file work like file folders in a drawer. They separate
variables based on what part of the EMC they refer to. A section line
looks like [THIS_SECTION]. The name of the section is enclosed
in brackets. Common INI files have several sections including;
Each of these section names are on a line by themselves so you can
quickly scan through the file.
- [EMC] general information ()
- [DISPLAY] selects and sets up some display characteristics
- [TASK] sets up the task planner ()
- [RS274NGC] location of interpreter specific file
- [EMCMOT] motion module and default characteristics
- [HAL] hardware configuration files and commands ()
- [TRAJ] information for the motion planner ()
- [AXIS_0] ... [AXIS_n] individual axis
- [EMCIO] emc's input and output variables. ()
A variable line is made up of a variable name, an equals sign(=),
and a value. Everything from the first non-whitespace
character after the = up to the end of the line is passed as the value,
so you can embed spaces in string symbols if you want to or need to.
A variable name is often called a keyword. These variables and the
values they are assigned are the way that the INI affects the operation
of the EMC. You can edit the values for each keyword in any text editor.
Changes don't take effect until the next time the controller is run.
The following sections detail each section of the
configuration file, using sample values for the configuration lines.
Some of the variables are used by EMC, and must always use the section
names and variable names shown. Other variables are used only by HAL,
and the section names and variable names shown are those used in the
sample configuration files.
INI Variable Definitions
- VERSION = $Revision: 1.3 $
version number for the INI file. The value shown here looks odd because
it is automatically updated when using the Revision Control System.
It's a good idea to change this number each time you revise your file.
If you want to edit this manually just change the number and leave
the other tags alone.
- MACHINE = My Controller
is the name of the controller, which is printed out at the top of
most graphical interfaces. You can put whatever you want here as long
as you make it a single line long.
- RS274NGC_STARTUP_CODE = G21 G90
string of NC codes that the interpreter is initialized with. These
are the codes that an interpreter will be reset to.
DISPLAY = tkemc The
name of the user interface to use. Valid options may include:
- BASE_PERIOD = 50000
- Base task period,
in nanoseconds - this is the fastest thread in the machine. It's units
are nanoseconds. This is a fairly conservative value but if you are
installing on a very old, slow processor you may have to make this
a larger number or the machine may lock up or reboot.
You might want to make this value smaller if you have a fast computer
because this value sets the maximum number of stepper pulses you can
get from your machine. It has little effect on servo systems so leave
it large. In the absence of long setup or hold times, the absolute
maximum step rate for a step+direction motor is one step per two BASE_PERIOD,
Thus, the BASE_PERIOD shown above gives an absolute maximum step
rate of 10000 steps per second.
- SERVO_PERIOD = 1000000
- Servo task period
is also in nanoseconds. This value will be rounded to an integer multiple
Most systems will not need to change this value. It is the update
rate of the low level motion planner. You'll need it even if you only
- TRAJ_PERIOD = 10000000
- Trajectory Planner
task period in nanoseconds This value will be rounded to an integer
multiple of SERVO_PERIOD.
Folk with fast computers have found that reducing this value by half
will give them smother motion blending during contour cutting .
The [TASK] section contains general parameters for EMCTASK, which
includes primarily the NC language interpreter and the sequencing
logic for sending commands to EMCMOT and EMCIO.
- CYCLE_TIME = 0.100
- The period, in seconds, at which EMCTASK
will run. This parameter mostly affects the polling interval when
waiting for motion to complete, or when executing a pause instruction.
It no longer affects the throughput when transferring segments to
the real-time layer. Making it 0.0 or a negative number will tell
EMCTASK not to sleep at all.
The [HAL] section lists files and commands to setup the Hardware
Abstraction Layer. If this is a stepper system you might see several
files here. The exact set would depend upon the configuration of signals
at the parallel port. At a minimum you would see the following. Sherline
mills use the ``standard_pinout'', and ``xylotex_pinout''
matches the setup for those brand of cards.
You can also add variables (commands really) here.1.4
- HALFILE = core_stepper.hal
HALFILE = standard_pinout.hal
# HALFILE = xylotex_pinout.hal
The [TRAJ] section contains general parameters
for the trajectory planning module in EMCMOT. You will not need to
change these if you are applying EMC to a common three axis mill in
the United States of America. If you are in an area using metric hardware
components you might be working with the stepper_mm.ini where these
numbers are already setup for that system of units.
- AXES = 3
- The number
of controlled axes in the system. If you have a four axis system put
that number here and edit the next two variables as well
- COORDINATES = X Y Z
names of the axes being controlled. X, Y, Z, A, B, and C are all valid.
It is also possible to have X Y Y Z and control ganged slides. For
a fourth axis mounted on X you would use X Y Z A. This has no effect
on the mapping from G-code axis names (X- Y- Z-) to joint numbers-kinematics
does this-but is largely for documentation.
- HOME = 0 0 0
of the homed position of each axis. Again for a fourth axis you will
need 0 0 0 0. This value is only used for machines with nontrivial
kinematics. On machines with trivial kinematics this value is ignored.
- LINEAR_UNITS = <units>
name of units to be used. Possible choices are (in, inch, imperial,
metric, mm). For systems executing in native English (inch) units,
this value shall be any one of 'in', 'inch' or 'imperial'. For systems
executing in native millimeter units, this value shall be 'mm' or
'metric'. This does not affect the ability to program in English or
metric units in NC code. It is used to determine how to interpret
the numbers reported in the controller status by external programs.
- ANGULAR_UNITS = <units>
name of units to be used. For systems executing in native degree units,
this value should be 'deg' or 'degree'. For systems executing in radians,
this value is 'rad' or 'radian'. Another possible value is 'grad'
or 'gon' for units operating in gradians (400 gradians in a full circle).
- DEFAULT_VELOCITY = 0.0167
initial velocity used for axis or coordinated axis motion, in user
units per second. The value shown is one unit per minute.
- DEFAULT_ACCELERATION = 2.0
initial acceleration used for axis or coordinated axis motion, in
user units per second per second.
- MAX_VELOCITY = 5.0
maximum velocity for any axis or coordinated move, in user units per
second. Think for a moment what this value really means in hardware
terms. The formula is MAX_VELOCITY * 60. In this case this is 300
inches per minute.
- MAX_ACCELERATION = 20.0
maximum acceleration for any axis or coordinated axis move, in user
units per second per second.
- POSITION_FILE = position.txt
- If set to a non-empty value,
the joint positions are stored between runs in this file. This allows
the machine to start with the same coordinates it had on shutdown.1.5 If unset, joint positions are not stored and will begin at 0 each
time emc is started.
The [AXIS_0], [AXIS_1], etc. sections contains
general parameters for the individual components in the axis control
module. The axis section names begin numbering at 0, and run through
the number of axes specified in the [TRAJ] AXES entry minus 1.
Values for the various parameters of LINEAR axes
are in the units specified in the [TRAJ] LINEAR_UNITS entry. Values
for the position of ANGULAR axes are in the units specified in the
[TRAJ] ANGULAR_UNITS entry.
- TYPE = LINEAR
- The type
of axes, either LINEAR or ANGULAR.
- MAX_VELOCITY = 1.2
- Per axis maximum velocity while coordinated
motion is in effect.
- MAX_ACCELERATION = 20.0
- Per axis maximum acceleration while
coordinated motion is in effect.
- BACKLASH = 0.000
- Backlash compensation value can be used to
make up for small deficiencies in the hardware used to drive an axis.
Don't expect this to compensate for poor mechanical elements. The
value set here is in UNITS.
- COMP_FILE = file.extension
- A file holding a compensation structure
for the specific axis. The values inside are triplets of nominal,
forward and reverse positions which correspond to the nominal position
(where it should be), forward (where the axis is while travelling
forward) and reverse (where the axis is while travelling back). One
set of triplets per line. Currently the limit inside EMC2 is for 256
triplets / axis.
- COMP_FILE_TYPE = 1
- Specifying a non-zero value changes the
expected format of the COMP_FILE. While type == 0, the expected values
are triplets for nominal, forward & reverse. With COMP_FILE_TYPE
non-zero, the expected values in the COMP_FILE are nominal, forward_trim
and reverse_trim. These correspond to the nominal, nominal-forward
and nominal-reverse defined above.
- INPUT_SCALE = 4000
variable has slightly different meaning for stepper and for servo
systems. For steppers, the only number it is the number of pulses
required to move the axis one UNIT.
For servos this value is the scale factors for the
axis input from the raw feedback device, e.g., an incremental encoder.
The units on the scale value are in raw units (e.g., counts) per user
units (e.g., inch).
The value for scale can be obtained by doing a unit
analysis, i.e., units are
For example, on a 2000 counts per rev encoder, and
10 revs/inch gearing, and desired units of mm, we have
and, as a result,
input[mm] = (encoder[counts])/787.4
- MIN_LIMIT = -1000
minimum limit (soft limit) for axis motion, in user units. When this
limit is exceeded, the controller aborts axis motion.
- MAX_LIMIT = 1000
maximum limit (soft limit) for axis motion, in user units. When this
limit is exceeded, the controller aborts axis motion.
- MIN_FERROR = 0.010
- This is the value by
which the axis is permitted to deviate from commanded position at
very low speeds. If MIN_FERROR is smaller than FERROR, the two produce
a ramp of error trip points. You could think of this as a graph where
one dimension is speed and the other is permitted following error.
As speed increases the amount of following error also increases toward
the FERROR value.
- FERROR = 1.0
is the maximum allowable following error, in user units. If the difference
between commanded and sensed position exceeds this amount, the controller
disables servo calculations, sets all the outputs to 0.0, and disables
the amplifiers. If MIN_FERROR is present in the .ini file, velocity-proportional
following errors are used. Here, the maximum allowable following error
is proportional to the speed, with FERROR applying to the rapid rate
set by [TRAJ]MAX_VELOCITY, and proportionally smaller following
errors for slower speeds. The maximum allowable following error will
always be greater than MIN_FERROR. This prevents small following
errors for stationary axes from inadvertently aborting motion. Small
following errors will always be present due to limited position resolution,
- UNITS = inch
- Historically, the UNITS were specified
for each axis. It is now preferable to specify the [TRAJ]LINEAR_UNITS
and [TRAJ]ANGULAR_UNITS values only, and have no [AXIS_n]UNITS
The next few parameters are Homing related, for a better explanation
- HOME_OFFSET = 0.0
- The axis position of the home switch or
- HOME_SEARCH_VEL = 0.0
- A value of
zero means assume that the current location is the home position for
the machine. If your machine has no home switches you will want to
leave this value alone.
- HOME_LATCH_VEL = 0.0
- This is the final velocity to be used
during a home sequence.
- HOME_USE_INDEX = NO
- If the encoder used for this axis has
an index pulse, and the motion card has provision for this signal
you may set it to yes. When it is yes, it will affect the kind of
home pattern used.
- HOME_IGNORE_LIMITS = NO
- Some machines use a limit switch
as a home switch. This variable should be set to yes if you machine
The following items are for servo-based systems and servo-like systems
including the univstep board from Pico Systems. 1.6
- P = 50
- The proportional
gain for the axis servo. This value multiplies the error between commanded
and actual position in user units, resulting in a contribution to
the computed voltage for the motor amplifier. The units on the P gain
are volts per user unit.
- I = 0
- The integral gain
for the axis servo. The value multiplies the cumulative error between
commanded and actual position in user units, resulting in a contribution
to the computed voltage for the motor amplifier. The units on the
I gain are volts per user unit-seconds.
- D = 0
- The derivative gain
for the axis servo. The value multiplies the difference between the
current and previous errors, resulting in a contribution to the computed
voltage for the motor amplifier. The units on the D gain are volts
per user unit per second.
- FF0 = 0
- The 0-th order
feedforward gain. This number is multiplied by the commanded position,
resulting in a contribution to the computed voltage for the motor
amplifier. The units on the FF0 gain are volts per user unit.
- FF1 = 0
- The 1st order
feedforward gain. This number is multiplied by the change in commanded
position per second, resulting in a contribution to the computed voltage
for the motor amplifier. The units on the FF1 gain are volts per user
unit per second.
- FF2 = 0
- The 2nd order
feedforward gain. This number is multiplied by the change in commanded
position per second per second, resulting in a contribution to the
computed voltage for the motor amplifier. The units on the FF1 gain
are volts per user unit per second per second.
- OUTPUT_SCALE = 1.000
- OUTPUT_OFFSET = 0.000
- These two values are
the scale and offset factors for the axis output to the motor amplifiers.
The second value (offset) is subtracted from the computed output (in
volts), and divided by the first value (scale factor), before being
written to the D/A converters. The units on the scale value are in
true volts per DAC output volts. The units on the offset value are
in volts. These can be used to linearize a DAC.
Specifically, when writing outputs, the EMC first
converts the desired output in quasi-SI units to raw actuator values,
e.g., volts for an amplifier DAC. This scaling looks like:
The value for scale can be obtained analytically by doing a unit
analysis, i.e., units are [output SI units]/[actuator units].
For example, on a machine with a velocity mode amplifier such that
1 volt results in 250 mm/sec velocity,
Note that the units of the offset are in user units, e.g., mm/sec,
and they are pre-subtracted from the sensor readings. The value for
this offset is obtained by finding the value of your output which
yields 0.0 for the actuator output. If the DAC is linearized, this
offset is normally 0.0.
] = (output
] - offset
The scale and offset can be used to linearize the
DACs as well, resulting in values that reflect the combined effects
of amplifier gain, DAC non-linearity, DAC units, etc. To do this,
follow this procedure:
- Build a calibration table for the output, driving
the DACs with a desired voltage and measuring the result. See table
for an example of voltage measurements.
- Do a least-squares linear fit to get coefficients
a, b such that
meas = a*raw + b
- Note that we want raw output such that our measured
result is identical to the commanded output. This means
cmd = a*raw + b
raw = (cmd - b)/a
- As a result, the a and b coefficients from the linear
fit can be used as the scale and offset for the controller directly.
- MAX_OUTPUT = 10
- The maximum
value for the output of the PID compensation that is written to the
motor amplifier, in volts. The computed output value is clamped to
this limit. The limit is applied before scaling to raw output units.
- MIN_OUTPUT = -10
minimum value for the output of the PID compensation that is written
to the motor amplifier, in volts. The computed output value is clamped
to this limit. The limit is applied before scaling to raw output units.
Output Voltage Measurements
The following items are used by core_stepper.hal to set
limits on the step waveforms that will be generated. They typically
include a headroom of 5% to 10% compared to the MAX_VELOCITY and
MAX_ACCEL items in the same AXIS.
- STEPGEN_MAXVEL = 1.4
- A value applied to the stepper pulse
generator to provide some overhead for following error catch up.1.7
- STEPGEN_MAXACCEL = 21.0
- Overhead for the stepper pulse generator
when it needs to catch up.
- CYCLE_TIME = 0.100
- The period, in seconds, at which EMCIO
will run. You can make this as small as you want to increase the throughput.
Making it 0.0 or a negative number will tell EMCIO not to sleep at
all. Ultimately the system loading will limit the effective throughput.
- TOOL_TABLE = tool.tbl
- The file which contains tool information,
- TOOL_CHANGE_POSITION = 0 0 2
- Specifies the XYZ location
to move to when performing a tool change.
- Don't confuse a text editor with a word processor. A text editor like
gedit or kwrite produce files that are plain text. They also produce
lines of text that are separated from each other. A word processor
like Open Office produce files with paragraphs and word wrapping and
lots of embedded codes that control font size and such. A text editor
does none of this.
- Usually this file is in the users home directory (e.g. /home/user/
- Complete reference to these files are left to the Integrator and Developer
- See the Integrator Handbook for details.
- This assumes there was no movement of the machine while powered off.
It helps on smaller machines without home switches.
- Refer to the the EMC2_Integrator_Manual for further information
about servo systems and PID control.
- The step generator module, stepgen, applies its own limits to acceleration
and velocity. We have discovered that it needs to have a little "headroom"
over the accel by the trajectory planner, otherwise it can fall slightly
behind during accel and later overshoot as it catches up. In the long
term we hope to come up with a clean fix for this problem. In the
meantime, please set STEPGEN_MAXVEL to a few percent higher than
MAX_VELOCITY, the regular velocity limit and STEPGEN_MAXACCEL slightly
larger that of MAX_ACCELERATION.