This is Part 2 of an exploration into the unexpected quirks of programming the Raspberry Pi Pico PIO with Micropython<\/a>. If you missed Part 1<\/a>, we uncovered four Wats<\/em> that challenge assumptions about register count, instruction slots, the behavior of Now, we continue our journey toward crafting a theremin-like musical instrument\u200a\u2014\u200aa project that reveals some of the quirks and perplexities of PIO programming. Prepare to challenge your understanding of constants in a way that brings to mind a Shakespearean tragedy.<\/p>\n In the world of PIO programming, constants should be reliable, steadfast, and, well, constant<\/em>. But what if they\u2019re not? This brings us to a puzzling Wat about how the set instruction in PIO works\u2014or doesn\u2019t\u2014when handling larger constants.<\/p>\n Much like Juliet doubting Romeo\u2019s constancy, you might find yourself wondering if PIO constants will, as she says, \u201cprove likewise variable.\u201d<\/p>\n Imagine you\u2019re programming an ultrasonic range finder and need to count down from 500 while waiting for the Echo signal to drop from high to low. To set up this wait time in PIO, you might na\u00efvely try to load the constant value directly using Aside: Don\u2019t try to understand the crazy <\/em>jmp<\/em> operations here. We\u2019ll discuss those next in <\/em>Wat 6<\/em><\/strong>.<\/em><\/p>\n<\/blockquote>\n But here\u2019s the tragic twist: the set instruction in PIO is limited to constants between 0 and 31. Moreover, the star-crossed set instruction doesn\u2019t report an error. Instead, it silently corrupts the entire PIO instruction<\/a>. This produces a nonsense result.<\/p>\n To address this limitation, consider the following approaches:<\/p>\n Much like Juliet cautioning against swearing by the inconstant moon, we\u2019ve discovered that PIO constants are not always as steadfast as they seem. Yet, just as their story takes unexpected turns, so too does ours, moving from the inconstancy of constants to the uneven nature of conditionals. In the next Wat, we\u2019ll explore how PIO\u2019s handling of conditional jumps can leave you questioning its loyalty to logic.<\/p>\n In most programming environments, logical conditionals feel balanced: you can test if a pin is high or low, or check registers for equality or inequality. In PIO, this symmetry breaks down. You can jump on pin high, but not pin low, and on These quirks force us to rewrite our code to fit the lopsided logic, creating a gulf between how we wish the code could be written and how we must write it.<\/p>\n Consider a simple scenario: using a range finder, you want to count down from a maximum wait time (y) until the ultrasonic echo pin goes low. Intuitively, you might write the logic like this:<\/p>\n And when processing the measurement, if we only wish to output values that differ from the previous value, we would write:<\/p>\n Unfortunately, PIO doesn\u2019t let you test Given PIO\u2019s limitations, we adapt our logic with a two-step approach that ensures the desired behavior despite the missing conditionals:<\/p>\n This workaround adds one extra jump (affecting the instruction limit), but the additional label is cost-free.<\/p>\n Here is the rewritten code for counting down until the pin goes low:<\/p>\n And here is the code for processing the measurement such that it will only output differing values:<\/p>\n In Through the Looking-Glass<\/em>, Alice learns to navigate Humpty Dumpty\u2019s peculiar world\u200a\u2014\u200ajust as you\u2019ll learn to navigate PIO\u2019s Wonderland of lopsided conditions.<\/p>\n But as soon as you master one quirk, another reveals itself. In the next Wat, we\u2019ll uncover a surprising behavior of jmp that, if it were an athlete, would shatter world records.<\/p>\n In Part 1<\/a>\u2019s Wat 1<\/strong> and Wat 3<\/strong>, we saw how If you guessed that it does not<\/strong> jump to The answer: 4,294,967,295.<\/strong> Why? Because y is decremented after<\/strong> it is tested for zero. Wat!?<\/em><\/p>\n Aside: If this doesn\u2019t surprise you, you likely have experience with C or C++ which distinguish between pre-increment (e.g., This value, 4,294,967,295, is the maximum for a 32-bit unsigned integer. It\u2019s as if a track-and-field long jumper launches off the takeoff board but, instead of landing in the sandpit, overshoots and ends up on another continent.<\/p>\n Aside: <\/strong>As foreshadowed in Wat 5<\/strong>, we can use this behavior intentionally to set a register to the value 4,294,967,295.<\/p>\n<\/blockquote>\n Now that we\u2019ve learned how to stick the landing with In Dr. Seuss\u2019s Too Many Daves<\/em>, Mrs. McCave had 23 sons, all named Dave, leading to endless confusion whenever she called out their name. In PIO programming, In PIO, both This table shows how PIO interprets the terms Here\u2019s a PIO program for measuring the distance to an object using Trigger<\/strong> and Echo<\/strong> pins. The key features of this program are:<\/p>\n Glance over the program and notice that although it is working with two pins\u200a\u2014\u200aTrigger<\/strong> and Echo<\/strong>\u200a\u2014\u200athroughout the program we only see To ensure the PIO program behaves as intended:<\/p>\n Here\u2019s how you can configure this in Rust (followed by an explanation):<\/p>\n The keys here are the As described in the table, other optional inputs include:<\/p>\n Although not required for this program, you can configure a range of pins in PIO by providing a slice of consecutive pins. For example, suppose we had two ultrasonic range finders:<\/p>\n A single instruction can then control both pins:<\/p>\n This approach lets you efficiently apply bit patterns to multiple pins simultaneously, streamlining control for applications involving multiple outputs.<\/p>\n Aside: The Word \u201cSet\u201d in Programming<\/em><\/strong><\/p>\n In programming, the word \u201cset\u201d is notoriously overloaded with multiple meanings. In the context of PIO, \u201cset\u201d refers to something to which you can assign a value\u200a\u2014\u200asuch as a pin\u2019s state. It does <\/em>not<\/em><\/strong> mean a collection of things, as it often does in other programming contexts. When PIO refers to a collection, it usually uses the term \u201crange\u201d instead. This distinction is crucial for avoiding confusion as you work with PIO.<\/em><\/p>\n<\/blockquote>\n In Too Many Daves<\/em>, Mrs. McCave lamented not giving her 23 Daves more distinct names. You can avoid her mistake by clearly documenting your pins with meaningful names\u200a\u2014\u200alike Trigger<\/strong> and Echo<\/strong>\u200a\u2014\u200ain your comments.<\/p>\n But if you think handling these pin ranges is tricky, debugging a PIO program adds an entirely new layer of challenge. In the next Wat, we\u2019ll dive into the kludgy debugging methods available. Let\u2019s see just how far we can push them.<\/p>\n I like to debug with interactive breakpoints in VS Code. I also do print debugging<\/strong>, where you insert temporary info statements to see what the code is doing and the values of variables. Using the Raspberry Pi Debug Probe<\/strong><\/a> and probe-rs<\/strong><\/a>, I can do both of these with regular Rust code on the Pico.<\/p>\n With PIO programming, however, I can do neither.<\/p>\n The fallback is push-to-print debugging<\/strong>. In PIO, you temporarily output integer values of interest. Then, in Rust, you use For example, in the following PIO program, we temporarily add instructions to push the value of Back in Rust, you can read and print these values to help understand what\u2019s happening in the PIO code (full code<\/a> and project<\/a>):<\/p>\n Outputs:<\/p>\n When push-to-print debugging isn\u2019t enough, you can turn to hardware tools. I bought my first oscilloscope (a FNIRSI DSO152<\/strong>, for $37). With it, I was able to confirm the Echo<\/strong> signal was working. The Trigger<\/strong> signal, however, was too fast for this inexpensive oscilloscope to capture clearly.<\/p>\n Using these methods\u200a\u2014\u200aespecially push-to-print debugging\u200a\u2014\u200ayou can trace the flow of your PIO program, even without a traditional debugger.<\/p>\n Aside<\/em>:<\/em><\/strong> In C\/C++ (and potentially Rust), you can get closer to a full debugging experience for PIO, for example, by using the <\/em>piodebug<\/em><\/strong> project<\/em><\/a>.<\/em><\/p>\n<\/blockquote>\n That concludes the nine Wats, but let\u2019s bring everything together in a bonus Wat.<\/p>\n Now that all the components are ready, it\u2019s time to combine them into a working theremin-like musical instrument. We need a Rust monitor program. This program starts both PIO state machines\u200a\u2014\u200aone for measuring distance and the other for generating tones. It then waits for a new distance measurement, maps that distance to a tone, and sends the corresponding tone frequency to the tone-playing state machine. If the distance is out of range, it stops the tone.<\/p>\n Rust\u2019s Place<\/strong>: At the heart of this system is a function that maps distances (from 0 to 50 cm) to tones (approximately B2<\/strong> to F5<\/strong>). This function is simple to write in Rust, leveraging Rust\u2019s floating-point math and exponential operations. Implementing this in PIO would be virtually impossible due to its limited instruction set and lack of floating-point support.<\/p>\n Here\u2019s the core monitor program to run the theremin (full file<\/a> and project<\/a>):<\/p>\n Using two PIO state machines alongside a Rust monitor program lets you literally run three programs at once. This setup is convenient on its own and is essential when strict timing or very high-frequency I\/O operations are required.<\/p>\n Aside:<\/em><\/strong> Alternatively, Rust Embassy\u2019s async tasks let you implement cooperative multitasking directly on a single main processor. You code in Rust rather than a mixture of Rust and PIO. Although Embassy tasks don\u2019t literally run in parallel, they switch quickly enough to handle applications like a theremin. Here\u2019s a snippet from <\/em>theremin_no_pio.rs<\/em><\/a> showing a similar core loop:<\/em><\/p>\n<\/blockquote>\npull noblock<\/code>, and smart yet cheap hardware.<\/p>\nWat 5: Inconstant constants<\/h2>\n
The problem: Constants are not as big as they seem<\/h2>\n
set<\/code>:<\/p>\n; In Rust, be sure 'config.shift_in.direction = ShiftDirection::Left;'\nset y, 15 ; Load upper 5 bits (0b01111)\nmov isr, y ; Transfer to ISR (clears ISR)\nset y, 20 ; Load lower 5 bits (0b10100)\nin y, 5 ; Shift in lower bits to form 500 in ISR\nmov y, isr ; Transfer back to y<\/code><\/pre>\n\n
Workarounds for inconstant constants<\/h2>\n
\n
osr<\/code> register, then transfer it to y. For example:<\/li>\n<\/ul>\n# Read the max echo wait into OSR.\npull ; same as pull block\nmov y, osr ; Load max echo wait into Y<\/code><\/pre>\n\n
; In Rust, be sure 'config.shift_in.direction = ShiftDirection::Left;'\n\nset y, 15 ; Load upper 5 bits (0b01111)\nmov isr, y ; Transfer to ISR (clears ISR)\nset y, 20 ; Load lower 5 bits (0b10100)\nin y, 5 ; Shift in lower bits to form 500 in ISR\nmov y, isr ; Transfer back to y<\/code><\/pre>\n\n
182<\/code>,216<\/code> to 500<\/code>.\u00a0<\/li>\n; Generate 10\u03bcs trigger pulse (4 cycles at 343_000Hz)\nset pins, 1 [3] ; Set trigger pin to high, add delay of 3\nset pins, 0 ; Set trigger pin to low voltage<\/code><\/pre>\n\n
4,294,967,295<\/code> (the maximum unsigned 32-bit integer) via subtraction.<\/li>\n<\/ul>\nWat 6: Conditionals through the looking-glass<\/h2>\n
x!=y<\/code>, but not x==y<\/code>. The rules are whimsical\u200a\u2014\u200alike Humpty Dumpty in Through the Looking-Glass<\/em>: \u201cWhen I define a conditional, it means just what I choose it to mean\u200a\u2014\u200aneither more nor less.\u201d<\/p>\nThe problem: Lopsided conditionals in action<\/h2>\n
measure_echo_loop:\n jmp !pin measurement_complete ; If echo voltage is low, measurement is complete\n jmp y-- measure_echo_loop ; Continue counting down unless timeout<\/code><\/pre>\nmeasurement_complete:\n jmp x==y cooldown ; If measurement is the same, skip to cool down\n mov isr, y ; Store measurement in ISR\n push ; Output ISR\n mov x, y ; Save the measurement in X<\/code><\/pre>\n!pin<\/code> or x==y<\/code> directly. You must restructure your logic to accommodate the available conditionals, such as pin<\/code> and x!=y<\/code>.<\/p>\nThe solution: The way it must be<\/h2>\n
\n
measure_echo_loop:\n jmp pin echo_active ; if echo voltage is high continue count down\n jmp measurement_complete ; if echo voltage is low, measurement is complete\necho_active:\n jmp y-- measure_echo_loop ; Continue counting down unless timeout<\/code><\/pre>\nmeasurement_complete:\n jmp x!=y send_result ; if measurement is different, then send it.\n jmp cooldown ; If measurement is the same, don't send.\n\nsend_result:\n mov isr, y ; Store measurement in ISR\n push ; Output ISR\n mov x, y ; Save the measurement in X<\/code><\/pre>\nLessons from Humpty Dumpty\u2019s conditionals<\/h2>\n
Wat 7: Overshooting jumps<\/h1>\n
jmp x--<\/code> or jmp y--<\/code> is often used to loop a fixed number of times by decrementing a register until it reaches 0. Straightforward enough, right? But what happens when y is 0 and we run the following instruction?<\/p>\njmp y-- measure_echo_loop<\/code><\/pre>\nmeasure_echo_loop<\/code> and instead falls through to the next instruction, you\u2019re absolutely correct. But for full credit, answer this: What value does y have after the instruction?<\/strong><\/p>\n\n
++x<\/code>) and post-increment (e.g., x++) operations. The behavior of jmp y--<\/code> is equivalent to a post-decrement, where the value is tested before<\/em> being decremented.<\/p>\n<\/blockquote>\n\n
jmp<\/code>, let\u2019s see if we can avoid getting stuck by the pins that PIO reads and sets.<\/p>\nWat 8: Too many \u201cpins\u201d<\/h1>\n
pin<\/code> and pins<\/code> can refer to completely different ranges of pins depending on the context. It\u2019s hard to know which Dave or Daves you\u2019re talking to.<\/p>\nThe problem: Pin ranges and subranges<\/h2>\n
pin<\/code> and pins<\/code> instructions depend on pin ranges<\/strong> defined in Rust, outside of PIO. However, individual instructions often operate on a subrange<\/strong> of those pin ranges. The behavior varies depending on the command: the subrange could be the first n<\/em> pins of the range, all the pins, or just a specific pin given by an index. To clarify PIO\u2019s behavior, I created the following table:<\/p>\n![\"\"](\"https:\/\/i0.wp.com\/contributor.insightmediagroup.io\/wp-content\/uploads\/2025\/03\/Pico-1.png?ssl=1\")
<\/figure>\npin<\/code> and pins<\/code> in different instructions, along with their associated contexts and configurations.<\/p>\nExample: Distance program for the range finder<\/h2>\n
\n
4,294,967,295<\/code> if no object is detected.<\/li>\npin<\/code> and pins<\/code>.<\/p>\n.program distance\n\n; X is the last value sent. Initialize it to\n; u32::MAX which means 'echo timeout'\n; (Set X to u32::MAX by subtracting 1 from 0)\n set x, 0\nsubtraction_trick:\n jmp x-- subtraction_trick\n\n; Read the max echo wait into OSR\n pull ; same as pull block\n\n; Main loop\n.wrap_target\n ; Generate 10\u03bcs trigger pulse (4 cycles at 343_000Hz)\n set pins, 0b1 [3] ; Set trigger pin to high, add delay of 3\n set pins, 0b0 ; Set trigger pin to low voltage\n\n ; When the trigger goes high, start counting down until it goes low\n wait 1 pin 0 ; Wait for echo pin to be high voltage\n mov y, osr ; Load max echo wait into Y\n\nmeasure_echo_loop:\n jmp pin echo_active ; if echo voltage is high continue count down\n jmp measurement_complete ; if echo voltage is low, measurement is complete\necho_active:\n jmp y-- measure_echo_loop ; Continue counting down unless timeout\n\n; Y tells where the echo countdown stopped. It\n; will be u32::MAX if the echo timed out.\nmeasurement_complete:\n jmp x!=y send_result ; if measurement is different, then sent it.\n jmp cooldown ; If measurement is the same, don't send.\n\nsend_result:\n mov isr, y ; Store measurement in ISR\n push ; Output ISR\n mov x, y ; Save the measurement in X\n\n; Cool down period before next measurement\ncooldown:\n wait 0 pin 0 ; Wait for echo pin to be low\n.wrap ; Restart the measurement loop<\/code><\/pre>\nConfiguring Pins<\/strong><\/h4>\n
\n
set pins, 0b1<\/code> should control the Trigger<\/strong> pin.<\/li>\nwait 1 pin 0<\/code> should monitor the Echo<\/strong> pin.<\/li>\njmp pin echo_active<\/code> should also monitor the Echo<\/strong> pin.<\/li>\n<\/ul>\nlet mut distance_state_machine = pio1.sm0;\nlet trigger_pio = pio1.common.make_pio_pin(hardware.trigger);\nlet echo_pio = pio1.common.make_pio_pin(hardware.echo);\ndistance_state_machine.set_pin_dirs(Direction::Out, &[&trigger_pio]);\ndistance_state_machine.set_pin_dirs(Direction::In, &[&echo_pio]);\ndistance_state_machine.set_config(&{\n let mut config = Config::default();\n config.set_set_pins(&[&trigger_pio]); \/\/ For set instruction\n config.set_in_pins(&[&echo_pio]); \/\/ For wait instruction\n config.set_jmp_pin(&echo_pio); \/\/ For jmp instruction\n let program_with_defines = pio_file!(\"examples\/distance.pio\");\n let program = pio1.common.load_program(&program_with_defines.program);\n config.use_program(&program, &[]); \/\/ No side-set pins\n config\n});<\/code><\/pre>\n<strong>set_set_pins<\/strong><\/code>, <strong>set_in_pins<\/strong><\/code>, and set_jmp_pin<\/code> <\/strong>methods on the Config struct.<\/p>\n\n
set_in_pins<\/code>: Specifies the pins for input operations<\/strong>, such as wait(1, pin, \u2026). The \u201cin\u201d pins must be consecutive.<\/li>\nset_set_pins<\/code>: Configures the pin for set operations<\/strong>, like set(pins, 1). The \u201cset\u201d pins must also be consecutive.<\/li>\nset_jmp_pin<\/code>: Defines the single pin used in conditional jumps<\/strong>, such as jmp(pin, ...)<\/code>.<\/li>\n<\/ul>\n\n
set_out_pins<\/code>: Sets the consecutive pins for output operations<\/strong>, such as out(pins, \u2026).<\/li>\nuse_program<\/code>: Sets a) the loaded program and b) consecutive pins for sideset operations. <\/strong>Sideset operations allow simultaneous pin toggling during other instructions.<\/li>\n<\/ul>\nConfiguring Multiple Pins<\/strong><\/h4>\n
let trigger_a_pio = pio1.common.make_pio_pin(hardware.trigger_a);\nlet trigger_b_pio = pio1.common.make_pio_pin(hardware.trigger_b);\nconfig.set_set_pins(&[&trigger_a_pio, &trigger_b_pio]);<\/code><\/pre>\nset pins, 0b11 [3] # Sets both trigger pins (17, 18) high, adds delay\nset pins, 0b00 # Sets both trigger pins low<\/code><\/pre>\n\n
Lessons from Mrs. McCave<\/h2>\n
Wat 9: Kludgy debugging<\/h1>\n
info!<\/code> to print those values for inspection.<\/p>\nx<\/code> for debugging. We also include set<\/code> and out<\/code> to push a constant value, such as 7, which must be between 0 and 31 inclusive.<\/p>\n.program distance\n\n; X is the last value sent. Initialize it to\n; u32::MAX which means 'echo timeout'\n; (Set X to u32::MAX by subtracting 1 from 0)\n set x, 0\nsubtraction_trick:\n jmp x-- subtraction_trick\n\n; DEBUG: See the value of x\n mov isr, x\n push\n\n; Read the max echo wait into OSR\n pull ; same as pull block\n\n; DEBUG: Send constant value\n set y, 7 ; Push '7' so that we know we've reached this point\n mov isr, y\n push\n; ...<\/code><\/pre>\n \/\/ ...\n distance_state_machine.set_enable(true);\n distance_state_machine.tx().wait_push(MAX_LOOPS).await;\n loop {\n let end_loops = distance_state_machine.rx().wait_pull().await;\n info!(\"end_loops: {}\", end_loops);\n }\n \/\/ ...\n<\/code><\/pre>\nINFO Hello, debug!\n\u2514\u2500 distance_debug::inner_main::{async_fn#0} @ examplesdistance_debug.rs:27\nINFO end_loops: 4294967295\n\u2514\u2500 distance_debug::inner_main::{async_fn#0} @ examplesdistance_debug.rs:57\nINFO end_loops: 7\n\u2514\u2500 distance_debug::inner_main::{async_fn#0} @ examplesdistance_debug.rs:57<\/code><\/pre>\n\n
Bonus Wat 10: Putting it all together<\/h1>\n
sound_state_machine.set_enable(true);\ndistance_state_machine.set_enable(true);\ndistance_state_machine.tx().wait_push(MAX_LOOPS).await;\nloop {\n let end_loops = distance_state_machine.rx().wait_pull().await;\n match loop_difference_to_distance_cm(end_loops) {\n None => {\n info!(\"Distance: out of range\");\n sound_state_machine.tx().wait_push(0).await;\n }\n Some(distance_cm) => {\n let tone_frequency = distance_to_tone_frequency(distance_cm);\n let half_period = sound_state_machine_frequency \/ tone_frequency as u32 \/ 2;\n info!(\"Distance: {} cm, tone: {} Hz\", distance_cm, tone_frequency);\n sound_state_machine.tx().push(half_period); \/\/ non-blocking push\n Timer::after(Duration::from_millis(50)).await;\n }\n }\n}<\/code><\/pre>\n\n
loop {\n match distance.measure().await {\n None => {\n info!(\"Distance: out of range\");\n sound.rest().await;\n }\n Some(distance_cm) => {\n let tone_frequency = distance_to_tone_frequency(distance_cm);\n info!(\"Distance: {} cm, tone: {} Hz\", distance_cm, tone_frequency);\n sound.play(tone_frequency).await;\n Timer::after(Duration::from_millis(50)).await;\n }\n }\n }<\/code><\/pre>\n