linuxcnc/docs/man/man9/encoder.9

.TH ENCODER "9" "2009-04-15" "LinuxCNC Documentation" "HAL Component"
.de TQ
.br
.ns
.TP \\$1
..

.SH NAME
encoder \- software counting of quadrature encoder signals
.SH SYNOPSIS
.B loadrt encoder [num_chan=\fInum\fB | names=\fIname1\fB[,\fIname2...\fB]]

.SH DESCRIPTION
\fBencoder\fR is used to measure position by counting the pulses
generated by a quadrature encoder.  As a software-based implementation
it is much less expensive than hardware, but has a limited maximum
count rate.  The limit is in the range of 10KHz to 50KHz, depending
on the computer speed and other factors.  If better performance is
needed, a hardware encoder counter is a better choice.  
Some hardware-based systems can count at MHz rates.
.P
\fBencoder\fR supports a maximum of eight channels.  The number of
channels actually loaded is set by the \fBnum_chan\fR argument when
the module is loaded.  Alternatively, specify names= and unique names
separated by commas.
.P
The \fBnum_chan=\fR and \fBnames=\fR specifiers are mutually exclusive.
If neither \fBnum_chan=\fR nor \fBnames=\fR are specified, or if
\fBnum_chan=0\fR is specified, the default value is three.
.P
\fBencoder\fR has a one-phase, unidirectional mode called \fIcounter\fR.
In this mode, the \fBphase-B\fR input is ignored; the counts increase on
each rising edge of \fBphase-A\fR.  This mode may be useful for counting
a unidirectional spindle with a single input line, though the noise-resistant
characteristics of quadrature are lost.

.SH FUNCTIONS
.TP 
\fBencoder.update-counters\fR (no floating-point)
Does the actual counting, by sampling the encoder signals and decoding
the quadrature waveforms.  Must be called as frequently as possible,
preferably twice as fast as the maximum desired count rate.  Operates
on all channels at once.
.TP
\fBencoder.capture-position\fR (uses floating point)
Captures the raw counts from \fBupdate-counters\fR and performs scaling
and other necessary conversion, handles counter rollover, etc.  Can
(and should) be called less frequently than \fBupdate-counters\fR.
Operates on all channels at once.

.SH NAMING
The names for pins and parameters are prefixed as:
  \fBencoder.N.\fR for N=0,1,...,num-1 when using \fBnum_chan=num\fR
  \fBnameN.\fR for nameN=name1,name2,... when using \fBnames=name1,name2,...\fR

The \fBencoder.N.\fR format is shown in the following descriptions.


.SH PINS

.TP
\fBencoder.\fIN\fB.counter-mode\fR bit i/o
Enables counter mode.  When true, the counter counts each rising edge of the
phase-A input, ignoring the value on phase-B.  This is useful for counting
the output of a single channel (non-quadrature) sensor.  When false (the
default), it counts in quadrature mode.
.TP
\fBencoder.\fIN\fB.counts\fR s32 out
Position in encoder counts.
.TP
\fBencoder.\fIN\fB.index-enable\fR bit i/o
When true, \fBcounts\fR and \fBposition\fR are reset to zero on the next
rising edge of \fBPhase-Z\fR.  At the same time, \fBindex-enable\fR is reset
to zero to indicate that the rising edge has occurred.
.TP
\fBencoder.\fIN\fB.min-speed-estimate\fR float in (default: 1.0)
Determine the minimum speed at which \fBvelocity\fR will be
estimated as nonzero and \fBpostition-interpolated\fR will be interpolated.
The units of \fBmin-speed-estimate\fR are the same as the units of
\fBvelocity\fR.  Setting this parameter too low will cause it to take a long
time for \fBvelocity\fR to go to 0 after encoder pulses have stopped arriving.
.TP
\fBencoder.\fIN\fB.phase-A\fR bit in
Quadrature input for encoder channel \fIN\fR.
.TP
\fBencoder.\fIN\fB.phase-B\fR bit in
Quadrature input.
.TP
\fBencoder.\fIN\fB.phase-Z\fR bit in
Index pulse input.
.TP
\fBencoder.\fIN\fB.position\fR float out
Position in scaled units (see \fBposition-scale\fR)
.TP
\fBencoder.\fIN\fB.position-interpolated\fR float out
Position in scaled units, interpolated between encoder counts.  Only valid when
velocity is approximately constant and above \fBmin-speed-estimate\fR.  Do
not use for position control.
.TP
\fBencoder.\fIN\fB.position-scale\fR float i/o
Scale factor, in counts per length unit.  For example, if \fBposition-scale\fR
is 500, then 1000 counts of the encoder will be reported as a position of 2.0
units.
.TP
\fBencoder.\fIN\fB.rawcounts\fR s32 out
The raw count, as determined by \fBupdate-counters\fR.  This value is updated
more frequently than \fBcounts\fR and \fBposition\fR.  It is also unaffected
by \fBreset\fR or the index pulse.
.TP
\fBencoder.\fIN\fB.reset\fR bit in
When true, \fBcounts\fR and \fBposition\fR are reset to zero immediately.
.TP
\fBencoder.\fIN\fB.velocity\fR float out
Velocity in scaled units per second.  \fBencoder\fR uses an algorithm that
greatly reduces quantization noise as compared to simply differentiating the
\fBposition\fR output.  When the magnitude of the true velocity is below
\fRmin-speed-estimate\fR, the \fRvelocity\fR output is 0.
.TP
\fBencoder.\fIN\fB.x4-mode\fR bit i/o
Enables times-4 mode.  When true (the default), the counter counts each edge
of the quadrature waveform (four counts per full cycle).  When false, it only
counts once per full cycle.  In \fBcounter-mode\fR, this parameter is ignored.
.TP
\fBencoder.\fIN\fB.latch-input\fR bit in
.TQ
\fBencoder.\fIN\fB.latch-falling\fR bit in (default: \fBTRUE\fR)
.TQ
\fBencoder.\fIN\fB.latch-rising\fR bit in (default: \fBTRUE\fR)
.TQ
\fBencoder.\fIN\fB.counts-latched\fR s32 out
.TQ
\fBencoder.\fIN\fB.position-latched\fR float out
Update \fBcounts-latched\fR and \fBposition-latched\fR on the rising and/or
falling edges of \fBlatch-input\fR as indicated by \fBlatch-rising\fR and
\fBlatch-falling\fR.
.TP
\fBencoder.\fIN\fB.counter-mode\fR bit rw
Enables counter mode.  When true, the counter counts each rising edge of the
phase-A input, ignoring the value on phase-B.  This is useful for counting
the output of a single channel (non-quadrature) sensor.  When false (the
default), it counts in quadrature mode.
\fBencoder.\fIN\fB.capture-position.tmax\fR s32 rw
Maximum number of CPU cycles it took to execute this function.

.SH PARAMETERS
The encoder component has no HAL Parameters.