Movements

Movements control the robot's motors and control system. You can use sequential movement commands by separating them with line breaks, like the Hello World! program. Sphero robots generally move with these basic instructions: 

• Heading

• Speed

• Duration or distance

For example, if you set heading = 0°, speed = 60, duration = 3 seconds, then the robot would roll forward for 3 seconds at a moderate speed. Some robots, like Sphero BOLT+ and Sphero RVR/RVR+ have improved motor encoders, which means you can set your robot to roll for a specific distance in centimeters (cm) rather than for a period of time. For example, if you set heading = 0°, speed = 60, distance = 50 centimeters, then the robot would roll forward at a moderate speed until it reached 50 centimeters traveled in total.

What is the 255 scale, and why is it used for speed?

The scale relates to computer memory and it's used instead of a percentage to allow young users to gain familiarity with how computer memory works. Memory at its most basic form consists of the binary digits 0 and 1 where a single one of those digits is referred to as a bit. Though a single bit can only represent 0 or 1, multiple bits can be combined to represent larger values, just as the single digits 1, 2, and 3 can be combined to represent the number 123 in the base 10 decimal counting system we typically use outside of the context of programming. In that base 10 example,  the 3 in the ones place, the 2 in the tens place, and the 1 in the hundreds place combine to represent the number one-hundred  twenty-three.  Since a binary digit can only represent one of two values, counting in binary uses a ones place, a twos place, a fours place, an eights place, a sixteens place, etc. instead of ones, tens, hundreds, places. 

Analyzing how a computer counts to five illustrates this concept. A 0 in the ones place (0) equals zero. A 1 in the ones place (1) equals one. A 1 in the twos place and a zero in the ones place (10) equals two. A 1 in both the ones and twos places (11) add together to equal three. A 1 in the fours place (100) equals four. Lastly, a 1 in both the fours and ones places (101) equals five. To recap, a computer counting from zero to five looks like 0, 1, 10, 11, 100, 101. Whereas a bit represents a single 1 or 0, a byte represents eight bits. Since a byte can thus contain eight ones or zeroes, the largest value a byte can represent with all eight bits filled with ones (11111111) equals 255. Therefore, using the smallest amount of memory for a value (one byte) offers a range of 0 - 255. Since Sphero robots have limited memory for storing values it's important to be efficient with our memory usage hence we use a single byte with the possible values from 0 - 255 to represent speed.

Roll

Combines heading, speed, and duration to make the robot roll for a specified amount of time. 

To have the robot roll with a 90° heading at a speed of 200 for 2s, use await roll(90, 200, 2).  The function is the same for both JavaScript and Python. 

Parameters:
heading {number} - The direction to roll in degrees (0 to 359º)
speed {number} - How fast to roll (-255 to 255)
duration {number} - For how long to roll (in seconds)

Block Notes:
Duration is always a required parameter when using the roll block in the block canvas. This means a stop block is not required after a roll block, since your robot will automatically stop after the duration is done. However, duration is an optional parameter when using the roll  function with JavaScript and Python in the text editor. If duration is not defined, the robot will continue to roll until a stop function is used. For example, to make the robot roll at a 0º heading  with a speed of 50, use await roll(0, 50).
For some older spherical robots like SPRK+, Mini, and BOLT, it can be useful to implement short delays (a second or less) between back-to-back roll blocks. This helps the robot settle before executing the next roll which can improve accuracy. Newer robots like BOLT+ and RVR+  handle back-to-back roll functions differently, so this technique is generally not needed.

Roll to Distance

Combines heading, maximum speed, and distance to make the robot roll to a specified distance. 

To roll with a 90° heading at a maximum speed of 200 for 200cm use:
JavaScript: await rollToDistance(90, 200, 200)
Python: await roll_to_distance(90, 200, 200)

Parameters:
heading {number} - The direction to roll in degrees (0 to 359º)
speed {number} - How fast to roll (-255 to 255)
distance {number} - For how far to roll (in centimeters)

Supported Robots:
BOLT+, RVR, RVR+

