Simple API module

This module implements a simple synchronous API for controlling a single Ozobot ORA robot. The API is designed to be simple and easy to use, while still providing a high level of control over the robot. The module exports static classes or instantiated and ready to be used objects to reduce the boilerplate. The API is synchronous, meaning that almost all calls will block the program execution until the robot has completed the requested action. This makes it easy to write simple scripts that control the robot in a straightforward manner.

Datatypes

The following datatypes are used throughout the library.

class ozobot.ora.simple.Cartesian(x: Value[DistanceDomain] | float | int = 0, y: Value[DistanceDomain] | float | int = 0, z: Value[DistanceDomain] | float | int = 0, w: Value[AngleDomain] | float | int = 0, p: Value[AngleDomain] | float | int = 0, r: Value[AngleDomain] | float | int = 0)

A structure representing a Cartesian pose.

Instantiate by calling Cartesian(x, y, z, w, p, r), where x, y, z, w, p, and r are the pose’s x, y, z, yaw, pitch, and roll values, respectively. The values can be either plain numbers (float or int) or physical quantities. Mixing the two is allowed. Both positional and named arguments can be used. Omitted values default to 0.

When using plain numbers, please make sure to use correct units. The default units are millimeters for distances and degrees for angles. For physical quantities, use the DistanceDomain for x, y, z and AngleDomain for w, p, r.

For example, the following are equivalent:

p1 = Cartesian(200, 50, 50, 0, 0, 180)

p2 = Cartesian(
    x=units(0.2, m),
    y=50,
    z=50,
    r=units(pi, rad)
)
Variables:

  • x – The x-coordinate of the pose represented as Value[DistanceDomain].

  • y – The y-coordinate of the pose represented as Value[DistanceDomain].

  • z – The z-coordinate of the pose represented as Value[DistanceDomain].

  • w – The yaw angle represented as Value[AngleDomain].

  • p – The pitch angle represented as Value[AngleDomain].

  • r – The roll angle represented as Value[AngleDomain].

class ozobot.ora.simple.Frame(x: Value[DistanceDomain] | float | int = 0, y: Value[DistanceDomain] | float | int = 0, z: Value[DistanceDomain] | float | int = 0, w: Value[AngleDomain] | float | int = 0, p: Value[AngleDomain] | float | int = 0, r: Value[AngleDomain] | float | int = 0)

A structure representing a Frame.

Instantiate by calling Frame(x, y, z, w, p, r), where x, y, z, w, p, and r are the pose’s x, y, z, yaw, pitch, and roll values, respectively. The values can be either plain numbers (float or int) or physical quantities. Mixing the two is allowed. Both positional and named arguments can be used. Omitted values default to 0.

When using plain numbers, please make sure to use correct units. The default units are millimeters for distances and degrees for angles. For physical quantities, use the DistanceDomain for x, y, z and AngleDomain for w, p, r.

For example, the following are equivalent:

p1 = Frame(200, 50, 50, 0, 0, 180)

p2 = Frame(
    x=units(0.2, m),
    y=50,
    z=50,
    r=units(pi, rad)
)
Variables:

  • x – Frame origin x-coordinate represented as Value[DistanceDomain].

  • y – Frame origin y-coordinate represented as Value[DistanceDomain].

  • z – Frame origin z-coordinate represented as Value[DistanceDomain].

  • w – Frame orientation yaw angle represented as Value[AngleDomain].

  • p – Frame orientation pitch angle represented as Value[AngleDomain].

  • r – Frame orientation roll angle represented as Value[AngleDomain].

class ozobot.ora.simple.Joints(a1: Value[AngleDomain] | float | int = 0, a2: Value[AngleDomain] | float | int = 0, a3: Value[AngleDomain] | float | int = 0, a4: Value[AngleDomain] | float | int = 0, a5: Value[AngleDomain] | float | int = 0, a6: Value[AngleDomain] | float | int = 0)

A structure representing a Joint configuration.

