Skip to Content
ProgrammingPython SDK

Programming Guide

BonicBot Python SDK - A comprehensive Python library for controlling BonicBot humanoid robots (A1, S1, and A2) via WebSocket communication for remote, wireless control.

Overview

The BonicBot Python SDK provides intuitive methods to control your BonicBot robot remotely from your laptop or PC. Using WebSocket communication, you can control individual servos, coordinate complex movements, manage base motors, and integrate AI capabilities - all through simple Python commands.

Compatible Robots

This SDK supports WebSocket-based control for:

RobotWebSocket SupportnNotes
BonicBot S1✅ Full supportProfessional humanoid with 6-DOF arm
BonicBot A1✅ Full supportSmartphone-powered humanoid
BonicBot A2✅ Full supportFor phone-based control (non-ROS mode)

For A2 Users: This guide covers WebSocket control using the smartphone. For ROS2-based development on A2’s Raspberry Pi, see the BonicBot A2 page.

Installation

Prerequisites

  • Python 3.7 or higher
  • BonicBot Controller App installed on robot’s smartphone
  • Same WiFi network for laptop and robot
  • Basic Python programming knowledge

Install from PyPI

# Install the BonicBot SDK
pip install bonicbot
 
# Test your installation
bonicbot-test
 
# Test your version
pip show bonicbot

Verify Installation

# Test core functionality
from bonicbot import BonicBotController, CommunicationType
print("✅ Core functionality works!")
 
# Test WebSocket controller creation
from bonicbot import create_websocket_controller
print("✅ WebSocket controller available!")
 
# Check version
import bonicbot
print(f"BonicBot SDK version: {bonicbot.__version__}")

WebSocket Communication

How It Works

Install BonicBot Controller App

Download and install the BonicBot Controller App  on your robot’s smartphone

Connect to Same Network

Ensure your laptop/PC and the robot are on the same WiFi network

Find Robot’s IP Address

Check the robot’s IP address in the BonicBot Controller app (usually shown on startup or in settings)

Connect via WebSocket

Use the Python SDK to connect to ws://ROBOT_IP:8080/control

Send Commands

Control the robot remotely from your laptop using Python

The BonicBot Controller app acts as a WebSocket server, receiving commands from your laptop and executing them on the robot.

Connection Setup

from bonicbot import create_websocket_controller
 
# Replace with your robot's IP address
robot_ip = "192.168.1.100"
websocket_uri = f"ws://{robot_ip}:8080/control"
 
# Create controller
bot = create_websocket_controller(websocket_uri)
 
# Or use context manager (recommended)
with create_websocket_controller(websocket_uri) as bot:
    # Your code here
    bot.control_head(pan_angle=45.0)
    # Connection automatically closed

Quick Start Guide

Basic Example

from bonicbot import create_websocket_controller
import time
 
# Connect to robot
robot_ip = "192.168.1.100"
bot = create_websocket_controller(f"ws://{robot_ip}:8080/control")
 
# Control individual servo
bot.control_servo('headPan', angle=45.0, speed=200)
time.sleep(1)
 
# Control head movement
bot.control_head(pan_angle=0.0, tilt_angle=-10.0)
time.sleep(1)
 
# Control left hand
bot.control_left_hand(gripper_angle=90.0, elbow_angle=45.0)
time.sleep(1)
 
# Move the robot base (A2 only)
bot.move_forward(speed=100)
time.sleep(2)
bot.stop()
 
# Close connection
bot.close()

The context manager automatically handles connection cleanup:

from bonicbot import create_websocket_controller
 
with create_websocket_controller('ws://192.168.1.100:8080/control') as bot:
    # Control head
    bot.control_head(pan_angle=45.0, tilt_angle=-10.0)
 
    # Control arms
    bot.control_left_hand(gripper_angle=90.0)
    bot.control_right_hand(wrist_angle=45.0)
 
    # Move base (A2)
    bot.move_forward(speed=100)
 
    # Connection automatically closed when exiting block

