How does the stalled() function work in Pybricks-MicroPython - micropython

Question

MicroPython 2.0 beta 5
Trying to understand how the stalled() function on the motor works. I run a motor at dc of 100, and hold the wheel so that it cannot move.
But the stalled function doesn't fire, indeed whatever I do I don't seem able to get it to return True?
I tried with less power, but still not able to get anything out of this function.
#!/usr/bin/env pybricks-micropython
from pybricks import ev3brick as brick
from pybricks.ev3devices import Motor
from pybricks.parameters import Port, Stop
left_motor = Motor(Port.B)
speed = 800
# option 1
left_motor.dc(100)
# option 2
#left_motor.run_until_stalled(speed, Stop.HOLD, 100)
while True:
if left_motor.stalled():
print("stalled")
If I use option 1: the motor runs, I hold it until it stops, nothing reported. I let go and off it goes again.
If I use option 2: the motor runs, I hold it, it stops. But at no point do I see a report saying it stalled.

Answer 1

A motor is stalled when it can't reach its target speed or angle, despite applying the maximum duty cycle.
Your example can be adapted like this:
#!/usr/bin/env pybricks-micropython
from pybricks.ev3devices import Motor
from pybricks.parameters import Port
from pybricks.tools import wait
# Initialize the motor
left_motor = Motor(Port.B)
# Start running the motor at 500 deg/s
left_motor.run(500)
# Do nothing until we are stalled
while not left_motor.stalled():
wait(10)
# Stop the motor
left_motor.stop()
This example is equivalent to the one-liner left_motor.run_until_stalled(500). The manual approach can be useful if you want to extend it to multiple motors.
The dc() method in the question does not set a target speed or angle; it sets the duty cycle directly, so there is no stall information.
Note: the left_motor.stalled() method is instead accessible through left_motor.control.stalled() as of Pybricks version Pybricks 2.0. It is in public beta only as of March 2020, so I'm not sure the version reported in the original post in August 2019 is correct.