path: root/docs/src/common/User_Concepts.txt

= Important User Concepts

[[cha:important-user-concepts]] (((User Concepts)))

This chapter covers important user concepts that should be understood
before attempting to run a CNC machine with g code.

[[sec:trajectory-control]]
== Trajectory Control
(((Trajectory Control)))

=== Trajectory Planning

[WARNING]
The new Trajectory Planner (TP) is on by default. +
If you have no TP settings in your [TRAJ] section - LinuxCNC defaults to: +
ARC_BLEND_ENABLE = 1 +
ARC_BLEND_FALLBACK_ENABLE = 0 +
ARC_BLEND_OPTIMIZATION_DEPTH = 50 +
ARC_BLEND_GAP_CYCLES = 4 +
ARC_BLEND_RAMP_FREQ = 100

For more information on the Trajectory Panner ini options see the Integrators
Manual.

Trajectory planning, in general, is the means by which LinuxCNC follows the
path specified by your G Code program, while still operating within the
limits of your machinery.

A G Code program can never be fully obeyed. For example, imagine you
specify as a single-line program the following move:

----
G1 X1 F10 (G1 is linear move, X1 is the destination, F10 is the speed)
----

In reality, the whole move can't be made at F10, since the machine
must accelerate from a stop, move toward X=1, and then decelerate to
stop again. Sometimes part of the move is done at F10, but for many
moves, especially short ones, the specified feed rate is never reached
at all. Having short moves in your G Code can cause your machine to
slow down and speed up for the longer moves if the 'naive cam detector'
is not employed with G64 Pn.

The basic acceleration and deceleration described above is not complex
and there is no compromise to be made. In the INI file the specified
machine constraints such as maximum axis velocity and axis acceleration
must be obeyed by the trajectory planner.


=== Path Following

A less straightforward problem is that of path following. When you
program a corner in G Code, the trajectory planner can do several
things, all of which are right in some cases: it can decelerate to a
stop exactly at the coordinates of the corner, and then accelerate in
the new direction. It can also do what is called blending, which is to
keep the feed rate up while going through the corner, making it
necessary to round the corner off in order to obey machine constraints.
You can see that there is a trade off here: you can slow down to get
better path following, or keep the speed up and have worse path
following. Depending on the particular cut, the material, the tooling,
etc., the programmer may want to compromise differently.

Rapid moves also obey the current trajectory control. With moves long
enough to reach maximum velocity on a machine with low acceleration and
no path tolerance specified, you can get a fairly round corner.

=== Programming the Planner(((Programming the Planner)))

The trajectory control commands are as follows:

* 'G61' - (Exact Path Mode) visits the programmed point exactly, even though
    that means it might temporarily come to a complete stop in order to
    change direction to the next programmed point. 

* 'G61.1' - (Exact Stop Mode) tells the planner to come to an exact stop at every
    segment's end. 

* 'G64' - (Blend Without Tolerance Mode) G64 is the default setting when you
    start LinuxCNC. G64 is just blending and the naive cam detector is not
    enabled. G64 and G64 P0 tell the planner to sacrifice path following
    accuracy in order to keep the feed rate up. This is necessary for some
    types of material or tooling where exact stops are harmful, and can
    work great as long as the programmer is careful to keep in mind that
    the tool's path will be somewhat more curvy than the program specifies.
    When using G0 (rapid) moves with G64 use caution on clearance moves and
    allow enough distance to clear obstacles based on the acceleration
    capabilities of your machine.

* 'G64 P- Q-' - (Blend With Tolerance Mode) This enables the 'naive cam detector' and
    enables blending with a tolerance. If you program G64 P0.05, you tell
    the planner that you want continuous feed, but at programmed corners
    you want it to slow down enough so that the tool path can stay within
    0.05 user units of the programmed path. The exact amount of slowdown
    depends on the geometry of the programmed corner and the machine
    constraints, but the only thing the programmer needs to worry about is
    the tolerance. This gives the programmer complete control over the path
    following compromise. The blend tolerance can be changed throughout the
    program as necessary. Beware that a specification of G64 P0 has the
    same effect as G64 alone (above), which is necessary for backward
    compatibility for old G Code programs. See the G Code Chapter for more
    information on G64 P- Q-.

