9 Pico PIO Wats with Rust (Half 2)

That is Half 2 of an exploration into the surprising quirks of programming the Raspberry Pi Pico PIO with Micropython. For those who missed Part 1, we uncovered 4 Wats that problem assumptions about register rely, instruction slots, the conduct of pull noblock, and good but low-cost {hardware}.

Now, we proceed our journey towards crafting a theremin-like musical instrument — a challenge that reveals among the quirks and perplexities of PIO programming. Put together to problem your understanding of constants in a manner that brings to thoughts a Shakespearean tragedy.

Wat 5: Inconstant constants

On the earth of PIO programming, constants ought to be dependable, steadfast, and, nicely, fixed. However what in the event that they’re not? This brings us to a puzzling Wat about how the set instruction in PIO works—or doesn’t—when dealing with bigger constants.

Very like Juliet doubting Romeo’s fidelity, you may end up questioning if PIO constants will, as she says, “show likewise variable.”

The issue: Constants should not as large as they appear

Think about you’re programming an ultrasonic vary finder and have to rely down from 500 whereas ready for the Echo sign to drop from excessive to low. To arrange this wait time in PIO, you may naïvely attempt to load the fixed worth straight utilizing set:

; In Rust, make certain 'config.shift_in.path = ShiftDirection::Left;'
set y, 15       ; Load higher 5 bits (0b01111)
mov isr, y      ; Switch to ISR (clears ISR)
set y, 20       ; Load decrease 5 bits (0b10100)
in y, 5         ; Shift in decrease bits to type 500 in ISR
mov y, isr      ; Switch again to y

Apart: Don’t attempt to perceive the loopy jmp operations right here. We’ll talk about these subsequent in Wat 6.

However right here’s the tragic twist: the set instruction in PIO is proscribed to constants between 0 and 31. Furthermore, the star-crossed set instruction doesn’t report an error. As an alternative, it silently corrupts the entire PIO instruction. This produces a nonsense consequence.

Workarounds for inconstant constants

To handle this limitation, contemplate the next approaches:

• Learn Values and Retailer Them in a Register: We noticed this method in Wat 1. You possibly can load your fixed within the osr register, then switch it to y. For instance:

# Learn the max echo wait into OSR.
pull                    ; identical as pull block
mov y, osr              ; Load max echo wait into Y

• Shift and Mix Smaller Values: Utilizing the isr register and the in instruction, you may construct up a relentless of any dimension. This, nonetheless, consumes time and operations out of your 32-operation funds (see Part 1, Wat 2).

; In Rust, make certain 'config.shift_in.path = ShiftDirection::Left;'

set y, 15       ; Load higher 5 bits (0b01111)
mov isr, y      ; Switch to ISR (clears ISR)
set y, 20       ; Load decrease 5 bits (0b10100)
in y, 5         ; Shift in decrease bits to type 500 in ISR
mov y, isr      ; Switch again to y

• Sluggish Down the Timing: Cut back the frequency of the state machine to stretch delays over extra system clock cycles. For instance, reducing the state machine pace from 125 MHz to 343 kHz reduces the timeout fixed 182,216 to 500. 
• Use Additional Delays and (Nested) Loops: All directions help an non-obligatory delay, permitting you so as to add as much as 31 additional cycles. (To generate even longer delays, use loops — and even nested loops.)

; Generate 10μs set off pulse (4 cycles at 343_000Hz)
set pins, 1 [3]       ; Set set off pin to excessive, add delay of three
set pins, 0           ; Set set off pin to low voltage

• Use the “Subtraction Trick” to Generate the Most 32-bit Integer: In Wat 7, we’ll discover a method to generate 4,294,967,295 (the utmost unsigned 32-bit integer) by way of subtraction.

Very like Juliet cautioning in opposition to swearing by the inconstant moon, we’ve found that PIO constants should not all the time as steadfast as they appear. But, simply as their story takes surprising turns, so too does ours, transferring from the inconstancy of constants to the uneven nature of conditionals. Within the subsequent Wat, we’ll discover how PIO’s dealing with of conditional jumps can depart you questioning its loyalty to logic.

Wat 6: Conditionals by the looking-glass

