.TH ENCODER "9" "2007-01-16" "EMC Documentation" "HAL Component"
.de TQ
.br
.ns
.TP \\$1
..

.SH NAME
encoder \- software counting of quadrature encoder signals
.SH SYNOPSIS
\fBloadrt encoder num_chan=\fInum\fR

.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.  If \fBnumchan\fR is not 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 PINS
.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.reset\fR bit in
When true, \fBcounts\fR and \fBposition\fR are reset to zero immediately.
.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.counts\fR s32 out
Position in encoder counts.
.TP
\fBencoder.\fIN\fB.position\fR float out
Position in scaled units (see \fBposition-scale\fR)
.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.

.SH PARAMETERS
.TP
\fBencoder.\fIN\fB.position-scale\fR float rw
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.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.
.TP
\fBencoder.\fIN\fB.x4-mode\fR bit rw
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.rawcounts\fR s32 ro
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.

.SH
SEE ALSO
\fBcounter(9)\fR