cozmo.robot¶

Classes and functions relating to an individual Cozmo robot.

The cozmo.conn.CozmoConnection.wait_for_robot() method returns an instance of Robot which controls a single Cozmo robot.

The Robot class has methods and properties to determine its current state, control its low-level motors, play animations and start behaviors as well as performing high-level actions such as detecting faces and picking up objects.

Each Robot has a Robot.world attribute which represents an instance of a cozmo.world.World. This tracks the state of the world that Cozmo knows about: The objects and faces it’s currently observing, the camera images it’s receiving, etc. You can monitor the world instance for various events that occur, or monitor individual objects directly: The world instance receives all events that the robot triggers, and nearly all SDK objects inherit from cozmo.event.Dispatcher and therefore inherit methods such as wait_for() and add_event_handler().

Classes

`DisplayOledFaceImage`(screen_data, …)	Represents the “display oled face image” action in progress.
`DockWithCube`(obj, approach_angle, …)	Represents the dock with cube action in progress.
`DriveOffChargerContacts`(**kw)	Represents the drive off charger contacts action in progress.
`DriveStraight`(distance, speed, …)	Represents the “drive straight” action in progress.
`EvtRobotReady`(**kwargs)	Generated when the robot has been initialized and is ready for commands.
`EvtRobotStateUpdated`(**kwargs)	Dispatched whenever the robot’s state is updated (multiple times per second).
`EvtUnexpectedMovement`(**kwargs)	Triggered whenever the robot does not move as expected (typically rotation).
`GoToObject`(object_id, distance_from_object, **kw)	Represents the go to object action in progress.
`GoToPose`(pose, **kw)	Represents the go to pose action in progress.
`LiftPosition`([height, ratio, angle])	Represents the position of Cozmo’s lift.
`PerformOffChargerContext`(robot, **kw)	A helper class to provide a context manager to do operations while Cozmo is off charger.
`PickupObject`(obj[, use_pre_dock_pose])	Represents the pickup object action in progress.
`PlaceObjectOnGroundHere`(obj, **kw)	Tracks the state of the “place object on ground here” action.
`PlaceOnObject`(obj[, use_pre_dock_pose])	Tracks the state of the “place on object” action.
`PopAWheelie`(obj, approach_angle, **kw)	Tracks the progress of a “pop a wheelie” robot action.
`Robot`(conn, robot_id, is_primary, **kw)	The interface to a Cozmo robot.
`RollCube`(obj, approach_angle, …)	Represents the roll cube action in progress.
`SayText`(text, play_excited_animation, …)	Tracks the progress of a say text robot action.
`SetHeadAngle`(angle, max_speed, accel, …)	Represents the Set Head Angle action in progress.
`SetLiftHeight`(height, max_speed, accel, …)	Represents the Set Lift Height action in progress.
`TurnInPlace`(angle, speed, accel, …)	Tracks the progress of a turn in place robot action.
`TurnTowardsFace`(face, **kw)	Tracks the progress of a turn towards face robot action.
`UnexpectedMovementSide`	Defines the side of collision that caused unexpected movement.
`UnexpectedMovementType`	Defines the type of unexpected movement.

cozmo.robot.MIN_HEAD_ANGLE = <Angle -0.44 radians (-25.00 degrees)>¶: The minimum angle the robot’s head can be set to

cozmo.robot.MAX_HEAD_ANGLE = <Angle 0.78 radians (44.50 degrees)>¶: The maximum angle the robot’s head can be set to

cozmo.robot.MIN_LIFT_HEIGHT = <Distance 32.00 mm (1.26 inches)>¶: The lowest height-above-ground that lift can be moved to

cozmo.robot.MAX_LIFT_HEIGHT = <Distance 92.00 mm (3.62 inches)>¶: The largest height-above-ground that lift can be moved to

cozmo.robot.MIN_LIFT_ANGLE = <Angle -0.20 radians (-11.36 degrees)>¶: The minimum angle the robot’s lift can be set to

cozmo.robot.MAX_LIFT_ANGLE = <Angle 0.79 radians (45.41 degrees)>¶: The maximum angle the robot’s lift can be set to

class cozmo.robot.EvtRobotReady(**kwargs)¶

Generated when the robot has been initialized and is ready for commands.

robot = 'Robot object representing the robot to command'¶

class cozmo.robot.EvtRobotStateUpdated(**kwargs)¶

Dispatched whenever the robot’s state is updated (multiple times per second).

robot = 'Robot object representing the robot to command'¶

class cozmo.robot.EvtUnexpectedMovement(**kwargs)¶

Triggered whenever the robot does not move as expected (typically rotation).

movement_side = 'An UnexpectedMovementSide Object representing the side that is obstructing movement'¶

movement_type = 'An UnexpectedMovementType Object representing the type of unexpected movement'¶

robot = 'Robot object representing the robot to command'¶

timestamp = 'Robot timestamp for when the unexpected movement occurred'¶

class cozmo.robot.LiftPosition(height=None, ratio=None, angle=None)¶

Represents the position of Cozmo’s lift.

The class allows the position to be referred to as either absolute height above the ground, as a ratio from 0.0 to 1.0, or as the angle of the lift arm relative to the ground.

Parameters:	height (`cozmo.util.Distance`) – The height of the lift above the ground. ratio (float) – The ratio from 0.0 to 1.0 that the lift is raised from the ground. angle (`cozmo.util.Angle`) – The angle of the lift arm relative to the ground.

angle¶

The angle of the lift arm relative to the ground.

Type:	`cozmo.util.Angle`

height¶

The height above the ground.

Type:	`cozmo.util.Distance`

ratio¶

The ratio from 0 to 1 that the lift is raised, 0 at the bottom, 1 at the top.

Type:	float

class cozmo.robot.UnexpectedMovementSide¶

