QT Py RP2040 & rotaryio - "Pins must be sequential" error isn't user friendly

[jpconstantineau]

CircuitPython version

Adafruit CircuitPython 7.0.0-beta.0

Code/REPL

import board
import rotaryio
# works
encoder = rotaryio.IncrementalEncoder(board.D4, board.D5)
# does not work -- returns RuntimeError: Pins must be sequential
encoder = rotaryio.IncrementalEncoder(board.D5, board.D6)

Behavior

Initializing a rotary encoder on D4 and D5 appears to be on sequential pins as they are next to each other on the QT PY RP2040 and even have sequential numbers. This combination works properly.

Initializing a rotary encoder on D5 and D6 also appears to be on sequential pins as they are next to each other on the QT PY RP2040 and even have sequential numbers. Unfortunately, rotaryio checks that the GPIOs on the chip are sequential (pin_GPIO25 and pin_GPIO20) using the function "common_hal_rp2pio_pins_are_sequential" and fails with the RuntimeError: Pins must be sequential.

For the QT Py RP2040, this message isn't clear. For users that don't have access to the circuitpython source code to troubleshoot this error message, they will think that the two pins combination are pretty much the same but behave differently.

Ideally, any combination of GPIOs should be able to be configured to work with the rotaryio module.

Description

No response

Additional information

No response

[dhalbert]

Ideally, any combination of GPIOs should be able to be configured to work with the rotaryio module.

This unfortunately is not possible, because we are using RP2040 PIO, which requires sequential pins.

We could say "Pins must be sequential as GPIO pins" or "GPIO pins must be sequential". In addition, we could add a note to the documentation explaining this in more detail.

[jpconstantineau]

I assumed as much when I saw the check in the code.

I suspect that "GPIO pins must be sequential" would be enough to point to the GPIO IDs as opposed to the Pin IDs.

Is there an easy way to find out the GPIO IDs from the REPL as opposed to digging in the code? That could be part of the documentation to help people troubleshoot.

Some documentation would be useful too but like most people, I still would have fallen into that trap when I designed one of my PCBs that's going to be compatible with the Xiao, QT Py and QT Py RP2040. That's why prototypes exist!

[dhalbert]

microcontroller.pin.GPIOnn objects are the same as the board.some_pin objects. They print preferentially as board.some_pin. E.g. on the MacroPad:

>>> microcontroller.pin.GPIO2
board.KEY2

So it's easy to go one way, but more work to go the other way.

The schematic and the code are really the ground truth. The schematic is available on the "Downloads" page for a particular board.

[Neradoc]

help(microcontroller.pin) gives you one name per pin:

>>> import microcontroller
>>> help(microcontroller.pin)
object <module ''> is of type module
  GPIO0 -- microcontroller.pin.GPIO0
  GPIO1 -- microcontroller.pin.GPIO1
  GPIO2 -- microcontroller.pin.GPIO2
  GPIO3 -- board.MOSI
  GPIO4 -- board.MISO
  GPIO5 -- board.RX
  GPIO6 -- board.SCK
  GPIO7 -- microcontroller.pin.GPIO7
  GPIO8 -- microcontroller.pin.GPIO8
  GPIO9 -- microcontroller.pin.GPIO9
  GPIO10 -- microcontroller.pin.GPIO10
  GPIO11 -- board.NEOPIXEL_POWER
  GPIO12 -- board.NEOPIXEL
  GPIO13 -- microcontroller.pin.GPIO13
  GPIO14 -- microcontroller.pin.GPIO14
  GPIO15 -- microcontroller.pin.GPIO15
  GPIO16 -- microcontroller.pin.GPIO16
  GPIO17 -- microcontroller.pin.GPIO17
  GPIO18 -- microcontroller.pin.GPIO18
  GPIO19 -- microcontroller.pin.GPIO19
  GPIO20 -- board.TX
  GPIO21 -- board.BUTTON
  GPIO22 -- board.SDA1
  GPIO23 -- board.SCL1
  GPIO24 -- board.SDA
  GPIO25 -- board.SCL
  GPIO26 -- board.A3
  GPIO27 -- board.A2
  GPIO28 -- board.A1
  GPIO29 -- board.A0

But this script will give you all the aliases:
https://gist.github.com/Neradoc/467cfba8a415a9648751633fe01df6aa

Adafruit CircuitPython 7.0.0-alpha.6 on 2021-08-12; Adafruit QT Py RP2040 with rp2040
>>> import mcc_pin_mapping_sorted
microcontroller.GPIO0
microcontroller.GPIO1
microcontroller.GPIO10
microcontroller.GPIO11 board.NEOPIXEL_POWER
microcontroller.GPIO12 board.NEOPIXEL
microcontroller.GPIO13
microcontroller.GPIO14
microcontroller.GPIO15
microcontroller.GPIO16
microcontroller.GPIO17
microcontroller.GPIO18
microcontroller.GPIO19
microcontroller.GPIO2
microcontroller.GPIO20 board.D6 board.TX
microcontroller.GPIO21 board.BUTTON
microcontroller.GPIO22 board.SDA1
microcontroller.GPIO23 board.SCL1
microcontroller.GPIO24 board.D4 board.SDA
microcontroller.GPIO25 board.D5 board.SCL
microcontroller.GPIO26 board.A3 board.D3
microcontroller.GPIO27 board.A2 board.D2
microcontroller.GPIO28 board.A1 board.D1
microcontroller.GPIO29 board.A0 board.D0
microcontroller.GPIO3 board.D10 board.MOSI
microcontroller.GPIO4 board.D9 board.MISO
microcontroller.GPIO5 board.D7 board.RX
microcontroller.GPIO6 board.D8 board.SCK
microcontroller.GPIO7
microcontroller.GPIO8
microcontroller.GPIO9

[dhalbert]

help(microcontroller.pin) gives you one name per pin:

Thanks! I don't think I ever knew this!