src/adafruit_blinka/microcontroller/bcm283x/rotaryio.py

   1 # SPDX-FileCopyrightText: 2025 Melissa LeBlanc-Williams for Adafruit Industries
   2 #
   3 # SPDX-License-Identifier: MIT
   4 """
   5 `rotaryio` - Support for reading rotation sensors
   6 ===========================================================
   7 See `CircuitPython:rotaryio` in CircuitPython for more details.
   8
   9 Raspberry Pi PIO implementation
  10
  11 * Author(s): Melissa LeBlanc-Williams
  12 """
  13
  14 from __future__ import annotations
  15 import microcontroller
  16 import array
  17 try:
  18     import adafruit_pioasm
  19     from adafruit_rp1pio import StateMachine
  20 except ImportError:
  21     raise("adafruit_pioasm and adafruit_rp1pio are required for this module")
  22
  23 _n_read = 17
  24 _program = adafruit_pioasm.Program("""
  25 ;
  26 ; Copyright (c) 2023 Raspberry Pi (Trading) Ltd.
  27 ;
  28 ; SPDX-License-Identifier: BSD-3-Clause
  29 ;
  30 .pio_version 0 // only requires PIO version 0
  31
  32 .program quadrature_encoder
  33
  34 ; the code must be loaded at address 0, because it uses computed jumps
  35 .origin 0
  36
  37
  38 ; the code works by running a loop that continuously shifts the 2 phase pins into
  39 ; ISR and looks at the lower 4 bits to do a computed jump to an instruction that
  40 ; does the proper "do nothing" | "increment" | "decrement" action for that pin
  41 ; state change (or no change)
  42
  43 ; ISR holds the last state of the 2 pins during most of the code. The Y register
  44 ; keeps the current encoder count and is incremented / decremented according to
  45 ; the steps sampled
  46
  47 ; the program keeps trying to write the current count to the RX FIFO without
  48 ; blocking. To read the current count, the user code must drain the FIFO first
  49 ; and wait for a fresh sample (takes ~4 SM cycles on average). The worst case
  50 ; sampling loop takes 10 cycles, so this program is able to read step rates up
  51 ; to sysclk / 10  (e.g., sysclk 125MHz, max step rate = 12.5 Msteps/sec)
  52
  53 ; 00 state
  54     jmp update    ; read 00
  55     jmp decrement ; read 01
  56     jmp increment ; read 10
  57     jmp update    ; read 11
  58
  59 ; 01 state
  60     jmp increment ; read 00
  61     jmp update    ; read 01
  62     jmp update    ; read 10
  63     jmp decrement ; read 11
  64
  65 ; 10 state
  66     jmp decrement ; read 00
  67     jmp update    ; read 01
  68     jmp update    ; read 10
  69     jmp increment ; read 11
  70
  71 ; to reduce code size, the last 2 states are implemented in place and become the
  72 ; target for the other jumps
  73
  74 ; 11 state
  75     jmp update    ; read 00
  76     jmp increment ; read 01
  77 decrement:
  78     ; note: the target of this instruction must be the next address, so that
  79     ; the effect of the instruction does not depend on the value of Y. The
  80     ; same is true for the "jmp y--" below. Basically "jmp y--, <next addr>"
  81     ; is just a pure "decrement y" instruction, with no other side effects
  82     jmp y--, update ; read 10
  83
  84     ; this is where the main loop starts
  85 .wrap_target
  86 update:
  87     mov isr, y      ; read 11
  88     push noblock
  89
  90 sample_pins:
  91     ; we shift into ISR the last state of the 2 input pins (now in OSR) and
  92     ; the new state of the 2 pins, thus producing the 4 bit target for the
  93     ; computed jump into the correct action for this state. Both the PUSH
  94     ; above and the OUT below zero out the other bits in ISR
  95     out isr, 2
  96     in pins, 2
  97
  98     ; save the state in the OSR, so that we can use ISR for other purposes
  99     mov osr, isr
 100     ; jump to the correct state machine action
 101     mov pc, isr
 102
 103     ; the PIO does not have a increment instruction, so to do that we do a
 104     ; negate, decrement, negate sequence
 105 increment:
 106     mov y, ~y
 107     jmp y--, increment_cont
 108 increment_cont:
 109     mov y, ~y
 110 .wrap    ; the .wrap here avoids one jump instruction and saves a cycle too
 111 """)
 112
 113 _zero_y = adafruit_pioasm.assemble("set y 0")
 114
 115 class IncrementalEncoder:
 116     """
 117     IncrementalEncoder determines the relative rotational position based on two series of
 118     pulses. It assumes that the encoder’s common pin(s) are connected to ground,and enables
 119     pull-ups on pin_a and pin_b.
 120
 121     Create an IncrementalEncoder object associated with the given pins. It tracks the
 122     positional state of an incremental rotary encoder (also known as a quadrature encoder.)
 123     Position is relative to the position when the object is constructed.
 124     """
 125
 126     def __init__(
 127         self, pin_a: microcontroller.Pin, pin_b: microcontroller.Pin, divisor: int = 4
 128     ):
 129         """Create an incremental encoder on pin_a and the next higher pin
 130
 131         Always operates in "x4" mode (one count per quadrature edge)
 132
 133         Assumes but does not check that pin_b is one above pin_a."""
 134         #if pin_b is not None and pin_b.id != pin_a.id + 1:
 135         #    raise ValueError("pin_b must be None or one higher than pin_a")
 136
 137         try:
 138             self._sm = StateMachine(
 139                 _program.assembled,
 140                 frequency=0,
 141                 init=_zero_y,
 142                 first_in_pin=pin_a,
 143                 in_pin_count=2,
 144                 pull_in_pin_up=0x3,
 145                 auto_push=True,
 146                 push_threshold=32,
 147                 in_shift_right=False,
 148                 **_program.pio_kwargs
 149             )
 150         except RuntimeError as e:
 151             if "(error -13)" in e.args[0]:
 152                 raise RuntimeError(
 153                     "This feature requires a rules file to allow access to PIO. See "
 154                     "https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/using-neopixels-on-the-pi-5#updating-permissions-3189429"
 155                 ) from e
 156             raise
 157         self._buffer = array.array('i',[0] * _n_read)
 158         self.divisor = divisor
 159         self._position = 0
 160
 161     def deinit(self):
 162         """Deinitializes the IncrementalEncoder and releases any hardware resources for reuse."""
 163         self._sm.deinit()
 164
 165     def __enter__(self) -> IncrementalEncoder:
 166         """No-op used by Context Managers."""
 167         return self
 168
 169     def __exit__(self, _type, _value, _traceback):
 170         """
 171         Automatically deinitializes when exiting a context. See
 172         :ref:`lifetime-and-contextmanagers` for more info.
 173         """
 174         self.deinit()
 175
 176     @property
 177     def position(self):
 178         self._sm.readinto(self._buffer) # read N stale values + 1 fresh value
 179         raw_position = self._buffer[-1]
 180         delta = int((raw_position - self._position * self.divisor) / self.divisor)
 181         self._position += delta
 182         return self._position
 183
 184 '''
 185 if __name__ == '__main__':
 186     import board
 187     # D17/D18 on header pins 11/12
 188     # GND on header pin 6/9
 189     # +5V on header pins 2/4
 190     q = IncrementalEncoder(board.D17)
 191     old_position = q.position
 192     while True:
 193         position = q.position
 194         if position != old_position:
 195             delta = position - old_position
 196             print(f"{position:8d} {delta=}")
 197         old_position = position
 198 '''