Skip to content
Python libraries for Ubertooth
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin pyubertooth_rx: use file context management Jun 5, 2018
notebooks notebook cleanup Apr 29, 2016
pyubertooth
.gitignore notebook cleanup Apr 29, 2016
LICENSE
README.md
setup.cfg
setup.py

README.md

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
You can’t perform that action at this time.