Metadata-Version: 2.4
Name: bonicbot
Version: 3.0.0
Summary: Unified Python library for controlling BonicBot via BLE and WebSocket Bridge
Home-page: https://github.com/Autobonics/bonicbot
Author: Autobonics Team
Author-email: Autobonics Team <admin@autobonics.com>
Maintainer-email: Autobonics Team <admin@autobonics.com>
License: MIT
Project-URL: Homepage, https://github.com/Autobonics/bonicbot
Project-URL: Documentation, https://github.com/Autobonics/bonicbot/docs
Project-URL: Repository, https://github.com/Autobonics/bonicbot.git
Project-URL: Bug Tracker, https://github.com/Autobonics/bonicbot/issues
Keywords: robot,robotics,servo,control,ble,bluetooth,humanoid,bonicbot,hardware,automation,websocket,bridge
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: websockets>=15.0
Requires-Dist: bleak>=0.21.0
Provides-Extra: gui
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# BonicBot Python Library

[![PyPI version](https://badge.fury.io/py/bonicbot.svg)](https://badge.fury.io/py/bonicbot)
[![Python versions](https://img.shields.io/pypi/pyversions/bonicbot.svg)](https://pypi.org/project/bonicbot/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A unified Python library for controlling the **BonicBot** humanoid robot. This library provides a single interface to control the robot's hardware directly via **Bluetooth Low Energy (BLE)** and high-level Android app features via a **WebSocket Bridge**.

## Key Features

- **Unified Controller**: One class (`BonicBotController`) handles everything.
- **Low Latency BLE**: Direct hardware control (servos, motors, sensors, LED matrix) over BLE binary protocol.
- **App Bridge**: Easy access to Android-specific features:
  - **Text-to-Speech (TTS)**: Make the robot speak.
  - **Sequences**: Play, pause, and manage complex movement sequences.
  - **Camera**: Start MJPEG streams and capture snapshots.
- **Type Safety**: Full use of Python type hints and dataclasses for robot state.
- **Async Foundation**: Built on `bleak` and `websockets` for modern, non-blocking performance.

## Installation

```bash
pip install bonicbot
```

### Dependencies
- `bleak`: For BLE communication.
- `websockets`: For communication with the BonicBot Android App.

## Quick Start

### Basic Hardware Control (BLE)
To control the robot's hardware (servos, wheels, LEDs), you only need the robot's BLE device name.

```python
from bonicbot import BonicBotController

# Connect via BLE only
bot = BonicBotController(device_name="BonicBot-S1")

if bot.connect():
    # Move the head
    bot.control_head(pan=30, tilt=-10)
    
    # Move the robot base
    bot.move_forward(speed=150, duration=2)
    
    # Control the LED matrix
    bot.set_display_text("HELLO")
    
    bot.close()
```

### Full Control (BLE + App Features)
To use features like TTS or Camera, provide the IP address of the Android device running the BonicBot app.

```python
from bonicbot import BonicBotController

# Connect via BLE and WebSocket Bridge
bot = BonicBotController(device_name="BonicBot-S1", ws_host="192.168.1.100")

if bot.connect():
    # Hardware (BLE)
    bot.move_forward(speed=100)
    
    # App Features (WebSocket)
    bot.speak("Hello! I am ready to assist you.")
    bot.play_sequence("Wave")
    
    # Capture a snapshot from the camera
    image = bot.capture_image()
    if image:
        with open("snapshot.jpg", "wb") as f:
            f.write(image.data)
            
    bot.close()
```

## Advanced Usage

### Reading Sensors
The robot streams battery and distance data back to the controller.

```python
def on_battery(data):
    print(f"Battery: {data['soc']}% ({data['voltage']}V)")

bot.start_battery_stream(callback=on_battery)
# The callback will be triggered whenever new data arrives over BLE.
```

### Hand Gestures
Control 6 servos per hand simultaneously using `HandCommand`.

```python
from bonicbot.controllers.models import HandCommand

# Open right gripper and lift arm
bot.control_right_hand(gripper=90, elbow=-45, shoulder_pitch=90)
```

## API Reference

### `BonicBotController(device_name, ws_host=None, ws_port=8080)`
- **`connect()`**: Establish BLE and WebSocket connections.
- **`close()`**: Disconnect all services.

#### Hardware Control (BLE)
- **`move_forward / backward / turn_left / right(speed, duration)`**
- **`control_servo(servo_id, angle, speed, acceleration)`**
- **`control_head(pan, tilt, mode, speed)`**
- **`control_right_hand / left_hand(**kwargs)`**
- **`set_display_text / color / animation / pixel / frame(...)`**
- **`read_battery() / read_distance()`**: Request a single update.
- **`start_battery_stream / start_distance_stream(interval, callback)`**

#### App Bridge (WebSocket)
- **`speak(text)`**: Android TTS.
- **`get_sequences()`**: Returns list of available sequences on the app.
- **`play_sequence(name, seq_id)`**: Triggers a sequence.
- **`stop_sequence() / pause_sequence() / resume_sequence()`**
- **`jump_to_step(step_index)`**
- **`start_camera_stream() / stop_camera_stream()`**
- **`capture_image()`**: Returns a `CapturedImage` object (JPEG).

## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started with development.

## License
MIT License - see the [LICENSE](LICENSE) file for details.
