[x] Sphero 2.0 / SPRK
[x] Sphero Ollie
[x] Sphero BB-8
[x] Sphero BB-9E
[x] Sphero R2-D2 / R2-Q5
[x] Sphero BOLT (In Progress)
[x] Sphero SPRK+ / SPRK 2.0
[x] Sphero Mini
[x] Sphero RVR
Found a better way to decompile, fixing a few things like Controls, Command Queueing, and Waiting for responses
[ ] Controls
[ ] Animation Control
[ ] Drive Control
[x] 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.
To install the library, run
pip install spherov2. Python version
>= 3.7 are supported.
The library currently has two adapters,
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
port by default being
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.
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
You can also find toys using specific filters. Please refer to the document for more information.
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)
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.