.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, 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.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-velocity-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-velocity-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 Parameter names for num_chan= specifier are: \fBencoder.\fIN\fB.the_parameter_name\fR .TP Parameter names for names= specifier are: \fBnameN\fB.the_parameter_name\fR .TP \fBencoder.\fIN\fB.min-velocity-estimate\fR float rw (default: 1.0) Determine the minimum true velocity magnitude at which \fBvelocity\fR will be estimated as nonzero and \fBpostition-interpolated\fR will be interpolated. The units of \fBmin-velocity-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.