Package: beacontools
A Python library for working with various types of Bluetooth LE Beacons.Currently supported types are:Eddystone BeaconsiBeacons(Apple and Cypress CYALKIT-E02)Estimote Beacons (Telemetry and Nearable)Control-J Monitor (temp/humidity/light)COVID-19 Exposure NotificationsThe BeaconTools library has two main components:a parser to extract information from raw binary beacon advertisementsa scanner which scans for Bluetoth LE advertisements using bluez and can be configured to look only for specific beacons or packet typesInstallationIf you only want to use theparserinstall the library using pip and you’re good to go:pip3installbeacontoolsIf you want to perfom beaconscanningthere 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 libpcap2sudoapt-getinstallpython3-devlibbluetooth-devlibcap2-bin# grant the python executable permission to access raw socket datasudosetcap'cap_net_raw,cap_net_admin+eip'"$(readlink-f"$(whichpython3)")"# install beacontools with scanning supportpip3installbeacontools[scan]UsageSee theexamplesdirectory for more usage examples.Parserfrombeacontoolsimportparse_packettlm_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:%dmV"%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)ScannerimporttimefrombeacontoolsimportBeaconScanner,EddystoneTLMFrame,EddystoneFilterdefcallback(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 beaconsdevice_filter=EddystoneFilter(namespace="12345678901234678901"),packet_filter=EddystoneTLMFrame)scanner.start()time.sleep(10)scanner.stop()importtimefrombeacontoolsimportBeaconScanner,IBeaconFilterdefcallback(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 uuidscanner=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 beaconscanner=BeaconScanner(callback,packet_filter=IBeaconAdvertisement)scanner.start()time.sleep(5)scanner.stop()Customizing Scanning ParametersSome 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:frombeacontoolsimportBeaconScanner,BluetoothAddressTypescanner=BeaconScanner(callback,scan_parameters={"address_type":BluetoothAddressType.PUBLIC})For all available options seeMonitor.set_scan_parameters.ChangelogBeacontools follows thesemantic versioningscheme.2.1.0Added support for extended BLE commands for devices using HCI >= 5.0 (Linux only, thanks toidaniel86)2.0.2Improved prefiltering of packets, fixes #482.0.1Removed (unused) rfu field from the Eddystone UID packet, fixes #392.0.0Dropped support for Python 2.7 and 3.4Added support for COVID-19 Exposure NotificationsAdded support for FreeBSD and fixed temperature parsing (thanks tomyfreeweb)Added support for Control-J Monitor beacons (thanks toclydebarrow)Added support for Estimote Nearables (thanks toShaunPlummer)1.3.1Multiple fixes and internal refactorings, including support for Raspberry Pi 3B+ (huge thanks tocereal)Updated dependencies1.3.0Added support for Estimote Telemetry packets (see examples/parser_example.py)Relaxed parsing constraints for RFU and flags fieldAdded temperature output in 8.8 fixed point decimal format for Eddystone TLM1.2.4Added support for Eddystone packets with Flags Data set to 0x1a (thanks toAndreasTornes)Updated dependencies1.2.3Fixed compatibility with construct >=2.9.411.2.2Moved import of bluez so that the library can be used in parsing-only mode, without having bluez installed.1.2.1Updated dependencies1.2.0Added support for Cypress iBeacons which transmit temp and humidity embedded in the minor value (thanks todarkskiez)Updated dependencies1.1.0Added support for Eddystone EID frames (thanks tomiek)Updated dependencies1.0.1Implemented a small tweak which reduces the CPU usage.1.0.0Implemented iBeacon supportAdded rssi to callback function.0.1.2Initial release