Defines the side of collision that caused unexpected movement.

This will always be UNKNOWN while reaction triggers are disabled. Call cozmo.robot.Robot.enable_all_reaction_triggers() to enable reaction triggers.

Back = _UnexpectedMovementSide(name='Back', id=2)¶: Obstruction detected behind the robot.

Front = _UnexpectedMovementSide(name='Front', id=1)¶: Obstruction detected in front of the robot.

Left = _UnexpectedMovementSide(name='Left', id=3)¶: Obstruction detected to the left of the robot

Right = _UnexpectedMovementSide(name='Right', id=4)¶: Obstruction detected to the right of the robot

Unknown = _UnexpectedMovementSide(name='Unknown', id=0)¶: Unable to tell what side obstructed movement. Usually caused by reaction triggers being disabled.

class cozmo.robot.UnexpectedMovementType¶

Defines the type of unexpected movement.

TurnedButStopped = _UnexpectedMovementType(name='TurnedButStopped', id=0)¶: Tried to turn, but couldn’t.

TurnedInOppositeDirection = _UnexpectedMovementType(name='TurnedInOppositeDirection', id=2)¶: Expected to turn in one direction, but turned the other way. Also happens when rotation is unexpected.

class cozmo.robot.DisplayOledFaceImage(screen_data, duration_ms, **kw)¶

Represents the “display oled face image” action in progress.

Returned by display_oled_face_image()

duration_ms = None¶

time to keep displaying this image on Cozmo’s face

Type:	float

screen_data = None¶

a sequence of pixels (8 pixels per byte)

Type:	`bytes`

class cozmo.robot.DockWithCube(obj, approach_angle, alignment_type, distance_from_marker, **kw)¶

Represents the dock with cube action in progress.

Returned by dock_with_cube()

obj = None¶: The object (e.g. an instance of cozmo.objects.LightCube) that is being put down

class cozmo.robot.DriveOffChargerContacts(**kw)¶

Represents the drive off charger contacts action in progress.

Returned by drive_off_charger_contacts()

class cozmo.robot.DriveStraight(distance, speed, should_play_anim, **kw)¶

Represents the “drive straight” action in progress.

Returned by drive_straight()

distance = None¶

The distance to drive

Type:	`cozmo.util.Distance`

should_play_anim = None¶

Whether to play an animation whilst driving

Type:	bool

speed = None¶

The speed to drive at

Type:	`cozmo.util.Speed`

class cozmo.robot.GoToObject(object_id, distance_from_object, **kw)¶

Represents the go to object action in progress.

Returned by go_to_object()

class cozmo.robot.GoToPose(pose, **kw)¶

Represents the go to pose action in progress.

Returned by go_to_pose()

class cozmo.robot.PerformOffChargerContext(robot, **kw)¶: A helper class to provide a context manager to do operations while Cozmo is off charger.

class cozmo.robot.PickupObject(obj, use_pre_dock_pose=True, **kw)¶

Represents the pickup object action in progress.

Returned by pickup_object()

obj = None¶: The object (e.g. an instance of cozmo.objects.LightCube) that was picked up

use_pre_dock_pose = None¶: A bool that is true when Cozmo needs to go to a pose before attempting to navigate to the object

class cozmo.robot.PlaceObjectOnGroundHere(obj, **kw)¶

Tracks the state of the “place object on ground here” action.

Returned by place_object_on_ground_here()

obj = None¶: The object (e.g. an instance of cozmo.objects.LightCube) that is being put down

class cozmo.robot.PlaceOnObject(obj, use_pre_dock_pose=True, **kw)¶

Tracks the state of the “place on object” action.

return by place_on_object()

obj = None¶: The object (e.g. an instance of cozmo.objects.LightCube) that the held object will be placed on

use_pre_dock_pose = None¶: A bool that is true when Cozmo needs to go to a pose before attempting to navigate to the object

class cozmo.robot.PopAWheelie(obj, approach_angle, **kw)¶

Tracks the progress of a “pop a wheelie” robot action.

Returned by pop_a_wheelie()

obj = None¶: An object (e.g. an instance of cozmo.objects.LightCube) being used as leverage to push cozmo on his back

class cozmo.robot.RollCube(obj, approach_angle, check_for_object_on_top, **kw)¶

Represents the roll cube action in progress.

Returned by roll_cube()

check_for_object_on_top = None¶

whether to check if there is an object on top

Type:	bool

obj = None¶: The object (e.g. an instance of cozmo.objects.LightCube) that is being put down

class cozmo.robot.SayText(text, play_excited_animation, use_cozmo_voice, duration_scalar, voice_pitch, **kw)¶

Tracks the progress of a say text robot action.

Returned by say_text()

class cozmo.robot.SetHeadAngle(angle, max_speed, accel, duration, warn_on_clamp, **kw)¶

Represents the Set Head Angle action in progress. Returned by set_head_angle()

accel = None¶

Acceleration of Cozmo’s head in radians per second squared

Type:	float

duration = None¶

Time for Cozmo’s head to turn in seconds

Type:	float

max_speed = None¶

Maximum speed of Cozmo’s head in radians per second

Type:	float

class cozmo.robot.SetLiftHeight(height, max_speed, accel, duration, **kw)¶

Represents the Set Lift Height action in progress. Returned by set_lift_height()

accel = None¶

Acceleration of Cozmo’s lift in radians per second squared

Type:	float

duration = None¶

Time for Cozmo’s lift to turn in seconds

Type:	float

max_speed = None¶

Maximum speed of Cozmo’s lift in radians per second

Type:	float

class cozmo.robot.TurnInPlace(angle, speed, accel, angle_tolerance, is_absolute, **kw)¶

Tracks the progress of a turn in place robot action.

Returned by turn_in_place()

accel = None¶

Acceleration of angular turn (per second squared).

