Basic interface

To interact with the robot there is a dedicated Python module ozobot. This is the one module that shall be imported by the user in any program. Module consists of two major parts:

  • ozobot module itself contains all related enumerators which may be used by user when communicating with a robot.

  • ozobot.get_robot() getter which returns an object representing one robot. The robot object (Bot for synchronous or BotAsync for asynchronous access) is all you need to tell the robot to “do something”. Simply said, robot object represents your physical robot.

Module ozobot

This module is the main procedural interface for communication with the Ozobot. Module allows the control of movement or LED colors, read various sensors and many other functionalities. Script accessing the robot may look like in the following example:

# First of all we have to import this module
import ozobot

# Sometimes we need also some additional modules such as asyncio
# or time. To be sure that these modules will be running on any type
# of robot, we shall use one of ozobot submodules.
#
# As we want to do some waiting for a certain time (sleep_ms),
# we will import module time here
from ozobot import time

# Second step is to get the robot which we want to use
# If we have just one robot, we can simply ask for the default robot
bot = ozobot.get_robot()

# Cool, now we have a robot, so lets start to play with it.
# We can e.g. control LED diodes on the robot or even play some sounds
lights = bot.light_effects
sounds = bot.sounds

# Just set some LED color and play note ...
lights.set_light_color(ozobot.SurfaceColor.RED, ozobot.Lights.FRONT_1)
sounds.play_note(6, ozobot.Note.C, 0.5)
lights.set_light_color(ozobot.SurfaceColor.RED, ozobot.Lights.FRONT_2)
sounds.play_note(6, ozobot.Note.E, 0.5)
lights.set_light_color(ozobot.SurfaceColor.RED, ozobot.Lights.FRONT_3)
sounds.play_note(6, ozobot.Note.G, 0.5)
lights.set_light_color(ozobot.SurfaceColor.RED, ozobot.Lights.FRONT_4)
sounds.play_note(7, ozobot.Note.C, 0.5)
lights.set_light_color(ozobot.SurfaceColor.RED, ozobot.Lights.FRONT_5)
time.sleep(0.5)

# Note that here we are using time.sleep_ms as mentioned above
lights.set_light_color(ozobot.SurfaceColor.BLACK, ozobot.Lights.FRONT_1)
time.sleep(0.5)
lights.set_light_color(ozobot.SurfaceColor.BLACK, ozobot.Lights.FRONT_2)
time.sleep(0.5)
lights.set_light_color(ozobot.SurfaceColor.BLACK, ozobot.Lights.FRONT_3)
time.sleep(0.5)
lights.set_light_color(ozobot.SurfaceColor.BLACK, ozobot.Lights.FRONT_4)
time.sleep(0.5)
lights.set_light_color(ozobot.SurfaceColor.BLACK, ozobot.Lights.FRONT_5)
time.sleep(0.5)

# .
# .
# .
# ... and so on

In some cases, especially in the future when this interface may be extended, it is beneficial to know the current OzoPy API version. For this purpose the version of the ozobot module is defined here.

class ozobot.Version(ver=None)

Helper class allows to get, stringify or compare between various versions of OzoPy API.

Example

Parameters

ver (tuple) –

# Checks if the requirement for minimal ozobot module version is met
from ozobot import Version

version  = Version()            # This gives current API version
at_least = Version((1, 2, 1))   # This gives minimal required API version as 1.2.1

if version.integer < at_least.integer:
    raise RuntimeError('This script requires at least OzoPy version {},'
                       ' but current version is {}!'.format(at_least, version))
version

OzoPy API version tuple containing major, minor and patch version.

test(min, max=None)

Test if API version is in desired range and raise an exception when API version is incompatible.

Parameters
  • min (tuple) – Minimum required API version

  • max (tuple - optional) – Maximum required API version

Example

# Checks if the requirement for minimal ozobot module version is met
from ozobot import Version

Version().test((1, 2, 1))
property integer: int

Return comparable integer representation of version

Return type

int

Access the robot

As mentioned above, a robot shall be exclusively accessed using ozobot.get_robot(). This getter returns a Python object Bot (or eventually BotAsync). Every robot object can control exactly one robot.

ozobot.get_robot(uuid=None, *, coro=False)

Get ozobot instance

_images/getrobot.png

The first call after the user hits “run” gets the first robot among the connected robots sorted primarily by name, secondarily by UUID. All following calls return the same robot (the robot is remembered until the user hits “run” again).

When python runs in ozobot directly, then only an instance of this robot is returned.

Parameters
  • uuid (str - optional) –

    When present, says which robot shall be chosen based on UUID. Otherwise nearest robot is chosen.

    When there is no robot with such UUID (when selected) the OzobotError with ID NO_SUCH_ROBOT is raised.

  • coro (bool - optional) –

    When set to True, coroutines variant of robot is returned

    Just note that only one variant of the robot is allowed to be used. E.g. once you choose coroutine based robot any other call of this function have to use coroutines based variant, otherwise OzobotError with ID MIXING_VARIANTS is raised.

Return type

Bot | BotAsync

Returns

Robot instance

Example

# Get default robot instance
import ozobot
bot = ozobot.get_robot()

Environment and error handling