Available Servos & Controls

Head Servos

Control the robot’s head movement for looking and tracking:

Servo IDDescriptionRangeUsage
headPanHead rotation (left/right)-90° to 90°Looking around
headTiltHead tilt (up/down)-38° to 45°Looking up/down

Example:

# Look right and up
bot.control_head(pan_angle=45.0, tilt_angle=20.0)
 
# Look left and down
bot.control_head(pan_angle=-45.0, tilt_angle=-20.0)
 
# Center position
bot.control_head(pan_angle=0.0, tilt_angle=0.0)

Left Arm Servos

Control the robot’s left arm for manipulation and gestures:

Servo IDDescriptionRange
leftGripperGripper open/close-90° to 90°
leftWristWrist rotation-90° to 90°
leftElbowElbow bend-90° to 0°
leftSholderPitchShoulder pitch (forward/back)-45° to 180°
leftSholderYawShoulder yaw (left/right)-90° to 90°
leftSholderRollShoulder roll (rotation)-3° to 144°

Example:

# Wave gesture
bot.control_left_hand(
    gripper_angle=0.0,          # Open gripper
    wrist_angle=0.0,
    elbow_angle=-45.0,          # Bend elbow
    sholder_pitch_angle=90.0,   # Raise arm
    sholder_yaw_angle=45.0,     # Angle outward
    sholder_roll_angle=0.0
)
 
# Grab object
bot.control_left_hand(
    gripper_angle=90.0,         # Close gripper
    elbow_angle=-60.0,
    sholder_pitch_angle=45.0
)

Right Arm Servos

Mirror controls for the right arm:

Servo IDDescriptionRange
rightGripperGripper open/close-90° to 90°
rightWristWrist rotation-90° to 90°
rightElbowElbow bend-90° to 0°
rightSholderPitchShoulder pitch-45° to 180°
rightSholderYawShoulder yaw-90° to 90°
rightSholderRollShoulder roll-3° to 144°

Example:

# Point gesture
bot.control_right_hand(
    gripper_angle=-90.0,        # Close gripper (point)
    elbow_angle=-30.0,
    sholder_pitch_angle=120.0,  # Extend arm
    sholder_yaw_angle=0.0
)

Base Motors (A2 Only)

For BonicBot A2 with mobile base:

# Move forward
bot.move_forward(speed=100)
 
# Move backward
bot.move_backward(speed=100)
 
# Turn left
bot.turn_left(speed=50)
 
# Turn right
bot.turn_right(speed=50)
 
# Stop all motors
bot.stop()
 
# Custom motor control
bot.control_base(left_motor_speed=100, right_motor_speed=100)

Speed Range: Motor speed values typically range from 0 to 255. Start with lower values (50-100) and increase as needed.

API Reference

BonicBotController Class

Constructor

BonicBotController(
    communication_type: str,
    websocket_uri: str,
    timeout: float = 1.0
)

Parameters:

  • communication_type: Communication method ('websocket')
  • websocket_uri: WebSocket URI (e.g., 'ws://192.168.1.100:8080/control')
  • timeout: Connection timeout in seconds (default: 1.0)

Individual Servo Control

control_servo(
    servo_id: str,
    angle: float,
    speed: int = 200,
    acc: int = 20
) -> bool

Parameters:

  • servo_id: Servo identifier (e.g., 'headPan', 'leftGripper')
  • angle: Target angle in degrees
  • speed: Movement speed (0-500, default: 200)
  • acc: Acceleration (0-100, default: 20)

Returns: True if command sent successfully

Example:

# Smooth head movement
bot.control_servo('headPan', angle=45.0, speed=150, acc=30)
 
# Fast gripper close
bot.control_servo('leftGripper', angle=90.0, speed=400, acc=50)

Group Control Methods

