rp2pio – Hardware interface to RP2 series’ programmable IO (PIO) peripheral.
Note
This module is intended to be used with the adafruit_pioasm library. For an introduction and guide to working with PIO in CircuitPython, see this Learn guide.
Warning
Using PIO inputs on Raspberry Pi RP2350 A2 stepping has some limitations
due to a GPIO hardware issue that causes excessive leakage current (~120uA).
A pin can read as high even when driven or pulled low, if the input signal is high
impedance or if an attached pull-down resistor is too weak (has too high a value).
See the warning in digitalio for more information.
Available on these boards
- rp2pio.pins_are_sequential(pins: List[microcontroller.Pin]) bool
Return True if the pins have sequential GPIO numbers, False otherwise
- rp2pio.FifoType
- rp2pio.FifoType_piov0
- rp2pio.MovStatusType
- rp2pio.MovStatusType_piov0
- class rp2pio.StateMachine(program: circuitpython_typing.ReadableBuffer, frequency: int, *, pio_version: int = 0, may_exec: circuitpython_typing.ReadableBuffer | None = None, init: circuitpython_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, sideset_enable: bool = False, jmp_pin: microcontroller.Pin | None = None, jmp_pin_pull: digitalio.Pull | None = None, 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, wrap_target: int = 0, wrap: int = -1, offset: int = -1, fifo_type: FifoType = 'auto', mov_status_type: MovStatusType = 'txfifo', mov_status_n: int = 0)
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.
The following parameters are usually supplied directly:
- Parameters:
program (ReadableBuffer) – the program to run with the state machine
frequency (int) – the target clock frequency of the state machine. Actual may be less. Use 0 for system clock speed.
init (ReadableBuffer) – a program to run once at start up. This is run after program is started so instructions may be intermingled
may_exec (ReadableBuffer) – Instructions that may be executed via
StateMachine.runcalls. Some elements of theStateMachine’s configuration are inferred from the instructions used; for instance, if there is noinorpushinstruction, then theStateMachineis configured without a receive FIFO. In this case, passing amay_execprogram containing anininstruction such asin x, a receive FIFO will be configured.first_out_pin (Pin) – the first pin to use with the OUT instruction
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
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
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
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
sideset_enable (bool) – True when the top sideset bit is to enable. This should be used with the “.side_set # opt” directive
jmp_pin (Pin) – the pin which determines the branch taken by JMP PIN instructions
jmp_pin_pull (Pull) – The pull value for the jmp pin, default is no pull.
exclusive_pin_use (bool) – When True, do not share any pins with other state machines. Pins are never shared with other peripherals
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.
user_interruptible (bool) – When True (the default),
write(),readinto(), andwrite_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.offset (int) – A specific offset in the state machine’s program memory where the program must be loaded. The default value, -1, allows the program to be loaded at any offset. This is appropriate for most programs.
The following parameters are usually set via assembler directives and passed using a
**program.pio_kwargsargument but may also be specified directly:- Parameters:
out_pin_count (int) – the count of consecutive pins to use with OUT starting at first_out_pin
in_pin_count (int) – the count of consecutive pins to use with IN starting at first_in_pin
set_pin_count (int) – the count of consecutive pins to use with SET starting at first_set_pin
sideset_pin_count (int) – the count of consecutive pins to use with a side set starting at first_sideset_pin. Does not include sideset enable
pio_version (int) – The version of the PIO peripheral required by the program. The constructor will raise an error if the actual hardware is not compatible with this program version.
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).
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).
wrap_target (int) – The target instruction number of automatic wrap. Defaults to the first instruction of the program.
wrap (int) – The instruction after which to wrap to the
wrapinstruction. As a special case, -1 (the default) indicates the last instruction of the program.fifo_type (FifoType) – How the program accessess the FIFOs. PIO version 0 only supports a subset of values.
mov_status_type (MovStatusType) – What condition the
mov statusinstruction checks. PIO version 0 only supports a subset of values.mov_status_n (MovStatusType) – The FIFO depth or IRQ the
mov statusinstruction checks for. Formov_status irqthis includes the encoding of thenext/prevselection bits.
- __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.
- run(instructions: circuitpython_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.
- write(buffer: circuitpython_typing.ReadableBuffer, *, start: int = 0, end: int | None = None, swap: bool = False) None
Write the data contained in
bufferto the state machine. If the buffer is empty, nothing happens.Writes to the FIFO will match the input buffer’s element size. For example, bytearray elements will perform 8 bit writes to the PIO FIFO. The RP2040’s memory bus will duplicate the value into the other byte positions. So, pulling more data in the PIO assembly will read the duplicated values.
To perform 16 or 32 bits writes into the FIFO use an
array.arraywith a type code of the desired size.- Parameters:
buffer (ReadableBuffer) – Write out the data in this buffer
start (int) – Start of the slice of
bufferto write out:buffer[start:end]end (int) – End of the slice; this index is not included. Defaults to
len(buffer)swap (bool) – For 2- and 4-byte elements, swap (reverse) the byte order
- background_write(once: circuitpython_typing.ReadableBuffer | None = None, *, loop: circuitpython_typing.ReadableBuffer | None = None, swap: bool = False) None
Write data to the TX fifo in the background, with optional looping.
First, if any previous
onceorloopbuffer has not been started, this function blocks until they have been started. This means that anyonceorloopbuffer will be written at least once. Then theonceand/orloopbuffers are queued. and the function returns. Theoncebuffer (if specified) will be written just once. Finally, theloopbuffer (if specified) will continue being looped indefinitely.Writes to the FIFO will match the input buffer’s element size. For example, bytearray elements will perform 8 bit writes to the PIO FIFO. The RP2040’s memory bus will duplicate the value into the other byte positions. So, pulling more data in the PIO assembly will read the duplicated values.
To perform 16 or 32 bits writes into the FIFO use an
array.arraywith a type code of the desired size, or usememoryview.castto change the interpretation of an existing buffer. To send just part of a larger buffer, slice amemoryviewof it.If a buffer is modified while it is being written out, the updated values will be used. However, because of interactions between CPU writes, DMA and the PIO FIFO are complex, it is difficult to predict the result of modifying multiple values. Instead, alternate between a pair of buffers.
Having both a
onceand aloopparameter is to support a special case in PWM generation where a change in duty cycle requires a special transitional buffer to be used exactly once. Most use cases will probably only use one ofonceorloop.Having neither
oncenorloopterminates an existing background looping write after exactly a whole loop. This is in contrast tostop_background_write, which interrupts an ongoing DMA operation.- Parameters:
once (~Optional[circuitpython_typing.ReadableBuffer]) – Data to be written once
loop (~Optional[circuitpython_typing.ReadableBuffer]) – Data to be written repeatedly
swap (bool) – For 2- and 4-byte elements, swap (reverse) the byte order
- stop_background_write() None
Immediately stop a background write, if one is in progress. Any DMA in progress is halted, but items already in the TX FIFO are not affected.
- pending: int
Returns the number of pending buffers for background writing.
If the number is 0, then a
StateMachine.background_writecall will not block.
- readinto(buffer: circuitpython_typing.WriteableBuffer, *, start: int = 0, end: int | None = None, swap: bool = False) None
Read into
buffer. If the number of bytes to read is 0, nothing happens. The buffer includes any data added to the fifo even if it was added before this was called.Reads from the FIFO will match the input buffer’s element size. For example, bytearray elements will perform 8 bit reads from the PIO FIFO. The alignment within the 32 bit value depends on
in_shift_right. Whenin_shift_rightis True, the upper N bits will be read. The lower bits will be read whenin_shift_rightis False.To perform 16 or 32 bits writes into the FIFO use an
array.arraywith a type code of the desired size.- Parameters:
buffer (WriteableBuffer) – Read data into this buffer
start (int) – Start of the slice of
bufferto read into:buffer[start:end]end (int) – End of the slice; this index is not included. Defaults to
len(buffer)swap (bool) – For 2- and 4-byte elements, swap (reverse) the byte order
- write_readinto(buffer_out: circuitpython_typing.ReadableBuffer, buffer_in: circuitpython_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_outwhile simultaneously reading data intobuffer_in. The lengths of the slices defined bybuffer_out[out_start:out_end]andbuffer_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.Data transfers to and from the FIFOs will match the corresponding buffer’s element size. See
writeandreadintofor details.To perform 16 or 32 bits writes into the FIFO use an
array.arraywith a type code of the desired size.- Parameters:
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_into 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)swap_out (bool) – For 2- and 4-byte elements, swap (reverse) the byte order for the buffer being transmitted (written)
swap_in (bool) – For 2- and 4-rx elements, swap (reverse) the byte order for the buffer being received (read)
- frequency: int
The actual state machine frequency. This may not match the frequency requested due to internal limitations.
- txstall: bool
True when the state machine has stalled due to a full TX FIFO since the last
clear_txstallcall.
- rxstall: bool
True when the state machine has stalled due to a full RX FIFO since the last
clear_rxfifocall.
- rxfifo: memorymap.AddressRange
Access the state machine’s rxfifo directly
If the state machine’s fifo mode is
txputthen accessing this object reads values stored by themov rxfifo[], isrPIO instruction, and the result of modifying it is undefined.If the state machine’s fifo mode is
txgetthen modifying this object writes values accessed by themov osr, rxfifo[]PIO instruction, and the result of accessing it is undefined.If this state machine’s mode is something else, then the property’s value is
None.Note: Since the
txputandtxgetfifo mode does not exist on RP2040, this property will always beNone.