Consider that distance accuracy is dependent on multiple factors, including the surface under your BOLT+ or RVR/RVR+ and the weight of any payload on board (in the case of RVR/RVR+). Since BOLT+ and RVR/RVR+ are trying to accurately target a precise distance with Roll to Distance, the firmware control systems will manage speed differently than when using await roll. There is a period of acceleration and deceleration at the start and end of the robot movement. This acceleration ramping helps reduce the slippage that would impact encoder accuracy. As a result, your maximum speed setting may not be met if you have set your BOLT+ or RVR/RVR+ to roll a shorter distance. Experiment with your set distance and maximum speed to get the results you need.

Block Notes:
When the distance parameter for a roll to distance block is achieved, your robot will automatically stop moving. This means you do not need to use a stop block after a roll to distance block. 

Drive

Enables or disables a driving interface in the Sphero Edu apps, which allows you to manually drive your Sphero BOLT+, RVR, or RVR+ while executing additional code. On computers, Sphero Edu uses keyboard keys for the drive input. On mobile devices like phones and tablets,  it will use a software joystick or slider controls. This command is valuable since it allows you to have manual control over your robot's movement during a program, which is not possible when programming each movement command individually. This opens up a lot of opportunities for dynamic programs that are responsive to your input.

To enable and disable the the manual driving interface with JavaScript, use:
On: drive(true)
Off: drive(false) 

To enable and disable the the manual driving interface with Python, use:
On: drive(True)
Off: drive(False) 

Parameters:
enable {boolean} -  Used to  enable or disable the  driving interface (true = on, false = off)

Block Notes:
When using the drive block in the block canvas, the enable parameter uses on instead of true, and off instead of false.

Compatible Robots:
BOLT+, RVR, RVR+

When drive is enabled, your robot will not move until you use the driving interface or until it is disabled by another command. It's important to know that the driving interface will be disabled automatically if most of the movement commands are used after the drive command. For example, observe the following code snippets:
JavaScript:

drive(true);
await delay(25);
await roll(0, 255, 5);

Python:

drive(True)
await delay(25)
await roll(0, 255, 5)

In the example above, the driving interface will be available  for 25 seconds, which is the duration of the delay function. Once the roll function occurs, the driving interface will automatically be disabled. The following movement functions will disable the driving interface when used after the drive function: 

• Roll

• Roll to Distance

• Spin

• Speed

• Heading

• Raw Motor

The following movement functions will not disable the driving interface when used after the drive function: 

• Stabilization

• Stop

• Reset Aim

The driving interface has two UI elements; controls to drive your robot, and a speed slider. Since there is no aim control in the driving interface, you will need to use the Reset Aim function in creative ways to reset your heading. For example, you can reset aim immediately after the drive command: 

JavaScript:

drive(true);
resetAim();

Python:

drive(True)
reset_aim()

Alternatively, you could use an On Button event to manually reset aim with a simple press of the software button at any time.
JavaScript:

var _softwareButtonEvents = ['Reset Aim'];

async function startProgram() {

registerSoftwareButton(_softwareButtonEvents);

drive(true);

}

async function onSoftwareButton(button) {

if (button !== 'Reset Aim') return;

resetAim();

}

registerEvent(EventType.onSoftwareButton, onSoftwareButton);

Python:

_softwareButtonEvents = ['Reset Aim']

async def startProgram():

    register_software_button(_softwareButtonEvents)

    drive(True)

async def onSoftwareButton(button):

    if button != 'Reset Aim':

        return

    reset_aim()

