ENCODER(9)

✨ NAME ✨

okay bestie, welcome to ENCODER(9) from the HAL Component fam! This page is literally about encoder — software counting of quadrature encoder signals. No cap. 💖

---

🎀 SYNOPSIS 🎀

loadrt encoder [num_chan=num | names=name1[,name2...]]

---

🌸 DESCRIPTION 🌸

okay so encoder is your software bestie for measuring position by counting the pulses that a quadrature encoder spits out. Because it's a software-based implementation, it's much less expensive than hardware, but it has a limited maximum count rate. That limit is in the range of 10 kHz to 50 kHz, depending on computer speed and other factors. If you need better performance, 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. Alternatively, specify names= and unique names separated by commas.

The num_chan= and names= specifiers are mutually exclusive. If neither num_chan= nor names= are specified, or if num_chan=0 is 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. 😭

If used in counter-mode it is also possible to enable the missing-teeth index mode, where a gap in the pulse train of one or more teeth is used as an index marker. This system is used extensively for automotive crank position sensors. vroom vroom 🏎️

---

🔥 FUNCTIONS 🔥

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

---

💅 NAMING 💅

The names for pins and parameters are prefixed as:

• encoder.N. for N=0,1,...,num-1 when using num_chan=num
• nameN. for nameN=name1,name2,... when using names=name1,name2,...

The encoder.N. format is shown in the following descriptions. iykyk ✨

---

👑 PINS 👑

• encoder.N.counter-mode 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.
• encoder.N.counts s32 out — Position in encoder counts.
• 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.min-speed-estimate float in (default: 1.0) — Determine the minimum speed at which velocity will be estimated as nonzero and postition-interpolated will be interpolated. The units of min-speed-estimate are the same as the units of velocity. Setting this parameter too low will cause it to take a long time for velocity to go to 0 after encoder pulses have stopped arriving. don't set it too low, bestie 😭
• 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.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 and above min-speed-estimate. Do not use for position control. periodt.
• encoder.N.position-scale float i/o — 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.missing-teeth s32 in — The number of teeth missing from the index gap. For example a 60 tooth gear with two teeth shortened to form an index so that there are 58 pulses per revolution would use a position-scale of 60 and a missing-teeth of 2.
• encoder.N.rawcounts s32 out — 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.
• encoder.N.reset bit in — When true, counts and position are reset to zero immediately.
• 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. When the magnitude of the true velocity is below min-speed-estimate, the velocity output is 0.
• encoder.N.velocity-rpm float out — Velocity in scaled units per minute. Simply encoder.N.velocity scaled by a factor of 60 for convenience.
• encoder.N.x4-mode 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 counter-mode, this parameter is ignored.

For the latch crew, update counts-latched and position-latched on the rising and/or falling edges of latch-input as indicated by latch-rising and latch-falling.

• encoder.N.latch-input bit in
• encoder.N.latch-falling bit in (default: TRUE)
• encoder.N.latch-rising bit in (default: TRUE)
• encoder.N.counts-latched s32 out
• encoder.N.position-latched float out
• 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.capture-position.tmax s32 rw — Maximum number of CPU cycles it took to execute this function.

---

🦋 PARAMETERS 🦋

The encoder component has no HAL Parameters. Zero. None. That's it. 💀

---

That's the whole vibe, bestie! This page was brought to you by LinuxCNC Documentation, dated 2009-04-15, for ENCODER(9). Go count some edges, slay, and remember: quadrature is iconic. 💖✨🦋