cozmo.run¶

The run module contains helper classes and functions for opening a connection to the engine.

To get started, the run_program() function can be used for most cases, it handles connecting to a device and then running the function you provide with the SDK-provided Robot object passed in.

The connect() function can be used to open a connection and run your own code connected to a cozmo.conn.CozmoConnection instance. It takes care of setting up an event loop, finding the Android or iOS device running the Cozmo app and making sure the connection is ok.

You can also use the connect_with_tkviewer() or connect_with_3dviewer() functions which works in a similar way to connect(), but will also display either a a window on the screen showing a view from Cozmo’s camera (using Tk), or a 3d viewer (with optional 2nd window showing Cozmo’s camera) (using OpenGL), if supported on your system.

Finally, more advanced progarms can integrate the SDK with an existing event loop by using the connect_on_loop() function.

All of these functions make use of a DeviceConnector subclass to deal with actually connecting to an Android or iOS device. There shouldn’t normally be a need to modify them or write your own.

Functions

`connect`(f[, conn_factory, connector])	Connects to the Cozmo Engine on the mobile device and supplies the connection to a function.
`connect_on_loop`(loop[, conn_factory, connector])	Uses the supplied event loop to connect to a device.
`connect_with_3dviewer`(f[, conn_factory, …])	Setup a connection to a device and run a user function while displaying Cozmo’s 3d world.
`connect_with_tkviewer`(f[, conn_factory, …])	Setup a connection to a device and run a user function while displaying Cozmo’s camera.
`run_program`(f[, use_viewer, conn_factory, …])	Connect to Cozmo and run the provided program/function f.
`setup_basic_logging`([general_log_level, …])	Helper to perform basic setup of the Python logging machinery.

Classes

`AndroidConnector`([adb_cmd, serial])	Connects to an attached Android device over USB.
`DeviceConnector`([cozmo_port, enable_env_vars])	Base class for objects that setup the physical connection to a device.
`FirstAvailableConnector`()	Connects to the first Android or iOS device running the Cozmo app in SDK mode.
`IOSConnector`([serial])	Connects to an attached iOS device over USB.
`TCPConnector`([tcp_port, ip_addr])	Connects to the Cozmo app directly via TCP.

class cozmo.run.DeviceConnector(cozmo_port=5106, enable_env_vars=True)¶

Base class for objects that setup the physical connection to a device.

connect(loop, protocol_factory, conn_check)¶

Connect attempts to open a connection transport to the Cozmo app on a device.

On opening a transport it will create a protocol from the supplied factory and connect it to the transport, returning a (transport, protocol) tuple. See asyncio.BaseEventLoop.create_connection()

class cozmo.run.IOSConnector(serial=None, **kw)¶

Connects to an attached iOS device over USB.

Opens a connection to the first iOS device that’s found to be running the Cozmo app in SDK mode.

iTunes (or another service providing usbmuxd) must be installed in order for this connector to be able to open a connection to a device.

An instance of this class can be passed to the connect_ prefixed functions in this module.

Parameters:	serial (string) – Serial number of the device to connect to. If None, then connect to the first available iOS device running the Cozmo app in SDK mode.

connect(loop, protocol_factory, conn_check)¶

Connect attempts to open a connection transport to the Cozmo app on a device.

On opening a transport it will create a protocol from the supplied factory and connect it to the transport, returning a (transport, protocol) tuple. See asyncio.BaseEventLoop.create_connection()

class cozmo.run.AndroidConnector(adb_cmd=None, serial=None, **kw)¶

Connects to an attached Android device over USB.

This requires the Android Studio command line tools to be installed, specifically adb.

By default the connector will attempt to locate adb (or adb.exe on Windows) in common locations, but it may also be supplied by setting the ANDROID_ADB_PATH environment variable, or by passing it to the constructor.

An instance of this class can be passed to the connect_ prefixed functions in this module.

Parameters:	serial (string) – Serial number of the device to connect to. If None, then connect to the first available Android device running the Cozmo app in SDK mode.

