GrimSqueaker/pycozmo

A pure-Python Anki Cozmo communication library.

PyCozmo

PyCozmo is a pure-Python Anki Cozmo communication library. 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 Anki Cozmo. It is unstable and heavily under development.

Usage

Basic mode:

import time
import pycozmo

def pycozmo_program(cli):
    cli.set_head_angle(angle=0.6)
    time.sleep(1)

pycozmo.run_program(pycozmo_program)

Advanced mode:

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/

Examples

Basic:

• minimal.py - minimal code to communicate with Cozmo, using PyCozmo
• go_to_pose.py - demonstrates moving to a specific pose (position and orientation)
• 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
• path.py - demonstrates following a predefined path

Advanced:

• display_lines.py - demonstrates 2D graphics, using PIL.ImageDraw on Cozmo's display
• rc.py - turns Cozmo into an RC tank that can be driven with an XBox 360 Wireless controller or Logitech Gamepad F310
• 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, 8-bit, mono WAVE file playback through Cozmo's speaker
• nvram.py - domonstrates 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
• anim.py - demonstrates animating Cozmo

Tools

• 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.

Robot Support

Sensors:

• Camera
• Cliff sensor
• Accelerometers
• Gyro
• Battery voltage
• Cube battery voltage
• Cube accelerometers

Actuators:

• Wheel motors
• Head motor
• Lift motor
• Backpack LEDs
• IR LED
• OLED display
• Speaker - work progress
• Cube LEDs
• Platform LEDs

Communication:

• Wi-Fi AP
• Bluetooth LE

Storage:

• NVRAM
• Firmware update

Functions:

• Localization
• Path tracking
• Procedural faces
• Animations from FlatBuffers .bin files

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)

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     |       PyCozmo       |      Cozmo       |
|      "game"      |      cozmoclad      |     "engine"     |                     |     "robot"      |
|                  | ------------------> |   Wi-Fi client   | ------------------> |     Wi-Fi AP     |
|                  |         USB         |    UDP client    |      UDP/Wi-Fi      |    UDP Server    |
+------------------+                     +------------------+                     +------------------+

Limitations

• some high-level Cozmo SDK features are implemented in the Cozmo app and have no equivalent in PyCozmo, today:
  • personality engine
  • behaviors
  • motion detection
  • face detection
  • facial expression estimation
  • text-to-speech
  • songs
• there is no Wi-Fi control. The library assumes a Wi-Fi connection to Cozmo, established in advance.
• frame retransmission is not implemented
• transmission of multiple packets in a single frame is not implemented

Requirements

• Python 3.5.4
• Pillow 6.0.0 - Python image library
• FlatBuffers - serialization library
• dpkt - TCP/IP packet parsing library

Installation

Using pip:

pip install pycozmo

From source:

git clone https://github.com/zayfod/pycozmo.git
cd pycozmo
python setup.py install

From source, for development:

git clone git@github.com:zayfod/pycozmo.git
cd pycozmo
python setup.py develop

Support

Bug reports and patches should be sent via GitHub:

https://github.com/zayfod/pycozmo

Anki Robot Discord server, channel #cozmo:

https://discord.gg/ew92haS

Disclaimer

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