rp2pio – Hardware interface to RP2 series” programmable IO (PIO) peripheral.

Available on these boards
  • Adafruit Feather RP2040
  • Adafruit ItsyBitsy RP2040
  • Adafruit KB2040
  • Adafruit Macropad RP2040
  • Adafruit QT Py RP2040
  • Adafruit QT2040 Trinkey
  • Arduino Nano RP2040 Connect
  • Challenger NB RP2040 WiFi
  • Challenger RP2040 LTE
  • Challenger RP2040 WiFi
  • Cytron Maker Nano RP2040
  • Cytron Maker Pi RP2040
  • EncoderPad RP2040
  • Melopero Shake RP2040
  • Oak Dev Tech BREAD2040
  • Pimoroni Interstate 75
  • Pimoroni Keybow 2040
  • Pimoroni PGA2040
  • Pimoroni Pico LiPo (16MB)
  • Pimoroni Pico LiPo (4MB)
  • Pimoroni PicoSystem
  • Pimoroni Plasma 2040
  • Pimoroni Tiny 2040
  • PyKey60
  • RP2040 Stamp
  • Raspberry Pi Pico
  • SparkFun MicroMod RP2040 Processor
  • SparkFun Pro Micro RP2040
  • SparkFun Thing Plus - RP2040

rp2pio.pins_are_sequential(pins: List[microcontroller.Pin]) → bool

Return True if the pins have sequential GPIO numbers, False otherwise

class rp2pio.StateMachine(program: _typing.ReadableBuffer, frequency: int, *, init: _typing.ReadableBuffer | None = None, first_out_pin: microcontroller.Pin | None = None, out_pin_count: int = 1, initial_out_pin_state: int = 0, initial_out_pin_direction: int = 4294967295, first_in_pin: microcontroller.Pin | None = None, in_pin_count: int = 1, pull_in_pin_up: int = 0, pull_in_pin_down: int = 0, first_set_pin: microcontroller.Pin | None = None, set_pin_count: int = 1, initial_set_pin_state: int = 0, initial_set_pin_direction: int = 31, first_sideset_pin: microcontroller.Pin | None = None, sideset_pin_count: int = 1, initial_sideset_pin_state: int = 0, initial_sideset_pin_direction: int = 31, exclusive_pin_use: bool = True, auto_pull: bool = False, pull_threshold: int = 32, out_shift_right: bool = True, wait_for_txstall: bool = True, auto_push: bool = False, push_threshold: int = 32, in_shift_right: bool = True, user_interruptible: bool = True)

A single PIO StateMachine

The programmable I/O peripheral on the RP2 series of microcontrollers is unique. It is a collection of generic state machines that can be used for a variety of protocols. State machines may be independent or coordinated. Program memory and IRQs are shared between the state machines in a particular PIO instance. They are independent otherwise.

This class is designed to facilitate sharing of PIO resources. By default, it is assumed that the state machine is used on its own and can be placed in either PIO. State machines with the same program will be placed in the same PIO if possible.

Construct a StateMachine object on the given pins with the given program.

