beacontools 2.1.0

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.

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)

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()

from beacontools import BeaconScanner, BluetoothAddressType

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

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