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

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: Direction straight recognized

LEFT = 2: Direction left recognized

RIGHT = 4: Direction right recognized

BACK = 8: Direction backward recognized

ERROR = 0: Direction not recognized

ANY = 15: 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: Top LED representation

FRONT_1 = 2: First front LED representation

FRONT_2 = 4: Second front LED representation

FRONT_3 = 8: Third front LED representation

FRONT_4 = 16: Fourth front LED representation

FRONT_5 = 32: Fifth front LED representation

LEFT_CYAN = 64: left cyan LEDs representation

BACK_RED = 128: Back red LEDs representation

ALL_FRONT = 62: All front LEDs representation

ALL_ROBOT = 255: All LEDs representation

class ozobot.Note(value)

Represents notes playable by robot.

C = 0: Note C

C_sharp = 1: Note C_#

D_flat = 1: Note D_b

D = 2: Note D

D_sharp = 3: Note D_#

E_flat = 3: Note E_b

E = 4: Note E

F = 5: Note F

F_sharp = 6: Note F_#

G_flat = 6: Note G_b

G = 7: Note G

G_sharp = 8: Note G_#

A_flat = 8: Note A_b

A = 9: Note A

A_sharp = 10: Note A_#

B_flat = 10: Note B_b

B = 11: Note B

class ozobot.LineColor

Represents lines colors sets recognized by robot.

BLACK = 0: Black color detected

RED = 1: Red color detected

GREEN = 2: Green color detected

BLUE = 4: Blue color detected

UNKNOWN = 8: No color detected

class ozobot.SurfaceColor(value)

Represents the set of basic colors recognized by robot.

BLACK = 0: Black color representation

RED = 1: Red color representation

GREEN = 2: Green color representation

BLUE = 4: Blue color representation

YELLOW = 3: Yellow color representation

MAGENTA = 5: Magenta color representation

CYAN = 6: Cyan color representation

WHITE = 7: White color representation

UNKNOWN = 8: Color is not known