Sphero Edu API¶

Get Started¶

Sphero robots aren’t just toys – they are programmable robots that are great for learning about computer science! This wiki is a guide to learn how to program Sphero robots with Python. You will need a Sphero robot, a Python 3 environment, and a hunger to learn.

Hello World!¶

Using your device with the Sphero Edu API, create a new python code file, and copy and paste these code samples into the file. Don’t forget to aim your robot, and then run the script to see what happens!

import time
from spherov2 import scanner
from spherov2.sphero_edu import SpheroEduAPI
from spherov2.types import Color

toy = scanner.find_toy()
with SpheroEduAPI(toy) as droid:
    droid.set_main_led(Color(r=0, g=0, b=255))
    droid.set_speed(60)
    time.sleep(2)
    droid.set_speed(0)

Movement¶

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 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.

class spherov2.sphero_edu.SpheroEduAPI¶

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.

Star Wars Droid Movements¶

class spherov2.sphero_edu.SpheroEduAPI¶

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.

class spherov2.sphero_edu.SpheroEduAPI¶

Lights¶

Lights control the color and brightness of LEDs on a robot.

class spherov2.sphero_edu.SpheroEduAPI¶

set_back_led(color: int)¶

Sets the brightness of the back aiming LED, aka the “Tail Light.” This LED is limited to blue only, with a brightness scale from 0 to 255. For example, use set_back_led(255) to set the back LED to full brightness. Use time.sleep() to set it on for a duration. For example, to create a dim and a bright blink sequence use:

set_back_led(0)  # Dim
delay(0.33)
set_back_led(255)  # Bright
delay(0.33)

Sphero BOLT Lights¶

Sphero BOLT has unique lighting capabilities with a front led, back led, and 8x8 led matrix. The matrix has 3 methods to program in increasing abstraction and sophistication that are very fun to play with! The 3 methods are setting pixels, text, and animations.

class spherov2.sphero_edu.SpheroEduAPI¶

set_front_led(color: spherov2.types.Color)¶: Changes the color of the front LED light. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the magenta color is expressed as set_front_color(Color(239, 0, 255))

set_back_led(color: spherov2.types.Color)¶: Changes the color of the back LED light, aka the “Tail Light” or “Aim Light.” Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the green color is expressed as set_back_led(Color(0, 255, 0)). Sphero BOLT has this as an RGB LED on the back, whereas previous Spheros are limited to blue only.

Sphero RVR Lights¶

class spherov2.sphero_edu.SpheroEduAPI¶

set_front_led(color: spherov2.types.Color)¶: Changes the color of RVR’s front two LED headlights together. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the magenta color is expressed as set_front_color(Color(239, 0, 255)).

set_back_led(color: spherov2.types.Color)¶: Changes the color of the back LED light, aka the “Tail Light” or “Aim Light.” Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above green color is expressed as set_back_led(Color(0, 255, 0)).

BB-9E Lights¶

class spherov2.sphero_edu.SpheroEduAPI¶

R2-D2 & R2-Q5 Lights¶

class spherov2.sphero_edu.SpheroEduAPI¶

set_front_led(color: spherov2.types.Color)¶: Changes the color of the front LED light. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the fuchsia color is expressed as set_front_color(Color(232, 0, 255))

set_back_led(color: spherov2.types.Color)¶: Changes the color of the back LED light. Set this using RGB (red, green, blue) values on a scale of 0 - 255. For example, the above green color is expressed as set_back_led(Color(0, 255, 0)).

Sounds¶

Control sounds and words which can play from your programming device’s speaker or the robot (R2-D2 & R2-Q5 only).

class spherov2.sphero_edu.SpheroEduAPI¶

Sensors¶

Querying sensor data allows you to react to real-time values coming from the robots’ physical sensors. For example, “if accelerometer z-axis > 3G’s, then set LED’s to green.”

class spherov2.sphero_edu.SpheroEduAPI¶

get_back_led()¶: get_back_led().b is the brightness of the back LED, from 0 to 255. For Sphero BOLT, use get_back_led() to get the RGB value.

Sphero BOLT Sensors¶

class spherov2.sphero_edu.SpheroEduAPI¶

get_back_led()¶: Provides the RGB color of the back LED, from 0 to 255 for each color channel.

get_front_led()¶: Provides the RGB color of the front LED, from 0 to 255 for each color channel.

Sphero RVR Sensors¶

class spherov2.sphero_edu.SpheroEduAPI¶

R2-D2 & R2-Q5 Sensors¶

class spherov2.sphero_edu.SpheroEduAPI¶

get_back_led()¶: Provides the RGB color of the back LED, from 0 to 255 for each color channel.

get_front_led()¶: Provides the RGB color of the front LED, from 0 to 255 for each color channel.

Communications¶

Infrared (IR) is invisible light with longer wavelengths than visible light, and it is commonly used in TV remote controls to transmit small amounts of data. IR is used in Sphero BOLT to transmit data such as relative distance and heading between robots to enable following and evading behavior among multiple robots, as well as to send custom messages. There are four IR emitters and receivers (pairs) for 360° awareness assuming there is a clear line of sight between two or more robots. The effective range is up to about 3 meters.

class spherov2.sphero_edu.SpheroEduAPI¶

listen_for_ir_message()¶: Refer to IR Message Received Event for usage.

listen_for_color_sensor()¶: Refer to Color Event for usage.