Type:	`cozmo.util.Angle`

angle = None¶

The angle to turn

Type:	`cozmo.util.Angle`

angle_tolerance = None¶

The minimum angular tolerance to consider the action complete (this is clamped to a minimum of 2 degrees internally).

Type:	`cozmo.util.Angle`

is_absolute = None¶

True to turn to a specific angle, False to turn relative to the current pose.

Type:	bool

speed = None¶

Angular turn speed (per second).

Type:	`cozmo.util.Angle`

class cozmo.robot.TurnTowardsFace(face, **kw)¶

Tracks the progress of a turn towards face robot action.

Returned by turn_towards_face()

face = None¶

The face to turn towards

Type:	`Face`

class cozmo.robot.Robot(conn, robot_id: int, is_primary: bool, **kw)¶

The interface to a Cozmo robot.

A robot has access to:

A World object (cozmo.robot.Robot.world),

which tracks the state of the world the robot knows about
A Camera object (cozmo.robot.Robot.camera),

which provides access to Cozmo’s camera
An Animations object, controlling the playing of animations on the robot
A Behaviors object, starting and ending robot behaviors such as looking around

Robots are instantiated by the CozmoConnection object and emit a EvtRobotReady when it has been configured and is ready to be commanded.

abort_all_actions(log_abort_messages=False)¶

Abort all actions on this robot

Parameters:	log_abort_messages (bool) – True to log info on every action that is aborted.

Abort / Cancel any action that is currently either running or queued within the engine

accelerometer = None¶

The current accelerometer reading (x,y,z) In mm/s^2, measured in Cozmo’s head (e.g. x=0 when Cozmo’s head is level but x = z = ~7000 mm/s^2 when Cozmo’s head is angled 45 degrees up)

Type:	`cozmo.util.Vector3`

anim_names¶

Set of all the available animation names

An alias of cozmo.conn.anim_names.

Generally animation triggers are preferred over explict animation names: See cozmo.anim.Triggers for available animation triggers.

Type:	set of string

anim_triggers¶

list of cozmo.anim.Triggers, specifying available animation triggers

These can be sent to the play_anim_trigger to make the robot perform animations.

An alias of cozmo.anim.Triggers.trigger_list.

animation_factory = functools.partial(<class 'cozmo.anim.Animation'>, loop=None)¶

The factory function that returns a cozmo.anim.Animation class or subclass instance.

Type:	callable

animation_trigger_factory = functools.partial(<class 'cozmo.anim.AnimationTrigger'>, loop=None)¶

The factory function that returns a cozmo.anim.AnimationTrigger class or subclass instance.

Type:	callable

are_wheels_moving¶

True if Cozmo’s wheels/treads are currently moving.

Type:	bool

backup_onto_charger(max_drive_time=3)¶

Attempts to reverse robot onto its charger.

This method assumes the charger is directly behind the robot and will keep driving straight back until charger is in contact, or until a timeout is reached.

Parameters:	max_drive_time (float) – The maximum amount of time in seconds to reverse the robot without detecting the charger.

battery_voltage = None¶

The current battery voltage (not linear, but < 3.5 is low)

Type:	float

behavior_factory = functools.partial(<class 'cozmo.behavior.Behavior'>, loop=None)¶

The factory function that returns a cozmo.behavior.Behavior class or subclass instance.

Type:	callable

camera = None¶

Provides access to the robot’s camera

Type:	`cozmo.camera.Camera`

camera_config¶

The read-only config/calibration for this robot’s camera

Deprecated since version 0.12.0: Use: cozmo.camera.Camera.config() instead.

Type:	`cozmo.robot.CameraConfig`

camera_factory = functools.partial(<class 'cozmo.camera.Camera'>, loop=None)¶

The factory function that returns a cozmo.camera.Camera class or subclass instance.

Type:	callable

carrying_object_id = None¶

The ID of the object currently being carried (-1 if none)

Type:	int

carrying_object_on_top_id = None¶

The ID of the object on top of the object currently being carried (-1 if none)

Type:	int

clear_idle_animation()¶: Clears any Idle Animation currently playing on Cozmo

conn = None¶

The active connection to the engine.

Type:	`cozmo.conn.CozmoConnection`

current_behavior¶

Cozmo’s currently active behavior.

Type:	`cozmo.behavior.Behavior`

device_accel_raw = None¶

The current accelerometer reading for the connected mobile device. Requires that you have first called enable_device_imu() with enable_raw = True. See device_accel_user for a user-filtered equivalent.

Type:	`cozmo.util.Vector3`

device_accel_user = None¶

The current user-filtered accelerometer reading for the connected mobile device. Requires that you have first called enable_device_imu() with enable_user = True. This filtered version removes the constant acceleration from Gravity. See device_accel_raw for a raw version.

Type:	`cozmo.util.Vector3`

device_gyro = None¶

The current gyro reading for the connected mobile device. Requires that you have first called enable_device_imu() with enable_gyro = True

Type:	`cozmo.util.Quaternion`

display_oled_face_image(screen_data, duration_ms, in_parallel=True)¶

Display a bitmap image on Cozmo’s OLED face screen.

Parameters:

screen_data (bytes) – a sequence of pixels (8 pixels per byte) (from e.g. cozmo.oled_face.convert_pixels_to_screen_data()).
duration_ms (float) – time to keep displaying this image on Cozmo’s face (clamped to 30 seconds in engine).
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.

Returns:

A cozmo.robot.DisplayOledFaceImage action object which: can be queried to see when it is complete.

Raises:

:class:`cozmo.exceptions.RobotBusy` if another action is already – running and in_parallel==False

display_oled_face_image_factory = functools.partial(<class 'cozmo.robot.DisplayOledFaceImage'>, loop=None)¶

The factory function that returns a DisplayOledFaceImage class or subclass instance.

