Started cleaning up latency-test.adoc, removing redundancies in pncconf.adoc and stepconf.adoc

Author: johnobrien

docs/src/config/pncconf.adoc

@@ -51,41 +51,26 @@ You can also launch it from the main menu by using the Configuration Selector 'L
 image::images/pncconf-basic.png["PnCconf Basic machine information"]
 
 Machine Basics::
-If you use a name with spaces PnCconf will replace the spaces with underscore
-(as a loose rule Linux doesn't like spaces in names)
-Pick an axis configuration - this selects what type of machine you are building and what axes are available.
-The Machine units selector allows data entry of metric or imperial units in the following pages.
+If you use a name with spaces PnCconf will replace the spaces with underscores
+(as a loose rule Linux doesn't like spaces in names).
+Picking an axis configuration selects what type of machine you are building and what axes are available.
+The "Machine units" selector allows data entry of metric or imperial units in later steps in the configuration process.
 
 TIP: Defaults are not converted when using metric so make sure they are sane values!
 
 Computer Response Time::
 
 The servo period sets the heart beat of the system.
-Latency refers to the amount of time the computer can be longer then that period.
-Just like a railroad, LinuxCNC requires everything on a very tight and consistent time line or bad things happen.
-LinuxCNC requires and uses a 'real time' operating system, which just means it has a low latency ( lateness ) response time
-when LinuxCNC requires its calculations and when doing LinuxCNCs calculations it cannot be interrupted by lower priority requests (such as user input to screen buttons or drawing etc).
-
-Testing the latency is very important and a key thing to check early.
-Luckily by using the Mesa card to do the work that requires the fastest response time (encoder counting and PWM generation) we can endure a lot more latency then if we used the parallel port for these things.
-The standard test in LinuxCNC is checking the BASE period latency (even though we are not using a base period).
-If you press the 'test base period jitter' button, this launches the latency test window ( you can also load this directly from the applications/cnc panel ).
-The test mentions to run it for a few minutes but the longer the better.
-Consider 15 minutes a bare minimum and overnight even better.
-At this time use the computer to load things, use the net, use USB etc we want to know the worst case latency and to find out if any particular activity hurts our latency.
-We need to look at base period jitter.
-Anything under 20000 is excellent - you could even do fast software stepping with the machine 20000 - 50000 is still good for software stepping and fine for us.
-50000 - 100000 is really not that great but could still be used with hardware cards doing the fast response stuff.
-So anything under 100000 is usable to us.
-If the latency is disappointing or you get a bad hiccup periodically you may still be able to improve it.
-
-TIP: There is a user compiled list of equipment and the latency obtained on the LinuxCNC wiki: https://wiki.linuxcnc.org/cgi-bin/wiki.pl?Latency-Test
-Please consider adding your info to the list.
-Also on that page are links to info about fixing some latency problems.
+Latency refers to the amount of time the computer can be longer than that period.
+Just like a railroad, LinuxCNC requires everything on a very tight and consistent timeline or bad things happen.
+LinuxCNC requires and uses a 'real-time' operating system, which just means it has a low-latency (lateness) response time.
+When LinuxCNC requires and is performing calculations, it cannot be interrupted by lower priority requests (such as user input to screen buttons or drawing etc).
+
+Testing the latency is crucial and a key thing to check before proceeding further. Please follow the directions on the <<sub:install:sec:latency-test,Latency Test>> page before proceeding further.
 
 Now we are happy with the latency and must pick a servo period.
 In most cases a servo period of 1000000 ns is fine (that gives a 1 kHz servo calculation rate - 1000 calculations a second).
-If you are building a closed loop servo system that controls torque (current) rather then velocity (voltage) a faster rate would be better - something like 200000 (5 kHz calculation rate).
+If you are building a closed loop servo system that controls torque (current) rather than velocity (voltage) a faster rate would be better - something like 200000 (5 kHz calculation rate).
 The problem with lowering the servo rate is that it leaves less time available for the computer to do other things besides LinuxCNC's calculations.
 Typically the display (GUI) becomes less responsive.
 You must decide on a balance. Keep in mind that if you tune your closed loop servo system then change the servo period you probably will need to tune them again.

docs/src/config/stepconf.adoc

@@ -98,63 +98,21 @@ The LinuxCNC Configuration Selector has configs for Sherline already configured.
   Enter the result of the Latency Test here.
   To run a latency test press the 'Test Base Period Jitter' button. See the
   <<sec:latency-test,Latency Test>> section for more details.
+
+.Latency Test
+image::images/latency-test_en.png["Latency Test",align="center"]
+
 * 'Max Step Rate' -(((Max Step Rate)))
   StepConf automatically calculates the Max Step Rate based
   on the driver characteristics entered and the latency test result.
 * 'Min Base Period' - (((Min Base Period)))
   StepConf automatically determines the Min Base Period
   based on the driver characteristics entered and latency test result.
 
-[[sub:latency-test]]
-== Latency Test(((Latency Test)))
-
-While the test is running, you should 'abuse' the computer. Move
-windows around on the screen. Surf the web. Copy some large files
-around on the disk. Play some music. Run an OpenGL program such as
-glxgears. The idea is to put the PC through its paces while the latency
-test checks to see what the worst case numbers are.  Run the test at least a few
-minutes. The longer you run the test the
-better it will be at catching events that might occur at less frequent
-intervals. This is a test for your computer only, so no hardware needs
-to be connected to run the test.
-
-[WARNING]
-Do not attempt run LinuxCNC while the latency test is running.
-
-.Latency Test
-image::images/latency-test_en.png["Latency Test",align="center"]
-
-Latency is how long it takes the PC to stop what it is doing and
-respond to an external request. In our case, the request is the
-periodic 'heartbeat' that serves as a timing reference for the step
-pulses. The lower the latency, the faster you can run the heartbeat,
-and the faster and smoother the step pulses will be.
-
-Latency is far more important than CPU speed. The CPU isn't the only
-factor in determining latency. Motherboards, video cards, USB ports,
-SMI issues, and a number of other things can hurt the latency.
-
-.Troubleshooting SMI Issues (LinuxCNC.org Wiki)
-************************************************************
-Fixing Realtime problems caused by SMI on Ubuntu
-
-https://wiki.linuxcnc.org/cgi-bin/wiki.pl?FixingSMIIssues
-************************************************************
 
-The important numbers are the 'max jitter'. In the example above 9075
+The important number from the result of the Latency Test is the 'max jitter'. In the example above, 9075
 nanoseconds (ns), or 9.075 microseconds (µs), is the highest jitter.
-Record this number, and enter it in the Base Period Maximum Jitter box.
-
-If your Max Jitter number is less than about 15-20 µs
-(15000-20000 ns), the computer should give very nice results
-with software stepping. If the max latency is more like 30-50 µs,
-you can still get good results, but your maximum step
-rate might be a little disappointing, especially if you use
-microstepping or have very fine pitch leadscrews. If the numbers are
-100 µs or more (100,000 ns), then the PC is not a good
-candidate for software stepping. Numbers over 1 millisecond (1,000,000 ns)
-mean the PC is not a good candidate for LinuxCNC, regardless of
-whether you use software stepping or not.
+Enter the max jitter it in the Base Period Maximum Jitter box.
 
 == Parallel Port Setup
 

docs/src/getting-started/system-requirements.adoc

@@ -13,7 +13,7 @@ the software before committing to a permanent installation on a computer.
 Keep in mind that the Latency Test numbers are more important than the
 processor speed for software step generation. More information on the
 Latency Test is <<sec:latency-test,here>>.
-In addition LinuxCNC needs to be run on an operating system that uses a
+In addition, LinuxCNC needs to be run on an operating system that uses a
 specially modified kernel,
 see <<sec:kernel_and_version_requirements,Kernel and Version Requirements>>.
 

docs/src/install/latency-test.adoc

@@ -23,8 +23,9 @@ Motherboards, video cards, USB ports, and a number of other things can hurt the
 The best way to find out what you are dealing with is to run the latency test.
 
 Generating step pulses in software has one very big advantage - it's free.
-Just about every PC has a parallel port that is
+Just about every PC that has a parallel port is
 capable of outputting step pulses that are generated by the software.
+
 However, software step pulses also have some disadvantages:
 
 - limited maximum step rate
@@ -45,7 +46,13 @@ Do not run LinuxCNC or StepConf while the latency test is running.
 [[sec:latency-test]]
 === Latency Test(((Latency Test)))
 
-To run the test, open a terminal window
+The latency test can be run a few different ways.
+
+If you are using PnCconf to configure your machine, you can launch the Latency Test by clicking the "Test Base Period Jitter button' during the 2nd step of the process.
+
+If you are using StepConf to configure your machine, you can launch the Latency Test by clicking the "Test Base Period Jitter button' during the 2nd step of the process.
+
+If you want to run the test from the command line, open a terminal window
 (in Ubuntu, from Applications → Accessories → Terminal)
 and run the following command:
 
@@ -91,26 +98,27 @@ You should run the test for at least several minutes; sometimes
 the worst case latency doesn't happen very often, or only happens
 when you do some particular action. For instance, one Intel
 motherboard worked pretty well most of the time, but every 64
-seconds it had a very bad 300 µs latency. Fortunately that was
-fixable, see https://wiki.linuxcnc.org/cgi-bin/wiki.pl?FixingSMIIssues .
-
-So, what do the results mean? If your Max Jitter number is less
-than about 15-20 microseconds (15000-20000 nanoseconds), the
-computer should give very nice results with software stepping.
-If the max latency is more like 30-50 microseconds, you can still
-get good results, but your maximum step rate might be a little
-disappointing, especially if you use microstepping or have very
-fine pitch leadscrews. If the numbers are 100 µs or more,
-i.e. >= 100,000 nanoseconds (ns), then the PC is not a good candidate for software
-stepping. Numbers over 1 millisecond (1,000,000 ns) mean
-the PC is not a good candidate for LinuxCNC, regardless of whether you
-use software stepping or not.
+seconds it had a very bad 300 µs latency. Fortunately that was fixable, see <<_latency_tuning>>.
+
+So, what do the results mean?
+
+If your Max Jitter number is less
+than about 20,000 nanoseconds, the
+computer should give very nice results with software stepping or a dedicated hardware card such as a Mesa 'Anything I/O' card.
+
+If the Max Jitter number is between 20,000 and 50,000 nanoseconds, you can still
+get good results with software stepping, but your maximum step rate might be a little
+disappointing, especially if you use microstepping or have very fine pitch leadscrews. You can, however, achieve excellent results using a hardware card.
+
+If the Max Jitter number is between 50,000 and 500,000 nanoseconds, you cannot use software stepping. You can, however, achieve acceptable results using a hardware card.
+
+If the Max Jitter number is above 500,000 nanoseconds, you cannot use software stepping or a hardware card with LinuxCNC and achieve acceptable results.
 
 [NOTE]
 If you get high numbers, there may be ways to improve them.
-Another PC had very bad latency (several milliseconds) when
+Another PC had very bad latency (several million nanoseconds) when
 using the onboard video. But a $5 used video card solved the problem.
-LinuxCNC does not require bleeding edge hardware.
+LinuxCNC does not require bleeding-edge hardware.
 
 For more information on stepper tuning see the
 <<cha:stepper-tuning,Stepper Tuning>> Chapter.
@@ -173,7 +181,7 @@ Options:
 When determining the latency, LinuxCNC and HAL should not be running, stop with `halrun -U`.
 Large number of bins and/or small binsizes will slow updates.
 For single thread, specify `--nobase` (and options for servo thread).
-Measured latencies outside of the +/- bin range are reported with special end bars.
+Measured latencies outside the +/- bin range are reported with special end bars.
 Use `--show` to show count for the off-chart [pos|neg] bin.
 
 .`latency-histogram` Window

docs/src/remap/remap.adoc

@@ -33,15 +33,15 @@ and moreover brings its own set of support issues.
 While it is conceivable that certain patches might make their way into the main LinuxCNC distribution,
 the result of this approach is a hodge-podge of special-case solutions.
 
-A good example for this deficiency is tool change support in LinuxCNC:
-While random tool changers are well supported, it is next to impossible to reasonably define a configuration for a manual-tool change machine
+A good example for this deficiency is tool change support in LinuxCNC.
+While random tool changers are supported well, it is next to impossible to reasonably define a configuration for a manual-tool change machine
 with, for example, an automatic tool length offset switch being visited after a tool change, and offsets set accordingly.
 Also, while a patch for a very specific rack tool changer exists, it has not found its way back into the main code base.
 
-However, many of these things may be fixed by using an O-word procedure instead of a built in code -
-whenever the - insufficient - built in code is to be executed, call the O-word procedure instead.
-While possible, it is cumbersome - it requires source-editing of NGC programs,
-replacing all calls to the deficient code by a an O-word procedure call.
+However, many of these things may be fixed by using an O-word procedure instead of built-in code.
+Whenever the insufficient built-in code is to be executed, call the O-word procedure instead.
+While possible, this approach is cumbersome - it requires source-editing of NGC programs,
+replacing all calls to the deficient code by an O-word procedure call.
 
 In its simplest form, a remapped code isn't much more than a spontaneous call to an O-word procedure.
 This happens behind the scenes - the procedure is visible at the configuration level, but not at the NGC program level.