Paramètres:

  • program (ReadableBuffer) – the program to run with the state machine

  • frequency (int) – the target clock frequency of the state machine. Actual may be less.

  • init (ReadableBuffer) – a program to run once at start up. This is run after program is started so instructions may be intermingled

  • first_out_pin (Pin) – the first pin to use with the OUT instruction

  • out_pin_count (int) – the count of consecutive pins to use with OUT starting at first_out_pin

  • initial_out_pin_state (int) – the initial output value for out pins starting at first_out_pin

  • initial_out_pin_direction (int) – the initial output direction for out pins starting at first_out_pin

  • first_in_pin (Pin) – the first pin to use with the IN instruction

  • in_pin_count (int) – the count of consecutive pins to use with IN starting at first_in_pin

  • pull_in_pin_up (int) – a 1-bit in this mask sets pull up on the corresponding in pin

  • pull_in_pin_down (int) – a 1-bit in this mask sets pull down on the corresponding in pin. Setting both pulls enables a « bus keep » function, i.e. a weak pull to whatever is current high/low state of GPIO.

  • first_set_pin (Pin) – the first pin to use with the SET instruction

  • set_pin_count (int) – the count of consecutive pins to use with SET starting at first_set_pin

  • initial_set_pin_state (int) – the initial output value for set pins starting at first_set_pin

  • initial_set_pin_direction (int) – the initial output direction for set pins starting at first_set_pin

  • first_sideset_pin (Pin) – the first pin to use with a side set

  • sideset_pin_count (int) – the count of consecutive pins to use with a side set starting at first_sideset_pin

  • initial_sideset_pin_state (int) – the initial output value for sideset pins starting at first_sideset_pin

  • initial_sideset_pin_direction (int) – the initial output direction for sideset pins starting at first_sideset_pin

  • jmp_pin (Pin) – the pin which determines the branch taken by JMP PIN instructions

  • exclusive_pin_use (bool) – When True, do not share any pins with other state machines. Pins are never shared with other peripherals

  • auto_pull (bool) – When True, automatically load data from the tx FIFO into the output shift register (OSR) when an OUT instruction shifts more than pull_threshold bits

  • pull_threshold (int) – Number of bits to shift before loading a new value into the OSR from the tx FIFO

  • out_shift_right (bool) – When True, data is shifted out the right side (LSB) of the OSR. It is shifted out the left (MSB) otherwise. NOTE! This impacts data alignment when the number of bytes is not a power of two (1, 2 or 4 bytes).

  • wait_for_txstall (bool) – When True, writing data out will block until the TX FIFO and OSR are empty and an instruction is stalled waiting for more data. When False, data writes won’t wait for the OSR to empty (only the TX FIFO) so make sure you give enough time before deiniting or stopping the state machine.

  • auto_push (bool) – When True, automatically save data from input shift register (ISR) into the rx FIFO when an IN instruction shifts more than push_threshold bits

  • push_threshold (int) – Number of bits to shift before saving the ISR value to the RX FIFO

  • in_shift_right (bool) – When True, data is shifted into the right side (LSB) of the ISR. It is shifted into the left (MSB) otherwise. NOTE! This impacts data alignment when the number of bytes is not a power of two (1, 2 or 4 bytes).

  • user_interruptible (bool) – When True (the default), write(), readinto(), and write_readinto() can be interrupted by a ctrl-C. This is useful when developing a PIO program: if there is an error in the program that causes an infinite loop, you will be able to interrupt the loop. However, if you are writing to a device that can get into a bad state if a read or write is interrupted, you may want to set this to False after your program has been vetted.

frequency :int

The actual state machine frequency. This may not match the frequency requested due to internal limitations.

rxstall :bool

True when the state machine has stalled due to a full RX FIFO since the last clear_rxfifo call.

in_waiting :int

The number of words available to readinto

deinit() → None

Turn off the state machine and release its resources.

__enter__() → StateMachine

No-op used by Context Managers. Provided by context manager helper.

__exit__() → None

Automatically deinitializes the hardware when exiting a context. See Lifetime and ContextManagers for more info.

restart() → None

Resets this state machine, runs any init and enables the clock.

run(instructions: _typing.ReadableBuffer) → None

Runs all given instructions. They will likely be interleaved with in-memory instructions. Make sure this doesn’t wait for input!

This can be used to output internal state to the RX FIFO and then read with readinto.

stop() → None

Stops the state machine clock. Use restart to enable it.

write(buffer: _typing.ReadableBuffer, *, start: int = 0, end: int | None = None) → None

Write the data contained in buffer to the state machine. If the buffer is empty, nothing happens.

Paramètres:

  • buffer (ReadableBuffer) – Write out the data in this buffer

  • start (int) – Start of the slice of buffer to write out: buffer[start:end]

  • end (int) – End of the slice; this index is not included. Defaults to len(buffer)

readinto(buffer: _typing.WriteableBuffer, *, start: int = 0, end: int | None = None) → None
Read into buffer. If the number of bytes to read is 0, nothing happens. The buffer

include any data added to the fifo even if it was added before this was called.

Paramètres:

  • buffer (WriteableBuffer) – Read data into this buffer

  • start (int) – Start of the slice of buffer to read into: buffer[start:end]

  • end (int) – End of the slice; this index is not included. Defaults to len(buffer)

write_readinto(buffer_out: _typing.ReadableBuffer, buffer_in: _typing.WriteableBuffer, *, out_start: int = 0, out_end: int | None = None, in_start: int = 0, in_end: int | None = None) → None

Write out the data in buffer_out while simultaneously reading data into buffer_in. The lengths of the slices defined by buffer_out[out_start:out_end] and buffer_in[in_start:in_end] may be different. The function will return once both are filled. If buffer slice lengths are both 0, nothing happens.

Paramètres:

  • buffer_out (ReadableBuffer) – Write out the data in this buffer

  • buffer_in (WriteableBuffer) – Read data into this buffer

  • out_start (int) – Start of the slice of buffer_out to write out: buffer_out[out_start:out_end]

  • out_end (int) – End of the slice; this index is not included. Defaults to len(buffer_out)

  • in_start (int) – Start of the slice of buffer_in to read into: buffer_in[in_start:in_end]

  • in_end (int) – End of the slice; this index is not included. Defaults to len(buffer_in)

clear_rxfifo() → None

Clears any unread bytes in the rxfifo.