* 'Blending without tolerance' - The controlled point will touch each specified movement at at least
    one point. The machine will never move at such a speed that it cannot
    come to an exact stop at the end of the current movement (or next
    movement, if you pause when blending has already started). The distance
    from the end point of the move is as large as it needs to be to keep up
    the best contouring feed.

* 'Naive Cam Detector' - Successive G1 moves that involve only the XYZ axes that deviate less
    than Q- from a straight line are merged into a single straight line.
    This merged movement replaces the individual G1 movements for the
    purposes of blending with tolerance. Between successive movements, the
    controlled point will pass no more than P- from the actual endpoints of
    the movements. The controlled point will touch at least one point on
    each movement. The machine will never move at such a speed that it
    cannot come to an exact stop at the end of the current movement (or
    next movement, if you pause when blending has already started) On G2/3
    moves in the G17 (XY) plane when the maximum deviation of an arc from a
    straight line is less than the G64 Q- tolerance the arc is broken into
    two lines (from start of arc to midpoint, and from midpoint to end).
    those lines are then subject to the naive cam algorithm for lines.
    Thus, line-arc, arc-arc, and arc-line cases as well as line-line
    benefit from the 'naive cam detector'. This improves contouring
    performance by simplifying the path. 

In the following figure the blue line represents the actual machine
velocity. The red lines are the acceleration capability of the machine.
The horizontal lines below each plot is the planned move. The upper
plot shows how the trajectory planner will slow the machine down when
short moves are encountered to stay within the limits of the machines
acceleration setting to be able to come to an exact stop at the end of
the next move. The bottom plot shows the effect of the Naive Cam
Detector to combine the moves and do a better job of keeping the
velocity as planned.

.Naive Cam Detector

image::images/naive-cam.png[align="center"]

=== Planning Moves

Make sure moves are 'long enough' to suit your machine/material.
Principally because of the rule that the machine will never move at
such a speed that it cannot come to a complete stop at the end of the
current movement, there is a minimum movement length that will allow
the machine to keep up a requested feed rate with a given acceleration
setting.

The acceleration and deceleration phase each use half the ini file
MAX_ACCELERATION. In a blend that is an exact reversal, this causes the
total axis acceleration to equal the ini file MAX_ACCELERATION. In
other cases, the actual machine acceleration is somewhat less than the
ini file acceleration

// This is a duplicate paragraph to the one below without latexmath.

To keep up the feed rate, the move must be longer than the distance it
takes to accelerate from 0 to the desired feed rate and then stop
again. Using A as *1/2* the ini file MAX_ACCELERATION 
and F as the feed rate *in units per second*, the acceleration time is 
*t~a~ = F/A* and the acceleration distance is 
*d~a~ = F*t~a~/2*. The deceleration time 
and distance are the same, making the critical distance 
*d = d~a~ + d~d~ = 2 * d~a~ = F^2^/A*. 

For example, for a feed rate of 1 inch per second and an acceleration of
*10 inches/sec^2^*, the critical distance is 
*1^2^/10 = 1/10 = 0.1 inches*.

For a feed rate of 0.5 inch per second, the critical distance is 
*5^2^/100 = 25/10 = 0.025* inches.

////
This section has been commented out until latexmath is working again.

To keep up the feed rate, the move must be longer than the distance it
takes to accelerate from 0 to the desired feed rate and then stop
again. Using A as latexmath:[$\frac{1}{2}$] the ini file MAX_ACCELERATION 
and F as the feed rate *in units per second*, the acceleration time is 
latexmath:[$ ta = \frac{F}{A} $] and the acceleration distance is 
latexmath:[$ da = \frac{1}{2} \times F \times ta $]. The deceleration time 
and distance are the same, making the critical distance 
latexmath:[$ d = da + dd = 2 \times da = \frac{F^{2}}{A} $]. 

For example, for a feed rate of 1 inch per second and an acceleration of 
latexmath:[$ 10 \frac{inch}{sec^{2}} $], the critical distance is 
latexmath:[$\frac{1^{2}}{10} = \frac{1}{10} = 0.1$] inch. 
For a feed rate of 0.5 inch per second, the critical distance is 
latexmath:[$ \frac{0.5^{2}}{10} = \frac{0.25}{10} = 0.025$] inch.
////

== G Code

=== Defaults