Type:	callable

dock_with_cube(target_object, approach_angle=None, alignment_type=_RobotAlignmentType(name='LiftPlate', id=1), distance_from_marker=None, in_parallel=False, num_retries=0)¶

Tells Cozmo to dock with a specified cube object.

Parameters:

target_object (cozmo.objects.LightCube) – The cube to dock with.
approach_angle (cozmo.util.Angle) – The angle to approach the cube from. For example, 180 degrees will cause cozmo to drive past the cube and approach it from behind.
alignment_type (cozmo.robot_alignment.RobotAlignmentTypes) – which part of the robot to line up with the front of the object.
distance_from_marker (cozmo.util.Distance) – distance from the cube marker to stop when using Custom alignment
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.DockWithCube action object which can be queried: to see when it is complete.

dock_with_cube_factory = functools.partial(<class 'cozmo.robot.DockWithCube'>, loop=None)¶

The factory function that returns a DockWithCube class or subclass instance.

Type:	callable

drive_off_charger_contacts(in_parallel=False, num_retries=0)¶

Tells Cozmo to drive forward slightly to get off the charger contacts.

All motor movement is disabled while Cozmo is on the charger to prevent hardware damage. This command is the one exception and provides a way to drive forward a little to disconnect from the charger contacts and thereby re-enable all other commands.

Parameters:

in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.DriveOffChargerContacts action object which: can be queried to see when it is complete.

drive_off_charger_contacts_factory = functools.partial(<class 'cozmo.robot.DriveOffChargerContacts'>, loop=None)¶

The factory function that returns a DriveOffChargerContacts class or subclass instance.

Type:	callable

drive_off_charger_on_connect = True¶

Set to True if the robot should drive off the charger as soon as the SDK connects to the engine. Defaults to True.

Type:	bool

drive_straight(distance, speed, should_play_anim=True, in_parallel=False, num_retries=0)¶

Tells Cozmo to drive in a straight line

Cozmo will drive for the specified distance (forwards or backwards)

Parameters:

distance (cozmo.util.Distance) – The distance to drive (>0 for forwards, <0 for backwards)
speed (cozmo.util.Speed) – The speed to drive at (should always be >0, the abs(speed) is used internally)
should_play_anim (bool) – Whether to play idle animations whilst driving (tilt head, hum, animated eyes, etc.)
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.DriveStraight action object which: can be queried to see when it is complete.

drive_straight_factory = functools.partial(<class 'cozmo.robot.DriveStraight'>, loop=None)¶

The factory function that returns a DriveStraight class or subclass instance.

Type:	callable

drive_wheel_motors(l_wheel_speed, r_wheel_speed, l_wheel_acc=None, r_wheel_acc=None)¶

Tell Cozmo to move his wheels / treads at a given speed.

The wheels will continue to move at that speed until commanded to drive at a new speed, or if stop_all_motors() is called.

Parameters:

l_wheel_speed (float) – Speed of the left tread (in millimeters per second)
r_wheel_speed (float) – Speed of the right tread (in millimeters per second)
l_wheel_acc (float) – Acceleration of left tread (in millimeters per second squared) None value defaults this to the same as l_wheel_speed.
r_wheel_acc (float) – Acceleration of right tread (in millimeters per second squared) None value defaults this to the same as r_wheel_speed.

drive_wheels(l_wheel_speed, r_wheel_speed, l_wheel_acc=None, r_wheel_acc=None, duration=None)¶

Tell Cozmo to move his wheels / treads at a given speed, and optionally stop them after a given duration.

If duration is None then this is equivalent to the non-async drive_wheel_motors() method.

Parameters:

l_wheel_speed (float) – Speed of the left tread (in millimeters per second).
r_wheel_speed (float) – Speed of the right tread (in millimeters per second).
l_wheel_acc (float) – Acceleration of left tread (in millimeters per second squared). None value defaults this to the same as l_wheel_speed.
r_wheel_acc (float) – Acceleration of right tread (in millimeters per second squared). None value defaults this to the same as r_wheel_speed.
duration (float) – Time for the robot to drive. Will call stop_all_motors() after this duration has passed.

enable_all_reaction_triggers(should_enable)¶

Enable or disable Cozmo’s responses to being handled or observing the world.

Parameters:	should_enable (bool) – True if the robot should react to its environment.

enable_auto_exposure()¶: Deprecated since version 0.12.0: Use: cozmo.camera.Camera.enable_auto_exposure() instead.

enable_device_imu(enable_raw=False, enable_user=False, enable_gyro=False)¶

Enable streaming of the connected Mobile devices’ IMU data.

The accelerometer and gyro data for the connected phone or tablet can be streamed from the app to the SDK. You can request any combination of the 3 data types.

Parameters:	enable_raw (bool) – True to enable streaming of the raw accelerometer data, which can be accessed via `device_accel_raw` enable_user (bool) – True to enable streaming of the user-filtered accelerometer data, which can be accessed via `device_accel_user` enable_gyro (bool) – True to enable streaming of the gyro data, which can be accessed via `device_gyro`

enable_facial_expression_estimation(enable=True)¶

Enable or Disable facial expression estimation

Cozmo can optionally estimate the facial expression for human faces to see if he thinks they’re happy, sad, etc.

Parameters:	enable (bool) – True to enable facial expression estimation, False to disable it. By default Cozmo starts with it disabled to save on processing time.

enable_freeplay_cube_lights(enable=True)¶

Enable, or disable, the automatic cube light mode used in freeplay.

Enabling the freeplay cube light mode causes the cubes to automatically pulse blue when Cozmo can see them - as seen in the Cozmo app during freeplay mode. This is disabled by default in SDK mode because it overrides any other calls to set the cube light colors.

Parameters:	enable (bool) – True to enable the freeplay cube light mode, False to disable it.

