----
# add the encoder to HAL and attach it to threads.
loadrt encoder num_chan=1
addf encoder.update-counters base-thread
addf encoder.capture-position servo-thread

# set the HAL encoder to 100 pulses per revolution.
setp encoder.3.position-scale 100

# set the HAL encoder to non-quadrature simple counting using A only.
setp encoder.3.counter-mode true

# connect the HAL encoder outputs to LinuxCNC.
net spindle-position encoder.3.position => motion.spindle-revs
net spindle-velocity encoder.3.velocity => motion.spindle-speed-in
net spindle-index-enable encoder.3.index-enable <=> motion.spindle-index-enable

# connect the HAL encoder inputs to the real encoder.
net spindle-phase-a encoder.3.phase-A <= parport.0.pin-10-in
net spindle-phase-b encoder.3.phase-B
net spindle-index encoder.3.phase-Z <= parport.0.pin-11-in
----

=== Spindle At Speed[[sec:Spindle-At-Speed]]

(((Spindle At Speed)))

To enable LinuxCNC to wait for the spindle to be at speed before executing
a series of moves you need to set motion.spindle-at-speed to true when
the spindle is at the commanded speed. To do this you need spindle
feedback from an encoder. Since the feedback and the commanded speed
are not usually 'exactly' the same you need to use the 'near'
component to say that the two numbers are close enough.

The connections needed are from the spindle
velocity command signal to near.n.in1 and from the spindle velocity
from the encoder to near.n.in2. Then the near.n.out is connected to
motion.spindle-at-speed. The near.n.scale needs to be set to say how
close the two numbers must be before turning on the output. Depending
on your setup you may need to adjust the scale to work with your
hardware.

The following is typical of the additions needed to your HAL
file to enable Spindle At Speed. If you already have near in your HAL
file then increase the count and adjust code to suit. Check to make
sure the signal names are the same in your HAL file.

----
# load a near component and attach it to a thread
loadrt near
addf near.0 servo-thread

# connect one input to the commanded spindle speed
net spindle-cmd => near.0.in1

# connect one input to the encoder-measured spindle speed
net spindle-velocity => near.0.in2

# connect the output to the spindle-at-speed input
net spindle-at-speed motion.spindle-at-speed <= near.0.out

# set the spindle speed inputs to agree if within 1%
setp near.0.scale 1.01
----

=== Spindle Orient[[sec:Spindle-Orient]]

(((Spindle Orient)))

LinuxCNC G-code offers the M19 command to perform spindle orientation moves.
For this to work there needs to be a PID-controller to operate the spindle in
a fashion much like a servo. This means that the spindle must be able to
rotate in both directions under software control and there needs to be spindle
feedback from an encoder (or similar).
As the spindle encoder counter will typically have counted many thousands of
rotations at the point when a spindle orient command is required it is not
possible to simply request a 0 to 360 degree angle. Instead one should use the
"orient" HAL component which creates a new position setpoint based on the
current spindle completed revs + the required angle.
The HAL configuration diagrammed below shows two PID controllers, one active
when the spindle is on to close the velocity loop, and the other active when
the spindle is in orient mode to close the position loop.

image::images/orient.svg[align="center"]

----