Movement

Movements control the robot motors and control system; they can be listed in programs by ending with a ; and separated with line breaks like the Hello World! program. Sphero robots move with three basic instructions: heading, speed, and duration. For example, if you set heading = 0°, speed = 60, duration = 3s, the robot would roll forward for 3s at a moderate speed.

Roll

await roll() combines heading(0-360°), speed(-255-255), and duration(time (s)) to make the robot roll with one line of code. For example, to have the robot roll at 90°, at speed 200 for 2s, use await roll(90, 200, 2)

Speed

setSpeed() sets the speed of the robot from -255 to 255, where positive speed is forward, negative speed is backward and 0 is stopped. Each robot type translates this value differently into a real world speed; Ollie is almost three times faster than Sphero. For example, use setSpeed(188) to set the speed to 188 which persists until you set a different speed. You can also read the real-time velocity value reported by encoders on the motors.

What is the 255 scale?
The scale relates to computer memory and it's used instead of a percentage to allow young users to truly understand how computer memory works. Sphero robots only have 128,000 - 256,000 bytes of memory, which is tiny compared to your computer which has 1,000,000,000's of bytes. Memory at it's most basic form consists of 1's and 0's. A simple example is how a computer counts to 5: 0, 1, 10, 11, 100, 101. Each byte can contain eight 1's or 0's, and with eight digits the biggest number you can make is 255, using "11111111". Therefore, using the smallest amount of memory for a value (one byte) offers a range of 0-255.

Stop

stopRoll() sets the speed to zero to stop the robot, effectively the same as the setSpeed(0) command.

setHeading() sets the direction the robot rolls. Assuming you aim the robot with the blue tail light facing you, then 0° is forward, 90° is right, 270° is left, and 180° is backward. For example, use setHeading(90) to face right.

Spin

await spin spins the robot for a given number of degrees over time, with 360° being a single revolution. For example, to spin the robot 360° over 1s, use: await spin(360, 1). Use setSpeed() prior to await Spin to have the robot move in an arc or circle.

Stabilization

setStabilization(true) turns the stabilization system on and setStabilization(false) turns it off. Stabilization is normally on to keep the robot upright using the Inertial Measurement Unit (IMU), a combination of readings from the Accelerometer (directional acceleration), Gyroscope (rotation speed), and Encoders (location and distance). When stabilization is off and you power the motors, the robot will not balance, resulting in possible unstable behaviors like jumping or wobbling. Some use cases to turn it off are:

1. Jumping: Set Motor Power to max values and the robot will jump off the ground!
2. Gyro: Programs like the Spinning Top where you want to to isolate the Gyroscope readings rather than having the robot auto balance inside the shell.

When stabilization is off you can't use setSpeed to set a speed because it requires the control system to be on to function. However, you can control the motors using Motor Power with rightMotorPwm and leftMotorPwm when the control system is off.

Raw Motor

await rawMotor controls the electrical power sent to the left and right motors independently, on a scale from -255 to 255 where positive is forward, negative is backward and 0 is stopped. If you set both motors to full power the robot will jump because stabilization (use of the IMU to keep the robot upright) is disabled when using this command. This is different from Set Speed because Raw Motor sends an "Electromotive force" to the motors, whereas Set Speed is a target speed measured by the encoders. For example, to set the raw motor to full power for 4s, making the robot jump off the ground, use await rawMotor(255, 255, 4).

Motor Power

rightMotorPwm and leftMotorPwm control the electrical power sent to the left and right motors independently, on a scale from -255 to 255. If you set both motors to full power the robot will jump because stabilization is disabled when using this command. Motor Power is different from Set Speed because Raw Motor sends an "Electromotive force" to the motors, whereas Set Speed is a target speed measured by the encoders.

Reset Aim

resetAim() resets the heading calibration (aim) angle to use the current direction of the robot as 0°, within a range of 0-360°. For example, use resetAim(90) to use the current right facing direction of the robot as 0°. When used in the block canvas, resetAim() is limited to set the current front facing direction of the robot as 0°.

Droid Animations

await Animation.DroidName.Category.AnimationName.play() plays iconic Star Wars Droid animations unique to BB-8, BB-9E, R2-D2 and R2-Q5 that combine movement, lights and sound. The droid names are written as BB8, BB9E, R2D2 and R2Q5. You can randomize animations sounds by not declaring a Category and AnimationName, such as await Animation.R2D2.play(). If you declare a Category but leave the AnimationName blank it will randomize in the given category, such as await Animation.R2D2.Patrol.play(). All animations are listed below:

BB-8

Positive: Giddy, Yes
Negative: Angry, No
Action: Electrified, Number 8, Searching, Square

BB-9E

Action: Retreat, Scan Sweep
Positive: Affirmative, Content, Greetings, Understood, Yes
Negative: Agitated, Alarm, Angry, Antagonized, Furious, No
Watch With Me: Angry, Antagonized, Bored, Bow, Defiant, Disagree, Disappointed, Disbelief, Double Take, Doubtful, Excited, Frustrated, Furious, Happy, Laugh, No, Ominous, Relieved, Shake, Suprised, Uncertain, Yelling, Yoohoo

R2-D2

Action: Drive, Scan, Sleep, Spin
Idle: Idle 1, Idle 2, Idle 3
Negative: Alarm, Angry, Annoyed, Ion Blast, No, Sad, Scared
Patrol: Alarm, Hit, Patrolling
Positive: Chatty, Confident, Excited, Happy, Laugh, Surprised, Yes
Watch With Me: Angry, Anxious, Bow, Concern, Curious, Double Take, Excited, Fiery, Frustrated, Happy, Jittery, Laugh, Long Shake, No, Ominous, Relieved, Sad, Scared, Shake, Surprised, Taunting, Whisper, Yelling, Yoohoo

R2-Q5

Animations are not available for R2-Q5 :(

R2-D2 & R2-Q5 Movements

The R2-D2 and R2-Q5 Droids are physically different from other Sphero robots, so there are some unique commands that only they can use. R2Q5 can replace R2D2 for these commands.

Dome Position

R2D2.setDomePosition() rotates the dome on it's axis, from -160° to 180°. For example, set to 45° using setDomePosition(45).

Stance

Boolean that changes the stance between bipod and tripod. Set to bipod using await setStance(Stance.Bipod) and to tripod using await setStance(Stance.Tripod). Tripod is required for rolling.

Boolean that turns the waddle walk on using await setWaddle(true) and off using await setWaddle(false).