enable_stop_on_cliff(enable)¶

Enable or disable Cozmo’s ability to drive off a cliff.

Parameters:	enable (bool) – True if the robot should stop moving when a cliff is encountered.

go_to_object(target_object, distance_from_object, in_parallel=False, num_retries=0)¶

Tells Cozmo to drive to the specified object.

Parameters:

target_object (cozmo.objects.ObservableObject) – The destination object. CustomObject instances are not supported.
distance_from_object (cozmo.util.Distance) – The distance from the object to stop. This is the distance between the origins. For instance, the distance from the robot’s origin (between Cozmo’s two front wheels) to the cube’s origin (at the center of the cube) is ~40mm.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.GoToObject action object which can be queried: to see when it is complete.

go_to_object_factory = functools.partial(<class 'cozmo.robot.GoToObject'>, loop=None)¶

The factory function that returns a GoToObject class or subclass instance.

Type:	callable

go_to_pose(pose, relative_to_robot=False, in_parallel=False, num_retries=0)¶

Tells Cozmo to drive to the specified pose and orientation.

If relative_to_robot is set to True, the given pose will assume the robot’s pose as its origin.

Since the robot understands position by monitoring its tread movement, it does not understand movement in the z axis. This means that the only applicable elements of pose in this situation are position.x position.y and rotation.angle_z.

Parameters:

pose – (cozmo.util.Pose): The destination pose.
relative_to_robot (bool) – Whether the given pose is relative to the robot’s pose.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.GoToPose action object which can be queried: to see when it is complete.

go_to_pose_factory = functools.partial(<class 'cozmo.robot.GoToPose'>, loop=None)¶

The factory function that returns a GoToPose class or subclass instance.

Type:	callable

gyro = None¶

The current gyro reading (x,y,z) In radians/s, measured in Cozmo’s head. Therefore a large value in a given component would indicate Cozmo is being rotated around that axis (where x=forward, y=left, z=up), e.g. y = -5 would indicate that Cozmo is being rolled onto his back

Type:	`cozmo.util.Vector3`

has_in_progress_actions¶

True if Cozmo has any SDK-triggered actions still in progress.

Type:	bool

head_angle¶

Cozmo’s head angle (up/down).

Type:	`cozmo.util.Angle`

head_tracking_object_id = None¶

The ID of the object the head is tracking to (-1 if none)

Type:	int

is_anim_buffer_full¶

True if Cozmo’s animation buffer is full (on robot).

Type:	bool

is_animating¶

True if Cozmo is currently playing an animation.

Type:	bool

is_animating_idle¶

True if Cozmo is currently playing an idle animation.

Type:	bool

is_behavior_running¶

True if Cozmo is currently running a behavior.

When Cozmo is running a behavior he will behave fairly autonomously (playing animations and other actions as desired). Attempting to drive Cozmo whilst in this mode will likely have unexpected behavior on the robot and confuse Cozmo.

Type:	bool

is_carrying_block¶

True if Cozmo is currently carrying a block.

Type:	bool

is_charging¶

True if Cozmo is currently charging.

Type:	bool

is_cliff_detected¶

True if Cozmo detected a cliff (in front of the robot).

Type:	bool

is_device_accelerometer_supported¶

True if the attached mobile device supports accelerometer data.

Type:	bool

is_device_gyro_supported¶

True if the attached mobile device supports gyro data.

Type:	bool

is_falling¶

True if Cozmo is currently falling.

Type:	bool

is_freeplay_mode_active¶

True if Cozmo is in freeplay mode.

When Cozmo is in freeplay mode he will behave autonomously (playing behaviors, animations and other actions as desired). Attempting to drive Cozmo whilst in this mode will likely have unexpected behavior on the robot and confuse Cozmo.

Type:	bool

is_head_in_pos¶

True if Cozmo’s head is in the desired position (False if still trying to move there).

Type:	bool

is_lift_in_pos¶

True if Cozmo’s lift is in the desired position (False if still trying to move there).

Type:	bool

is_localized¶

True if Cozmo is localized (i.e. knows where he is with respect to a cube, and has both treads on the ground).

Type:	bool

is_moving¶

True if Cozmo is currently moving anything (head, lift or wheels/treads).

Type:	bool

is_on_charger¶

True if Cozmo is currently on the charger.

Type:	bool

is_pathing¶

True if Cozmo is currently traversing a path.

Type:	bool

is_picked_up¶

True if Cozmo is currently picked up (in the air).

Type:	bool

is_picking_or_placing¶

True if Cozmo is picking or placing something.

Type:	bool

is_primary = None¶

Specifies that this is the primary robot (always True currently)

Type:	bool

is_ready¶

True if the robot has been initialized and is ready to accept commands.

Type:	bool

last_image_robot_timestamp = None¶

The robot’s timestamp for the last image seen. None if no image was received yet. In milliseconds relative to robot epoch.

Type:	int

left_wheel_speed = None¶

Speed of the left wheel

Type:	`cozmo.util.Speed`

lift_angle¶

Angle of Cozmo’s lift relative to the ground.

In MIN_LIFT_ANGLE to MAX_LIFT_ANGLE range.

Type:	`cozmo.util.Angle`

lift_height¶

Height of Cozmo’s lift from the ground.

In MIN_LIFT_HEIGHT to MAX_LIFT_HEIGHT range.

Type:	`cozmo.util.Distance`

lift_position¶

The position of Cozmo’s lift.

Type:	`LiftPosition`

lift_ratio¶

Ratio from 0 to 1 of how high Cozmo’s lift is.

Type:	float

localized_to_object_id = None¶

The ID of the object that the robot is localized to (-1 if none)

Type:	int

move_head(speed)¶

Tell Cozmo’s head motor to move with a certain speed.

Positive speed for up, negative speed for down. Measured in radians per second.