When LinuxCNC first starts up many G and M codes are loaded by default. The
current active G and M codes can be viewed on the MDI tab in the
'Active G-Codes:' window in the AXIS interface. These G and M codes
define the behavior of LinuxCNC and it is important that you understand what
each one does before running LinuxCNC. The defaults can be changed when
running a G-Code file and left in a different state than when you
started your LinuxCNC session. The best practice is to set the defaults
needed for the job in the preamble of your G-Code file and not assume
that the defaults have not changed. Printing out the G-Code
<<quick-reference-table,Quick Reference>> page can help you remember
what each one is.

=== Feed Rate

How the feed rate is applied depends on if an axis involved with the
move is a rotary axis. Read and understand the <<sub:feed-rate,Feed Rate>>
section if you have a rotary axis or a lathe.

=== Tool Radius Offset

Tool Radius Offset (G41/42) requires that the tool be able to touch
somewhere along each programmed move without gouging the two adjacent
moves. If that is not possible with the current tool diameter you will
get an error. A smaller diameter tool may run without an error on the
same path. This means you can program a cutter to pass down a path that
is narrower than the cutter without any errors. See the 
<<sec:cutter-compensation,Cutter Compensation>> Section
for more information.

== Homing

After starting LinuxCNC each axis must be homed prior to running a program
or running a MDI command. 

If your machine does not have home switches a match mark on each axis
can aid in homing the machine coordinates to the same place each time.

Once homed your soft limits that are set in the ini file will be used.

If you want to deviate from the default behavior, or want to use the
Mini interface you will need to set the option NO_FORCE_HOMING = 1 in
the [TRAJ] section of your ini file. More information on homing can be
found in the Integrator Manual.

== Tool Changes

There are several options when doing manual tool changes. See the
[EMCIO] section of the Integrator Manual for information on
configuration of these options. Also see the G28 and G30 section of the
User Manual.

== Coordinate Systems

The Coordinate Systems can be confusing at first. Before running a CNC
machine you must understand the basics of the coordinate systems used
by LinuxCNC. In depth information on the LinuxCNC Coordinate Systems
is in the <<cha:coordinate-system,Coordinate System>> Section of this
manual.

=== G53 Machine Coordinate

When you home LinuxCNC you set the G53 Machine Coordinate System to 0 for
each axis homed.

 - No other coordinate systems or tool offsets are changed by homing. 

The only time you move in the G53 machine coordinate system is when
you program a G53 on the same line as a move. Normally you are in the
G54 coordinate system.

=== G54-59.3 User Coordinates

Normally you use the G54 Coordinate System. When an offset is applied
to a current user coordinate system a small blue ball with lines will
be at the machine origin when your DRO is displaying 'Position:
Relative Actual' in Axis. If your offsets are temporary use the Zero
Coordinate System from the Machine menu or program 'G10 L2 P1 X0 Y0 Z0'
at the end of your G Code file. Change the 'P' number to suit the
coordinate system you wish to clear the offset in.

 -  Offsets stored in a user coordinate system are retained when LinuxCNC is
   shut down.
 -  Using the 'Touch Off' button in Axis sets an offset for the chosen
   User Coordinate System.

=== When You're Lost

If you're having trouble getting 0,0,0 on the DRO when you think you
should, you may have some offsets programmed in and need to remove
them.

 - Move to the Machine origin with G53 G0 X0 Y0 Z0
 - Clear any G92 offset with G92.1
 - Use the G54 coordinate system with G54
 - Set the G54 coordinate system to be the same as the 
   machine coordinate system with G10 L2 P1 X0 Y0 Z0 R0
 - Turn off tool offsets with G49
 - Turn on the Relative Coordinate Display from the menu

Now you should be at the machine origin X0 Y0 Z0 and the relative
coordinate system should be the same as the machine coordinate system.

== Machine Configurations

The following diagram shows a typical mill showing direction of travel
of the tool and the mill table and limit switches. Notice how the mill table
moves in the opposite direction of the Cartesian coordinate system arrows
shown by the 'Tool Direction' image. This makes the 'tool' move in the
correct direction in relation to the material.

.Mill Configuration
image::images/mill-diagram.png[align="center"]

The following diagram shows a typical lathe showing direction of travel
of the tool and limit switches.

.Lathe Configuration
image::images/lathe-diagram.png[align="center"]