spherov2.py

An unofficial Python library for Sphero toys that supports its Version 2 Bluetooth low energy API described here. Toys that are supported includes (implemented ones are checked):

• Sphero 2.0 / SPRK
• Sphero Ollie
• Sphero BB-8
• Sphero BB-9E
• Sphero R2-D2 / R2-Q5
• Sphero BOLT (In Progress)
• Sphero SPRK+ / SPRK 2.0
• Sphero Mini
• Sphero RVR

Current Progress:

• Found a better way to decompile, fixing a few things like Controls, Command Queueing, and Waiting for responses
• Controls
  • Animation Control
  • Drive Control
  • LED Control
  • Sensor Control
  • Stats Control
  • Streaming Control

The logic is written based on reverse-engineering the official Sphero Edu for Android, with the help from available documentation and other unofficial community-based Sphero libraries like igbopie/spherov2.js and EnotYoyo/pysphero.

This project uses the hbldh/bleak Bluetooth Low Energy library, which works across all platforms.

Usage

To install the library, run pip install spherov2. Python version >= 3.7 are supported.

The library currently has two adapters, BleakAdapter and TCPAdapter. BleakAdapter is used by default when adapter is not specified, which connects to toys using the local Bluetooth adapter. For example:

from spherov2 import scanner

with scanner.find_toy() as toy:
    ...

TCPAdapter allows the user to send and receive Bluetooth packets connected to another host via a server running on that host as a relay. To start the server, run python -m spherov2.adapter.tcp_server [host] [port], with host and port by default being 0.0.0.0 and 50004. To use the adapter, for example:

from spherov2 import scanner
from spherov2.adapter.tcp_adapter import get_tcp_adapter

with scanner.find_toy(adapter=get_tcp_adapter('localhost')) as toy:
    ...

The TCP server is written in asynchronous fashion using asyncio, so that it supports bleak on all platforms.

On whichever device you decide to connect to the toys, you have to first install the BLE library by pip install bleak.

Scanner

You can scan the toys around you using the scanner helper. To find all possible toys, simply call scanner.find_toys(). To find only a single toy, use scanner.find_toy().

You can also find toys using specific filters. Please refer to the document for more information.

APIs

There are two ways you can interact with the toys, one is to use the low-level APIs implemented for each toy with the commands they support. Low-level APIs can be found for each toy under spherov2.toy.*, and is not documented.

The other and recommended way is to use the high level API spherov2.sphero_edu.SpheroEduAPI, which is an implementation of the official Sphero Edu APIs. Documentations can be found inside the source files with the docstrings, or here as an HTML rendered version. For example:

from spherov2 import scanner
from spherov2.sphero_edu import SpheroEduAPI

toy = scanner.find_toy()
with SpheroEduAPI(toy) as api:
    api.spin(360, 1)

Acknowledgments

This library is made for educational purposes. It is used by students in CIS 521 - Artificial Intelligence at the University of Pennsylvania, where we use Sphero robots to help teach the foundations of AI.

It is published as an open-source library under the MIT License.

Authors

• Hanbang Wang - https://www.cis.upenn.edu/~hanbangw/
• Elionardo Feliciano