In most programming environments, logical conditionals really feel balanced: you may check if a pin is excessive or low, or examine registers for equality or inequality. In PIO, this symmetry breaks down. You possibly can soar on pin excessive, however not pin low, and on x!=y, however not x==y. The foundations are whimsical — like Humpty Dumpty in By means of the Trying-Glass: “Once I outline a conditional, it means simply what I select it to imply — neither extra nor much less.”

These quirks power us to rewrite our code to suit the lopsided logic, making a gulf between how we want the code may very well be written and the way we should write it.

The issue: Lopsided conditionals in motion

Think about a easy situation: utilizing a spread finder, you need to rely down from a most wait time (y) till the ultrasonic echo pin goes low. Intuitively, you may write the logic like this:

measure_echo_loop:
 jmp !pin measurement_complete   ; If echo voltage is low, measurement is full
 jmp y-- measure_echo_loop       ; Proceed counting down except timeout

And when processing the measurement, if we solely want to output values that differ from the earlier worth, we might write:

measurement_complete:
 jmp x==y cooldown             ; If measurement is identical, skip to chill down
 mov isr, y                    ; Retailer measurement in ISR
 push                          ; Output ISR
 mov x, y                      ; Save the measurement in X

Sadly, PIO doesn’t allow you to check !pin or x==y straight. You have to restructure your logic to accommodate the obtainable conditionals, resembling pin and x!=y.

The answer: The best way it should be

Given PIO’s limitations, we adapt our logic with a two-step method that ensures the specified conduct regardless of the lacking conditionals:

• Leap on the alternative conditional to skip two directions ahead.
• Subsequent, use an unconditional soar to achieve the specified goal.

This workaround provides one additional soar (affecting the instruction restrict), however the further label is cost-free.

Right here is the rewritten code for counting down till the pin goes low:

measure_echo_loop:
   jmp pin echo_active     ; if echo voltage is excessive proceed rely down
   jmp measurement_complete ; if echo voltage is low, measurement is full
echo_active:
   jmp y-- measure_echo_loop ; Proceed counting down except timeout

And right here is the code for processing the measurement such that it’s going to solely output differing values:

measurement_complete:
   jmp x!=y send_result    ; if measurement is totally different, then ship it.
   jmp cooldown            ; If measurement is identical, do not ship.

send_result:
   mov isr, y              ; Retailer measurement in ISR
   push                    ; Output ISR
   mov x, y               ; Save the measurement in X

Classes from Humpty Dumpty’s conditionals

In By means of the Trying-Glass, Alice learns to navigate Humpty Dumpty’s peculiar world — simply as you’ll study to navigate PIO’s Wonderland of lopsided situations.

However as quickly as you grasp one quirk, one other reveals itself. Within the subsequent Wat, we’ll uncover a stunning conduct of jmp that, if it have been an athlete, would shatter world data.

In Part 1’s Wat 1 and Wat 3, we noticed how jmp x-- or jmp y-- is usually used to loop a hard and fast variety of occasions by decrementing a register till it reaches 0. Easy sufficient, proper? However what occurs when y is 0 and we run the next instruction?

jmp y-- measure_echo_loop

For those who guessed that it does not soar to measure_echo_loop and as a substitute falls by to the subsequent instruction, you’re completely appropriate. However for full credit score, reply this: What worth does y have after the instruction?

The reply: 4,294,967,295. Why? As a result of y is decremented after it’s examined for zero. Wat!?

Apart: If this doesn’t shock you, you seemingly have expertise with C or C++ which distinguish between pre-increment (e.g., ++x) and post-increment (e.g., x++) operations. The conduct of jmp y-- is equal to a post-decrement, the place the worth is examined earlier than being decremented.

This worth, 4,294,967,295, is the utmost for a 32-bit unsigned integer. It’s as if a track-and-field lengthy jumper launches off the takeoff board however, as a substitute of touchdown within the sandpit, overshoots and finally ends up on one other continent.

Apart: As foreshadowed in Wat 5, we will use this conduct deliberately to set a register to the worth 4,294,967,295.

Now that we’ve realized methods to stick the touchdown with jmp, let’s see if we will keep away from getting caught by the pins that PIO reads and units.

In Dr. Seuss’s Too Many Daves, Mrs. McCave had 23 sons, all named Dave, resulting in infinite confusion every time she referred to as out their identify. In PIO programming, pin and pins can seek advice from fully totally different ranges of pins relying on the context. It’s onerous to know which Dave or Daves you’re speaking to.

