Codelab#

pw_async2: Cooperative async tasks for embedded

Welcome to the pw_async2 codelab! This codelab provides a hands-on introduction to Pigweed’s cooperative asynchronous framework.

What you’ll learn#

By the end of this codelab, you’ll understand all of the core pw_async2 primitives and will have experience implementing common pw_async2 patterns, such as:

  • Implementing a Task as a state machine

  • Calling async functions and managing state across suspension points

  • Writing your own pendable functions that use a Waker to handle external events

  • Using InlineAsyncQueue for basic inter-task communication

  • Using TimeProvider and Select to implement timeouts

To get hands-on experience with these primitives and patterns, you’ll be building a simple, simulated vending machine application. Your vending machine will asynchronously wait for user input events like coin insertions and keypad presses before dispensing items.

Tip

We encourage you to figure out solutions on your own, but we’ll provide lots of help along the way if anything is unclear:

  • Click the Hint dropdown at the end of an instruction in order to see a line-by-line breakdown of the code changes that you need to make at that point.

  • At the end of each step, the Checkpoint section provides a complete working example of the code at that point.

Your code doesn’t have to look exactly the same as the hints and checkpoints that we provide. They are only there to help you get back on track if you get lost.

Getting help#

If you get stuck or have any questions about pw_async2, you’re welcome to message us on our Discord or file an issue. Or, drop into our monthly community meeting, Pigweed Live:

Pigweed Live

Our next Pigweed Live is Mon Oct 20, 2025 1PM (PDT). Please join us to discuss what’s new in Pigweed and anything else Pigweed-related that’s on your mind. Join our mailing list to receive an invite to the next meeting.

Setup#

The code for this codelab lives in the Upstream Pigweed repository. If you don’t have the upstream Pigweed repo set up on your development machine, do so now:

  1. Install developer tools. The important thing is to set up bazelisk, which is the core tool for interacting with the repo’s Bazel-based build system. You’ll use bazelisk to build and run your vending machine app.

  2. Clone the repo.

  3. cd into the root of the Pigweed repo:

    cd pigweed

    Note

    For the remainder of the codelab, we’ll assume that your current working directory is the root of the upstream Pigweed repo.

  4. We’ve already set up the vending machine app boilerplate for you. Run the starting code now to verify that your setup is working correctly:

    bazelisk run //pw_async2/codelab

    You should see some logs from Bazel about the build followed by these informational logs from the app:

    INF  ==========================================
INF  Command line HW simulation notes:
INF    Type 'q' (then enter) to quit.
INF    Type 'd' to show the dispatcher state.
INF    Type 'c' to insert a coin.
INF    Type 'i' to signal an item dropped.
INF    Type '1'..'4' to press a keypad key.
INF  ==========================================

  5. Inspect the codelab directory:

    ls pw_async2/codelab

    There are a lot of files and directories here, but throughout the codelab, you only need to edit these files:

Next steps#

Proceed to 1. Run a task to start learning pw_async2 basics.

On this page