Motor & Encoder Limits · Code Explainer

The Big Idea

● Smart Mode

Closed-Loop Program

The bot reads its own wheel sensors to check its actual speed. If it's going too slow, it gives the motors more power. If it's going too fast, it pulls back. The result: a steady, predictable distance every time.

● Raw Mode

Open-Loop Program

The bot sends a fixed voltage to the motors and never checks whether it's actually moving at the right speed. Friction, low battery, and startup delay all affect the distance — and nothing corrects for them.

⏱️

Both programs are locked at 3000 milliseconds (3 seconds). Keeping time the same is what makes this test fair — any difference in distance is caused by the program, not the clock.

Smart Mode — Closed-Loop Program

This program uses a block called cruise control. That block turns on the bot's speed-correction system. Tiny sensors on each wheel count how fast the wheel is spinning. The controller compares that count to your target speed, then adjusts the motor power to close the gap — dozens of times per second.

Speed Calculator — How SPEED Becomes cm/s

targetSpeed = 20 + ((SPEED − 1) × (50 − 20)) / (20 − 1)

Your SPEED stat is a number from 1 to 20. This formula stretches that range across the bot's real speed limits (20–50 cm/s).
SPEED 1 → 20 cm/s | SPEED 6 → 27.9 cm/s | SPEED 20 → 50 cm/s

⚠️

The sensor system has a hard floor at 20 cm/s. Below that speed, the wheel sensors can't count fast enough to keep up. The correction system loses track and the bot either stalls or moves unpredictably. That's a hardware limit — you can't fix it in code.

Starting Values — Set These Before You Download

Loading blocks…

let targetSpeed = 0
let minSpeed = 20
let maxSpeed = 50
let SPEED = 6
targetSpeed = minSpeed + ((SPEED - 1) * (maxSpeed - minSpeed)) / (20 - 1)

These four variables run at startup, before you press anything.

minSpeed (20) and maxSpeed (50) are the physical limits of the speed-correction system — don't change them.

SPEED (6) is your stat. Change this number (1–20) to match your bot's Speed stat before you download the program.

The last line runs the formula and stores the result as targetSpeed, which Button B uses.

Button A — Full Speed (50 cm/s)

Loading blocks…

let maxSpeed = 50
input.onButtonPressed(Button.A, function () {
    CutebotPro.cruiseControl(maxSpeed, maxSpeed, CutebotProSpeedUnits.Cms)
    basic.pause(3000)
    CutebotPro.stopImmediately(CutebotProMotors.ALL)
})

Cruise control turns on the speed-correction system and tells it to hold 50 cm/s on both wheels.

Pause 3000 keeps the program waiting for exactly 3 seconds. The correction system keeps working the whole time — it never takes a break.

Stop immediately cuts both motors at once when the 3 seconds are up.

Expected distance: ~143 cm

Button B — Your SPEED Setting (27.9 cm/s at SPEED 6)

Loading blocks…

let targetSpeed = 0
input.onButtonPressed(Button.B, function () {
    CutebotPro.cruiseControl(targetSpeed, targetSpeed, CutebotProSpeedUnits.Cms)
    basic.pause(3000)
    CutebotPro.stopImmediately(CutebotProMotors.ALL)
})

Same structure as Button A — but this time it uses targetSpeed, which was calculated from your SPEED stat when the program started.

At SPEED 6, targetSpeed = 27.9 cm/s. The speed-correction system holds that value for the full 3 seconds.

Expected distance: ~77 cm

Button A

50 cm/s · Max Speed

The speed-correction system holds 50 cm/s the entire 3 seconds. The distance is consistent run after run because the system corrects for friction and battery changes automatically.

Button B

27.9 cm/s · Your Stat

The speed-correction system tracks your SPEED setting. It works well above 20 cm/s. Below that floor, the wheel sensors can't read fast enough and the bot stalls.

Raw Mode — Open-Loop Program

This program uses a block called PWM cruise control. PWM stands for Pulse-Width Modulation — it's how the chip controls voltage to the motors. Think of it like a volume dial: 100% means full power, 30% means low power. The wheel sensors are completely ignored. Whatever physics happen, they happen uncorrected.

Button A — 100% Power (Full Voltage)

Loading blocks…

input.onButtonPressed(Button.A, function () {
    CutebotPro.pwmCruiseControl(100, 100)
    basic.pause(3000)
    CutebotPro.stopImmediately(CutebotProMotors.ALL)
})

PWM cruise control at 100 sends full battery voltage to both motors. No speed target. No corrections. The bot goes as fast as the battery will allow.

This is the fastest possible open-loop run — but run it ten times and you'll notice the distance slowly shrinks as the battery drains. That's the hardware showing its limits.

Expected distance: Maximum — drops as battery dies

Button B — 30% Power (Low Voltage)

Loading blocks…

