This documentation is no longer maintained. For documentation of the current version of emc2, please see http://www.linuxcnc.org/docview/html

INI Configuration

Files Used for Configuration

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 is running.

Configuration files include;

INI: 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.
HAL: The hal files start up process modules and provide linkages between EMC signals and specific hardware pins.
VAR: The var file provide a set of numbered variables for use by the interpreter. These values are saved from one run to another.
TBL: The tbl file saves tool information.
NML: 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 several computers.
.emcrc: 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

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 machine.^1.3

The INI File Layout

A typical INI file follows a rather simple layout that includes;

comments.
sections,
variables.

Each of these elements is separated on single lines. Each end of line or newline character creates a new element.

Comments

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.

: ; This is my little mill configuration file.
; I set it up on January 12, 2006

Comments can also be used to select between several values of a single variable.

: # DISPLAY = tkemc
DISPLAY = axis
# DISPLAY = mini
# DISPLAY = keystick

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.

Sections

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;

[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 variables ()
[EMCIO] emc's input and output variables. ()

Each of these section names are on a line by themselves so you can quickly scan through the file.

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

[EMC] Section

VERSION = $Revision: 1.3 $: The 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: This 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: A string of NC codes that the interpreter is initialized with. These are the codes that an interpreter will be reset to.

[DISPLAY] Section

DISPLAY = tkemc The name of the user interface to use. Valid options may include:

axis
keystick
mini
tkemc
xemc

[EMCMOT] Section

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, so

max $\displaystyle \_step$ $\displaystyle \_rate$

[ $\displaystyle {\frac{{steps}}{{second}}}$ ] =

$\displaystyle {\frac{{10^{9}}}{{2*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 of BASE_PERIOD.
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 have steppers.

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 .

[TASK] Section

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.

[HAL] section

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.

: HALFILE = core_stepper.hal
HALFILE = standard_pinout.hal
# HALFILE = xylotex_pinout.hal

You can also add variables (commands really) here.^1.4

[TRAJ] Section

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: The 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: Coordinates 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>: The 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>: The 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: The 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: The initial acceleration used for axis or coordinated axis motion, in user units per second per second.
MAX_VELOCITY = 5.0: The 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: The 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.

[AXIS_<num>] Section

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

This 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

$\displaystyle {\frac{{sensor\, units}}{{desired\, input\, SI\, units}}}$

For example, on a 2000 counts per rev encoder, and 10 revs/inch gearing, and desired units of mm, we have

[scaleunits]	=	2000 $\displaystyle {\frac{{counts}}{{rev}}}$ 10 $\displaystyle {\frac{{rev}}{{inch}}}$ 1/25.4 $\displaystyle {\frac{{inch}}{{mm}}}$
	=	787.4 $\displaystyle {\frac{{{counts}}}{{mm}}}$

and, as a result,

input[mm] = (encoder[counts])/787.4

MIN_LIMIT = -1000

The minimum limit (soft limit) for axis motion, in user units. When this limit is exceeded, the controller aborts axis motion.

MAX_LIMIT = 1000

The 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

FERROR 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, vibration, etc.

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 setting.

Homing-related items

The next few parameters are Homing related, for a better explanation read Section

HOME_OFFSET = 0.0: The axis position of the home switch or index pulse.
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 does this.

Servo-related items

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:

raw = $\displaystyle {\frac{{{output-offset}}}{{scale}}}$

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,

amplifier[volts] = (output[ $\displaystyle {\frac{{mm}}{{sec}}}$ ] - offset[ $\displaystyle {\frac{{mm}}{{sec}}}$ ])/250 $\displaystyle {\frac{{mm}}{{sec\, volt}}}$

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.
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
1. cmd = a*raw + b
2. 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

The 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

Raw	Measured
-10	-9.93
-9	-8.83
0	-0.03
1	0.96
9	9.87
10	10.87

Stepper-related items

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.

[EMCIO] Section

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, described in
TOOL_CHANGE_POSITION = 0 0 2: Specifies the XYZ location to move to when performing a tool change.

Footnotes

...^1.1: 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.
...^1.2: Usually this file is in the users home directory (e.g. /home/user/ )
...^1.3: Complete reference to these files are left to the Integrator and Developer Handbooks.
...^1.4: See the Integrator Handbook for details.
...^1.5: This assumes there was no movement of the machine while powered off. It helps on smaller machines without home switches.
...^1.6: Refer to the the EMC2_Integrator_Manual for further information about servo systems and PID control.
...^1.7: 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.

2007-01-27