The issue: Pin ranges and subranges

In PIO, each pin and pins directions depend upon pin ranges outlined in Rust, outdoors of PIO. Nevertheless, particular person directions typically function on a subrange of these pin ranges. The conduct varies relying on the command: the subrange may very well be the primary n pins of the vary, all of the pins, or only a particular pin given by an index. To make clear PIO’s conduct, I created the next desk:

This desk reveals how PIO interprets the phrases pin and pins in numerous directions, together with their related contexts and configurations.

Instance: Distance program for the vary finder

Right here’s a PIO program for measuring the gap to an object utilizing Set off and Echo pins. The important thing options of this program are:

• Steady Operation: The vary finder runs in a loop as quick as potential.
• Most Vary Restrict: Measurements are capped at a given distance, with a return worth of 4,294,967,295 if no object is detected.
• Filtered Outputs: Solely measurements that differ from their speedy predecessor are despatched, lowering the output fee.

Look over this system and see that though it’s working with two pins — Set off and Echo — all through this system we solely see pin and pins.

.program distance

; X is the final worth despatched. Initialize it to
; u32::MAX which implies 'echo timeout'
; (Set X to u32::MAX by subtracting 1 from 0)
   set x, 0
subtraction_trick:
   jmp x-- subtraction_trick

; Learn the max echo wait into OSR
   pull                         ; identical as pull block

; Primary loop
.wrap_target
   ; Generate 10μs set off pulse (4 cycles at 343_000Hz)
   set pins, 0b1 [3]       ; Set set off pin to excessive, add delay of three
   set pins, 0b0           ; Set set off pin to low voltage

   ; When the set off goes excessive, begin counting down till it goes low
   wait 1 pin 0            ; Look forward to echo pin to be excessive voltage
   mov y, osr              ; Load max echo wait into Y

measure_echo_loop:
   jmp pin echo_active     ; if echo voltage is excessive proceed rely down
   jmp measurement_complete ; if echo voltage is low, measurement is full
echo_active:
   jmp y-- measure_echo_loop ; Proceed counting down except timeout

; Y tells the place the echo countdown stopped. It
; will likely be u32::MAX if the echo timed out.
measurement_complete:
   jmp x!=y send_result    ; if measurement is totally different, then despatched it.
   jmp cooldown            ; If measurement is identical, do not ship.

send_result:
   mov isr, y              ; Retailer measurement in ISR
   push                    ; Output ISR
   mov x, y               ; Save the measurement in X

; Settle down interval earlier than subsequent measurement
cooldown:
   wait 0 pin 0           ; Look forward to echo pin to be low
.wrap                      ; Restart the measurement loop

Configuring Pins

To make sure the PIO program behaves as meant:

• set pins, 0b1 ought to management the Set off pin.
• wait 1 pin 0 ought to monitor the Echo pin.
• jmp pin echo_active also needs to monitor the Echo pin.

Right here’s how one can configure this in Rust (adopted by a proof):

let mut distance_state_machine = pio1.sm0;
let trigger_pio = pio1.frequent.make_pio_pin({hardware}.set off);
let echo_pio = pio1.frequent.make_pio_pin({hardware}.echo);
distance_state_machine.set_pin_dirs(Course::Out, &[&trigger_pio]);
distance_state_machine.set_pin_dirs(Course::In, &[&echo_pio]);
distance_state_machine.set_config(&{
   let mut config = Config::default();
   config.set_set_pins(&[&trigger_pio]); // For set instruction
   config.set_in_pins(&[&echo_pio]); // For wait instruction
   config.set_jmp_pin(&echo_pio); // For jmp instruction
   let program_with_defines = pio_file!("examples/distance.pio");
   let program = pio1.frequent.load_program(&program_with_defines.program);
   config.use_program(&program, &[]); // No side-set pins
   config
});

The keys listed here are the <sturdy>set_set_pins</sturdy>, <sturdy>set_in_pins</sturdy>, and set_jmp_pin strategies on the Config struct.

• set_in_pins: Specifies the pins for enter operations, resembling wait(1, pin, …). The “in” pins should be consecutive.
• set_set_pins: Configures the pin for set operations, like set(pins, 1). The “set” pins should even be consecutive.
• set_jmp_pin: Defines the one pin utilized in conditional jumps, resembling jmp(pin, ...).