Parameters:	speed (float) – Motor speed for Cozmo’s head, measured in radians per second.

move_lift(speed)¶

Tell Cozmo’s lift motor to move with a certain speed.

Positive speed for up, negative speed for down. Measured in radians per second.

Parameters:	speed (float) – Motor speed for Cozmo’s lift, measured in radians per second.

perform_off_charger()¶

Returns a context manager to move the robot off of and back onto the charger.

If the robot is on the charger, it will move a short distance off the contacts, perform the code wrapped by the context and then move the robot back onto the charger after the wrapped code completes.

Synchronous example:

with robot.perform_off_charger():
    action = robot.say_text("Hello")
    action.wait_for_completed()

Asynchronous example:

async with robot.perform_off_charger():
    action = robot.say_text("Hello")
    await action.wait_for_completed()

perform_off_charger_factory = functools.partial(<class 'cozmo.robot.PerformOffChargerContext'>, loop=None)¶

The factory function that returns a cozmo.robot.PerformOffChargerContext class or subclass instance.

Type:	callable

pickup_object(obj, use_pre_dock_pose=True, in_parallel=False, num_retries=0)¶

Instruct the robot to pick up the supplied object.

Parameters:

obj (cozmo.objects.ObservableObject) – The target object to pick up where obj.pickupable is True.
use_pre_dock_pose (bool) – whether or not to try to immediately pick up an object or first position the robot next to the object.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.PickupObject action object which can be: queried to see when it is complete.

Raises:

:class:`cozmo.exceptions.RobotBusy` if another action is already – running and in_parallel==False
cozmo.exceptions.NotPickupable if object type can’t be picked up.

pickup_object_factory = functools.partial(<class 'cozmo.robot.PickupObject'>, loop=None)¶

The factory function that returns a PickupObject class or subclass instance.

Type:	callable

place_object_on_ground_here(obj, in_parallel=False, num_retries=0)¶

Ask Cozmo to place the object he is carrying on the ground at the current location.

Parameters:

in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.PlaceObjectOnGroundHere action object which: can be queried to see when it is complete.

Raises:

:class:`cozmo.exceptions.RobotBusy` if another action is already – running and in_parallel==False

place_object_on_ground_here_factory = functools.partial(<class 'cozmo.robot.PlaceObjectOnGroundHere'>, loop=None)¶

The factory function that returns a PlaceObjectOnGroundHere class or subclass instance.

Type:	callable

place_on_object(obj, use_pre_dock_pose=True, in_parallel=False, num_retries=0)¶

Asks Cozmo to place the currently held object onto a target object.

Parameters:

obj (cozmo.objects.ObservableObject) – The target object to place current held object on, where obj.place_objects_on_this is True.
use_pre_dock_pose (bool) – Whether or not to try to immediately pick up an object or first position the robot next to the object.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.PlaceOnObject action object which can be: queried to see when it is complete.

Raises:

:class:`cozmo.exceptions.RobotBusy` if another action is already – running and in_parallel==False
cozmo.exceptions.CannotPlaceObjectsOnThis if the object cannot have objects
placed on it.

place_on_object_factory = functools.partial(<class 'cozmo.robot.PlaceOnObject'>, loop=None)¶

The factory function that returns a PlaceOnObject class or subclass instance.

Type:	callable

play_anim(name, loop_count=1, in_parallel=False, num_retries=0, ignore_body_track=False, ignore_head_track=False, ignore_lift_track=False)¶

Starts an animation playing on a robot.

Returns an Animation object as soon as the request to play the animation has been sent. Call the wait_for_completed method on the animation if you wish to wait for completion (or listen for the cozmo.anim.EvtAnimationCompleted event).

Warning: Specific animations may be renamed or removed in future updates of the app.: If you want your program to work more reliably across all versions we recommend using play_anim_trigger() instead.

Parameters:

name (str) – The name of the animation to play.
loop_count (int) – Number of times to play the animation.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.
ignore_body_track (bool) – True to ignore the animation track for Cozmo’s body (i.e. the wheels / treads).
ignore_head_track (bool) – True to ignore the animation track for Cozmo’s head.
ignore_lift_track (bool) – True to ignore the animation track for Cozmo’s lift.

Returns:

A cozmo.anim.Animation action object which can be queried: to see when it is complete.

Raises:

ValueError if supplied an invalid animation name.

play_anim_trigger(trigger, loop_count=1, in_parallel=False, num_retries=0, use_lift_safe=False, ignore_body_track=False, ignore_head_track=False, ignore_lift_track=False)¶

Starts an animation trigger playing on a robot.

As noted in the Triggers class, playing a trigger requests that an animation of a certain class starts playing, rather than an exact animation name as influenced by the robot’s mood, and other factors.

Parameters:

trigger (object) – An attribute of the cozmo.anim.Triggers class
loop_count (int) – Number of times to play the animation
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.
use_lift_safe (bool) – True to automatically ignore the lift track if Cozmo is currently carrying an object.
ignore_body_track (bool) – True to ignore the animation track for Cozmo’s body (i.e. the wheels / treads).
ignore_head_track (bool) – True to ignore the animation track for Cozmo’s head.
ignore_lift_track (bool) – True to ignore the animation track for Cozmo’s lift.

Returns:

A cozmo.anim.AnimationTrigger action object which can be: queried to see when it is complete

Raises:

ValueError if supplied an invalid animation trigger.

play_audio(audio_event)¶

Sends an audio event to the engine

Most of these come in pairs, with one to start an audio effect, and one to stop if desired.

Example

cozmo.audio.AudioEvents.SfxSharedSuccess starts a sound cozmo.audio.AudioEvents.SfxSharedSuccessStop interrupts that sound in progress

Some events are part of the TinyOrchestra system which have special behavior. This system can be intitialized and stopped, and various musical instruments can be turned on and off while it is running.

