jm_quadrature.spin2

'' ===============================================================================================
''
''   File....... jm_quadrature.spin2
''   Purpose.... Quadrature encoder with [optional] button
''   Author..... Jon "JonnyMac" McPhalen
''               Copyright (c) 2020 Jon McPhalen
''               -- see below for terms of use
''   E-mail..... jon.mcphalen@gmail.com
''   Started....
''   Updated.... 29 JUN 2020
''
'' =================================================================================================

{

  A/B quadrature encoder using P2 smart pin. B pin must be within +/-3 of A pin

  Note that some detented encoders will return 4 counts per detent.
  -- set det4x to true

}


con { fixed io pins }

  RX1     = 63  { I }                                           ' programming / debug
  TX1     = 62  { O }

  FS_CS   = 61  { O }                                           ' flash storage
  FS_CLK  = 60  { O }
  FS_MOSI = 59  { O }
  FS_MISO = 58  { I }


con

  #-1, DETENT, NO_DETENT


var

  long  apin                                                    ' A input
  long  btnpin                                                  ' button input (optional)
  long  mod4x                                                   ' 4x per detent modification
  long  offset                                                  ' for preset
  long  lolimit, hilimit                                        ' for range limiting
  long  setup                                                   ' true when pin setup


pub null()

'' This is not a top-level object


pub start(a, b, btn, d4x, preset, lo, hi) : result | dif

'' Start the encoder object
'' -- continuous count mode
'' -- a & b are encoder inputs (active-low)
'' -- btn is the button input (active-low, -1 if not used)
'' -- set d4x to true if each "click" is 4 counts
'' -- preset is initial value for encoder
'' -- lo & hi are limit values for encoder

  stop()

  dif := b - a
  if ((dif == 0) or (abs(dif) > 3))                             ' check pins
    result := false
  else
    apin := a                                                   ' save pins & limits
    longmove(@btnpin, @btn, 5)
    mod4x := (d4x) ? 2 : 0                                      ' fix detent modifier
    pinstart(apin, P_QUADRATURE | dif.[2..0] << 24, 0, 0)       ' start a/b quadrature mode
    set(preset)                                                 ' preset encoder value
    result := setup := true


pub stop()

'' Disable encoder smart pin if previously configured

  if (setup)
    pinclear(apin)                                              ' disable smart pin
    longfill(@apin, 0, 7)                                       ' mark disabled


pub set(preset) : result

'' Set encoder to preset value

  pinfloat(apin)                                                ' reset & clear
  pinlow(apin)                                                  ' re-enable
  offset := preset                                              ' set encoder value
  result := preset


pub value() : result

'' Return encoder value
'' -- returns encoder value turncated to lolimit..hilimit

  result := raw() + offset                                      ' read and update value

  if (result < lolimit)                                         ' limit range
    result := set(lolimit)
  elseif (result > hilimit)
    result := set(hilimit)


pub button(delay) : result

'' Debounce encoder button for delay milliseconds
'' -- return 1 for pressed, 0 for not pressed

  if ((setup) and (btnpin >=0))                                 ' button used
    if (pinread(btnpin) == 0)                                   ' pressed now?
      result := 1                                               ' start pressed
      repeat (delay #> 0)                                       ' start debounce loop
        waitms(1)
        result &= pinread(btnpin) ^ 1


pub raw() : result

'' Returns encoder value w/o offset
'' -- for development & debugging

  result := rdpin(apin) sar mod4x


con { license }

{{

  Terms of Use: MIT License

  Permission is hereby granted, free of charge, to any person obtaining a copy of this
  software and associated documentation files (the "Software"), to deal in the Software
  without restriction, including without limitation the rights to use, copy, modify,
  merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to the following
  conditions:

  The above copyright notice and this permission notice shall be included in all copies
  or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
  INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
  OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

}}