Skip to main content

A Python library for working with various types of Bluetooth LE Beacons.

Project description

PyPI Package Build Status Coverage Status Requirements Status

A Python library for working with various types of Bluetooth LE Beacons.

Currently supported types are:

The BeaconTools library has two main components:

  • a parser to extract information from raw binary beacon advertisements

  • a scanner which scans for Bluetoth LE advertisements using bluez and can be configured to look only for specific beacons or packet types

Installation

If you only want to use the parser install the library using pip and you’re good to go:

pip3 install beacontools

If you want to perfom beacon scanning there are a few more requirements. First of all, you need a supported OS: currently that’s Linux with BlueZ, and FreeBSD. Second, you need raw socket access (via Linux capabilities, or by running as root).

On a typical Linux installation, it would look like this:

# install libbluetooth headers and libpcap2
sudo apt-get install python3-dev libbluetooth-dev libcap2-bin
# grant the python executable permission to access raw socket data
sudo setcap 'cap_net_raw,cap_net_admin+eip' "$(readlink -f "$(which python3)")"
# install beacontools with scanning support
pip3 install beacontools[scan]

Usage

See the examples directory for more usage examples.

Parser

from beacontools import parse_packet

tlm_packet = b"\x02\x01\x06\x03\x03\xaa\xfe\x11\x16\xaa\xfe\x20\x00\x0b\x18\x13\x00\x00\x00" \
             b"\x14\x67\x00\x00\x2a\xc4\xe4"
tlm_frame = parse_packet(tlm_packet)
print("Voltage: %d mV" % tlm_frame.voltage)
print("Temperature: %d °C" % tlm_frame.temperature)
print("Advertising count: %d" % tlm_frame.advertising_count)
print("Seconds since boot: %d" % tlm_frame.seconds_since_boot)

Scanner

import time

from beacontools import BeaconScanner, EddystoneTLMFrame, EddystoneFilter

def callback(bt_addr, rssi, packet, additional_info):
    print("<%s, %d> %s %s" % (bt_addr, rssi, packet, additional_info))

# scan for all TLM frames of beacons in the namespace "12345678901234678901"
scanner = BeaconScanner(callback,
    # remove the following line to see packets from all beacons
    device_filter=EddystoneFilter(namespace="12345678901234678901"),
    packet_filter=EddystoneTLMFrame
)
scanner.start()
time.sleep(10)
scanner.stop()
import time
from beacontools import BeaconScanner, IBeaconFilter

def callback(bt_addr, rssi, packet, additional_info):
    print("<%s, %d> %s %s" % (bt_addr, rssi, packet, additional_info))

# scan for all iBeacon advertisements from beacons with the specified uuid
scanner = BeaconScanner(callback,
    device_filter=IBeaconFilter(uuid="e5b9e3a6-27e2-4c36-a257-7698da5fc140")
)
scanner.start()
time.sleep(5)
scanner.stop()

# scan for all iBeacon advertisements regardless from which beacon
scanner = BeaconScanner(callback,
    packet_filter=IBeaconAdvertisement
)
scanner.start()
time.sleep(5)
scanner.stop()

Customizing Scanning Parameters

Some Bluetooth dongle don’t allow scanning in Randomized MAC mode. If you don’t receive any scan results, try setting the scan mode to PUBLIC:

from beacontools import BeaconScanner, BluetoothAddressType

scanner = BeaconScanner(
    callback,
    scan_parameters={"address_type": BluetoothAddressType.PUBLIC}
)

For all available options see Monitor.set_scan_parameters.

Changelog

Beacontools follows the semantic versioning scheme.

  • 2.1.0
    • Added support for extended BLE commands for devices using HCI >= 5.0 (Linux only, thanks to idaniel86)

  • 2.0.2
    • Improved prefiltering of packets, fixes #48

  • 2.0.1
    • Removed (unused) rfu field from the Eddystone UID packet, fixes #39

  • 2.0.0
    • Dropped support for Python 2.7 and 3.4

    • Added support for COVID-19 Exposure Notifications

    • Added support for FreeBSD and fixed temperature parsing (thanks to myfreeweb)

    • Added support for Control-J Monitor beacons (thanks to clydebarrow)

    • Added support for Estimote Nearables (thanks to ShaunPlummer)

  • 1.3.1
    • Multiple fixes and internal refactorings, including support for Raspberry Pi 3B+ (huge thanks to cereal)

    • Updated dependencies

  • 1.3.0
    • Added support for Estimote Telemetry packets (see examples/parser_example.py)

    • Relaxed parsing constraints for RFU and flags field

    • Added temperature output in 8.8 fixed point decimal format for Eddystone TLM

  • 1.2.4
    • Added support for Eddystone packets with Flags Data set to 0x1a (thanks to AndreasTornes)

    • Updated dependencies

  • 1.2.3
    • Fixed compatibility with construct >=2.9.41

  • 1.2.2
    • Moved import of bluez so that the library can be used in parsing-only mode, without having bluez installed.

  • 1.2.1
    • Updated dependencies

  • 1.2.0
    • Added support for Cypress iBeacons which transmit temp and humidity embedded in the minor value (thanks to darkskiez)

    • Updated dependencies

  • 1.1.0
    • Added support for Eddystone EID frames (thanks to miek)

    • Updated dependencies

  • 1.0.1
    • Implemented a small tweak which reduces the CPU usage.

  • 1.0.0
    • Implemented iBeacon support

    • Added rssi to callback function.

  • 0.1.2
    • Initial release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

beacontools-2.1.0.tar.gz (24.8 kB view details)

Uploaded Source

Built Distribution

beacontools-2.1.0-py2.py3-none-any.whl (27.0 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file beacontools-2.1.0.tar.gz.

File metadata

  • Download URL: beacontools-2.1.0.tar.gz
  • Upload date:
  • Size: 24.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.7.4

File hashes

Hashes for beacontools-2.1.0.tar.gz
Algorithm Hash digest
SHA256 1676832e14e702f0d4784ea47c1ac20d7044c89befce2e4b895798b32dcf0731
MD5 ffef07f4c5c67729adafe7e544b83538
BLAKE2b-256 be342ce4821fe67c9c3246edc974a371ec8a9ae8365573d87c5817a77e6284f8

See more details on using hashes here.

File details

Details for the file beacontools-2.1.0-py2.py3-none-any.whl.

File metadata

  • Download URL: beacontools-2.1.0-py2.py3-none-any.whl
  • Upload date:
  • Size: 27.0 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.47.0 CPython/3.7.4

File hashes

Hashes for beacontools-2.1.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 4fbfd0714030f3b57d3c6591faa67fb6d73fe94df60b97a1ad5ee46c6bf2ed23
MD5 6a6692087c6c48b4f2ca03bd485bc49a
BLAKE2b-256 edb8d8ba78359be4fe66ee78e7827187e9dae45f060d4f5363d62a6e3a19c5f7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page