As described within the desk, different non-obligatory inputs embody:

• set_out_pins: Units the consecutive pins for output operations, resembling out(pins, …).
• use_program: Units a) the loaded program and b) consecutive pins for sideset operations. Sideset operations permit simultaneous pin toggling throughout different directions.

Configuring A number of Pins

Though not required for this program, you may configure a spread of pins in PIO by offering a slice of consecutive pins. For instance, suppose we had two ultrasonic vary finders:

let trigger_a_pio = pio1.frequent.make_pio_pin({hardware}.trigger_a);
let trigger_b_pio = pio1.frequent.make_pio_pin({hardware}.trigger_b);
config.set_set_pins(&[&trigger_a_pio, &trigger_b_pio]);

A single instruction can then management each pins:

set pins, 0b11 [3]  # Units each set off pins (17, 18) excessive, provides delay
set pins, 0b00      # Units each set off pins low

This method allows you to effectively apply bit patterns to a number of pins concurrently, streamlining management for purposes involving a number of outputs.

Apart: The Phrase “Set” in Programming

In programming, the phrase “set” is notoriously overloaded with a number of meanings. Within the context of PIO, “set” refers to one thing to which you’ll assign a price — resembling a pin’s state. It does not imply a set of issues, because it typically does in different programming contexts. When PIO refers to a set, it normally makes use of the time period “vary” as a substitute. This distinction is essential for avoiding confusion as you’re employed with PIO.

Classes from Mrs. McCave

In Too Many Daves, Mrs. McCave lamented not giving her 23 Daves extra distinct names. You possibly can keep away from her mistake by clearly documenting your pins with significant names — like Set off and Echo — in your feedback.

However when you assume dealing with these pin ranges is difficult, debugging a PIO program provides a wholly new layer of problem. Within the subsequent Wat, we’ll dive into the kludgy debugging strategies obtainable. Let’s see simply how far we will push them.

I wish to debug with interactive breakpoints in VS Code. I additionally do print debugging, the place you insert momentary data statements to see what the code is doing and the values of variables. Utilizing the Raspberry Pi Debug Probe and probe-rs, I can do each of those with common Rust code on the Pico.

With PIO programming, nonetheless, I can do neither.

The fallback is push-to-print debugging. In PIO, you quickly output integer values of curiosity. Then, in Rust, you utilize data! to print these values for inspection.

For instance, within the following PIO program, we quickly add directions to push the worth of x for debugging. We additionally embody set and out to push a relentless worth, resembling 7, which should be between 0 and 31 inclusive.

.program distance

; X is the final worth despatched. Initialize it to
; u32::MAX which implies 'echo timeout'
; (Set X to u32::MAX by subtracting 1 from 0)
   set x, 0
subtraction_trick:
   jmp x-- subtraction_trick

; DEBUG: See the worth of x
   mov isr, x
   push

; Learn the max echo wait into OSR
   pull                         ; identical as pull block

; DEBUG: Ship fixed worth
   set y, 7           ; Push '7' in order that we all know we have reached this level
   mov isr, y
   push
; ...

Again in Rust, you may learn and print these values to assist perceive what’s taking place within the PIO code (full code and project):

  // ...
   distance_state_machine.set_enable(true);
   distance_state_machine.tx().wait_push(MAX_LOOPS).await;
   loop {
       let end_loops = distance_state_machine.rx().wait_pull().await;
       data!("end_loops: {}", end_loops);
   }
  // ...

Outputs:

INFO  Hey, debug!
└─ distance_debug::inner_main::{async_fn#0} @ examplesdistance_debug.rs:27
INFO  end_loops: 4294967295
└─ distance_debug::inner_main::{async_fn#0} @ examplesdistance_debug.rs:57
INFO  end_loops: 7
└─ distance_debug::inner_main::{async_fn#0} @ examplesdistance_debug.rs:57

When push-to-print debugging isn’t sufficient, you may flip to {hardware} instruments. I purchased my first oscilloscope (a FNIRSI DSO152, for $37). With it, I used to be capable of verify the Echo sign was working. The Set off sign, nonetheless, was too quick for this cheap oscilloscope to seize clearly.

Utilizing these strategies — particularly push-to-print debugging — you may hint the move of your PIO program, even with out a conventional debugger.

Apart: In C/C++ (and doubtlessly Rust), you may get nearer to a full debugging expertise for PIO, for instance, through the use of the piodebug project.

That concludes the 9 Wats, however let’s deliver every little thing collectively in a bonus Wat.

Now that each one the parts are prepared, it’s time to mix them right into a working theremin-like musical instrument. We want a Rust monitor program. This program begins each PIO state machines — one for measuring distance and the opposite for producing tones. It then waits for a brand new distance measurement, maps that distance to a tone, and sends the corresponding tone frequency to the tone-playing state machine. If the gap is out of vary, it stops the tone.

Rust’s Place: On the coronary heart of this method is a perform that maps distances (from 0 to 50 cm) to tones (roughly B2 to F5). This perform is straightforward to write down in Rust, leveraging Rust’s floating-point math and exponential operations. Implementing this in PIO could be just about not possible as a consequence of its restricted instruction set and lack of floating-point help.

Right here’s the core monitor program to run the theremin (full file and project):

sound_state_machine.set_enable(true);
distance_state_machine.set_enable(true);
distance_state_machine.tx().wait_push(MAX_LOOPS).await;
loop {
   let end_loops = distance_state_machine.rx().wait_pull().await;
   match loop_difference_to_distance_cm(end_loops) {
       None => {
           data!("Distance: out of vary");
           sound_state_machine.tx().wait_push(0).await;
       }
       Some(distance_cm) => {
           let tone_frequency = distance_to_tone_frequency(distance_cm);
           let half_period = sound_state_machine_frequency / tone_frequency as u32 / 2;
           data!("Distance: {} cm, tone: {} Hz", distance_cm, tone_frequency);
           sound_state_machine.tx().push(half_period); // non-blocking push
           Timer::after(Length::from_millis(50)).await;
       }
   }
}

Utilizing two PIO state machines alongside a Rust monitor program allows you to actually run three applications directly. This setup is handy by itself and is important when strict timing or very high-frequency I/O operations are required.

Apart: Alternatively, Rust Embassy’s async duties allow you to implement cooperative multitasking straight on a single fundamental processor. You code in Rust relatively than a combination of Rust and PIO. Though Embassy duties don’t actually run in parallel, they swap shortly sufficient to deal with purposes like a theremin. Right here’s a snippet from theremin_no_pio.rs exhibiting the same core loop:

loop {
       match distance.measure().await {
           None => {
               data!("Distance: out of vary");
               sound.relaxation().await;
           }
           Some(distance_cm) => {
               let tone_frequency = distance_to_tone_frequency(distance_cm);
               data!("Distance: {} cm, tone: {} Hz", distance_cm, tone_frequency);
               sound.play(tone_frequency).await;
               Timer::after(Length::from_millis(50)).await;
           }
       }
   }

See our recent article on Rust Embassy programming for extra particulars.

Now that we’ve assembled all of the parts, let’s watch the video once more of me “enjoying” the musical instrument. On the monitor display, you may see the debugging prints displaying the gap measurements and the corresponding tones. This visible connection highlights how the system responds in actual time.

Conclusion

PIO programming on the Raspberry Pi Pico is a fascinating mix of simplicity and complexity, providing unparalleled {hardware} management whereas demanding a shift in mindset for builders accustomed to higher-level programming. By means of the 9 Wats we’ve explored, PIO has each shocked us with its limitations and impressed us with its uncooked effectivity.

Whereas we’ve coated vital floor — managing state machines, pin assignments, timing intricacies, and debugging — there’s nonetheless far more you may study as wanted: DMA, IRQ, side-set pins, variations between PIO on the Pico 1 and Pico 2, autopush and autopull, FIFO be part of, and extra.

Really useful Assets

At its core, PIO’s quirks mirror a design philosophy that prioritizes low-level {hardware} management with minimal overhead. By embracing these traits, PIO is not going to solely meet your challenge’s calls for but additionally open doorways to new prospects in embedded methods programming.

Please follow Carl on Towards Data Science and on @carlkadie.bsky.social. I write on scientific programming in Rust and Python, machine studying, and statistics. I have a tendency to write down about one article per 30 days.