register_event(EventType.on_software_button, onSoftwareButton

There are many other ways you can creatively aim while using the drive function. Experiment! 

Stabilization

Turns the stabilization system "on" or "off". When stabilization is "on" the robot is upright using the Inertial Measurement Unit (IMU), which is a combination of readings from the Accelerometer (directional acceleration), Gyroscope (rotation speed), and Encoders (location and distance). You can generally confirm if stabilization is on for spherical robots by rotating the robot. If the internal hardware components maintain an upright position per the default heading (0º ) while you rotate, then stabilization is on. 

To enable and disable stabilization with JavaScript, use:
On: setStabilization(true)
Off: setStabilization(false) 

To enable and disable the the driving interface with Python, use:
On: set_stabilization(True)
Off: set_stabilization(False) 

Parameters:
enable {boolean} - A boolean value to enable the stabilization system (true = on, false = off)

Block Notes:
When using the stabilization block in the block canvas, the enable parameter uses on instead of true, and off instead of false.

Unsupported Robots:
RVR, RVR+, and Mini do not support the stabilization block and function

Spin

Rotates the robot for a given number of degrees over a specified time, with 360° being a single revolution.

To spin the robot 360° over 1 second, use  await spin(360, 1). The function is the same for both JavaScript and Python. 

The spin function can be used in combination with a speed function to  move the robot in  an arc or  a circle, as shown in the following example:
JavaScript: 

setSpeed(100);
await spin(360, 1);

Python: 

set_speed(100)
await spin(360, 1)

Parameters:
rotation {number} - Amount of spinning (in degrees)
duration {number} - For how long to spin (in seconds)

For the rotation parameter, you are not limited to 360 degrees. If you want your robot to spin more than once in a single command, you can multiply 360 with the number of rotations you want. As an example, 360 * 3 is 1080. So if you want to rotate 3 times over 5 seconds, use await spin(1080, 5).

You can set parameter values that are hard or impossible for your robot to physically execute. For example, your robot cannot smoothly rotate 5 times in half a second due to the physical limitations of the motors. Likewise, your robot cannot rotate 999,999 degrees in 5 seconds. So these would not be valid: 
await spin(1800, 0.5)
await spin(999999, 5)
While you can technically send these parameter values without runtime errors, your robot will hitch or behave erratically.  To resolve, adjust the rotation and duration parameters until you get better results.

Speed

Sets the speed of the robot from -255 to 255, where positive speed is forward, negative speed is backward, and 0 is stopped.

Use the following examples to roll at a speed of 100:
JavaScript: setSpeed(100)
Python: set_speed(100)

Parameters:
speed {number} - How fast to roll (-255 to 255)

Each robot type translates the parameter value differently into a real world speed. For example, BOLT+ and RVR+ are faster than Mini. If you set speed 255 for BOLT+, it will move faster than if you set speed to 255 for Mini. 

You can also read the real-time velocity value in centimeters per second reported by the motor encoders. 

Stop

Sets the speed to zero to stop the robot. The roll and roll to distance functions already stop after a set duration or distance, so it is not necessary to call the stop function after using those functions. Primarily used in conjunction with the speed function. 

Use the examples below to  stop:
JavaScript: stopRoll()
Python: stop_roll()

Parameters:
heading {number} - Can optionally be specified to direct the robot to orient to a specific heading (in degrees) when it stops

Block Notes:
The heading parameter is not available for the stop block in the block canvas. It's only available when coding in the text canvas with JavaScript and Python.

Heading

Sets the direction that the robot rolls. Given a robot's aim, 0° is forward, 90° is right, 270° is left, and 180° is backward. This is the simplest way to rotate your robot without moving in a direction.

Use the following examples to face right (90º):
JavaScript: setHeading(90)
Python: set_heading(90)

Parameters:
heading {number} - The direction to roll in degrees (0º to 359º)

Raw Motor

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. 

Use the following examples to apply maximum electrical power to the left motor for 2 seconds:
JavaScript: await rawMotor(255, 0, 2)
Python: await raw_motor(255, 0, 2)

Parameters:
left {number} - Electrical power to the left motor (-255 to 255)
right {number} - Electrical power to the right motor (-255 to 255)
duration {number} - For how long to power motors (in seconds)

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 function. For example, to set the raw motors to full power for 4 seconds, making the robot jump off the ground, use:
JavaScript: await rawMotor(255, 255, 4)
Python: await raw_motor(255, 255, 4)

If you are using raw motor commands to make your robot roll in a straight line, you may notice that it veers a little to the left or right. Raw motors commands bypass the control system of most Sphero robots, which means there is no firmware in place to compensate for slight differences in motor performance. As a result, sending the same electrical power to each motor can result in slightly different performance output on a per motor basis. 

Reset Aim

Resets the heading calibration (aim) angle to use the current direction of the robot as 0°.

JavaScript: resetAim()
Python: reset_aim()

Aiming is an important concept for the spherical Sphero robots. Since a sphere has no "clear" front, it's important to define a heading that can be used as a reference for following movement commands. A default 0º heading is forward for Sphero robots. If you rotate your robot 90º and then use the reset aim function, that direction will then be the new default 0º heading. 

Sphero BOLT Movements

Sphero BOLT has a compass (magnetometer) sensor that has unique functionality. Nearby metallic and magnetic objects can affect the accuracy of the compass, so try to use this feature in an area without that interference, or hold it up in the air if you can't get away from interference.

Calibrate Compass

Calibrates the magnetometer by spinning the BOLT in place. You need to run this command before setting or getting the compass direction. Nearby metallic and magnetic objects can affect the accuracy of the compass. Generally, it's a good idea to use the calibrate compass command at the start of your program if you intend to use the compass direction command throughout. 

JavaScript: await calibrateCompass()
Python: await calibrate_compass()

Compatible Robots:
BOLT

Compass Direction

 Sets the real-world direction based on the last compass calibration. Requires the calibrate compass function to be called first at some point in the code.

Use the example below to calibrate the compass, then point Sphero BOLT North based on that calibration:
JavaScript:

await calibrateCompass();

setCompassDirection(0);

Python:

await calibrate_compass()

set_compass_direction(0)

Parameters:
direction {number}  - The heading to set in degrees (0° = North, 90° = East, 180° = South, 270° = West)

For most use cases, you will likely want your robot to roll in a specific compass direction. To do this, you will first need to align your heading to your compass direction. This is accomplished by resetting the heading after setting a compass direction. In the example below we are setting your heading (0º) to be true North, then driving in that direction. 
JavaScript:

await calibrateCompass();

setCompassDirection(0);
resetAim();

await roll(0, 100, 5);

Python:

await calibrate_compass()

set_compass_direction(0)

reset_aim()

await roll(0, 100, 5)

Compatible Robots:
BOLT

Star Wars Droid Movements

Droid Animations

Plays iconic Star Wars Droid animations unique to BB-8, BB-9E, and R2-D2 that combine movement, lights and sound. To play a specific animation for a specific Droid from a specific category, include the Droid name, category, and animation name in this format:
await Animation.DroidName.Category.AnimationName.play() 

The droid names are written as BB8, BB9E, and R2D2. You can randomize animations and 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(). To specifically play the R2-D2 Alarm animation use await Animation.R2D2.Patrol.Alarm.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, Surprised, 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 :(

Rotates the dome to a specific position along its axis, from -160° to 180°. 

Use the following examples to set the dome to 45º:
JavaScript: setDomePosition(45)
Python: set_dome_position(45)

Parameters:
position {number} - The angle to set the dome position, from -160° to 180°

Compatible Robots:
R2-D2, R2-Q5

Stance

Changes the stance between bipod and tripod. Tripod is required for rolling. The function takes a Stance enum value of either Bipod or Tripod, but the equivalent block in the block canvas accepts booleans and will set Tripod when true is passed and Bipod when false is passed.

To set the stance with JavaScript, use:
Bipod: await setStance(Stance.Bipod)
Tripod: await setStance(Stance.Tripod) 

To set the stance with Python, use:
Bipod: await set_stance(Stance.bipod)
Tripod: await set_stance(Stance.tripod) 

Parameters:
stance {Stance} - The stance to set, either Stance.Bipod or Stance.Tripod

Block Notes:
When using the stance block in the block canvas, the stance parameter uses bipod instead of Stance.Bipod, and tripod instead of Stance.Tripod.

Compatible Robots:
R2-D2, R2-Q5

Waddle

Boolean that turns the waddle walk on or off.

To enable and disable waddle walk with JavaScript, use:
On: await setWaddle(true)
Off: await setWaddle(false) 

To enable and disable waddle walk with Python, use:
On: await set_waddle(True)
Off: await set_waddle(False) 

Parameters:
onOff {boolean} - Boolean to enable the waddle walk (true = enabled, false = disabled)

Block Notes:
When using the waddle block in the block canvas, the onOff parameter uses on instead of true, and off instead of false.

Compatible Robots:
R2-D2, R2-Q5