| Name | sphero-bolt-plus JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | Modern Python library for controlling Sphero BOLT+ robots with enhanced features |
| upload_time | 2025-08-21 05:48:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
bluetooth
bolt
education
robotics
sphero
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Sphero BOLT+ Python Library
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
A modern, fully async Python library for controlling Sphero BOLT+ robots with comprehensive type annotations and enhanced features.
## Features
- 🚀 **Fully Async**: Built with `asyncio` for non-blocking operations
- 📝 **Type Annotations**: Complete type safety with mypy support
- 🎯 **Modern Python**: Supports Python 3.9+ with latest language features
- 🤖 **Multiple Models**: Support for BOLT, BOLT+, RVR, Mini, and Spark
- 🎨 **LED Control**: Main LED, back LED, front LED, and 8x8 LED matrix
- 🎮 **Movement**: Roll, spin, stop with precise control
- 📊 **Sensors**: Accelerometer, gyroscope, compass, location, velocity, battery
- 🔍 **Auto-Discovery**: Bluetooth scanning and robot detection
- ⚡ **Event-Driven**: Sensor callbacks and real-time data streaming
- 🛡️ **Robust**: Comprehensive error handling and connection management
## Installation
```bash
pip install sphero-bolt-plus
```
For development:
```bash
pip install sphero-bolt-plus[dev]
```
## Quick Start
### Basic Connection and Movement
```python
import asyncio
from sphero_bolt_plus import SpheroScanner, SpheroBot, Colors
async def main():
# Scan for robots
async with SpheroScanner() as scanner:
robots = await scanner.scan_for_robots()
print(f"Found {len(robots)} robots")
# Connect to first robot
async with SpheroBot(robots[0]) as robot:
# Set LED color
await robot.set_main_led(Colors.BLUE)
# Move forward
await robot.roll(speed=100, heading=0, duration=2.0)
# Spin in place
await robot.spin(360, duration=2.0)
# Stop
await robot.stop()
asyncio.run(main())
```
### LED Matrix Control (BOLT/BOLT+ only)
```python
import asyncio
from sphero_bolt_plus import SpheroScanner, SpheroBot, Colors
async def matrix_demo():
async with SpheroScanner() as scanner:
robots = await scanner.scan_for_robots()
async with SpheroBot(robots[0]) as robot:
# Clear matrix
await robot.clear_matrix()
# Set individual pixels
await robot.set_matrix_pixel(0, 0, Colors.RED)
await robot.set_matrix_pixel(7, 7, Colors.BLUE)
# Scroll text
await robot.scroll_matrix_text("HELLO!", Colors.GREEN, speed=5)
asyncio.run(matrix_demo())
```
### Sensor Reading
```python
import asyncio
from sphero_bolt_plus import SpheroScanner, SpheroBot
async def sensor_demo():
async with SpheroScanner() as scanner:
robots = await scanner.scan_for_robots()
async with SpheroBot(robots[0]) as robot:
# Get battery status
battery = await robot.get_battery()
print(f"Battery: {battery.percentage}% ({battery.voltage}V)")
# Get compass heading
compass = await robot.get_compass()
print(f"Heading: {compass.heading}°")
# Get accelerometer data
accel = await robot.get_accelerometer()
print(f"Acceleration: X={accel.x}, Y={accel.y}, Z={accel.z}")
asyncio.run(sensor_demo())
```
### Real-time Sensor Streaming
```python
import asyncio
from sphero_bolt_plus import SpheroScanner, SpheroBot
def on_accelerometer_data(reading):
print(f"Accel: {reading.x:.2f}, {reading.y:.2f}, {reading.z:.2f}")
async def streaming_demo():
async with SpheroScanner() as scanner:
robots = await scanner.scan_for_robots()
async with SpheroBot(robots[0]) as robot:
# Register sensor callback
robot.register_sensor_callback("accelerometer", on_accelerometer_data)
# Move around to see sensor data
await robot.roll(100, 0, duration=5.0)
asyncio.run(streaming_demo())
```
## Advanced Usage
### Custom Color Control
```python
from sphero_bolt_plus import Color, Colors
# Create custom colors
custom_color = Color(255, 128, 64) # Orange-ish
hex_color = Color.from_hex("#FF8040")
rgb_tuple = (255, 128, 64)
# Use with robot
await robot.set_main_led(custom_color)
await robot.set_main_led("#FF8040")
await robot.set_main_led((255, 128, 64))
```
### Error Handling
```python
import asyncio
from sphero_bolt_plus import (
SpheroScanner,
SpheroBot,
ConnectionError,
CommandError,
RobotNotFoundError,
)
async def robust_demo():
try:
async with SpheroScanner(scan_timeout=5.0) as scanner:
robots = await scanner.scan_for_robots()
except RobotNotFoundError:
print("No robots found!")
return
try:
async with SpheroBot(robots[0], connection_timeout=15.0) as robot:
await robot.roll(100, 0, duration=2.0)
except ConnectionError as e:
print(f"Connection failed: {e}")
except CommandError as e:
print(f"Command failed: {e}")
asyncio.run(robust_demo())
```
### Finding Specific Robots
```python
from sphero_bolt_plus import SpheroScanner, RobotModel
async with SpheroScanner() as scanner:
# Find by name
robot_info = await scanner.find_robot_by_name("SB-1234")
# Filter by model
bolt_robots = await scanner.scan_for_robots(model_filter=RobotModel.BOLT_PLUS)
# Filter by partial name
classroom_robots = await scanner.scan_for_robots(name_filter="classroom")
```
## API Reference
### SpheroScanner
- `scan_for_robots(model_filter=None, name_filter=None)`: Scan for available robots
- `find_robot_by_name(name, timeout=None)`: Find specific robot by name
- `scan_continuously(callback, ...)`: Continuous scanning with callback
### SpheroBot
#### Connection
- `connect()`: Connect to robot
- `disconnect()`: Disconnect from robot
- `is_connected`: Check connection status
- `connection_state`: Get connection state
#### Movement
- `roll(speed, heading, duration=None)`: Move robot
- `stop()`: Stop movement
- `spin(angle, duration)`: Spin robot
#### LED Control
- `set_main_led(color)`: Set main LED color
- `set_back_led(brightness)`: Set back LED brightness
- `set_front_led(color)`: Set front LED color (BOLT+ only)
- `set_matrix_pixel(x, y, color)`: Set matrix pixel (BOLT+ only)
- `clear_matrix()`: Clear LED matrix (BOLT+ only)
- `scroll_matrix_text(text, color, speed)`: Scroll text (BOLT+ only)
#### Sensors
- `get_accelerometer()`: Get accelerometer reading
- `get_gyroscope()`: Get gyroscope reading
- `get_compass()`: Get compass reading
- `get_location()`: Get location reading
- `get_velocity()`: Get velocity reading
- `get_battery()`: Get battery status
#### Configuration
- `set_stabilization(enabled)`: Enable/disable stabilization
- `calibrate_compass()`: Calibrate compass
## Supported Robots
| Model | Movement | Main LED | Back LED | Front LED | Matrix | Sensors |
|-------|----------|----------|----------|-----------|--------|---------|
| BOLT+ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| BOLT | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| RVR | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
| Mini | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
| Spark | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |
## Requirements
- Python 3.9+
- Bluetooth Low Energy (BLE) support
- Compatible Sphero robot
## Development
```bash
git clone https://github.com/assistant/sphero-bolt-plus
cd sphero-bolt-plus
pip install -e .[dev]
# Run tests
pytest
# Format code
black sphero_bolt_plus
# Type checking
mypy sphero_bolt_plus
# Linting
ruff check sphero_bolt_plus
```
## Contributing
Contributions are welcome! Please read our contributing guidelines and submit pull requests.
## License
MIT License - see LICENSE file for details.
## Acknowledgments
- Based on the original `sphero_unsw` library by Kathryn Kasmarik and Reda Ghanem
- Built on top of the `spherov2` library
- Thanks to the Sphero community for protocol documentation
Raw data
{
"_id": null,
"home_page": null,
"name": "sphero-bolt-plus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "bluetooth, bolt, education, robotics, sphero",
"author": null,
"author_email": "Assistant <assistant@example.com>",
"download_url": "https://files.pythonhosted.org/packages/3d/8b/911ff1466231f55053424f4a852833042060b857dd891160142fe4aca46e/sphero_bolt_plus-1.0.1.tar.gz",
"platform": null,
"description": "# Sphero BOLT+ Python Library\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\nA modern, fully async Python library for controlling Sphero BOLT+ robots with comprehensive type annotations and enhanced features.\n\n## Features\n\n- \ud83d\ude80 **Fully Async**: Built with `asyncio` for non-blocking operations\n- \ud83d\udcdd **Type Annotations**: Complete type safety with mypy support\n- \ud83c\udfaf **Modern Python**: Supports Python 3.9+ with latest language features\n- \ud83e\udd16 **Multiple Models**: Support for BOLT, BOLT+, RVR, Mini, and Spark\n- \ud83c\udfa8 **LED Control**: Main LED, back LED, front LED, and 8x8 LED matrix\n- \ud83c\udfae **Movement**: Roll, spin, stop with precise control\n- \ud83d\udcca **Sensors**: Accelerometer, gyroscope, compass, location, velocity, battery\n- \ud83d\udd0d **Auto-Discovery**: Bluetooth scanning and robot detection\n- \u26a1 **Event-Driven**: Sensor callbacks and real-time data streaming\n- \ud83d\udee1\ufe0f **Robust**: Comprehensive error handling and connection management\n\n## Installation\n\n```bash\npip install sphero-bolt-plus\n```\n\nFor development:\n```bash\npip install sphero-bolt-plus[dev]\n```\n\n## Quick Start\n\n### Basic Connection and Movement\n\n```python\nimport asyncio\nfrom sphero_bolt_plus import SpheroScanner, SpheroBot, Colors\n\nasync def main():\n # Scan for robots\n async with SpheroScanner() as scanner:\n robots = await scanner.scan_for_robots()\n print(f\"Found {len(robots)} robots\")\n \n # Connect to first robot\n async with SpheroBot(robots[0]) as robot:\n # Set LED color\n await robot.set_main_led(Colors.BLUE)\n \n # Move forward\n await robot.roll(speed=100, heading=0, duration=2.0)\n \n # Spin in place\n await robot.spin(360, duration=2.0)\n \n # Stop\n await robot.stop()\n\nasyncio.run(main())\n```\n\n### LED Matrix Control (BOLT/BOLT+ only)\n\n```python\nimport asyncio\nfrom sphero_bolt_plus import SpheroScanner, SpheroBot, Colors\n\nasync def matrix_demo():\n async with SpheroScanner() as scanner:\n robots = await scanner.scan_for_robots()\n \n async with SpheroBot(robots[0]) as robot:\n # Clear matrix\n await robot.clear_matrix()\n \n # Set individual pixels\n await robot.set_matrix_pixel(0, 0, Colors.RED)\n await robot.set_matrix_pixel(7, 7, Colors.BLUE)\n \n # Scroll text\n await robot.scroll_matrix_text(\"HELLO!\", Colors.GREEN, speed=5)\n\nasyncio.run(matrix_demo())\n```\n\n### Sensor Reading\n\n```python\nimport asyncio\nfrom sphero_bolt_plus import SpheroScanner, SpheroBot\n\nasync def sensor_demo():\n async with SpheroScanner() as scanner:\n robots = await scanner.scan_for_robots()\n \n async with SpheroBot(robots[0]) as robot:\n # Get battery status\n battery = await robot.get_battery()\n print(f\"Battery: {battery.percentage}% ({battery.voltage}V)\")\n \n # Get compass heading\n compass = await robot.get_compass()\n print(f\"Heading: {compass.heading}\u00b0\")\n \n # Get accelerometer data\n accel = await robot.get_accelerometer()\n print(f\"Acceleration: X={accel.x}, Y={accel.y}, Z={accel.z}\")\n\nasyncio.run(sensor_demo())\n```\n\n### Real-time Sensor Streaming\n\n```python\nimport asyncio\nfrom sphero_bolt_plus import SpheroScanner, SpheroBot\n\ndef on_accelerometer_data(reading):\n print(f\"Accel: {reading.x:.2f}, {reading.y:.2f}, {reading.z:.2f}\")\n\nasync def streaming_demo():\n async with SpheroScanner() as scanner:\n robots = await scanner.scan_for_robots()\n \n async with SpheroBot(robots[0]) as robot:\n # Register sensor callback\n robot.register_sensor_callback(\"accelerometer\", on_accelerometer_data)\n \n # Move around to see sensor data\n await robot.roll(100, 0, duration=5.0)\n\nasyncio.run(streaming_demo())\n```\n\n## Advanced Usage\n\n### Custom Color Control\n\n```python\nfrom sphero_bolt_plus import Color, Colors\n\n# Create custom colors\ncustom_color = Color(255, 128, 64) # Orange-ish\nhex_color = Color.from_hex(\"#FF8040\")\nrgb_tuple = (255, 128, 64)\n\n# Use with robot\nawait robot.set_main_led(custom_color)\nawait robot.set_main_led(\"#FF8040\")\nawait robot.set_main_led((255, 128, 64))\n```\n\n### Error Handling\n\n```python\nimport asyncio\nfrom sphero_bolt_plus import (\n SpheroScanner,\n SpheroBot,\n ConnectionError,\n CommandError,\n RobotNotFoundError,\n)\n\nasync def robust_demo():\n try:\n async with SpheroScanner(scan_timeout=5.0) as scanner:\n robots = await scanner.scan_for_robots()\n \n except RobotNotFoundError:\n print(\"No robots found!\")\n return\n \n try:\n async with SpheroBot(robots[0], connection_timeout=15.0) as robot:\n await robot.roll(100, 0, duration=2.0)\n \n except ConnectionError as e:\n print(f\"Connection failed: {e}\")\n except CommandError as e:\n print(f\"Command failed: {e}\")\n\nasyncio.run(robust_demo())\n```\n\n### Finding Specific Robots\n\n```python\nfrom sphero_bolt_plus import SpheroScanner, RobotModel\n\nasync with SpheroScanner() as scanner:\n # Find by name\n robot_info = await scanner.find_robot_by_name(\"SB-1234\")\n \n # Filter by model\n bolt_robots = await scanner.scan_for_robots(model_filter=RobotModel.BOLT_PLUS)\n \n # Filter by partial name\n classroom_robots = await scanner.scan_for_robots(name_filter=\"classroom\")\n```\n\n## API Reference\n\n### SpheroScanner\n\n- `scan_for_robots(model_filter=None, name_filter=None)`: Scan for available robots\n- `find_robot_by_name(name, timeout=None)`: Find specific robot by name\n- `scan_continuously(callback, ...)`: Continuous scanning with callback\n\n### SpheroBot\n\n#### Connection\n- `connect()`: Connect to robot\n- `disconnect()`: Disconnect from robot\n- `is_connected`: Check connection status\n- `connection_state`: Get connection state\n\n#### Movement\n- `roll(speed, heading, duration=None)`: Move robot\n- `stop()`: Stop movement\n- `spin(angle, duration)`: Spin robot\n\n#### LED Control\n- `set_main_led(color)`: Set main LED color\n- `set_back_led(brightness)`: Set back LED brightness\n- `set_front_led(color)`: Set front LED color (BOLT+ only)\n- `set_matrix_pixel(x, y, color)`: Set matrix pixel (BOLT+ only)\n- `clear_matrix()`: Clear LED matrix (BOLT+ only)\n- `scroll_matrix_text(text, color, speed)`: Scroll text (BOLT+ only)\n\n#### Sensors\n- `get_accelerometer()`: Get accelerometer reading\n- `get_gyroscope()`: Get gyroscope reading\n- `get_compass()`: Get compass reading\n- `get_location()`: Get location reading\n- `get_velocity()`: Get velocity reading\n- `get_battery()`: Get battery status\n\n#### Configuration\n- `set_stabilization(enabled)`: Enable/disable stabilization\n- `calibrate_compass()`: Calibrate compass\n\n## Supported Robots\n\n| Model | Movement | Main LED | Back LED | Front LED | Matrix | Sensors |\n|-------|----------|----------|----------|-----------|--------|---------|\n| BOLT+ | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |\n| BOLT | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |\n| RVR | \u2705 | \u2705 | \u2705 | \u274c | \u274c | \u2705 |\n| Mini | \u2705 | \u2705 | \u2705 | \u274c | \u274c | \u2705 |\n| Spark | \u2705 | \u2705 | \u2705 | \u274c | \u274c | \u2705 |\n\n## Requirements\n\n- Python 3.9+\n- Bluetooth Low Energy (BLE) support\n- Compatible Sphero robot\n\n## Development\n\n```bash\ngit clone https://github.com/assistant/sphero-bolt-plus\ncd sphero-bolt-plus\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Format code\nblack sphero_bolt_plus\n\n# Type checking\nmypy sphero_bolt_plus\n\n# Linting\nruff check sphero_bolt_plus\n```\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines and submit pull requests.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Acknowledgments\n\n- Based on the original `sphero_unsw` library by Kathryn Kasmarik and Reda Ghanem\n- Built on top of the `spherov2` library\n- Thanks to the Sphero community for protocol documentation",
"bugtrack_url": null,
"license": null,
"summary": "Modern Python library for controlling Sphero BOLT+ robots with enhanced features",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://sphero-bolt-plus.readthedocs.io",
"Homepage": "https://github.com/assistant/sphero-bolt-plus",
"Issues": "https://github.com/assistant/sphero-bolt-plus/issues",
"Repository": "https://github.com/assistant/sphero-bolt-plus"
},
"split_keywords": [
"bluetooth",
" bolt",
" education",
" robotics",
" sphero"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "19e1a3bf5d1788592b3c47c5288c320bdb3d5ba3dc55eb5ac228e3994f220ca0",
"md5": "e76dc73906ae86f981014e6108bcaf52",
"sha256": "6efeb755fbeee276b1286b20f5579a59463565b251f203f6c277b1b5a3e9a928"
},
"downloads": -1,
"filename": "sphero_bolt_plus-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e76dc73906ae86f981014e6108bcaf52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13751,
"upload_time": "2025-08-21T05:48:15",
"upload_time_iso_8601": "2025-08-21T05:48:15.066428Z",
"url": "https://files.pythonhosted.org/packages/19/e1/a3bf5d1788592b3c47c5288c320bdb3d5ba3dc55eb5ac228e3994f220ca0/sphero_bolt_plus-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3d8b911ff1466231f55053424f4a852833042060b857dd891160142fe4aca46e",
"md5": "7e26799d4324c8ecc961a332d5c858f2",
"sha256": "586018aa00f77fcdde4f7924b0cf85ba8880b4f934e242f3c011dff365c15e49"
},
"downloads": -1,
"filename": "sphero_bolt_plus-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7e26799d4324c8ecc961a332d5c858f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24367,
"upload_time": "2025-08-21T05:48:16",
"upload_time_iso_8601": "2025-08-21T05:48:16.195465Z",
"url": "https://files.pythonhosted.org/packages/3d/8b/911ff1466231f55053424f4a852833042060b857dd891160142fe4aca46e/sphero_bolt_plus-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 05:48:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "assistant",
"github_project": "sphero-bolt-plus",
"github_not_found": true,
"lcname": "sphero-bolt-plus"
}
