PyUbertooth

• Python libraries for Ubertooth

Project Description:

• The goal of PyUbertooth is to provide libraries and tools to interact with an ubertooth device in python.
• All modules and libraries provided by PyUbertooth provide pure python implementations.
• Cpython implementations will be provided in the future, but will always have pure python alternatives.

Core PyUbertooth Libraries:

• pyubertooth/ubertooth.py: Provides direct access to an ubertooth device.
• pyubertooth/bluetooth_packet.py: Provides methods and data structures for converting ubertooth data into bluetooth baseband data.

Core PyUbertooth Tools:

• pyubertooth_rx: This file provides some CLI functionality to control the ubertooth.
• ubertooth_dump: A simple script to dump data from an ubertooth device to a file. This dump data is compatible with the ubertooth C libraries and tools (i.e. used with the -i flag with the ubertooth-rx tool).

Upcoming Milestones:

• Finish up porting over all USB get/set/mode command functions (WIP)
• The library is still lacking verbose doc strings. These will be added soon and all of my shitty useless comments will get cleaned up
• Rewrite my pure python libbtbb lib (WIP)
• Create Ctypes libbtbb bindings (WIP)
• Rewrite my ubertooth scapy rx layer
• Create an ubertooth scapy tx layer

Core CLI Script: pyubertooth_rx

• A pure python interface to an ubertooth device.
• TODO: Switch to *args, **kwargs for my argparse methods
• TODO: Many of the simple ubertooth usb contols will be added soon (such as led control, etc)
• TODO: Full python library documentation.

Sample command line usage:

For usage help:

pyubertooth_rx --help

To log ubertooth data to a file (usable with ubertooth-rx -i filename):

pyubertooth_rx --outfile=dump_filename.dump

To log ubertooth data directly to a file from bluetooth channel 60:

pyubertooth_rx --outfile=dump_filename.dump --channel 60

To log 30 seconds worth of ubertooth data directly to a file :

pyubertooth_rx --outfile=dump_filename.dump -t 30

To log 300 ubertooth usb data packets directly to a file :

pyubertooth_rx --outfile=dump_filename.dump -n 300

To read raw ubertooth usb data from a dump file to std out:

pyubertooth_rx --infile=dump_filename.dump

To display bluetooth packet information from a dump file (LAP, UAP, channel, etc):

pyubertooth_rx --infile=dump_filename.dump --btbb

To display bluetooth packet information from a live stream (LAP, UAP, channel, etc):

pyubertooth_rx --btbb

Sample python library usage:

To open a connection to an ubertooth device:

from pyubertooth.ubertooth import Ubertooth
ut = Ubertooth()

To access 5 data blocks from an ubertooth device as a python iterator:

from pyubertooth.ubertooth import Ubertooth
ut = Ubertooth()
for data in ut.rx_stream(count=5):
    print data
ut.close()

To access data blocks from an ubertooth device as a python iterator for 30 seconds:

from pyubertooth.ubertooth import Ubertooth
ut = Ubertooth()
for data in ut.rx_stream(secs=30):
    print data
ut.close()

To access data from an ubertooth device until ctrl-C is pressed:

from pyubertooth.ubertooth import Ubertooth
ut = Ubertooth()
try:
    for data in ut.rx_stream():
        print data
except KeyboardInterrupt:
    pass
ut.close()

An example of directly streaming ubertooth data to a file for 60 seconds:

from pyubertooth.ubertooth import Ubertooth
ut = Ubertooth()
f = open("dump_filename.dump", 'wb')
for data in ut.rx_stream(secs=60):
    f.write(data)
f.close()
ut.close()

Changing the channel on an ubertooth device:

from pyubertooth.ubertooth import Ubertooth 
ut = Ubertooth()
ut.set_channel(66)

Core Library: pylibbtbb/bluetooth_packet.py

• This is a pure python implementation of bluetooth_packet from libbtbb. It serves as library for python applications. It is currently in its early stages and based off of the c library libbtbb and some of my ugly POC code
• LAP & channel detection is working (still needs some cleanup).
• UAP and packet type detection still needs ported from my alpha POC code.
• TODO: utilized the pure python module BitVector.
• TODO: be as cool as the C libbtbb

Sample python library usage:

To display bluetooth packet data for an ubertooth device stream:

from pyubertooth.ubertooth import Ubertooth() 
from pyubertooth.bluetooth_packet import BtbbPacket
ut = Ubertooth()
for data in ut.rx_stream():
    print BtbbPacket(data=data)
ut.close()

Core Tools: tools/ubertooth_dump.py

• A simple stand alown pure python script to dump data from an ubertooth into a file. The dump format is compatible with the ubertooth-rx tool. This allows for data to be collected in python and parsed with the core ubertooth libraries.

To dump data from an ubertooth to a file:

python ubertooth_dump.py dump_filename.dump