Head Control
control_head(
    pan_angle: float = 0.0,
    tilt_angle: float = 0.0,
    speed: int = 200,
    acc: int = 20
) -> bool

Example:

# Look at object
bot.control_head(pan_angle=30.0, tilt_angle=-15.0, speed=150)
Left Hand Control
control_left_hand(
    gripper_angle: float = 0.0,
    wrist_angle: float = 0.0,
    elbow_angle: float = 0.0,
    sholder_pitch_angle: float = 0.0,
    sholder_yaw_angle: float = 0.0,
    sholder_roll_angle: float = 0.0,
    speed: int = 200,
    acc: int = 20
) -> bool

Example:

# Reach and grab
bot.control_left_hand(
    gripper_angle=0.0,
    elbow_angle=-45.0,
    sholder_pitch_angle=90.0,
    speed=150
)
Right Hand Control
control_right_hand(
    gripper_angle: float = 0.0,
    wrist_angle: float = 0.0,
    elbow_angle: float = 0.0,
    sholder_pitch_angle: float = 0.0,
    sholder_yaw_angle: float = 0.0,
    sholder_roll_angle: float = 0.0,
    speed: int = 200,
    acc: int = 20
) -> bool
Base Control (A2)
control_base(
    left_motor_speed: int = 0,
    right_motor_speed: int = 0
) -> bool

Example:

# Differential drive
bot.control_base(left_motor_speed=100, right_motor_speed=80)

Movement Methods (A2)

move_forward(speed: int = 100) -> bool
move_backward(speed: int = 100) -> bool
turn_left(speed: int = 100) -> bool
turn_right(speed: int = 100) -> bool
stop() -> bool

Example:

import time
 
# Navigate in a square
for _ in range(4):
    bot.move_forward(speed=100)
    time.sleep(2)
    bot.turn_right(speed=80)
    time.sleep(1)
 
bot.stop()

Connection Management

close() -> None

Closes the WebSocket connection. Always call this when done, or use context manager.

# Manual close
bot = create_websocket_controller(uri)
try:
    bot.control_head(pan_angle=45.0)
finally:
    bot.close()
 
# Or use context manager (automatic close)
with create_websocket_controller(uri) as bot:
    bot.control_head(pan_angle=45.0)

Programming Examples

Example 1: Head Tracking

Simulate head tracking by scanning the environment:

from bonicbot import create_websocket_controller
import time
 
with create_websocket_controller('ws://192.168.1.100:8080/control') as bot:
    # Scan left to right
    for angle in range(-60, 61, 10):
        bot.control_head(pan_angle=float(angle), tilt_angle=0.0)
        time.sleep(0.3)
 
    # Return to center
    bot.control_head(pan_angle=0.0, tilt_angle=0.0)

Example 2: Waving Gesture

Create a friendly waving motion:

from bonicbot import create_websocket_controller
import time
 
with create_websocket_controller('ws://192.168.1.100:8080/control') as bot:
    # Raise arm to wave position
    bot.control_right_hand(
        gripper_angle=-90.0,
        elbow_angle=-30.0,
        sholder_pitch_angle=120.0,
        sholder_yaw_angle=30.0
    )
    time.sleep(1)
 
    # Wave motion
    for _ in range(3):
        bot.control_servo('rightWrist', angle=45.0, speed=300)
        time.sleep(0.4)
        bot.control_servo('rightWrist', angle=-45.0, speed=300)
        time.sleep(0.4)
 
    # Return to rest
    bot.control_right_hand(
        gripper_angle=0.0,
        elbow_angle=0.0,
        sholder_pitch_angle=0.0
    )

Example 3: Pick and Place (S1)

For BonicBot S1 with 6-DOF arm:

from bonicbot import create_websocket_controller
import time
 