Instantiate by calling Joint(a1, a2, a3, a4, a5, a6), where a1, a2, a3, a4, a5, and a6 are the joint angles. The values can be either plain numbers (float or int) or physical quantities. Mixing the two is allowed. Both positional and named arguments can be used. Omitted values default to 0.

When using plain numbers, please make sure to use correct units. The default units are degrees. For physical quantities, use the AngleDomain.

For example, the following are equivalent:

j1 = Joints(0, 0, 90, 0, 90, 45)

j2 = Joints(
    a3=90,
    a5=units(pi/2, rad),
    a6=units(45, deg)
)
Variables:

  • a1 – Angle of the first joint represented as Value[AngleDomain].

  • a2 – Angle of the second joint represented as Value[AngleDomain].

  • a3 – Angle of the third joint represented as Value[AngleDomain].

  • a4 – Angle of the fourth joint represented as Value[AngleDomain].

  • a5 – Angle of the fifth joint represented as Value[AngleDomain].

  • a6 – Angle of the sixth joint represented as Value[AngleDomain].

class ozobot.ora.simple.Tool(*, type: ToolType, tcp: Frame, center_of_gravity: tuple[Value[domains.DistanceDomain], Value[domains.DistanceDomain], Value[domains.DistanceDomain]], weight: Value[domains.WeightDomain], collider: ToolCollider)

Motion control

class ozobot.ora.simple.move

Class providing methods for moving single robot and setting the motion parameters. The methods are static, therefore they can be called without creating an instance of the class, for example:

move.joint(...)
move.linear(...)
move.linear_rel(...)
move.linear_tool(...)
move.circ(...)
move.set_default_radius(...)
move.set_defaults_joint(...)
move.set_defaults_linear(...)
static circ(p_aux: Cartesian, p_end: Cartesian, *, arc_angle: Value[domains.AngleDomain], speed: Value[domains.SpeedDomain] | None = None, acceleration: Value[domains.AccelerationDomain] | None = None) → None

Move the robot to the specified Cartesian position over a circular segment path in Cartesian space.

The call is blocking.

Circular segment movement is a movement in the Cartesian space, where the robot moves along a circular path between two points. The circle is defined by the current point, auxiliary point, the end point and the arc angle. Robot may suffer from singularities.

_images/circular-motion.svg

Figure shows the three-point circle definition and how the arc angle influences the arc length.

Parameters:

  • p_aux – Auxiliary point on the circle.

  • p_end – End point on the circle.

  • arc_angle – Angle of the arc that the robot will move along.

  • speed – Optional speed of the movement. If unset, the default speed is used.

  • acceleration – Optional acceleration of the movement. If unset, the default acceleration is used.

Note

static joint(pose: Joints | Cartesian, *, speed: Value[domains.RatioDomain] | None = None, acceleration: Value[domains.AngularAccelerationDomain] | None = None) → None

Move the robot to the specified position by a joint movement.

The call is blocking.

Joint movement is a movement in the joint space, where each individual joint angle is changed by the shortest movement possible. The path that the TCP follows is generally not a line. Does not suffer from singularities. Robot may, and probably will, not go over a straight line between two points.

# example code to move the robot to the specified joint configuration
move.joint(Joints(0, 0, 0, 0, 0, 0))
Parameters:

  • pose – Joints configuration or Cartesian pose to move the robot to.

  • speed – Optional speed of the movement. If unset, the default speed is used.

  • acceleration – Optional acceleration of the movement. If unset, the default acceleration is used.

Note

static linear(pose: Cartesian, *, speed: Value[SpeedDomain] | None = None, acceleration: Value[AccelerationDomain] | None = None) → None

Move the robot to the specified Cartesian pose along a linear path in Cartesian space.

The call is blocking.

Linear movement is a movement in the Cartesian space, where the robot moves in a straight line between two points. Robot may suffer from singularities.

The figure depicts reference frame relation. In this case, the Cartesian coordinates represent a transformation from the world frame to the desired Tool Frame.

