Multitasking: when is await _required_?

[dmusican]

Some students and I spent some time this morning trying to diagnose this bug, which I've isolated below:

eyes = UltrasonicSensor(Port.B)
print("Distance works: ", eyes.distance())

async def foo():
    print("Distance does not work:", eyes.distance())  

async def main():
    await multitask(foo())

run_task(main())

This results in the following output, in which the second call to eyes.distance() does not work as expected.

Distance works:  206
Distance does not work: <wait>

The fix is to put await in front of eyes.distance() inside the function foo. Clearly including await is a best practice and worth doing because it allows the opportunity for other coroutines to kick in, but I didn't realize it was required. This was the first example I found where things didn't work as expected when await was left out. When is it required? It's not the case that it is always required when await is a possibility; for example, hub.speaker.beep() works fine inside a coroutine, even without await.

[dlech]

If the documentation says await before the function, then await is needed when multitasking.

There are some functions that may seem to work without await, but what is really happening is that they are running in the background while the program continues with the next lines. So if you did two beeps in a row, it probably wouldn't work as expected without await.

[dmusican]

That makes sense. Thank you!

[FLL-Team-24277]

Coming in from the cheap seats... I know about multitasking from my computer science classes I took MANY (too many) years ago, but I don't know anything about "await" in python. I'm going to read up on it. But I do know that many of the pybricks commands have an optional "wait=True" or "wait=False" parameter. We used it a lot last year, most commonly to have a medium motor do something while the robot is driving. It seemed to work perfectly. Is there some advantage that we may gain from using await? This sort of feels like a "if it ain't broke, don't fix it" situation.

[laurensvalk]

Here is a visual example of multitasking. Let's say you want to operate a gripper and a hatch mechanism at the same time:

This translates to:

from pybricks.hubs import PrimeHub
from pybricks.parameters import Direction, Port, Stop
from pybricks.pupdevices import Motor
from pybricks.tools import multitask, run_task, wait

# Set up all devices.
hub = PrimeHub()
gripper = Motor(Port.A, Direction.CLOCKWISE)
hatch = Motor(Port.B, Direction.CLOCKWISE)

async def main():
    for count in range(4):
        await multitask(gripper.run_angle(500, 90), hatch.run_angle(-200, 45))
        await hub.speaker.beep(500, 100)

run_task(main())

Here, it waits until both the hatch and the gripper motion are done and then it plays a sound. In this particular case, you could achieve that with the older wait=False method like this:

gripper.run_angle(500, 90, wait=False)
hatch.run_angle(-200, 45, wait=False)
while not gripper.done() or not hatch.done()
    wait(10)
hub.speaker.beep(500, 100)

If this is enough for what you need, this is perfectly fine.

But now consider this example, which remains equally simple when multitasking. But it would get much more complicated to make with the wait=False method:

And yet, if you look past the additional await keyword, this code snippet looks almost like any other chronological function. But they can run in parallel.

from pybricks.hubs import PrimeHub
from pybricks.parameters import Color, Direction, Port, Stop
from pybricks.pupdevices import Motor
from pybricks.tools import multitask, run_task, wait

# Set up all devices.
hub = PrimeHub()
gripper = Motor(Port.A, Direction.CLOCKWISE)
hatch = Motor(Port.B, Direction.CLOCKWISE)

async def gripper_task():
    await gripper.run_angle(500, 90)
    await wait(1000)
    await gripper.run_angle(500, 90)

async def hatch_task():
    await hatch.run_angle(-200, 45)
    hub.light.on(Color.RED)
    await wait(100)

async def main():
    for count in range(4):
        await multitask(gripper_task(), hatch_task())
        await hub.speaker.beep(500, 100)


run_task(main())

---

The default (without async/await) is much easier for beginners. When we added it, we made it strictly optional for more advanced users. Any existing code continues to work as it did.

Note that the current official LEGO SPIKE app requires you to use async/await from the very start, which we don't think is a suitable approach.

[dmusican]

This detailed example above from @laurensvalk is great. As another example: in my summer program for high school students, I teach a four-morning class in robotics principles. One of my goals is to teach them subsumption architecture. A typical way to think about subsumption is that there are multiple sub-behaviors going on as parallel processes, and higher-level behaviors suppress lower-level behaviors as necessary. While wait=False works in some isolated cases such as with the motors, it doesn't generalize to this entire architecture. I had given up teaching subsumption when I switched to pybricks before async/await was there, but now that it's in, I brought subsumption back to my curriculum for this summer.

Here's a proof-of-concept example I share with my students to show three bottom-level sub-behaviors (count, beep, and chirp), with a higher-level behavior enabling or disabling lower level ones. This specific program could unquestionably be implemented in a simpler way without using subsumption, but it's just an example to show the concept before asking them to move on to a more complex example where subsumption makes more sense.

from pybricks.hubs import PrimeHub
from pybricks.tools import wait, multitask, run_task
from pybricks.parameters import Button

async def doCount():
    global countValue
    while True:
        if counting:
            hub.display.number(countValue)
            countValue = (countValue+1) % 100
            await wait(1000)
        else:
            await wait(1)

async def doBeep():
    while True:
        if beeping:
            await hub.speaker.beep()
            await wait(200)
        else:
            await wait(1)

async def doChirp():
    while True:
        if chirping:
            await hub.speaker.beep(800)
            await wait(800)
        else:
            await wait(1)

async def overseeBehaviors():
    global counting, beeping, chirping
    while True:
        pressed = hub.buttons.pressed()
        beeping = Button.LEFT in pressed
        chirping = Button.RIGHT in pressed
        counting = not (beeping or chirping)
        await wait(1)

hub = PrimeHub()
hub.speaker.volume(30)

countValue = 0
counting = True
beeping = False
chirping = False

async def main():
    await multitask(doCount(), doBeep(), doChirp(), overseeBehaviors())

run_task(main())

One fairly simple specific example is I ask them to make a robot that drives forward quietly, but plays a "song" (i.e., a sequence of notes) while it's moving when the color sensor detects white paper underneath. If they implement that in a purely naive fashion, they use a sequence of beep calls to play the song, and then check to see what the sensor is showing when the beeps are done to see whether or not they should repeat the sequence. The problem with that implementation is that they only check when the beeps are done, which means the bot reacts poorly; it won't stop playing the sequence of notes mid-sequence if the bot rolls off the paper. They could doing it by doing a check after every beep, but that's messy. Instead, they can have two parallel coroutines; one manages the color sensor checking for paper/detection, and either suppresses or enables the sound-playing behavior (via setting a global variable).

[laurensvalk]

Thanks for your additional example @dmusican !

The problem with that implementation is that they only check when the beeps are done, which means the bot reacts poorly; it won't stop playing the sequence of notes mid-sequence if the bot rolls off the paper.

Just to make the introduction above complete: Another interesting parameter is the race setting. You can multitask until all tasks are done, or until the quickest task is done.

This lets you do various things quite trivially that would otherwise require global mutex-like variables:

The code is similar as before, but the multitask now reads:

await multitask(square_task(), sensor_wait_task(), race=True)

[FLL-Team-24277]

This is all very interesting. Thanks!!