Similar to other Python modules, the ozobot module also uses exceptions with custom exception error type OzobotError derived from RuntimeError.

class ozobot.OzobotError(id, txt)

Ozobot exception class

This class is raised whenever any error inside robot logic is detected

id

Error identifier string (unique and stable for each error type - see ErrorCode)

class ozobot.ErrorCode(value)

Represents error codes which may be raised with OzobotError

NO_SUCH_ROBOT = 0

There is no such robot matching to choosen UUID

MIXING_VARIANTS = 1

Detected attempt to mix coroutines and synchronous based variant of robot instance

INVALID_ENVIRONMENT = 2

Invalid environment detected by environment checker in user code (see EnvironmentInfo)

class ozobot.EnvironmentInfo

Ozobot environment info

Time after time is handy to use some platform specific python modules (e.g. numpy) which are not compatible with all supported Ozobot platforms. In this case is benefitial to know which platform of the robot we are running.

This class provides information and methods allowing us to read and checks environment compatibility.

Note

See environment to get list of currently supported environments

Example

# Checks if we are running in web browser

env = EnvironmentInfo() # This gives current environment info
env.required('web')     # Throws an exception if we are not in web environment
property environment: str

Get current environment where we are running.

Currently supported environments are following:

Name

Environment

“web”

Python running directly in web browser (based on Pyodide)

“robot”

Python running directly inside the robot

Getter

Returns this direction’s name

Return type

str

required(req)

Test for exact environment

Parameters

req (str) – Requested environment (see table in environment)

Tests if we are running in selected environment and throw exception OzobotError with error code INVALID_ENVIRONMENT when environment does not match.

Robot enums

In order to communicate with a robot, it is sometimes handy to have some “dictionary” of words which the robot is able to understand. One option is to use strings ("LEFT", "RIGHT", "RED", "GREEN", …), however strings have their own disadvantages, as parsing of them may be not that fast as their numeric (integer) representation. It is also more easy to miss-spell a command (e.g. to use "FRONT1" instead of "FRONT 1"). In this case, intellisense is even unable to give you a good hint. Therefore, enumerators have been used for communication with the robot. Enumerators are objects which have exactly one meaning (e.g. FRONT_1 means first front LED light). It is also possible to combine more enums (e.g. FRONT_1 | FRONT_2 means that the first two front LEDs are affected by the command).

Here is the list of all enumerators usable with robot:

class ozobot.Directions(value)

Represents directions of robot.

There can be more directions detected by robot, e.g. like in following example:

import ozo

bot = ozobot.get_robot()
dir = ozobot.navigation.get_last_intersection_type()

if ozobot.Directions.LEFT in dir or ozobot.Directions.RIGHT in dir:
    bot.sounds.say_direction(dir)
FORWARD = 1

dir_forward Direction straight recognized

LEFT = 2

dir_left Direction left recognized

RIGHT = 4

dir_right Direction right recognized

BACK = 8

dir_backward Direction backward recognized

ERROR = 0

dir_error Direction not recognized

ANY = 15

dir_any Use any possible direction

class ozobot.Lights(value)

Represents LED lights positions. This positions can be combined by logical operation e.g. like in following example:

import ozo
side_lights = ozobot.Lights.FRONT_1 | ozobot.Lights.FRONT_5
TOP = 1

led_top Top LED representation

FRONT_1 = 2

led_front_1 First front LED representation

FRONT_2 = 4

led_front_2 Second front LED representation

FRONT_3 = 8

led_front_3 Third front LED representation

FRONT_4 = 16

led_front_4 Fourth front LED representation

FRONT_5 = 32

led_front_5 Fifth front LED representation

LEFT_CYAN = 64

led_left_cyan left cyan LEDs representation

BACK_RED = 128

led_back_red Back red LEDs representation

ALL_FRONT = 62

led_front_all All front LEDs representation

ALL_ROBOT = 255

led_all All LEDs representation

class ozobot.Note(value)

Represents notes playable by robot.

_images/notes.png
C = 0

Note C

C_sharp = 1

Note C#

D_flat = 1

Note Db

D = 2

Note D

D_sharp = 3

Note D#

E_flat = 3

Note Eb

E = 4

Note E

F = 5

Note F

F_sharp = 6

Note F#

G_flat = 6

Note Gb

G = 7

Note G

G_sharp = 8

Note G#

A_flat = 8

Note Ab

A = 9

Note A

A_sharp = 10

Note A#

B_flat = 10

Note Bb

B = 11

Note B

class ozobot.LineColor

Represents lines colors sets recognized by robot.

BLACK = 0

line_black Black color detected

RED = 1

line_red Red color detected

GREEN = 2

line_green Green color detected

BLUE = 4

line_blue Blue color detected

UNKNOWN = 8

No color detected

class ozobot.SurfaceColor(value)

Represents the set of basic colors recognized by robot.

BLACK = 0

lights_black Black color representation

RED = 1

lights_red Red color representation

GREEN = 2

lights_green Green color representation

BLUE = 4

lights_blue Blue color representation

YELLOW = 3

lights_yellow Yellow color representation

MAGENTA = 5

lights_magenta Magenta color representation

CYAN = 6

lights_cyan Cyan color representation

WHITE = 7

lights_white White color representation

UNKNOWN = 8

Color is not known