_images/absolute-motion.svg

The dotted line represents pose parameter - the relation between the current robot frame (World Frame) and the Tool Frame.

# example code to move the robot to the specified joint configuration
move.linear(Cartesian(100, 0, 0, 0, 0, 180))
Parameters:

  • pose – Cartesian pose to move the robot to.

  • speed – Optional speed of the movement. If unset, the default speed is used.

  • acceleration – Optional acceleration of the movement. If unset, the default acceleration is used.

Note

static linear_rel(offset: Cartesian, *, speed: Value[SpeedDomain] | None = None, acceleration: Value[AccelerationDomain] | None = None) → None

Move the robot by the specified Cartesian offset along a linear path in Cartesian space.

Same as linear(), but the movement is relative to the current position of the robot.

The figure depicts reference frame relation. In this case, the Cartesian coordinates represent an offset from point P1 to point P2 in the World Frame. In the example below, transformation from P1 to P2 would have positive X value and zero Y value, because we are in the World Frame.

_images/relative-motion.svg

Dotted lines emphasise the offset is relative the World Frame.

Parameters:

  • offset – Cartesian offset to move the robot to.

  • speed – Optional speed of the movement. If unset, the default speed is used.

  • acceleration – Optional acceleration of the movement. If unset, the default acceleration is used.

static linear_tool(offset: Cartesian, *, speed: Value[SpeedDomain] | None = None, acceleration: Value[AccelerationDomain] | None = None) → None

Move the robot to the specified Cartesian position in the tool coordinate frame along a linear path in Cartesian space.

Same as linear(), but the movement is relative to the current position of the robot.

The figure depicts reference frame relation. In this case, the Cartesian coordinates represent a transformation of the Tool Frame from the current point P1 to the desired point P2. In the example below, transformation from P1 to P2 would have negative Y value and zero X value, because we are in the Tool Frame.

_images/tool-motion.svg

Dotted line emphasises the offset is relative the Tool Frame.

Parameters:

  • offset – Cartesian pose to move the robot to.

  • speed – Optional speed of the movement. If unset, the default speed is used.

  • acceleration – Optional acceleration of the movement. If unset, the default acceleration is used.

static set_defaults_joint(*, speed: Value[domains.RatioDomain] | None = None, acceleration: Value[domains.AngularAccelerationDomain] | None = None, jerk: Value[domains.AngularJerkDomain] | None = None) → None

Set default parameters for joint movement.

All the parameters are optional, therefore it’s possible to set only the ones that should be changed.

See also

See Units for more information on how to use parameters with units.

Parameters:

  • speed – Default speed for joint movement.

  • acceleration – Default acceleration for joint movement.

  • jerk – Default jerk for joint movement.

static set_defaults_linear(*, speed: Value[SpeedDomain] | None = None, acceleration: Value[AccelerationDomain] | None = None, jerk: Value[JerkDomain] | None = None) → None

Set default parameters for linear movement.

All the parameters are optional, therefore it’s possible to set only the ones that should be changed.

See also

See Units for more information on how to use parameters with units.

Parameters:

  • speed – Default speed for linear movement.

  • acceleration – Default acceleration for linear movement.

  • jerk – Default jerk for linear movement.

Gripper state

To use the gripper class, extra types are necessary.

class ozobot.ora.simple.gripper

Class providing methods for controlling gripper of single robot. The methods are static, therefore they can be called without creating an instance of the class, for example:

gripper.set_state(...)
static set_state(state: FingerGripperState | VacuumGripperState) → None

Set the state of the gripper.

Sets the state of the gripper to the specified state. The correct gripper has to be configured and attached to the robot, there is no check for the tool’s physical presence. If there are any commands in the queue, function only sets the gripper state after the last command is executed.

# example code to close the finger gripper
gripper.set_state(FingerGripperState.CLOSE)
Parameters:

state – State of the gripper. Can be either FingerGripperState or VacuumGripperState value.