input.onButtonPressed(Button.B, function () {
    CutebotPro.pwmCruiseControl(30, 30)
    basic.pause(3000)
    CutebotPro.stopImmediately(CutebotProMotors.ALL)
})

PWM cruise control at 30 sends only 30% of battery voltage to the motors. At this low level, the gears inside the motor resist moving from a dead stop — so the bot hesitates for a moment before it rolls.

That startup delay eats into your 3-second window. You'll find the 30% distance is more than half the 100% distance — the ratio doesn't scale the way you'd expect.

Expected distance: More than half of the 100% run

Button A

100% PWM · Watch It Drop

Full power, no corrections. Distance is the highest you'll see — but it's not guaranteed. Run it twice and measure whether the second run was shorter. If it is, that's battery drain.

Button B

30% PWM · Startup Lag

Low voltage fights gear friction at startup. The motors waste part of the 3-second window just getting moving. No correction system can help because this program doesn't use one.

🔋

Battery state changes your distance. Open-loop sends a percentage of whatever voltage is left in the battery. A full battery at 30% and a half-dead battery at 30% will travel different distances. The Smart Mode program doesn't have this problem because it corrects for voltage changes automatically.

Side-by-Side Results

Program	Button	Input	What the Bot Does	Expected Distance
Smart Mode	A	50 cm/s	Wheel sensors check speed constantly and adjust power to hold 50 cm/s.	~143 cm
Smart Mode	B	27.9 cm/s	Holds your SPEED stat speed closely. Stalls if target drops below 20 cm/s.	~77 cm
Raw Mode	A	100% PWM	Full battery voltage to motors. No corrections. Distance shrinks as battery drains.	Max — drops each run
Raw Mode	B	30% PWM	Low voltage + gear friction = startup delay. The 3-second window starts before the bot does.	More than ½ of 100% run

📐

Pay attention to the ratio, not just the numbers. In Smart Mode, the 50 cm/s run should be about 1.8× the 27.9 cm/s run. In Raw Mode, the 100% run will not be 3.3× the 30% run — startup lag breaks the ratio.

Why This Happens

⚙️

Gear Friction at Low Power

The motor spins through a set of gears before reaching the wheel. At low PWM, the voltage isn't strong enough to get those gears moving from a standing stop. The bot hesitates — sometimes for 200–400 ms — before it starts rolling. You'll see this most at 30% PWM.

🔋

Battery Drain Changes Speed

Open-loop sends a fixed percentage of battery voltage. If the battery is low, 100% of a weak battery is less power than 100% of a full battery. Smart Mode doesn't have this problem — the wheel sensors detect that the bot slowed down and increase motor power to compensate.

📡

How the Wheel Sensors Work

Each wheel has a small disk with slots cut into it. An optical sensor counts how fast those slots pass by. That count tells the correction system how fast the wheel is actually spinning. Below 20 cm/s, the slots pass too slowly for the sensor to get a reliable count — so the correction system gives up.

⚡

What PWM Actually Does

PWM (Pulse-Width Modulation) rapidly switches the motor on and off. 100% means it's on the whole time. 30% means it's on 30% of the time and off 70%. The motor averages that into a lower speed — but only if it can overcome friction. If it can't, those off-pulses kill the momentum the on-pulses just built.

Speed Calculator

Try your SPEED setting Shows what Smart Mode will target when you press Button B

SPEED stat 6

Set this to match your bot's Speed stat before downloading the Smart Mode program.

Target Speed

27.9

cm/s

Est. Distance

83.7

cm in 3 s

% of Speed Range

50%

of 20–50 cm/s

Variables at a Glance

Variable Name	Starting Value	What It Does
SPEED	6	Your Speed stat from the game. Change this to 1–20 before downloading. Only matters in Smart Mode.
minSpeed	20	The slowest speed the correction system can hold. The sensor hardware cannot track reliably below this. Don't change it.
maxSpeed	50	The fastest speed this gear ratio can hold with stable correction. Don't change it.
targetSpeed	calculated	The result of the speed formula. Computed once at startup from your SPEED stat. Button B passes this to cruise control.
basic.pause	3000	How long (in milliseconds) the program keeps the motors running. Locked at 3000 for this test — do not change it.

How to Run the Test

1 Download the Smart Mode program. Set SPEED to your bot's Speed stat before downloading. Put a piece of tape on the floor as your start line.
2 Press A. Mark where the bot stops. Press B. Mark where it stops. Write down both distances.
3 Download the Raw Mode program without charging the battery. Same start line. Press A, press B. Write down both distances.
4 Compare the ratios. In Smart Mode, the fast run should be about 1.8× the slower run. In Raw Mode, the 100% run will not be 3.3× the 30% run — the ratio breaks down because of gear friction at startup.
5 Run Raw Mode 10 more times at 100% without recharging. If the distance shrinks, you've measured battery drain in real time.

⚠️

Clear the path before every run. Both programs drive straight for 3 seconds with no obstacle avoidance. The bot will not stop for a wall or a table edge.