connect(loop, protocol_factory, conn_check)¶

Connect attempts to open a connection transport to the Cozmo app on a device.

On opening a transport it will create a protocol from the supplied factory and connect it to the transport, returning a (transport, protocol) tuple. See asyncio.BaseEventLoop.create_connection()

class cozmo.run.TCPConnector(tcp_port=None, ip_addr='127.0.0.1', **kw)¶

Connects to the Cozmo app directly via TCP.

Generally only used for testing and debugging.

Requires that a SDK_TCP_PORT environment variable be set to the port number to connect to.

connect(loop, protocol_factory, conn_check)¶

Connect attempts to open a connection transport to the Cozmo app on a device.

On opening a transport it will create a protocol from the supplied factory and connect it to the transport, returning a (transport, protocol) tuple. See asyncio.BaseEventLoop.create_connection()

cozmo.run.connect(f, conn_factory=<class 'cozmo.conn.CozmoConnection'>, connector=None)¶

Connects to the Cozmo Engine on the mobile device and supplies the connection to a function.

Accepts a function, f, that is given a cozmo.conn.CozmoConnection object as a parameter.

The supplied function may be either an asynchronous coroutine function (normally defined using async def) or a regular synchronous function.

If an asynchronous function is supplied it will be run on the same thread as the Cozmo event loop and must use the await keyword to yield control back to the loop.

If a synchronous function is supplied then it will run on the main thread and Cozmo’s event loop will run on a separate thread. Calls to asynchronous methods returned from CozmoConnection will automatically be translated to synchronous ones.

The connect function will return once the supplied function has completed, as which time it will terminate the connection to the robot.

Parameters:

f (callable) – The function to execute
conn_factory (callable) – Override the factory function to generate a cozmo.conn.CozmoConnection (or subclass) instance.
connector (DeviceConnector) – Optional instance of a DeviceConnector subclass that handles opening the USB connection to a device. By default it will connect to the first Android or iOS device that has the Cozmo app running in SDK mode.

cozmo.run.connect_with_3dviewer(f, conn_factory=<class 'cozmo.conn.CozmoConnection'>, connector=None, enable_camera_view=False, show_viewer_controls=True)¶

Setup a connection to a device and run a user function while displaying Cozmo’s 3d world.

This displays an OpenGL window on the screen with a 3D view of Cozmo’s understanding of the world. Optionally, if use_viewer is True, a 2nd OpenGL window will also display showing a view of Cozmo’s camera. It will return an error if the current system does not support PyOpenGL.

The function may be either synchronous or asynchronous (defined used async def).

The function must accept a cozmo.CozmoConnection object as its only argument. This call will block until the supplied function completes.

Parameters:

f (callable) – The function to execute
conn_factory (callable) – Override the factory function to generate a cozmo.conn.CozmoConnection (or subclass) instance.
connector (DeviceConnector) – Optional instance of a DeviceConnector subclass that handles opening the USB connection to a device. By default it will connect to the first Android or iOS device that has the Cozmo app running in SDK mode.
enable_camera_view (bool) – Specifies whether to also open a 2D camera view in a second OpenGL window.
show_viewer_controls (bool) – Specifies whether to draw controls on the view.

cozmo.run.connect_with_tkviewer(f, conn_factory=<class 'cozmo.conn.CozmoConnection'>, connector=None, force_on_top=False)¶

Setup a connection to a device and run a user function while displaying Cozmo’s camera.

This displays a Tk window on the screen showing a view of Cozmo’s camera. It will return an error if the current system does not support Tk.

The function may be either synchronous or asynchronous (defined used async def).

The function must accept a cozmo.CozmoConnection object as its only argument. This call will block until the supplied function completes.

Parameters:

f (callable) – The function to execute
conn_factory (callable) – Override the factory function to generate a cozmo.conn.CozmoConnection (or subclass) instance.
connector (DeviceConnector) – Optional instance of a DeviceConnector subclass that handles opening the USB connection to a device. By default it will connect to the first Android or iOS device that has the Cozmo app running in SDK mode.
force_on_top (bool) – Specifies whether the window should be forced on top of all others