See also

See tool.set() to learn how to set the tool type.

class ozobot.ora.datatypes.FingerGripperState(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The state of the finger gripper.

OPEN
CLOSED
OFF
class ozobot.ora.datatypes.VacuumGripperState(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The state of the vacuum gripper.

ON
OFF

Attention

Enum values need to be referenced by their full name, for example FingerGripperState.OPEN, not just OPEN.

Input/output

The following classes are used to read and write digital and analog signals.

ozobot.ora.simple.di

di is a object allows to create a readable digital input definition.

Individual inputs can be accessed by using square brackets, the same way as the list is indexed. Input and output indexes are zero-based. Under the hood, its custom implementation of __getitem__ method supports both integer indices, slices and tuples of integers. In case of the tuple or slice, an InputGroup object is returned, which allows to read multiple inputs at once. Input object is returned otherwise.

Both types can be used to read the current input value. Both then return the value of the input which is a sequence of boolean values for input groups or a single boolean value for single inputs. High values on the input yield True and low values False.

Examples

Reading

fifth_input = di[5]
state = fifth_input.read()
# state now contains True or False value

Referencing an input group by slice

# or reading multiple inputs at once
first_three_inputs = di[0:3]
states = first_three_inputs.read()
# states variable now contain list of True or False values, 
# for example [True, False, True]

Referencing an input group by tuple

# or reading multiple inputs at once
my_inputs = di[0, 1, 3]
states = my_inputs.read()
# states variable now contain list of True or False values, 
# for example [True, False, True]
ozobot.ora.simple.do

do is a object allows to create a writable digital output definition.

Individual outputs can be accessed by using square brackets, the same way as the list is indexed. Input and output indexes are zero-based. Under the hood, its custom implementation of __getitem__ method supports both integer indices, slices and tuples of integers. In case of the tuple or slice, an OutputGroup object is returned, which allows to read multiple inputs at once. Output object is returned otherwise.

Both types can be used to write boolean values to the output. A single value in case of Output, a sequence of values in case of OutputGroup.

Examples

Writing

fifth_output = do[4]
fifth_output.write(True)
# fifth output is now set to HIGH

Writing an output group

first_three_outputs = do[0:3]
first_three_outputs.write([True, False, True])
# first three outputs are now set to HIGH, LOW, HIGH
ozobot.ora.simple.ai

ai is a object allows to create a readable analog input definition.

Individual inputs can be accessed by using square brackets, the same way as the list is indexed. Input and output indexes are zero-based. Under the hood, its custom implementation of __getitem__ method supports both integer indices, slices and tuples of integers. In case of the tuple or slice, an InputGroup object is returned, which allows to read multiple inputs at once. Input object is returned otherwise.

Both types can be used to read the current input value. Both then return the value of the input which is a sequence of float values for input groups or a single float value for single inputs.

Examples

Reading

first_input = ai[0]

state = first_input.read()
# state now contains a `float` value, for example 4.5

Referencing an input group by slice

# or reading multiple inputs at once
first_two_inputs = ai[0:2]
states = first_two_inputs.read()
# states variable now contain list of `float` values, 
# for example [0.1, 2.34]

Referencing an input group by tuple

# or reading multiple inputs at once
my_inputs = ai[0, 1]
states = my_inputs.read()
# states variable now contain list of `float` values, 
# for example [0.1, 2.34]
ozobot.ora.simple.ao

ao is a object allows to create a writable analog output definition.

Individual outputs can be accessed by using square brackets, the same way as the list is indexed. Input and output indexes are zero-based. Under the hood, its custom implementation of __getitem__ method supports both integer indices, slices and tuples of integers. In case of the tuple or slice, an OutputGroup object is returned, which allows to read multiple inputs at once. Output object is returned otherwise.

Both types can be used to write float values to the output. A single value in case of Output, a sequence of values in case of OutputGroup.

Examples

Writing

fifth_output = do[4]
fifth_output.write(True)
# fifth output is now set to HIGH

Writing an output group

first_three_outputs = do[0:3]
first_three_outputs.write([True, False, True])
# first three outputs are now set to HIGH, LOW, HIGH

State

This section describes how to read robot states and how to change current tool and frame.

class ozobot.ora.simple.tool

Class providing methods for controlling tool (TCP, weight, control outputs) of single robot. The methods are static, therefore they can be called without creating an instance of the class, for example:

_images/user-tool.svg

Robot’s Cartesian pose the position of the current Tool Center Point (TCP) with respect to the selected Frame.

tool.set(...)
current_tool = tool.get()

with tool.context(...):
    ...
static context(tool: Tool) → Iterator[None]

Context manager for setting the tool for a block of code.

Context manager that configures the selected tool for calls made within the code block.

Parameters:

tool – Tool to set for the code block.

tool.set(tools.FINGER_GRIPPER)
move.linear(...)  # this movement is done with the finger gripper tool

with tool.context(tools.VACUUM_GRIPPER):
    move.linear(...)  # this movement is done with the vacuum gripper tool
    move.linear(...)  # this movement is done with the vacuum gripper tool

move.linear(...)  # this movement is done with the finger gripper tool
static get() → Tool

Get the current tool configuration.

This is the software configuration, there is no check for the tool’s physical presence.

Returns:

Current tool configuration.

static set(tool: Tool) → None

Set the tool.

Sets the tool to the specified tool. The correct tool has to be attached to the robot, there is no check for the tool’s physical presence. If there are any commands in the queue, function only sets the gripper state after the last command is executed.

Parameters:

tool – Tool to set.

# example code to set the vacuum gripper as a tool
tool.set(tools.VACUUM_GRIPPER)

# complex example with custom TCP offset
my_tool = tools.VACUUM_GRIPPER
my_tool.tcp += Frame(z=10)
tool.set(my_tool)
class ozobot.ora.simple.frame

Class providing methods for controlling user frame of single robot. The methods are static, therefore they can be called without creating an instance of the class, for example:

_images/user-frame.svg

Robot’s Cartesian pose is the position with restpect to the selected Frame.

frame.set(...)
current_frame = frame.get()

with frame.context(...):
    ...
static context(frame: Frame)

Context manager for setting the current frame for a block of code.

Context manager that configures the selected frame for calls made within the code block.

Parameters:

frame – Frame to set for the code block.

frame.set(frames.WORLD)
move.linear(...)  # this movement is done in the world frame

with tool.context(tools.CONVEYOR):
    move.linear(...)  # this movement is done in the conveyor frame

move.linear(...)  # this movement is done in the world frame
static get() → Frame

Get the current frame.

Returns:

Current frame.

static set(frame: Frame) → None

Set the current frame.

Parameters:

frame – Frame to set.

# example code to set the CONVEYOR user frame
frame.set(frames.CONVEYOR)

# complex example with modified frame
modified_conveyor_frame = frames.CONVEYOR
modified_conveyor_frame.z = 100
frame.set(modified_conveyor_frame)
class ozobot.ora.simple.state

Class providing methods for getting the current state of the robot. The methods are static, therefore they can be called without creating an instance of the class, for example:

pose = state.get_pose()
joints = state.get_joints()
static get_joints() → Joints

Get the current joint configuration of the robot.

static get_pose() → Cartesian

Get the current pose of the robot in the current frame.

Units

Unit system allows to easily convert physical values with user preferred units to the units compatible with the robot. It also allows to do some basic type checking to prevent typos and unit mismatch. Some units can be combined, for example distance over time yields speed.

See also

Detailed description of the framework can be found in the Units document.

ozobot.ora.simple.units(number: float, units: PhysicalQuantity[_TDomain]) → Value[_TDomain]

Create an object representing numeric value with units.

Note

See Units for more information.

Parameters:

  • number – The numeric value.

  • units – The units.

Indices and tables