with create_websocket_controller('ws://192.168.1.100:8080/control') as bot:
    # Approach object
    bot.control_left_hand(
        gripper_angle=0.0,          # Open gripper
        elbow_angle=-60.0,
        sholder_pitch_angle=60.0
    )
    time.sleep(2)
 
    # Grab object
    bot.control_servo('leftGripper', angle=90.0, speed=200)
    time.sleep(1)
 
    # Lift object
    bot.control_servo('leftSholderPitch', angle=120.0, speed=150)
    time.sleep(2)
 
    # Move to new position
    bot.control_servo('leftSholderYaw', angle=45.0, speed=150)
    time.sleep(2)
 
    # Release object
    bot.control_servo('leftGripper', angle=0.0, speed=200)
    time.sleep(1)
 
    # Return to rest
    bot.control_left_hand(
        gripper_angle=0.0,
        elbow_angle=0.0,
        sholder_pitch_angle=0.0,
        sholder_yaw_angle=0.0
    )

Example 4: Patrol Route (A2)

Autonomous patrol pattern using base motors:

from bonicbot import create_websocket_controller
import time
 
with create_websocket_controller('ws://192.168.1.100:8080/control') as bot:
    # Patrol in a rectangle
    for _ in range(2):
        # Move forward
        bot.move_forward(speed=100)
        time.sleep(3)
        bot.stop()
        time.sleep(0.5)
 
        # Turn 90 degrees
        bot.turn_right(speed=80)
        time.sleep(1)
        bot.stop()
        time.sleep(0.5)
 
        # Move forward (shorter side)
        bot.move_forward(speed=100)
        time.sleep(2)
        bot.stop()
        time.sleep(0.5)
 
        # Turn 90 degrees
        bot.turn_right(speed=80)
        time.sleep(1)
        bot.stop()
        time.sleep(0.5)

Example 5: Synchronized Movements

Coordinate multiple servos for complex gestures:

from bonicbot import create_websocket_controller
import time
 
with create_websocket_controller('ws://192.168.1.100:8080/control') as bot:
    # Both arms raise simultaneously
    bot.control_left_hand(sholder_pitch_angle=120.0)
    bot.control_right_hand(sholder_pitch_angle=120.0)
    time.sleep(2)
 
    # Wave both hands
    for _ in range(3):
        bot.control_servo('leftWrist', angle=45.0, speed=300)
        bot.control_servo('rightWrist', angle=-45.0, speed=300)
        time.sleep(0.4)
 
        bot.control_servo('leftWrist', angle=-45.0, speed=300)
        bot.control_servo('rightWrist', angle=45.0, speed=300)
        time.sleep(0.4)
 
    # Return to rest
    bot.control_left_hand()
    bot.control_right_hand()

Best Practices

Connection Management

# ✅ Good: Use context manager
with create_websocket_controller(uri) as bot:
    bot.control_head(pan_angle=45.0)
# Connection automatically closed
 
# ❌ Bad: Manual connection without cleanup
bot = create_websocket_controller(uri)
bot.control_head(pan_angle=45.0)
# Connection never closed!

Movement Timing

import time
 
# ✅ Good: Add delays between movements
bot.control_head(pan_angle=45.0, speed=200)
time.sleep(1.0)  # Wait for movement to complete
bot.control_head(pan_angle=-45.0, speed=200)
 
# ❌ Bad: No delays
bot.control_head(pan_angle=45.0, speed=200)
bot.control_head(pan_angle=-45.0, speed=200)  # Conflicts!

Error Handling

# ✅ Good: Handle potential errors
try:
    with create_websocket_controller(uri) as bot:
        bot.control_head(pan_angle=45.0)
except ConnectionError as e:
    print(f"Failed to connect: {e}")
except Exception as e:
    print(f"Error: {e}")
 
# ❌ Bad: No error handling
bot = create_websocket_controller(uri)
bot.control_head(pan_angle=45.0)

Speed and Smoothness

# ✅ Good: Smooth, controlled movement
bot.control_servo('headPan', angle=45.0, speed=150, acc=30)
 
# ❌ Bad: Too fast, jerky movement
bot.control_servo('headPan', angle=45.0, speed=500, acc=100)

