:lang: en
:toc:

[[cha:stepper-diagnostics]]
= Stepper Diagnostics(((Stepper Diagnostics)))

// Custom lang highlight
// must come after the doc title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

If what you get is not what you expect many times you just got some
experience. Learning from the experience increases your understanding
of the whole. Diagnosing problems is best done by divide and conquer.
By this I mean if you can remove 1/2 of the variables from the equation
each time you will find the problem the fastest. In the real world this
is not always the case, but it's usually a good place to start.

== Common Problems

=== Stepper Moves One Step

The most common reason in a new installation for a stepper motor not to
move is that the step and direction signals are exchanged. If you press the
jog forward and jog backward keys, alternately , and the stepper moves
one step each time, and in the same direction, there is your clue.

=== No Steppers Move

Many drives have an enable pin or need a charge pump to enable the
output.

=== Distance Not Correct

If you command the axis to move a specific distance and it does not
move that distance, then your scale setting is wrong.

== Error Messages

=== Following Error

The concept of a following error is strange when talking about stepper
motors. Since they are an open loop system, there is no position
feedback to let you know if you actually are out of range. LinuxCNC
calculates if it can keep up with the motion called for, and if not, then
it gives a following error. Following errors usually are the result of
one of the following on stepper systems.

- FERROR too small
- MIN_FERROR too small
- MAX_VELOCITY too fast
- MAX_ACCELERATION too fast
- BASE_PERIOD set too long
- Backlash added to an axis

Any of the above can cause the real-time pulsing to not be able to keep up
the requested step rate. This can happen if you didn't run the latency
test long enough to get a good number to plug into the Stepconf Wizard,
or if you set the Maximum Velocity or Maximum Acceleration too high.

If you added backlash you need to increase the STEPGEN_MAXACCEL up to
double the MAX_ACCELERATION in the AXIS section of the INI file for
each axis you added backlash to. LinuxCNC uses "extra acceleration" at a
reversal to take up the backlash. Without backlash correction, step
generator acceleration can be just a few percent above the motion
planner acceleration.

=== RTAPI Error

When you get this error:

----
RTAPI: ERROR: Unexpected realtime delay on task n
----

This error is generated by rtapi based on an indication from RTAI that
a deadline was missed. It is usually an indication that the BASE_PERIOD
in the [EMCMOT] section of the ini file is set too low. You should run
the Latency Test for an extended period of time to see if you have any
delays that would cause this problem. If you used the Stepconf Wizard,
run it again, and test the Base Period Jitter again, and adjust the Base
Period Maximum Jitter on the Basic Machine Information page. You might
have to leave the test running for an extended period of time to find
out if some hardware causes intermittent problems.

LinuxCNC tracks the number of CPU cycles between invocations of the
real-time thread. If some element of your hardware is causing delays or
your realtime threads are set too fast you will get this error.

[NOTE]
This error is only displayed once per session. If you had your
BASE_PERIOD too low you could get hundreds of thousands of error
messages per second if more than one was displayed.

== Testing

=== Step Timing

If you are seeing an axis ending up in the wrong location over
multiple moves, it is likely that you do not have the correct direction
hold times or step timing for your stepper drivers. Each direction
change may be losing a step or more. If the motors are stalling, it is
also possible you have either the MAX_ACCELERATION or MAX_VELOCITY set
too high for that axis.

The following program will test the Z axis configuration for proper
setup. Copy the program to your \~/emc2/nc_files directory and name it
TestZ.ngc or similar. Zero your machine with Z = 0.000 at the table
top. Load and run the program. It will make 200 moves back and forth
from 0.5 to 1". If you have a configuration issue, you will find that
the final position will not end up 0.500" that the axis window is
showing. To test another axis just replace the Z with your axis in the
G0 lines.

[source,{ngc}]
----
( test program to see if Z axis loses position )
( msg, test 1 of Z axis configuration )
G20 #1000=100 ( loop 100 times )
( this loop has delays after moves )
( tests acc and velocity settings )
o100 while [#1000]
   G0 Z1.000
   G4 P0.250
   G0 Z0.500
   G4 P0.250
   #1000 = [#1000 - 1]
o100 endwhile
( msg, test 2 of Z axis configuration S to continue)
M1 (stop here)
#1000=100 ( loop 100 times )
( the next loop has no delays after moves )
( tests direction hold times on driver config and also max accel setting )
o101 while [#1000]
   G0 Z1.000
   G0 Z0.500
   #1000 = [#1000 - 1]
o101 endwhile
( msg, Done...Z should be exactly .5" above table )
M2
----

// vim: set syntax=asciidoc:
