bonicbot 3.0.0

Unified Python library for controlling BonicBot via BLE and WebSocket Bridge

BonicBot Python Library

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

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.

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.

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.

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.

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 for details on how to get started with development.

License

MIT License - see the LICENSE file for details.