NAME

       encoder - software counting of quadrature encoder signals

SYNOPSIS

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

DESCRIPTION

       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 10 kHz to 50 kHz,
       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.  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 in index marker. This system is
       used extensively for automotive crank position sensors.

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.

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.

       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.

       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.

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