cozmo.run.connect_on_loop(loop, conn_factory=<class 'cozmo.conn.CozmoConnection'>, connector=None)¶

Uses the supplied event loop to connect to a device.

Will run the event loop in the current thread until the connection succeeds or fails.

If you do not want/need to manage your own loop, then use the connect() function to handle setup/teardown and execute a user-supplied function.

Parameters:

loop (asyncio.BaseEventLoop) – The event loop to use to connect to Cozmo.
conn_factory (callable) – Override the factory function to generate a cozmo.conn.CozmoConnection (or subclass) instance.
connector (DeviceConnector) – Optional instance of a DeviceConnector subclass that handles opening the USB connection to a device. By default, it will connect to the first Android or iOS device that has the Cozmo app running in SDK mode.

Returns:

A cozmo.conn.CozmoConnection instance.

cozmo.run.run_program(f, use_viewer=False, conn_factory=<class 'cozmo.conn.CozmoConnection'>, connector=None, force_viewer_on_top=False, deprecated_filter='default', use_3d_viewer=False, show_viewer_controls=True, exit_on_connection_error=True)¶

Connect to Cozmo and run the provided program/function f.

Parameters:

f (callable) – The function to execute, accepts a connected cozmo.robot.Robot as the parameter.
use_viewer (bool) – Specifies whether to display a view of Cozmo’s camera in a window.
conn_factory (callable) – Override the factory function to generate a cozmo.conn.CozmoConnection (or subclass) instance.
connector (DeviceConnector) – Optional instance of a DeviceConnector subclass that handles opening the USB connection to a device. By default it will connect to the first Android or iOS device that has the Cozmo app running in SDK mode.
force_viewer_on_top (bool) – Specifies whether the window should be forced on top of all others (only relevant if use_viewer is True). Note that this is ignored if use_3d_viewer is True (as it’s not currently supported on that windowing system).
deprecated_filter (str) – The filter for any DeprecationWarning messages. This is defaulted to “default” which shows the warning once per location. You can hide all deprecated warnings by passing in “ignore”, see https://docs.python.org/3/library/warnings.html#warning-filter for more information.
use_3d_viewer (bool) – Specifies whether to display a 3D view of Cozmo’s understanding of the world in a window. Note that if both this and use_viewer are set then the 2D camera view will render in an OpenGL window instead of a TkView window.
show_viewer_controls (bool) – Specifies whether to draw controls on the view.
exit_on_connection_error (bool) – Specify whether the program should exit on connection error or should an error be raised. Default to true.

cozmo.run.setup_basic_logging(general_log_level=None, protocol_log_level=None, protocol_log_messages='all', target=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='UTF-8'>, deprecated_filter='default')¶

Helper to perform basic setup of the Python logging machinery.

The SDK defines two loggers:

logger (“cozmo.general”) - For general purpose information about events within the SDK; and
logger_protocol (“cozmo.protocol”) - For low level communication messages between the device and the SDK.

Generally only logger is interesting.

Parameters:

general_log_level (str) – ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’ or an equivalent constant from the logging module. If None then a value will be read from the COZMO_LOG_LEVEL environment variable.
protocol_log_level (str) – as general_log_level. If None then a value will be read from the COZMO_PROTOCOL_LOG_LEVEL environment variable.
protocol_log_messages (list) – The low level messages that should be logged to the protocol log. Defaults to all. Will read from the COMZO_PROTOCOL_LOG_MESSAGES if available which should be a comma separated list of message names (case sensitive).
target (object) – The stream to send the log data to; defaults to stderr
deprecated_filter (str) – The filter for any DeprecationWarning messages. This is defaulted to “default” which shows the warning once per location. You can hide all deprecated warnings by passing in “ignore”, see https://docs.python.org/3/library/warnings.html#warning-filter for more information.