Events¶

Events are predefined robot functions into which you can embed conditional logic. When an event occurs, the conditional logic is called in a newly spawned thread. The event will be called every time it occurs by default, unless you customize it. For example, “on collision, change LED lights to red and play the Collision sound,” while the main loop is still running.

class spherov2.sphero_edu.SpheroEduAPI¶

On Collision¶

Executes conditional logic when the robot collides with an object.

def on_collision(api):
    # code to execute on collision

api.register_event(EventType.on_collision, on_collision)

For example, below is a basic pong program where Sphero bounces off walls, or your hands/feet in perpetuity. Place the robot on the floor between two parallel walls/objects and run the program with the robot pointed perpendicularly at one wall. On collision, the program will print “collision” and change the LED’s to red, then continue in the opposite direction:

def on_collision(api):
    api.stop_roll()
    api.set_main_led(Color(255, 0, 0))
    print('Collision')
    api.set_heading(api.get_heading() + 180)
    time.sleep(0.5)
    api.set_main_led(Color(255, 22, 255))
    api.set_speed(100)

api.register_event(EventType.on_collision, on_collision)
api.set_main_led(Color(255, 255, 255))
api.set_speed(100)

On Freefall¶

Executes conditional logic when gravity is the only force acting on the robot, such as when dropping or throwing it. Freefall is measured by an accelerometer reading of < 0.1g for => 0.1s, where 1g is resting. On earth, objects in freefall accelerate downwards at 9.81 m/s^2. If you are in orbit, objects appear to be at rest with a reading of 0g because they (and you) are always in freefall, but they never hit the Earth.

def on_freefall(api):
    # code to execute on freefall

api.register_event(EventType.on_freefall, on_freefall)

For example, to print “freefall” and change the LED’s to red on freefall use:

def on_freefall(api):
    api.set_main_led(Color(255, 0, 0))
    print('freefall')

api.register_event(EventType.on_freefall, on_freefall)
api.set_main_led(Color(255, 255, 255))

On Landing¶

Executes conditional logic when the robot lands after an being in freefall. You don’t need to define an on_freefall event for the robot to experience an on_landing, but the robot must meet the conditions for freefall before land.

def on_landing(api):
    # code to execute on landing

api.register_event(EventType.on_landing, on_landing)

For example, to print “landing” and change the LED’s to green after landing use:

def on_landing(api):
    api.set_main_led(Color(0, 255, 0))
    print('land')

api.register_event(EventType.on_landing, on_landing)
api.set_main_led(Color(255, 255, 255))

On Gyro Max¶

Executes conditional logic when the robot exceeds the bounds of measurable rotational velocity of -2,000° - 2,000° per second. This can be triggered by spinning the robot around like a top on a table really fast. You need to spin it around > 5.5 revolutions per second.

def on_gyro_max(api):
    # code to execute on gyromax

api.register_event(EventType.on_gyro_max, on_gyro_max)

For example, to print “gyromax” and change the LED’s to red when you reach gyromax, use:

def on_gyro_max(api):
    api.set_main_led(Color(255, 0, 0))
    print('gyromax')

api.register_event(EventType.on_gyro_max, on_gyro_max)
api.set_stabilization(False)
api.set_back_led(255)
api.set_main_led(Color(255, 255, 255))

On Charging¶

Executes conditional logic called when the robot starts charging its battery. This can be triggered by placing your robot in it’s charging cradle, or by plugging it in.

def on_charging(api):
    # code to execute on charging

api.register_event(EventType.on_charging, on_charging)

On Not Charging¶

Executes conditional logic called when the robot stops charging its battery. This can be triggered by removing your robot from it’s charging cradle, or unplugging it.

def on_not_charging(api):
    # code to execute on not charging

api.register_event(EventType.on_not_charging, on_not_charging)

For example, to have Sphero execute 2 different conditions for on charging, and on not charging, use the below.

def on_charging(api):
    api.set_main_led(Color(6, 0, 255))
    print('charging')
    time.sleep(1)
    print('remove me from my charger')

api.register_event(EventType.on_charging, on_charging)

def on_not_charging(api):
    api.set_main_led(Color(255, 0, 47))
    print('not charging')

api.register_event(EventType.on_not_charging, on_not_charging)

print('place me in my charger')
while True:
    api.set_main_led(Color(3, 255, 0))
    time.sleep(0.5)

On IR Message Received¶

Executes conditional logic called when an infrared message is received on the specified channel. This can be triggered by one Sphero BOLT robot receiving a message from another Sphero BOLT. For example, to have Sphero BOLT change the matrix to red when receiving a message on channel 4:

message_channels = (4, )

def on_ir_message_4(api, channel):
    if channel != 4:
        return
    api.set_main_led(Color(255, 0, 0))
    api.listen_for_ir_message(message_channels)

api.register_event(EventType.on_ir_message, on_ir_message_4)
api.listen_for_ir_message(message_channels)

On Color¶

Executes conditional logic called when Sphero RVR’s color sensor returns a specified RGB color value.

color = (Color(255, 15, 60), )

def on_color(api, color):
    if color != Color(255, 15, 60):
        return

api.register_event(EventType.on_color, on_color)
api.listen_for_color_sensor(colors)

The color that RVR’s color sensor returns needs to be very close to the color set with listen_for_color_sensor() for the event to execute correctly.