pyBittle, Open Source library to connect and control Bittle

Hello, I have developed this Python library that allows connecting to Bittle through Bluetooth and WiFi (and Serial communication soon) and sending commands and custom messages.

pyBittle objective is keeping it simple to connect to and manage Bittle while allowing more complex operations.

The library repository can be found here: github/pyBittle

You can read in-depth documentation and usage examples here: gitbook/pyBittle

pyBittle can be installed using the following comand:

pip install pyBittle

Connecting to your Bittle and sending commands to it is as simple as shown below:

bittle = pyBittle.Bittle()  # Create Bittle instance

# Connecting through Bluetooth
is_connected = bittle.connect_bluetooth()
if is_connected:
    bittle.send_command_bluetooth(pyBittle.Command.GREETING)


# Connecting through WiFi
bittle.wifiManager.ip = '192.168.1.132'  # Set Bittle IP address
has_connection = bittle.has_wifi_connection()
if has_connection:
    bittle.send_command_wifi(pyBittle.Command.SIT)

pyBittle has been tested on Raspbian and Windows10. WiFi and Bluetooth connection are supported on Raspbian, only WiFi connection is supported on Windows10 due to pyBluez (dependency) limitations.

pyBittle structure

pyBittle is composed of three modules:

• bittleManager: High level module that allows connecting to Bittle through Bluetooth and WiFi and sending and receiving messages to control it. bittleManager contains the following classes:

  • Bittle: This class represents your Bittle. Has a bluetoothManager and a wifiManager that allow sending messages and receive their responses from your Bittle.

  • Command: Enum that defines avaliable commands that can be sent to Bittle (greeting, sit, pushup, balance...).

  • Direction: Enum that defines avaliable movement directions (forward, forward left, backward...).

  • Gait: Enum that defines avaliable gaits (walk, crawl, trot, run).

• bluetoothManager: Module that manages Bluetooth connection; allows finding your Bittle among paired devices, connecting to it and sending and receiving messages.

• wifiManager: Module that manages WiFi connection through REST API hosted in providen WiFi dongle; allows sending and receiving messages to Bittle.

bittleManager is the main module, instanciating Bittle class is enough to manage and control your Bittle.

Usage examples

The following examples show the full process of creating a Bittle instance and communicating with it through Bluetooth and WiFi.

Sending 'khi' (greet) and 'd' (rest) commands through Bluetooth:

import pyBittle
import time

greet_command = pyBittle.Command.GREETING  # 'khi' message
rest_command = pyBittle.Command.REST  # 'd' message

bittle = pyBittle.Bittle()  # Create Bittle instance

isConnected = bittle.connect_bluetooth()  # Search for your Bittle among paired devices and connect to it
if isConnected:
    bittle.send_command_bluetooth(greet_command)  # Send 'khi' message
    received_msg = bittle.receive_msg_bluetooth()  # Get response from Bittle
    decoded_msg = received_msg.decode('utf-8')  # received_msg is byte type
    decoded_msg = decoded_msg.replace('\r\n', '')  # Remove new line from decoded_msg
    print(f"Received message: {decoded_msg}, expected: k")
    time.sleep(5)  # Give Bittle few seconds to finish the sent action

    bittle.send_command_bluetooth(rest_command)  # Send 'd' message
    received_msg = bittle.receive_msg_bluetooth()
    decoded_msg = received_msg.decode('utf-8')
    decoded_msg = decoded_msg.replace('\r\n', '')
    print(f"Received message: {decoded_msg}, expected: d")
    time.sleep(5)
    bittle.disconnect_bluetooth()  # Close Bluetooth connection
else:
    print("Can't connect to Bittle!")

Sending 'kstr' (stretch) and 'ksit' (sit) commands through WiFi:

import pyBittle
import time

stretch_command = pyBittle.Command.STRETCH  # 'kstr' message
sit_command = pyBittle.Command.SIT  # 'ksit' message

bittle = pyBittle.Bittle() # Create Bittle instance
bittle.wifiManager.ip = '192.168.1.131' # Set REST API IP address

if bittle.has_wifi_connection():
    response = bittle.send_command_wifi(stretch_command) # Send 'kstr' message
    print(f"Received response: {response}, expected: 200")
    time.sleep(5)  # Give Bittle few seconds to finish the sent action
 
    response = bittle.send_command_wifi(sit_command) # Send 'ksit' message
    print(f"Received response: {response}, expected: 200")
    time.sleep(5)
else:
    print("Can't connect to Bittle!")

Changing gait and sending movement commands:

import pyBittle
import time

forward = pyBittle.Direction.FORWARD
forward_right = pyBittle.Direction.FORWARDRIGHT
stop = pyBittle.Command.BALANCE  # BALANCE is Command type, not Direction type!

crawl = pyBittle.Gait.CRAWL
trot = pyBittle.Gait.TROT

bittle = pyBittle.Bittle() # Create Bittle instance
bittle.wifiManager.ip = '192.168.1.132' # Set Bittle IP address

has_connection = bittle.has_wifi_connection()
if has_connection:
    bittle.gait = crawl  # Change current gait (by default, WALK) to CRAWL
    bittle.send_movement_wifi(forward)
    time.sleep(5)
    bittle.send_movement_wifi(forward_right)
    time.sleep(3)
 
    bittle.gait = trot # Change current gait (WALK) to TROT
    bittle.send_movement_wifi(forward)
    time.sleep(5)
 
    bittle.send_command_wifi(stop) # Send command, not movement (as BALANCE is Command type)
    time.sleep(2)
else:
   print("Can't connect to Bittle!")

Project made with pyBittle

One of the Bittle-related projects I have made is BittleXboxController, which makes use of pyBittle. This project makes full use of command sending and movement management.

pyBittle has been my most ambitious and serious project so far, I hope you all find it useful.