Advanced Topics

Custom Movement Sequences

Create reusable movement sequences:

from bonicbot import create_websocket_controller
import time
 
def wave_sequence(bot, hand='right'):
    """Execute a waving gesture"""
    if hand == 'right':
        bot.control_right_hand(
            sholder_pitch_angle=120.0,
            sholder_yaw_angle=30.0
        )
    else:
        bot.control_left_hand(
            sholder_pitch_angle=120.0,
            sholder_yaw_angle=-30.0
        )
 
    time.sleep(1)
 
    for _ in range(3):
        wrist_servo = 'rightWrist' if hand == 'right' else 'leftWrist'
        bot.control_servo(wrist_servo, angle=45.0, speed=300)
        time.sleep(0.4)
        bot.control_servo(wrist_servo, angle=-45.0, speed=300)
        time.sleep(0.4)
 
# Usage
with create_websocket_controller(uri) as bot:
    wave_sequence(bot, hand='right')
    wave_sequence(bot, hand='left')

Gesture Library

Build a library of common gestures:

class GestureLibrary:
    def __init__(self, bot):
        self.bot = bot
 
    def nod(self, times=2):
        """Nod head up and down"""
        for _ in range(times):
            self.bot.control_head(tilt_angle=20.0, speed=200)
            time.sleep(0.5)
            self.bot.control_head(tilt_angle=-10.0, speed=200)
            time.sleep(0.5)
        self.bot.control_head(tilt_angle=0.0)
 
    def shake_head(self, times=2):
        """Shake head left and right"""
        for _ in range(times):
            self.bot.control_head(pan_angle=30.0, speed=200)
            time.sleep(0.5)
            self.bot.control_head(pan_angle=-30.0, speed=200)
            time.sleep(0.5)
        self.bot.control_head(pan_angle=0.0)
 
    def point(self, direction='right'):
        """Point in a direction"""
        if direction == 'right':
            self.bot.control_right_hand(
                gripper_angle=-90.0,
                sholder_pitch_angle=90.0,
                sholder_yaw_angle=90.0
            )
        else:
            self.bot.control_left_hand(
                gripper_angle=-90.0,
                sholder_pitch_angle=90.0,
                sholder_yaw_angle=-90.0
            )
 
# Usage
with create_websocket_controller(uri) as bot:
    gestures = GestureLibrary(bot)
    gestures.nod()
    gestures.shake_head()
    gestures.point('right')

Additional Resources

Documentation & Support

Official package repository with version history

📦 PyPI Package

Source code, issues, and community discussions

💻 GitHub Repository

Download the BonicBot Controller app

📱 Controller App

Cloud platform for projects and learning

🌐 Bonic.ai Platform

Community & Help

  • Email Support: support@autobonics.com
  • GitHub Issues: Report bugs and request features
  • Documentation: Complete guides at bonic.ai
  • Video Tutorials: YouTube channel with examples

Example Projects

Browse the examples/ directory in the GitHub repository:

  • basic_control.py: Basic servo and movement control
  • head_movements.py: Head tracking and scanning patterns
  • hand_gestures.py: Hand gestures and manipulation tasks
  • base_movement.py: Navigation patterns (A2)

Next Steps

Master the Basics

Start with simple servo control and movement examples

Explore Gestures

Create custom gesture sequences and test them

Build Projects

Combine movements with AI features for interactive applications

Share & Contribute

Contribute examples and improvements to the GitHub repository

Ready to start programming? Install the SDK with pip install bonicbot and check out the examples on GitHub !

Version & Compatibility

SDK VersionCompatible RobotsPython VersionFeatures
LatestA1, S1, A23.7+WebSocket control, Full API
2.x.xA1, S13.7+Basic WebSocket, Servo control

Check your installed version:

pip show bonicbot

Update to latest version:

pip install --upgrade bonicbot
Last updated on
BonicBot S1