Skip to main content

PyCozmo

PyCozmo is a pure-Python communication library, alternative SDK, and application for the Cozmo robot . It allows controlling a Cozmo robot directly, without having to go through a mobile device, running the Cozmo app.

The library is loosely based on the Anki Cozmo Python SDK and the cozmoclad ("C-Like Abstract Data") library.

This project is a tool for exploring the hardware and software of the Digital Dream Labs (originally Anki) Cozmo robot. It is unstable and heavily under development.

Usage

Basic:

import time
import pycozmo

with pycozmo.connect() as cli:
    cli.set_head_angle(angle=0.6)
    time.sleep(1)

Advanced:

import pycozmo

cli = pycozmo.Client()
cli.start()
cli.connect()
cli.wait_for_robot()

cli.drive_wheels(lwheel_speed=50.0, rwheel_speed=50.0, duration=2.0)

cli.disconnect()
cli.stop()

Documentation

https://pycozmo.readthedocs.io/

Robot Support

Sensors:

  • Camera
  • Cliff sensor
  • Accelerometers
  • Gyro
  • Battery voltage
  • Cube battery voltage
  • Cube accelerometers
  • Backpack button (v1.5 hardware and newer)

Actuators:

  • Wheel motors
  • Head motor
  • Lift motor
  • OLED display
  • Speaker
  • Backpack LEDs
  • IR LED
  • Cube LEDs
  • Platform LEDs (when available)

On-board functions (see docs/functions.md for details:

  • Wi-Fi AP
  • Bluetooth LE
  • Localization
  • Path tracking
  • NV RAM storage
  • Over-the-air (OTA) firmware updates

Off-board functions (see docs/offboard_functions.md for details:

  • Procedural face generation
  • Cozmo animations from FlatBuffers .bin files
  • Personality engine - work in progress
  • Cozmo behaviors - work in progress
  • Motion detection
  • Object (cube and platform) detection
  • Cube marker recognition
  • Face detection
  • Face recognition
  • Facial expression estimation
  • Pet detection
  • Camera calibration
  • Navigation map building
  • Text-to-speech
  • Songs

Extra off-board functions:

  • Vector animations from FlatBuffers .bin files
  • Vector behaviors
  • ArUco marker recognition
  • Cozmo and Vector robot detection
  • Drivable area estimation
  • Voice commands

If you have ideas for other functionality share them via GitHub.

Tools

Note: PyCozmo and pycozmo_protocol_generator.py in particular could be used as a base for creating a Cozmo protocol encoder code generator for languages other than Python (C/C++, Java, etc.).

Examples

Basic:

  • minimal.py - minimal code to communicate with Cozmo, using PyCozmo
  • extremes.py - demonstrates Cozmo lift and head control
  • backpack_lights.py - demonstrates Cozmo backpack LED control
  • display_image.py - demonstrates visualization of image files on Cozmo's display
  • events.py - demonstrates event handling
  • camera.py - demonstrates capturing a camera image
  • go_to_pose.py - demonstrates moving to a specific pose (position and orientation)
  • path.py - demonstrates following a predefined path

Advanced:

PyCozmo In The Wild

Connecting to Cozmo over Wi-Fi

A Wi-Fi connection needs to be established with Cozmo before using PyCozmo applications.

  1. Wake up Cozmo by placing it on the charging platform
  2. Make Cozmo display it's Wi-Fi PSK by rising and lowering its lift
  3. Scan for Cozmo's Wi-Fi SSID (depends on the OS)
  4. Connect using Cozmo's Wi-Fi PSK (depends on the OS)

This video summarizes the connection process.

PyCozmo vs. the Cozmo SDK

A Cozmo SDK application (aka "game") acts as a client to the Cozmo app (aka "engine") that runs on a mobile device. The low-level communication happens over USB and is handled by the cozmoclad library.

In contrast, an application using PyCozmo basically replaces the Cozmo app and acts as the "engine". PyCozmo handles the low-level UDP communication with Cozmo.

+------------------+                   +------------------+                   +------------------+
|     SDK app      |     Cozmo SDK     |    Cozmo app     |       Cozmo       |      Cozmo       |
|      "game"      |     cozmoclad     |     "engine"     |      protocol     |     "robot"      |
|                  | ----------------> |   Wi-Fi client   | ----------------> |     Wi-Fi AP     |
|                  |        USB        |    UDP client    |     UDP/Wi-Fi     |    UDP Server    |
+------------------+                   +------------------+                   +------------------+

Requirements

  • Python 3.11 or newer
  • Pillow 6.0.0 or newer - Python image library
  • FlatBuffers 2.0 or newer - serialization library
  • dpkt - TCP/IP packet parsing library
  • OpenCV 4.0.0 or newer - computer vision library

Installation

Using pip:

pip install pycozmo

pycozmo_resources.py download

From source:

git clone https://github.com/zayfod/pycozmo.git
cd pycozmo
pip install .

pycozmo_resources.py download

From source, for development (requires pip 25.1 or newer):

git clone git@github.com:zayfod/pycozmo.git
cd pycozmo
pip install -e . --group dev

pycozmo_resources.py download

Running the tests and linters:

flake8
mypy
pytest

Support

Bug reports and changes should be sent via GitHub:

https://github.com/zayfod/pycozmo

DDL Robot Discord server, channel #development-cozmo:

https://discord.gg/ew92haS

Disclaimer

This project is not affiliated with Digital Dream Labs or Anki.

Metadata

Release files for pycozmo 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycozmo 0.9.0
File Size Uploaded Provenance Actions
pycozmo-0.9.0.tar.gz 128.8 kB With provenance Details for pycozmo-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pycozmo 0.9.0
File Interpreter ABI Platform Actions
pycozmo-0.9.0-py3-none-any.whl Python 3 none any Details for pycozmo-0.9.0-py3-none-any.whl

Total release size: 276.5 kB

Release files / pycozmo-0.9.0.tar.gz

Download URL pycozmo-0.9.0.tar.gz
Size 128.8 kB
Tags Source
SHA-256 checksum
How to use checksums
408f8c848c4beed377c3e0d6ff2aeb0a11c5255c02e424a8f26491bc72d3b054
BLAKE2b-256 checksum
How to use checksums
9b3700fcb1a9049e0ea8e272d7c52e25cadc5004b7a9077a801acb3c5f1b1ca8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / pycozmo-0.9.0-py3-none-any.whl

Download URL pycozmo-0.9.0-py3-none-any.whl
Size 147.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2c5a310308deb86fde3a06b6e955de50c5d8e6146f854164f1bc12faa8c7af0e
BLAKE2b-256 checksum
How to use checksums
ad5f04a0c2f44b5986466d247317ff93bd0827b1d3961546656f40fbd46a40a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for pycozmo 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pycozmo-0.9.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page