This documentation is no longer maintained. For documentation of the current version of emc2, please see




encoder − software counting of quadrature encoder signals


loadrt encoder num_chan=num


encoder 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.

encoder supports a maximum of eight channels. The number of channels actually loaded is set by the num_chan argument when the module is loaded. If numchan is not specified, the default value is three.

encoder has a one-phase, unidirectional mode called counter. In this mode, the phase-B input is ignored; the counts increase on each rising edge of phase-A. This mode may be useful for counting a unidirectional spindle with a single input line, though the noise-resistant characteristics of quadrature are lost.


encoder.update-counters (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.

encoder.capture-position (uses floating point)

Captures the raw counts from update-counters and performs scaling and other necessary conversion, handles counter rollover, etc. Can (and should) be called less frequently than update-counters. Operates on all channels at once.


encoder.N.phase-A bit in

Quadrature input for encoder channel N.

encoder.N.phase-B bit in

Quadrature input.

encoder.N.phase-Z bit in

Index pulse input.

encoder.N.reset bit in

When true, counts and position are reset to zero immediately.

encoder.N.index-enable bit i/o

When true, counts and position are reset to zero on the next rising edge of Phase-Z. At the same time, index-enable is reset to zero to indicate that the rising edge has occurred.

encoder.N.counts s32 out

Position in encoder counts.

encoder.N.position float out

Position in scaled units (see position-scale)

encoder.N.position-interpolated float out

Position in scaled units, interpolated between encoder counts. Only valid when velocity is approximately constant, do not use for position control.

encoder.N.velocity float out

Velocity in scaled units per second. encoder uses an algorithm that greatly reduces quantization noise as compared to simply differentiating the position output.


encoder.N.position-scale float rw

Scale factor, in counts per length unit. For example, if position-scale is 500, then 1000 counts of the encoder will be reported as a position of 2.0 units.

encoder.N.counter-mode 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.

encoder.N.x4-mode 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 counter-mode, this parameter is ignored.

encoder.N.rawcounts s32 ro

The raw count, as determined by update-counters. This value is updated more frequently than counts and position. It is also unaffected by reset or the index pulse.