4a897203bc
groff treats '-' (the character you get when you hit the "minus" key on the keyboard) as "hyphen", not as "minus". Thus it renders incorrectly in some locales, and line-wraps strangely. groff treats the two-character sequence "\-" as "minus", and the four-character sequence "\(hy" as "hyphen". Details here: https://lists.debian.org/debian-devel/2003/03/msg01481.html This commit replaces every instance of "-" in our manpages where the meaning is "minus" with "\-", so it works right. This fixes many lintian warnings.
147 lines
6 KiB
Groff
147 lines
6 KiB
Groff
.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.
|
|
|