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
- pycozmo_app.py - an alternative Cozmo application, implementing off-board functions (video).
- pycozmo_dump.py - a command-line application that can read and annotate Cozmo communication from pcap files or capture it live using pypcap.
- pycozmo_replay.py - a basic command-line application that can replay .pcap files back to Cozmo.
- pycozmo_anim.py - a tool for examining and manipulating animation files.
- pycozmo_update.py - a tool for over-the-air (OTA) updates of Cozmo's firmware.
- pycozmo_protocol_generator.py - a tool for generating Cozmo protocol encoder code.
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:
- display_lines.py - demonstrates 2D graphics, using PIL.ImageDraw on Cozmo's display (video)
- rc.py - turns Cozmo into an RC tank that can be driven with an XBox 360 Wireless controller or Logitech Gamepad F310
- video.py - demonstrates visualizing video captured from the camera back on display
- cube_lights.py - demonstrates cube connection and LED control
- cube_light_animation.py - demonstrates cube LED animation control
- charger_lights.py - demonstrates Cozmo charging platform LED control
- audio.py - demonstrates 22 kHz, 16-bit, mono WAVE file playback through Cozmo's speaker
- nvram.py - demonstrates reading data from Cozmo's NVRAM (non-volatile memory)
- procedural_face.py - demonstrates drawing a procedural face on Cozmo's display
- procedural_face_show.py - demonstrates generating a procedural face
- procedural_face_expressions.py - demonstrates displaying various facial expressions (video)
- anim.py - demonstrates animating Cozmo
PyCozmo In The Wild
- Expressive Eyes - rendering various facial expressions using PyCozmo's procedural_face module
- an application that recognizes ArUco markers, using OpenCV
- a ROS2 driver
- another ROS2 driver
Connecting to Cozmo over Wi-Fi
A Wi-Fi connection needs to be established with Cozmo before using PyCozmo applications.
- Wake up Cozmo by placing it on the charging platform
- Make Cozmo display it's Wi-Fi PSK by rising and lowering its lift
- Scan for Cozmo's Wi-Fi SSID (depends on the OS)
- 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:
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.