Parameters:	audio_event (object) – An attribute of the `cozmo.audio.AudioEvents` class

play_song(song_notes, loop_count=1, in_parallel=False, num_retries=0)¶

Starts playing song on the robot.

Plays a provided array of SongNotes using a custom animation on the robot.

Parameters:	song_notes (object[]) – An array of `cozmo.song.SongNote` classes
Returns:	A `cozmo.anim.Animation` action object which can be queried to see when it is complete.

pop_a_wheelie(target_object, approach_angle=None, in_parallel=False, num_retries=0)¶

Tells Cozmo to “pop a wheelie” using a light cube.

Parameters:

target_object (cozmo.objects.LightCube) – The cube to push down on with cozmo’s lift, to start the wheelie.
approach_angle (cozmo.util.Angle) – The angle to approach the cube from. For example, 180 degrees will cause cozmo to drive past the cube and approach it from behind.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.PopAWheelie action object which can be queried: to see when it is complete.

pop_a_wheelie_factory = functools.partial(<class 'cozmo.robot.PopAWheelie'>, loop=None)¶

The factory function that returns a PopAWheelie class or subclass instance.

Type:	callable

pose¶

The current pose (position and orientation) of Cozmo

Type:	`cozmo.util.Pose`

pose_angle¶

Cozmo’s pose angle (heading in X-Y plane).

Type:	`cozmo.util.Angle`

pose_pitch¶

Cozmo’s pose pitch (angle up/down).

Type:	`cozmo.util.Angle`

right_wheel_speed = None¶

Speed of the right wheel

Type:	`cozmo.util.Speed`

robot_id = None¶

The internal ID number of the robot.

Type:	int

roll_cube(target_object, approach_angle=None, check_for_object_on_top=False, in_parallel=False, num_retries=0)¶

Tells Cozmo to roll a specified cube object.

Parameters:

target_object (cozmo.objects.LightCube) – The cube to roll.
approach_angle (cozmo.util.Angle) – The angle to approach the cube from. For example, 180 degrees will cause cozmo to drive past the cube and approach it from behind.
check_for_object_on_top (bool) – If there is a cube on top of the specified cube, and check_for_object_on_top is True, then Cozmo will ignore the action.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.RollCube action object which can be queried: to see when it is complete.

roll_cube_factory = functools.partial(<class 'cozmo.robot.RollCube'>, loop=None)¶

The factory function that returns a RollCube class or subclass instance.

Type:	callable

run_timed_behavior(behavior_type, active_time)¶

Executes a behavior for a set number of seconds.

This call blocks and stops the behavior after active_time seconds.

Parameters:	behavior_type (`cozmo.behavior._BehaviorType`) – An attribute of `cozmo.behavior.BehaviorTypes`. active_time (float) – specifies the maximum time to execute in seconds
Raises:	`TypeError` if an invalid behavior type is supplied.

say_text(text, play_excited_animation=False, use_cozmo_voice=True, duration_scalar=1.0, voice_pitch=0.0, in_parallel=False, num_retries=0)¶

Have Cozmo say text!

Parameters:

text (string) – The words for Cozmo to say.
play_excited_animation (bool) – Whether to also play an excited animation while speaking (moves Cozmo a lot).
use_cozmo_voice (bool) – Whether to use Cozmo’s robot voice (otherwise, he uses a generic human male voice).
duration_scalar (float) – Adjust the relative duration of the generated text to speech audio.
voice_pitch (float) – Adjust the pitch of Cozmo’s robot voice [-1.0, 1.0]
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.SayText action object which can be: queried to see when it is complete

say_text_factory = functools.partial(<class 'cozmo.robot.SayText'>, loop=None)¶

The factory function that returns a SayText class or subclass instance.

Type:	callable

serial¶

The serial number, as a hex-string (e.g “02e08032”), for the robot.

This matches the Cozmo Serial value in the About section of the settings menu in the app.

Type:	string

set_all_backpack_lights(light)¶

Set the lights on Cozmo’s backpack to the same color.

Parameters:	light (`cozmo.lights.Light`) – The lights for Cozmo’s backpack.

set_backpack_lights(light1, light2, light3, light4, light5)¶

Set the lights on Cozmo’s backpack.

The light descriptions below are all from Cozmo’s perspective.

Note: The left and right lights only contain red LEDs, so e.g. setting them to green will look off, and setting them to white will look red

Parameters:	light1 (`cozmo.lights.Light`) – The left backpack light light2 (`cozmo.lights.Light`) – The front backpack light light3 (`cozmo.lights.Light`) – The center backpack light light4 (`cozmo.lights.Light`) – The rear backpack light light5 (`cozmo.lights.Light`) – The right backpack light

set_backpack_lights_off()¶: Set the lights on Cozmo’s backpack to off.

set_center_backpack_lights(light)¶

Set the lights in the center of Cozmo’s backpack to the same color.

Forces the lights on the left and right to off (this is useful as those lights only support shades of red, so cannot generally be set to the same color as the center lights).

Parameters:	light (`cozmo.lights.Light`) – The lights for Cozmo’s backpack.

set_head_angle(angle, accel=10.0, max_speed=10.0, duration=0.0, warn_on_clamp=True, in_parallel=False, num_retries=0)¶

Tell Cozmo’s head to turn to a given angle.

Parameters:

angle – (cozmo.util.Angle): Desired angle for Cozmo’s head. (MIN_HEAD_ANGLE to MAX_HEAD_ANGLE).
accel (float) – Acceleration of Cozmo’s head in radians per second squared.
max_speed (float) – Maximum speed of Cozmo’s head in radians per second.
duration (float) – Time for Cozmo’s head to turn in seconds. A value of zero will make Cozmo try to do it as quickly as possible.
warn_on_clamp (bool) – True to log a warning if the angle had to be clamped to the valid range (MIN_HEAD_ANGLE to MAX_HEAD_ANGLE).
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.SetHeadAngle action object which can be: queried to see when it is complete

