Additionally obtainable: A MicroPython version of this article
In JavaScript and different languages, we name a surprising or inconsistent behavior a “Wat!” [that is, a “What!?”]. For instance, in JavaScript, an empty array plus an empty array produces an empty string, [] + [] === "". Wat!
Rust, by comparability, is constant and predictable. Nevertheless, one nook of Rust on the Raspberry Pi Pico microcontroller affords comparable surprises. Particularly, the Pico’s Programmable Enter/Output (PIO) subsystem, whereas extremely highly effective and versatile, comes with peculiarities.
PIO programming issues as a result of it supplies an ingenious resolution to the problem of exact, low-level {hardware} management. It’s extremely quick and versatile: slightly than counting on special-purpose {hardware} for the numerous peripherals you may wish to management, PIO means that you can outline customized behaviors in software program, seamlessly adapting to your wants with out including {hardware} complexity.
Take into account this straightforward instance: a $15 theremin-like musical instrument. By waving their hand within the air, the musician adjustments the pitch of (admittedly annoying) tones. Utilizing PIO supplies a easy technique to program this gadget that ensures it reacts immediately to motion.
So, all is fantastic, besides — to paraphrase Spider-Man:
With nice energy comes… 9 Wats!?
We’ll discover and illustrate these 9 PIO Wats via the creation of this theremin.
Who Is This Article For?
- All Programmers: Microcontrollers just like the Pico value beneath $7 and assist high-level languages like Python, Rust, and C/C++. This text will present how microcontrollers let your applications work together with the bodily world and introduce you to programming the Pico’s low-level, high-performance PIO {hardware}.
- Rust Pico Programmers: Curious concerning the Pico’s hidden potential? Past its two foremost cores, it has eight tiny “state machines” devoted to PIO programming. These state machines take over time-critical duties, liberating up the principle processors for different work and enabling shocking parallelism.
- C/C++ Pico Programmers: Whereas this text makes use of Rust, PIO programming is — for good and unhealthy — almost equivalent throughout all languages. For those who perceive it right here, you’ll be well-equipped to use it in C/C++.
- MicroPython Pico Programmers: Chances are you’ll want to learn the MicroPython version of this article.
- PIO Programmers: The journey via 9 Wats will not be as entertaining as JavaScript’s quirks (fortunately), however it’ll make clear the peculiarities of PIO programming. For those who’ve ever discovered PIO programming complicated, this text ought to reassure you that the issue isn’t (essentially) you — it’s partly PIO itself. Most significantly, understanding these Wats will make writing PIO code easier and more practical.
Lastly, this text isn’t about “fixing” PIO programming. PIO excels at its main function: effectively and flexibly dealing with customized peripheral interfaces. Its design is purposeful and well-suited to its objectives. As an alternative, this text focuses on understanding PIO programming and its quirks — beginning with a bonus Wat.
Regardless of their title, the eight “PIO state machines” within the Raspberry Pi Pico are usually not state machines in the formal computer science sense. As an alternative, they’re tiny programmable processors with their very own assembly-like instruction set, able to looping, branching, and conditional operations. In actuality, they’re nearer to Harvard architecture machines or, like most sensible computer systems, von Neumann machines.
Every state machine processes one instruction per clock cycle. The $4 Pico 1 runs at 125 million cycles per second, whereas the $5 Pico 2 affords a sooner 150 million cycles per second. Every instruction performs a easy operation, reminiscent of “transfer a worth” or “soar to a label”.
With that bonus Wat out of the way in which, let’s transfer to our first foremost Wat.
In PIO programming, a register is a small, quick storage location that acts like a variable for the state machine. You may dream of an abundance of variables to carry your counters, delays, and non permanent values, however the actuality is brutal: you solely get two general-purpose registers, x and y. It is like The Starvation Video games, the place irrespective of what number of tributes enter the sector, solely Katniss and Peeta emerge as victors. You’re pressured to winnow down your wants to suit inside these two registers, ruthlessly deciding what to prioritize and what to sacrifice. Additionally, just like the Starvation Video games, we are able to typically bend the foundations.
Let’s begin with a problem: create a backup beeper — 1000 Hz for ½ second, silence for ½ second, repeat. The outcome? “Beep Beep Beep…”
We want 5 variables:
half_period:The variety of clock cycles to carry the voltage excessive after which low to create a 1000 Hz tone. That is 125,000,000 / 1000 / 2 = 62,500 cycles excessive and 62, 500 cycles low.
y: Loop counter from 0 tohalf_periodto create a delay.period_count: The variety of repeated durations wanted to fill ½ second of time. 125,000,000 × 0.5 / (62,500 × 2) = 500.x: Loop counter from 0 toperiod_countto fill ½ second of time.silence_cycles: The variety of clock cycles for ½ second of silence. 125,000,000 × 0.5 = 62,500,000.
We would like 5 registers however can solely have two, so let the video games start! Might the chances be ever in your favor.
First, we are able to eradicate silence_cycles as a result of it may be derived as half_period × period_count × 2. Whereas PIO doesn’t assist multiplication, it does assist loops. By nesting two loops—the place the interior loop delays for two clock cycles—we are able to create a delay of 62,500,000 clock cycles.
One variable down, however how can we eradicate two extra? Happily, we don’t need to. Whereas PIO solely supplies two general-purpose registers, x and y, it additionally consists of two special-purpose registers: osr (output shift register) and isr (enter shift register).
The PIO code that we’ll see in a second implements the backup beeper. Right here’s the way it works:
Initialization:
- The
pull blockinstruction reads the half interval of the tone (62,500 clock cycles) from a buffer and locations the worth intoosr. - The worth is then copied to
isrfor later use. - The second
pull blockreads the interval depend (500 repeats) from the buffer and locations the worth inosr, the place we depart it.
Beep Loops:
- The
mov x, osrinstruction copies the interval depend into thexregister, which serves because the outer loop counter. - For the interior loops,
mov y, isrrepeatedly copies the half interval intoyto create delays for the excessive and low states of the tone.
Silence Loops:
- The silence loops mirror the construction of the beep loops however don’t set any pins, so that they act solely as a delay.
Wrap and Steady Execution:
- The
.wrap_targetand.wrapdirectives outline the principle loop of the state machine. - After ending each the beep and silence loops, the state machine jumps again close to the beginning of this system, repeating the sequence indefinitely.
With this define in thoughts, right here’s the PIO meeting code for producing the backup beeper sign.
.program backup; Learn preliminary configuration
pull block ; Learn the half interval of the beep sound
mov isr, osr ; Retailer the half interval in ISR
pull block ; Learn the period_count
.wrap_target ; Begin of the principle loop
; Generate the beep sound
mov x, osr ; Load period_count into X
beep_loop:
set pins, 1 ; Set the buzzer to excessive voltage (begin the tone)
mov y, isr ; Load the half interval into Y
beep_high_delay:
jmp y--, beep_high_delay ; Delay for the half interval
set pins, 0 ; Set the buzzer to low voltage (finish the tone)
mov y, isr ; Load the half interval into Y
beep_low_delay:
jmp y--, beep_low_delay ; Delay for the low length
jmp x--, beep_loop ; Repeat the beep loop
; Silence between beeps
mov x, osr ; Load the interval depend into X for outer loop
silence_loop:
mov y, isr ; Load the half interval into Y for interior loop
silence_delay:
jmp y--, silence_delay [1] ; Delay for 2 clock cycles (jmp + 1 additional)
jmp x--, silence_loop ; Repeat the silence loop
.wrap ; Finish of the principle loop, jumps again to wrap_target
Right here’s the core Rust code to configure and run the PIO program for the backup beeper. It makes use of the Embassy framework for embedded functions. The operate initializes the state machine, calculates the timing values (half_period and period_count), and sends them to the PIO. It then performs the beeping sequence for five seconds earlier than getting into an countless loop. The total supply file and project can be found on GitHub.
async fn inner_main(_spawner: Spawner) -> Consequence {
data!("Good day, back_up!");
let {hardware}: {Hardware}<'_> = {Hardware}::default();
let mut pio0 = {hardware}.pio0;
let state_machine_frequency = embassy_rp::clocks::clk_sys_freq();
let mut back_up_state_machine = pio0.sm0;
let buzzer_pio = pio0.frequent.make_pio_pin({hardware}.buzzer);
back_up_state_machine.set_pin_dirs(Path::Out, &[&buzzer_pio]);
back_up_state_machine.set_config(&{
let mut config = Config::default();
config.set_set_pins(&[&buzzer_pio]); // For set instruction
let program_with_defines = pio_file!("examples/backup.pio");
let program = pio0.frequent.load_program(&program_with_defines.program);
config.use_program(&program, &[]);
config
});back_up_state_machine.set_enable(true);
let half_period = state_machine_frequency / 1000 / 2;
let period_count = state_machine_frequency / (half_period * 2) / 2;
data!(
"Half interval: {}, Interval depend: {}",
half_period, period_count
);
back_up_state_machine.tx().wait_push(half_period).await;
back_up_state_machine.tx().wait_push(period_count).await;
Timer::after(Period::from_millis(5000)).await;
data!("Disabling back_up_state_machine");
back_up_state_machine.set_enable(false);
// run ceaselessly
loop {
Timer::after(Period::from_secs(3_153_600_000)).await; // 100 years
}
}
Right here’s what occurs whenever you run this system:
Apart 1: Working this your self
The best — however usually irritating — technique to run Rust code on the Pico is to cross-compile it in your desktop and manually copy over the ensuing information. A a lot better method is to spend money on a $12 Raspberry Pi Debug Probe and arrange probe-rs in your desktop. With this setup, you need to usecargo runto mechanically compile in your desktop, copy to your Pico, after which begin your code working. Even higher, your Pico code can usedata!statements to ship messages again to your desktop, and you’ll carry out interactive breakpoint debugging. For setup directions, go to the probe-rs web site.To listen to sound, I related a passive buzzer, a resistor, and a transistor to the Pico. For detailed wiring diagrams and a components checklist, take a look at the passive buzzer instructions within the SunFounder’s Kepler Equipment.
Apart 2: In case your solely purpose is to generate tones with the Pico, PIO isn’t needed. MicroPython is quick sufficient to toggle pins directly, or you need to use the Pico’s built-in pulse width modulation (PWM) feature.
Various Endings to the Register Starvation Video games
We used 4 registers — two normal and two particular — to resolve the problem. If this resolution feels lower than satisfying, listed below are different approaches to think about:
Use Constants: Why make half_period, period_count, and silence_cycles variables in any respect? Hardcoding the constants “62,500,” “500,” and “62,500,000” might simplify the design. Nevertheless, PIO constants have limitations, which we’ll discover in Wat 5.
Pack Bits: Registers maintain 32 bits. Do we actually want two registers (2×32=64 bits) to retailer half_period and period_count? No. Storing 62,500 solely requires 16 bits, and 500 requires 9 bits. We might pack these right into a single register and use the out instruction to shift values into x and y. This method would release both osr or isr for different duties, however solely one after the other—the opposite register should maintain the packed worth.
Sluggish Movement: In Rust with the Embassy framework, you’ll be able to configure a PIO state machine to run at a slower frequency by setting its clock_divider. This permits the state machine to run as gradual as ~1907 Hz. Working the state machine at a slower velocity implies that values like half_period might be smaller, doubtlessly as small as 2. Small values are simpler to hardcode as constants and extra compactly bit-packed into registers.
A Blissful Ending to the Register Starvation Video games
The Register Starvation Video games demanded strategic sacrifices and artistic workarounds, however we emerged victorious by leveraging PIO’s particular registers and intelligent looping constructions. If the stakes had been increased, different strategies might have helped us adapt and survive.
However victory in a single area doesn’t imply the challenges are over. Within the subsequent Wat, we face a brand new trial: PIO’s strict 32-instruction restrict.
Congratulations! You’ve bought a visit world wide for simply $4. The catch? All of your belongings should match right into a tiny carry-on suitcase. Likewise, PIO applications can help you create unimaginable performance, however each PIO program is proscribed to only 32 directions.
Wat! Solely 32 directions? That’s not a lot area to pack all the things you want! However with intelligent planning, you’ll be able to normally make it work.
- No PIO program might be longer than 32 directions.
- The
wrap_targetandwrapdirectives don’t depend. - Labels don’t depend.
- A Pico 1 consists of eight state machines, organized into two blocks of 4. A Pico 2 consists of twelve state machines, organized into three blocks of 4. Every block shares 32 instruction slots. So, as a result of all 4 state machines in a block draw from the identical 32-instruction pool, if one machine’s program makes use of all 32 slots, there’s no area left for the opposite three.
In case your thought doesn’t match within the PIO instruction slots, these packing tips might assist. (Disclaimer: I haven’t tried all of those myself.)
- Swap PIO Packages on the Fly:
As an alternative of making an attempt to cram all the things into one program, take into account swapping out applications mid-flight. Load solely what you want, whenever you want it. - Share Packages Throughout State Machines:
A number of state machines can run the identical program on the similar time. Every state machine could make the shared program behave otherwise primarily based on an enter worth. - Use Rust/Embassy’s
exec_instrCommand:
Save area by offloading directions to Rust. For instance, you’ll be able to execute initialization steps earlier than enabling the state machine:
let half_period = state_machine_frequency / 1000 / 2;
back_up_state_machine.tx().push(half_period); // Utilizing non-blocking push since FIFO is empty
let pull_block = pio_asm!("pull block").program.code[0];
unsafe {
back_up_state_machine.exec_instr(pull_block);
}
- Use PIO’s
execinstructions:
Inside your state machine, you’ll be able to dynamically execute directions utilizing PIO’sexecmechanism. For instance, you’ll be able to execute an instruction worth saved inosrwithout exec. Alternatively, you need to usemov exec, xormov exec, yto execute directions immediately from these registers. - Offload to the Principal Processors:
If all else fails, transfer extra of your program to the Pico’s bigger twin processors — consider this as transport your additional baggage to your vacation spot individually. The Pico SDK (part 3.1.4) calls this “bit banging”.
Along with your luggage now packed, let’s be a part of Dr. Dolittle’s seek for a fabled creature.
Two readers identified an vital PIO Wat that I missed — so right here’s a bonus! When programming PIO, you’ll discover one thing peculiar:
- The PIO
pullinstruction receives values from TX FIFO (transmit buffer) and inputs them into the output shift register (osr). So, it inputs into output and transmits from obtain. - Likewise, the PIO
pushinstruction outputs values from the enter shift register (isr) and transmits them to the RX FIFO (obtain buffer). So, it outputs from enter and receives from transmit.
Wat!? Just like the two-headed Pushmi-Pullyu from the Dr. Dolittle tales, one thing appears backwards. But it surely begins to make sense whenever you notice PIO names most issues from the host’s perspective (MicroPython, Rust, C/C++), not the viewpoint of the PIO program.
This desk summarizes the directions, registers, and buffer names. (“FIFO” stands for first-in-first-out.)
With the Pushmi-Pullyu in hand, we subsequent transfer to the scene of a thriller.
In Wat 1, we programmed our audio {hardware} as a backup beeper. However that’s not what we’d like for our musical instrument. As an alternative, we would like a PIO program that performs a given tone indefinitely — till it’s advised to play a brand new one. This system must also wait silently when given a particular “relaxation” tone.
Resting till a brand new tone is offered is straightforward to program with pull block—we’ll discover the small print under. Taking part in a tone at a particular frequency can also be simple, constructing on the work we did in Wat 1.
However how can we verify for a brand new tone whereas persevering with to play the present one? The reply lies in utilizing “noblock” as a substitute of “block” in pull noblock. Now, if there’s a brand new worth, it will likely be loaded into osr, permitting this system to replace seamlessly.
Right here’s the place the thriller begins: what occurs to osr if pull noblock is known as and there’s no new worth?
I assumed it might maintain its earlier worth. Flawed! Perhaps it will get reset to 0? Flawed once more! The shocking reality: it will get the worth of x. Why? (No, not y — x.) As a result of the Pico SDK says so. Particularly, part 3.4.9.2 explains:
A nonblocking PULL on an empty FIFO has the identical impact as MOV OSR, X.
Figuring out how pull noblock works is vital, however there’s an even bigger lesson right here. Deal with the Pico SDK documentation just like the again of a thriller novel. Don’t attempt to clear up all the things by yourself—cheat! Skip to the “who achieved it” part, and in part 3.4, learn the effective particulars for every command you employ. Studying only a few paragraphs can prevent hours of confusion.
Apart: When even the SDK documentation feels unclear, flip to the RP2040 (Pico 1) and RP2350 (Pico 2) datasheets. These encyclopedias — 600 and 1,300 pages respectively — are like all-powerful narrators: they supply the bottom reality.
With this in thoughts, let’s have a look at a sensible instance. Beneath is the PIO program for enjoying tones and rests repeatedly. It makes use of pull block to attend for enter throughout a relaxation and pull noblock to verify for updates whereas taking part in a tone.
.program sound; Relaxation till a brand new tone is obtained.
resting:
pull block ; Look forward to a brand new delay worth
mov x, osr ; Copy delay into X
jmp !x resting ; If delay is zero, maintain resting
; Play the tone till a brand new delay is obtained.
.wrap_target ; Begin of the principle loop
set pins, 1 ; Set the buzzer excessive voltage.
high_voltage_loop:
jmp x-- high_voltage_loop ; Delay
set pins, 0 ; Set the buzzer low voltage.
mov x, osr ; Load the half interval into X.
low_voltage_loop:
jmp x-- low_voltage_loop ; Delay
; Learn any new delay worth. If none, maintain the present delay.
mov x, osr ; set x, the default worth for "pull(noblock)"
pull noblock ; Learn a brand new delay worth or use the default.
; If the brand new delay is zero, relaxation. In any other case, proceed taking part in the tone.
mov x, osr ; Copy the delay into X.
jmp !x resting ; If X is zero, relaxation.
.wrap ; Proceed taking part in the sound.
We’ll ultimately use this PIO program in our theremin-like musical instrument. For now, let’s see the PIO program in motion by taking part in a well-recognized melody. This demo makes use of “Twinkle, Twinkle, Little Star” to point out how one can management a melody by feeding frequencies and durations to the state machine. With simply this code (full file and project), you can also make the Pico sing!
const TWINKLE_TWINKLE: [(u32, u64, &str); 16] = [
// Bar 1
(262, 400, "Twin-"), // C
(262, 400, "-kle"), // C
(392, 400, "twin-"), // G
(392, 400, "-kle"), // G
(440, 400, "lit-"), // A
(440, 400, "-tle"), // A
(392, 800, "star"), // G
(0, 400, ""), // rest
// Bar 2
(349, 400, "How"), // F
(349, 400, "I"), // F
(330, 400, "won-"), // E
(330, 400, "-der"), // E
(294, 400, "what"), // D
(294, 400, "you"), // D
(262, 800, "are"), // C
(0, 400, ""), // rest
];async fn inner_main(_spawner: Spawner) -> Consequence {
data!("Good day, sound!");
let {hardware}: {Hardware}<'_> = {Hardware}::default();
let mut pio0 = {hardware}.pio0;
let state_machine_frequency = embassy_rp::clocks::clk_sys_freq();
let mut sound_state_machine = pio0.sm0;
let buzzer_pio = pio0.frequent.make_pio_pin({hardware}.buzzer);
sound_state_machine.set_pin_dirs(Path::Out, &[&buzzer_pio]);
sound_state_machine.set_config(&{
let mut config = Config::default();
config.set_set_pins(&[&buzzer_pio]); // For set instruction
let program_with_defines = pio_file!("examples/sound.pio");
let program = pio0.frequent.load_program(&program_with_defines.program);
config.use_program(&program, &[]);
config
});
sound_state_machine.set_enable(true);
for (frequency, ms, lyrics) in TWINKLE_TWINKLE.iter() {
if *frequency > 0 {
let half_period = state_machine_frequency / frequency / 2;
data!("{} -- Frequency: {}", lyrics, frequency);
// Ship the half interval to the PIO state machine
sound_state_machine.tx().wait_push(half_period).await;
Timer::after(Period::from_millis(*ms)).await; // Wait because the tone performs
sound_state_machine.tx().wait_push(0).await; // Cease the tone
Timer::after(Period::from_millis(50)).await; // Give a brief pause between notes
} else {
sound_state_machine.tx().wait_push(0).await; // Play a silent rust
Timer::after(Period::from_millis(*ms + 50)).await; // Look forward to the remainder length + a brief pause
}
}
data!("Disabling sound_state_machine");
sound_state_machine.set_enable(false);
// run ceaselessly
loop {
Timer::after(Period::from_secs(3_153_600_000)).await; // 100 years
}
}
Right here’s what occurs whenever you run this system:
We’ve solved one thriller, however there’s at all times one other problem lurking across the nook. In Wat 4, we’ll discover what occurs when your good {hardware} comes with a catch — it’s additionally very low-cost.
With sound working, we flip subsequent to measuring the gap to the musician’s hand utilizing the HC-SR04+ ultrasonic vary finder. This small however highly effective gadget is accessible for lower than two {dollars}.
HC-SR04+ Vary Finder (Pen added for scale.)
This little peripheral took me on an emotional curler coaster of “Wats!?”:
- Up: Amazingly, this $2 vary finder consists of its personal microcontroller, making it smarter and simpler to make use of.
- Down: Frustratingly, that very same “good” conduct is unintuitive.
- Up: Conveniently, the Pico can provide peripherals with both 3.3V or 5V energy.
- Down: Unpredictably, many vary finders are unreliable — or fail outright — at 3.3V, they usually can injury your Pico at 5V.
- Up: Fortunately, each broken vary finders and Picos are cheap to switch, and a dual-voltage model of the vary finder solved my issues.
Particulars
I initially assumed the vary finder would set the Echo pin excessive when the echo returned. I used to be fallacious.
As an alternative, the vary finder emits a sample of 8 ultrasonic pulses at 40 kHz (consider it as a backup beeper for canines). Instantly after, it units Echo excessive. The Pico ought to then begin measuring the time till Echo goes low, which indicators that the sensor detected the sample — or that it timed out.
As for voltage, the documentation specifies the vary finder operates at 5V. It appeared to work at 3.3V — till it didn’t. Across the similar time, whereas my Pico saved working with Rust (through the Debug Probe and probe-rs), it stopped working with any of the MicroPython IDEs, which depend on a particular USB protocol.
So, at this level each the Pico and the vary finder have been broken.
After experimenting with numerous cables, USB drivers, programming languages, and even an older 5V-only vary finder, I lastly resolved the problem by:
Wat 4: Classes Realized
Because the curler coaster return to the station, I discovered two key classes. First, due to microcontrollers, even easy {hardware} can behave in non-intuitive ways in which require cautious studying of the documentation. Second, whereas this {hardware} is intelligent, it’s additionally cheap — and which means it’s vulnerable to failure. When it fails, take a deep breath, keep in mind it’s only some {dollars}, and substitute it.
{Hardware} quirks, nonetheless, are solely a part of the story. In Wat 5, in Half 2, we’ll shift our focus again to software program: the PIO programming language itself. We’ll uncover a conduct so surprising, it’d depart you questioning all the things you thought you knew about constants.
