Skip to content
GitLab
Commit dd971aad authored by Kaloyan Tenchov's avatar Kaloyan Tenchov
Browse files

Merge branch 'dev'

parents e9928fc8 b330bcf4
Hide whitespace changes
Inline Side-by-side
.gitignore
View file @ dd971aad
.DS_Store
__pycache__/
*.pyc
......
CHANGES.md 0 → 100644
View file @ dd971aad
Revision History
================
v0.4.0 (Sep 13, 2019)
---------------------
- New commands: Enable, TurnInPlace, DriveStraight, ButtonPressed, HardwareInfo, BodyInfo, EnableColorImages,
EnableStopOnCliff, NvStorageOp, NvStorageOpResult, FirmwareUpdate, FirmwareUpdateResult.
- New events: AnimationState, ObjectAvailable, ImageIMUData.
- New examples: cube_lights.py, charger_lights.py, cube_light_animation.py.
- Improved handling of 0x04 frames
- Added support for Int8, Int32, and enumeration packet fields.
- Improved robot state access.
- Added object availability and animation state access.
- Added initial pycozmo_replay.py tool for replaying .pcap files to Cozmo.
- Added OLED display initial image encoder code.
- Added initial function description.
v0.3.0 (Sep 1, 2019)
--------------------
- Camera control and image reconstruction commands.
- Initial robot state commands (coordinates, orientation, track speed, battery voltage).
- Cube control commands.
- Fall detection commands.
- Audio volume control command.
- Firmware signature identification commands.
- Improved logging control.
- Python 3.5 compatibility fixes (thanks to Cyke).
v0.2.0 (Aug 25, 2019)
---------------------
- Backpack light control commands and example.
- Raw display control commands and example.
- Audio output commands and example.
v0.1.0 (Aug 15, 2019)
---------------------
- Initial release.
README.md
View file @ dd971aad
......@@ -5,7 +5,7 @@ PyCozmo
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](https://github.com/anki/cozmo-python-sdk) and the
[cozmoclad](https://pypi.org/project/cozmoclad/) library.
[cozmoclad](https://pypi.org/project/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.
......@@ -52,36 +52,44 @@ Documentation
-------------
- [Cozmo protocol](docs/protocol.md) description
- [Cozmo function](docs/functions.md) description
- [Capturing Cozmo communication](docs/capturing.md)
Tools
-----
- `pycozmo_dump.py` - a command-line application that can read and annotate Cozmo communication from
[pcap files](https://en.wikipedia.org/wiki/Pcap)
- API documentation: http://pycozmo.readthedocs.io/
Examples
--------
- [rc.py](examples/rc.py) - turns Cozmo into an RC tank that can be driven with an XBox 360 Wireless Controller
- [rc.py](examples/rc.py) - turns Cozmo into an RC tank that can be driven with an XBox 360 Wireless controller or
Logitech Gamepad F310
- [extremes.py](examples/extremes.py) - demonstrates Cozmo lift and head control
- [backpack_lights.py](examples/backpack_lights.py) - demonstrates Cozmo backpack LED control
- [cube_lights.py](examples/cube_lights.py) - demonstrates cube connection and LED control
- [cube_light_animation.py](examples/cube_light_animation.py) - demonstrates cube LED animation control
- [charger_lights.py](examples/charger_lights.py) - demonstrates Cozmo charging platform LED control
- [display.py](examples/display.py) - demonstrates low-level visualization of images on Cozmo's display
- [audio.py](examples/audio.py) - demonstrates 22 kHz, 8-bit, mono WAVE file playback through Cozmo's speaker
- [events.py](examples/events.py) - demonstrates event handling
- [camera.py](examples/camera.py) - demonstrates capturing a camera image
Tools
-----
- `pycozmo_dump.py` - a command-line application that can read and annotate Cozmo communication from
[pcap files](https://en.wikipedia.org/wiki/Pcap)
- `pycozmo_replay.py` - a basic command-line application that can replay .pcap files back to Cozmo.
Robot Support
-------------
Sensors:
- Camera - supported
- Cliff sensor - not supported
- Accelerometers - work in progress
- Gyro - work in progress
- Cliff sensor - supported
- Accelerometers - supported
- Gyro - supported
- Battery voltage - supported
- Cube battery voltage - supported
- Cube accelerometers - supported
......@@ -93,13 +101,17 @@ Actuators:
- Backpack LEDs - supported
- IR LED - supported
- OLED display - work in progress
- Speaker - supported
- Speaker - work in progress
- Cube LEDs - supported
Communication:
- Wi-Fi AP - supported
- Bluetooth LE - supported
Storage:
- NVRAM - supported
- Firmware update - supported
Connecting to Cozmo over Wi-Fi
------------------------------
......@@ -134,10 +146,12 @@ the low-level UDP communication with Cozmo.
Limitations
-----------
- some high-level Cozmo SDK features are implemented in the Cozmo app and have no equivalent in PyCozmo:
- 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.
......@@ -148,7 +162,7 @@ Limitations
Requirements
------------
- Python 3.5
- Python 3.5.4
Installation
......
docs/functions.md 0 → 100644
View file @ dd971aad
Cozmo Functions
===============
Overview
--------
### Head
`HardwareInfo`
`FirmwareSignature`
### Body
`BodyInfo`
### Cubes
- LEDs
- Accelerometers
- Battery voltage
### Charging Platform
Some charging platforms (aka "pads") can be communicated with over Bluetooth LE. They contains 3 RGB LEDs that can be
controlled, similar to cube LEDs.
Wi-Fi
-----
Wi-Fi is activated automatically when the head board is powered on. The robot operates in access point mode.
`cozmoclad` defines a `SetBodyRadioMode` message that seems to allow changing the Wi-Fi channel but it is unclear
how it can be used with the Cozmo protocol.
Backpack LEDs
-------------
The 5 Backpack LEDs can be set controlled with 2 messages:
- `lightStateCenter` - controls the top, middle, and bottom RGB LEDs.
- `LightStateSide` - controls the left and right red-only LEDs.
Each color is defined by a 5-bit value for a total of 32768 colors.
See [backpack_lights.py](../examples/backpack_lights.py) for example usage.
Backpack Button
---------------
Newer Cozmo models have a backpack button. The `RobotState` message has a `backpack_touch_sensor_raw` field but
it seems that it's value does not change as a result of button presses.
Button press and release events are communicated bu the `ButtonPressed` message. It is immediately available on
connection and does not require `Enable` to be used.
Wheels
------
The left and the right motor speeds can be controlled directly using the `DriveWheels` and `TurnInPlaceAtSpeed`
messages.
In addition, the motors can be stopped using the `StopAllMotors` message.
The actual speed of wheels is measured with Hall magnetic sensors. The values for each wheel can be
read through the `lwheel_speed_mmps` and `rwheel_speed_mmps` fields of the `RobotState` message.
`TurnInPlace`
`DriveStraight`
Localization
------------
`RobotState`
`RobotDelocalized`
Head
----
The head motor can be controlled directly, using the `DriveHead` and `SetHeadAngle` messages.
In addition, the motor can be stopped using the `StopAllMotors` message.
The actual head angle can be read through the `head_angle_rad` field of the `RobotState` message.
See [extremes.py](../examples/extremes.py) for example usage.
`AcknowledgeAction`
Lift
----
The head motor can be controlled directly, using the `DriveLift` and `SetLiftHeight` messages.
In addition, the motor can be stopped using the `StopAllMotors` message.
The actual lift height can be read through the `lift_height_mm` field of the `RobotState` message.
See [extremes.py](../examples/extremes.py) for example usage.
`AcknowledgeAction`
OLED display
------------
See [display.py](../examples/display.py) for example usage.
`NextFrame`
`DisplayImage`
`AnimationState`
Speaker
-------
See [audio.py](../examples/audio.py) for example usage.
`OutputAudio`
`SetRobotVolume`
`AnimationState`
Camera
------
See [camera.py](../examples/camera.py) for example usage.
`EnableCamera`
`SetCameraParams`
`EnableColorImages`
`ImageChunk`
`ImageImuData`
IR LED
------
The IR head light can be turned on and off using the `SetHeadLight` message.
Accelerometers
--------------
See [events.py](../examples/events.py) for example usage.
`RobotState`
`RobotPoked`
`FallingStarted`
`FallingStopped`
Gyro
----
`RobotState`
Cliff Sensor
------------
`RobotState`
`EnableStopOnCliff`
Battery voltage
---------------
`RobotState`
NV RAM Storage
--------------
`NvStorageOp`
`NvStorageOpResult`
Firmware Updates
----------------
Cozmo firmware updates are distributed in "cozmo.safe" files that seem to contain firmware images for all three of
Cozmos controllers - the Wi-Fi controller (Espressif ESP8266), the body controller (NXP Kinetis K02), and the Bluetooth
LE controller (Nordic nRF51822).
The "cozmo.safe" files start with a firmware signature in JSON format:
```json
{
"version": 2381,
"git-rev": "408d28a7f6e68cbb5b29c1dcd8c8db2b38f9c8ce",
"date": "Tue Jan 8 10:27:05 2019",
"time": 1546972025,
"messageEngineToRobotHash": "9e4a965ace4e09d86997b87ba14235d5",
"messageRobotToEngineHash": "a259247f16231db440957215baba12ab",
"build": "DEVELOPMENT",
"wifiSig": "69ca03352e42143d340f0f7fac02ed8ff96ef10b",
"rtipSig": "36574986d76144a70e9252ab633be4617a4bc661",
"bodySig": "695b59eff43664acd1a5a956d08c682b3f8bd2c8"
}
```
This is the same signature, delivered with the `FirmwareSignature` message on initial connection establishment.
See [versions.md](versions.md) for more examples.
There seem to be individual signatures for each controller but the structure of the `cozmo.safe` files is not known.
The firmware image is transferred as-is from the engine to the robot, using `FirmwareUpdate` messages. It is divided
into 1024 B chunks that are numbered consecutively, starting with 0. Each chunk is confirmed by the robot with a
`FirmwareUpdateResult` message with `status` field set to 0.
Firmware transfer completion is indicated by the engine with e `FirmwareUpdate` message with chunk ID set to 0xFFFF and
data set to all-zeros. The robot confirms firmware update completion by sending a `FirmwareUpdateResult` message that
repeats the last chunk ID and has a `status` field set to 10.
Bluetooth LE
------------
"Objects", that can be connected to over Bluettoth LE announce their availability with an `ObjectAvailable` message
periodically. The `ObjectAvailable` message contains the object type (e.g. light cube 1, 2, 3 or charging pad) and
the object factory ID which identifies it uniquely.
The `ObjectConnect` message is used to initiate or terminate a connection to objects, using their factory ID.
Connection establishment and termination is announced with the `ObjectConnectionState` message. It contains a temporary
"object ID" that is used to identify the object for the duration of the connection with it.
Cube LEDs
---------
Cubes have 4 RGB LEDs that can be controlled individually.
A cube has to be "selected" first, using the `CubeId` message. A subsequent `CubeLights` message sets the state of all
4 cube LEDs.
Cubes can be programmed to perform simple LED light animations autonomously using the `LightState` structure and the
`CubeId.rotation_period_frames` field.
Cube Battery Voltage
--------------------
`ObjectPowerLevel`
Cube Accelerometers
-------------------
`ObjectMoved`
`ObjectStoppedMoving`
`ObjectUpAxisChnaged`
`ObjectTapped`
`ObjectTapFiltered`
docs/protocol.md
View file @ dd971aad
......@@ -14,6 +14,8 @@ The two exchange frames, encapsulated in UDP packets.
Each frame can contain 0, 1, or more packets.
See [protocol_declaration.py](../pycozmo/protocol_declaration.py) for packet details.
Network Setup
-------------
......@@ -66,7 +68,7 @@ Type Source Description
0x01 engine Reset
0x02 robot Reset ACK
0x03 engine Disconnect
0x04 engine Unknown
0x04 engine Engine action
0x07 engine Engine packets
0x09 robot Robot packets
0x0b engine Out-of-band engine ping
......@@ -91,6 +93,98 @@ Type OOB Source Description
Out of band packets do not get assigned sequence IDs.
Packet content is Cozmo firmware version specific.
Commands
--------
```
ID Min Max Name
---------------------------------------------------------------------------------
0x03 31 31 LightStateCenter
0x04 40 40 CubeLights
0x05 5 5 ObjectConnect
0x0b 1 1 SetHeadLight
0x0c 1 1
0x10 5 5 CubeId
0x11 21 21 LightStateSide
0x25 0 0 Enable
0x32 16 16 DriveWheels
0x33 10 10 TurnInPlaceAtSpeed
0x34 4 4 DriveLift
0x35 4 4 DriveHead
0x36 17 17 SetLiftHeight
0x37 17 17 SetHeadAngle
0x39 20 20 TurnInPlace
0x3b 0 0 StopAllMotors
0x3d DriveStraight
0x45 24 24
0x4b 8 8
0x4c 2 2 EnableCamera
0x50 2 2
0x54 2 2
0x57 7 7 SetCameraParams
0x60 1 1 EnableStopOnCliff
0x64 2 2 SetRobotVolume
0x66 1 1 EnableColorImages
0x80 4 4
0x81 12 144 * NvStorageOp
0x8d 0 0
0x8e 744 744 OutputAudio
0x8f 0 0 NextFrame
0x93 3 3
0x94 3 3
0x97 4 188 * DisplayImage
0x98 10 10
0x99 4 4
0x9a 0 0
0x9b 1 1
0x9d 1 1
0x9e 1 1
0x9f 0 0
0xa0 16 16
0xaf 1026 1026 FirmwareUpdate
0xb0 8 40 * UnknownB0
0xb2 16 16
0xb4 21 21 ObjectMoved
0xb5 8 8 ObjectStoppedMoving
0xb6 12 12 ObjectTapped
0xb9 10 10 ObjectTapFiltered
0xc2 0 0 RobotDelocalized
0xc3 0 0 RobotPoked
0xc4 1 1 AcknowledgeAction
0xc8 29 29
0xc9 6 6 HardwareInfo
0xca 1 1
0xcb 1 1
0xcd 12 1036 * NvStorageOpResult
0xce 9 9 ObjectPowerLevel
0xcf 8 8
0xd0 13 13 ObjectConnectionState
0xd1 3 3
0xd2 44 44
0xd7 9 9 ObjectUpAxisChanged
0xec 4 4
0xed 12 12 BodyInfo
0xee 449 449 FirmwareSignature
0xef 7 7 FirmwareUpdateResult
```
Events
------
```
ID Min Max Name
---------------------------------------------------------------------------------
0xf0 91 91 RobotState
0xf1 15 15 AnimationState
0xf2 24 1172 * ImageChunk
0xf3 9 9 ObjectAvailable
0xf4 17 17 ImageImuData
```
Connection Establishment
------------------------
......
docs/source/Makefile 0 → 100644
View file @ dd971aad
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
docs/source/conf.py 0 → 100644
View file @ dd971aad
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
# noinspection PyPep8
import pycozmo
# -- Project information -----------------------------------------------------
project = 'PyCozmo'
# noinspection PyShadowingBuiltins
copyright = '2019, Kaloyan Tenchov'
author = 'Kaloyan Tenchov'
# The full version, including alpha/beta/rc tags
release = pycozmo.__version__
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.coverage',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = []
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['**tests**']
master_doc = 'index'
# -- Options for HTML output -------------------------------------------------
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
docs/source/index.rst 0 → 100644
View file @ dd971aad
.. PyCozmo documentation master file, created by
sphinx-quickstart on Thu Sep 5 00:44:55 2019.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to PyCozmo's documentation!
===================================
.. toctree::
:maxdepth: 3
:caption: Contents:
pycozmo
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
docs/source/make.bat 0 → 100644
View file @ dd971aad
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was