set_head_angle_factory = functools.partial(<class 'cozmo.robot.SetHeadAngle'>, loop=None)¶

The factory function that returns a SetHeadAngle class or subclass instance.

Type:	callable

set_head_light(enable)¶

Turn Cozmo’s IR headlight on or off.

The headlight is on the front of Cozmo’s chassis, between his two front wheels, underneath his head. Cozmo’s camera is IR sensitive so although you cannot see the IR light with the naked eye you will see it in Cozmo’s camera feed.

Parameters:	enable (bool) – True turns the light on, False turns it off.

set_idle_animation(anim_trigger)¶

Set the Idle Animation on Cozmo

Idle animations keep Cozmo alive inbetween the times other animations play. They behave the same as regular animations except that they loop forever until another animation is started.

Parameters:	anim_trigger (`cozmo.anim.Triggers`) – The animation trigger to set
Raises:	`ValueError` if supplied an invalid animation trigger.

set_lift_height(height, accel=10.0, max_speed=10.0, duration=0.0, in_parallel=False, num_retries=0)¶

Tell Cozmo’s lift to move to a given height

Parameters:

height (float) – desired height for Cozmo’s lift 0.0 (bottom) to 1.0 (top) (we clamp it to this range internally).
accel (float) – Acceleration of Cozmo’s lift in radians per second squared.
max_speed (float) – Maximum speed of Cozmo’s lift in radians per second.
duration (float) – Time for Cozmo’s lift to move in seconds. A value of zero will make Cozmo try to do it as quickly as possible.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.SetLiftHeight action object which can be: queried to see when it is complete.

set_lift_height_factory = functools.partial(<class 'cozmo.robot.SetLiftHeight'>, loop=None)¶

The factory function that returns a SetLiftHeight class or subclass instance.

Type:	callable

set_manual_exposure(exposure_ms, gain)¶: Deprecated since version 0.12.0: Use: cozmo.camera.Camera.set_manual_exposure() instead.

set_needs_levels(repair_value=1, energy_value=1, play_value=1)¶

Manually set Cozmo’s current needs levels.

The needs levels control whether Cozmo needs repairing, feeding or playing with. Values outside of the 0.0 to 1.0 range are clamped internally.

Parameters:	repair_value (float) – How repaired is Cozmo - 0=’broken’, 1=’fully repaired’ energy_value (float) – How energetic is Cozmo - 0=’no-energy’, 1=’full energy’ play_value (float) – How in need of play is Cozmo - 0=’bored’, 1=’happy’

set_robot_volume(robot_volume)¶

Set the volume for the speaker in the robot.

Parameters:	robot_volume (float) – The new volume (0.0 = mute, 1.0 = max).

start_behavior(behavior_type)¶

Starts executing a behavior.

Call the stop() method on the behavior object at some point in the future to terminate execution.

Parameters:	behavior_type (`cozmo.behavior._BehaviorType`) – An attribute of `cozmo.behavior.BehaviorTypes`.
Returns:	`cozmo.behavior.Behavior`
Raises:	`TypeError` if an invalid behavior type is supplied.

start_freeplay_behaviors()¶

Start running freeplay behaviors on Cozmo

Puts Cozmo into a freeplay mode where he autonomously drives around and does stuff based on his mood and environment.

You shouldn’t attempt to drive Cozmo during this, as it will clash with whatever the current behavior is attempting to do.

stop_all_motors()¶: Tell Cozmo to stop all motors.

stop_freeplay_behaviors()¶

Stop running freeplay behaviors on Cozmo

Forces Cozmo out of Freeplay mode and stops any currently running behaviors and actions.

turn_in_place(angle, in_parallel=False, num_retries=0, speed=None, accel=None, angle_tolerance=None, is_absolute=False)¶

Turn the robot around its current position.

Parameters:

angle (cozmo.util.Angle) – The angle to turn. Positive values turn to the left, negative values to the right.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.
speed (cozmo.util.Angle) – Angular turn speed (per second).
accel (cozmo.util.Angle) – Acceleration of angular turn (per second squared).
angle_tolerance (cozmo.util.Angle) – angular tolerance to consider the action complete (this is clamped to a minimum of 2 degrees internally).
is_absolute (bool) – True to turn to a specific angle, False to turn relative to the current pose.

Returns:

A cozmo.robot.TurnInPlace action object which can be: queried to see when it is complete.

turn_in_place_factory = functools.partial(<class 'cozmo.robot.TurnInPlace'>, loop=None)¶

The factory function that returns a TurnInPlace class or subclass instance.

Type:	callable

turn_towards_face(face, in_parallel=False, num_retries=0)¶

Tells Cozmo to turn towards this face.

Parameters:

face – (cozmo.faces.Face): The face Cozmo will turn towards.
in_parallel (bool) – True to run this action in parallel with previous actions, False to require that all previous actions be already complete.
num_retries (int) – Number of times to retry the action if the previous attempt(s) failed.

Returns:

A cozmo.robot.TurnTowardsFace action object which can be: queried to see when it is complete

turn_towards_face_factory = functools.partial(<class 'cozmo.robot.TurnTowardsFace'>, loop=None)¶

The factory function that returns a TurnTowardsFace class or subclass instance.

Type:	callable

wait_for_all_actions_completed()¶: Waits until all SDK-initiated actions are complete.

world = None¶

Tracks state information about Cozmo’s world.

Type:	`cozmo.world.World`

world_factory = functools.partial(<class 'cozmo.world.World'>, loop=None)¶

The factory function that returns a cozmo.world.World class or subclass instance.

Type:	callable