# spherov2.py
  [](https://pypi.org/project/spherov2/) [](https://spherov2.readthedocs.io/en/latest/) [](LICENSE) 
An unofficial Python library for [Sphero](https://sphero.com/) toys that supports its Version 2 Bluetooth low energy API described [here](https://sdk.sphero.com/docs/api_spec/general_api/). Toys that are supported includes (implemented ones are checked):
- [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
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
- [x] LED Control
- [ ] Sensor Control
- [ ] Stats Control
- [ ] Streaming Control
The logic is written based on reverse-engineering the official [Sphero Edu for Android](https://play.google.com/store/apps/details?id=com.sphero.sprk), with the help from available documentation and other unofficial community-based Sphero libraries like [igbopie/spherov2.js](https://github.com/igbopie/spherov2.js) and [EnotYoyo/pysphero](https://github.com/EnotYoyo/pysphero).
This project uses the [hbldh/bleak](https://github.com/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:
```python
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:
```python
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](https://spherov2.readthedocs.io/en/latest/scanner.html) 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](https://sphero.docsapp.io/docs/get-started). Documentations can be found inside the source files with the docstrings, or [here](https://spherov2.readthedocs.io/en/latest/sphero_edu.html) as an HTML rendered version. For example:
```python
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](http://artificial-intelligence-class.org/) 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](LICENSE).
## Authors
* **Hanbang Wang** - [https://www.cis.upenn.edu/~hanbangw/](https://www.cis.upenn.edu/~hanbangw/)
* **Elionardo Feliciano**
Raw data
{
"_id": null,
"home_page": "https://github.com/artificial-intelligence-class/spherov2.py",
"name": "spherov2",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "robotics Sphero toy bluetooth ble",
"author": "Hanbang Wang",
"author_email": "hanbangw@cis.upenn.edu",
"download_url": "https://files.pythonhosted.org/packages/ea/11/a7e868c08e6b3a4a359b90007b96c197b203dff981fe5f8b7f700856e1aa/spherov2-0.12.1.tar.gz",
"platform": null,
"description": "# spherov2.py\n\n  [](https://pypi.org/project/spherov2/) [](https://spherov2.readthedocs.io/en/latest/) [](LICENSE) \n\nAn unofficial Python library for [Sphero](https://sphero.com/) toys that supports its Version 2 Bluetooth low energy API described [here](https://sdk.sphero.com/docs/api_spec/general_api/). Toys that are supported includes (implemented ones are checked):\n\n- [x] Sphero 2.0 / SPRK\n- [x] Sphero Ollie\n- [x] Sphero BB-8\n- [x] Sphero BB-9E\n- [x] Sphero R2-D2 / R2-Q5\n- [x] Sphero BOLT (In Progress)\n- [x] Sphero SPRK+ / SPRK 2.0\n- [x] Sphero Mini\n- [x] Sphero RVR\n\nCurrent Progress:\n- Found a better way to decompile, fixing a few things like Controls, Command Queueing, and Waiting for responses\n- [ ] Controls\n\t- [ ] Animation Control\n\t- [ ] Drive Control\n\t- [x] LED Control\n\t- [ ] Sensor Control\n\t- [ ] Stats Control\n\t- [ ] Streaming Control\n\nThe logic is written based on reverse-engineering the official [Sphero Edu for Android](https://play.google.com/store/apps/details?id=com.sphero.sprk), with the help from available documentation and other unofficial community-based Sphero libraries like [igbopie/spherov2.js](https://github.com/igbopie/spherov2.js) and [EnotYoyo/pysphero](https://github.com/EnotYoyo/pysphero).\n\nThis project uses the [hbldh/bleak](https://github.com/hbldh/bleak) Bluetooth Low Energy library, which works across all platforms.\n\n## Usage\n\nTo install the library, run `pip install spherov2`. Python version `>= 3.7` are supported.\n\nThe 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:\n\n```python\nfrom spherov2 import scanner\n\nwith scanner.find_toy() as toy:\n ...\n```\n\n`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:\n\n```python\nfrom spherov2 import scanner\nfrom spherov2.adapter.tcp_adapter import get_tcp_adapter\n\nwith scanner.find_toy(adapter=get_tcp_adapter('localhost')) as toy:\n ...\n```\n\nThe TCP server is written in asynchronous fashion using `asyncio`, so that it supports `bleak` on all platforms.\n\nOn whichever device you decide to connect to the toys, you have to first install the BLE library by `pip install bleak`.\n\n### Scanner\n\nYou 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()`.\n\nYou can also find toys using specific filters. Please refer to the [document](https://spherov2.readthedocs.io/en/latest/scanner.html) for more information.\n\n### APIs\n\nThere 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.\n\nThe 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](https://sphero.docsapp.io/docs/get-started). Documentations can be found inside the source files with the docstrings, or [here](https://spherov2.readthedocs.io/en/latest/sphero_edu.html) as an HTML rendered version. For example:\n\n```python\nfrom spherov2 import scanner\nfrom spherov2.sphero_edu import SpheroEduAPI\n\ntoy = scanner.find_toy()\nwith SpheroEduAPI(toy) as api:\n api.spin(360, 1)\n```\n\n## Acknowledgments\n\nThis library is made for educational purposes. It is used by students in [CIS 521 - Artificial Intelligence](http://artificial-intelligence-class.org/) at the University of Pennsylvania, where we use Sphero robots to help teach the foundations of AI.\n\nIt is published as an open-source library under the [MIT License](LICENSE).\n\n## Authors\n\n* **Hanbang Wang** - [https://www.cis.upenn.edu/~hanbangw/](https://www.cis.upenn.edu/~hanbangw/)\n* **Elionardo Feliciano**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An unofficial Bluetooth low energy library for Sphero toys in Python.",
"version": "0.12.1",
"project_urls": {
"Homepage": "https://github.com/artificial-intelligence-class/spherov2.py"
},
"split_keywords": [
"robotics",
"sphero",
"toy",
"bluetooth",
"ble"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b93009e57c153964c16ebaa26f8899610c9b4e43afb9bc8d67a405f8009fc95f",
"md5": "e9238af657135ba1540483536cc57fd5",
"sha256": "f182796b6b73225a1e6968c38243c56945ef6a5e953224e604aa8d1a83adb0fd"
},
"downloads": -1,
"filename": "spherov2-0.12.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9238af657135ba1540483536cc57fd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 71086,
"upload_time": "2024-01-29T01:51:30",
"upload_time_iso_8601": "2024-01-29T01:51:30.403832Z",
"url": "https://files.pythonhosted.org/packages/b9/30/09e57c153964c16ebaa26f8899610c9b4e43afb9bc8d67a405f8009fc95f/spherov2-0.12.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea11a7e868c08e6b3a4a359b90007b96c197b203dff981fe5f8b7f700856e1aa",
"md5": "a1ccd41ed292909a83fef3a5c05b97ee",
"sha256": "087929a28164af78c8a258396593a51d45fc89af23e86c524d86d0a5d094908f"
},
"downloads": -1,
"filename": "spherov2-0.12.1.tar.gz",
"has_sig": false,
"md5_digest": "a1ccd41ed292909a83fef3a5c05b97ee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 55956,
"upload_time": "2024-01-29T01:51:31",
"upload_time_iso_8601": "2024-01-29T01:51:31.675606Z",
"url": "https://files.pythonhosted.org/packages/ea/11/a7e868c08e6b3a4a359b90007b96c197b203dff981fe5f8b7f700856e1aa/spherov2-0.12.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-29 01:51:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "artificial-intelligence-class",
"github_project": "spherov2.py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spherov2"
}
JSON
