{"id":13650656,"url":"https://github.com/frawau/aioblescan","last_synced_at":"2026-01-04T09:59:30.526Z","repository":{"id":44966806,"uuid":"95285422","full_name":"frawau/aioblescan","owner":"frawau","description":"Python only library to scan and decode advertised BLE info. Uses asyncio. Can decode Ruuvi Tag. Can broadcast EddyStone packets.","archived":false,"fork":false,"pushed_at":"2023-01-14T12:21:32.000Z","size":133,"stargazers_count":117,"open_issues_count":5,"forks_count":63,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-02-26T01:00:31.825Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frawau.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-24T08:29:17.000Z","updated_at":"2024-02-26T01:00:31.826Z","dependencies_parsed_at":"2023-02-09T19:31:03.792Z","dependency_job_id":null,"html_url":"https://github.com/frawau/aioblescan","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frawau%2Faioblescan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frawau%2Faioblescan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frawau%2Faioblescan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frawau%2Faioblescan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frawau","download_url":"https://codeload.github.com/frawau/aioblescan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250297479,"owners_count":21407216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T02:00:38.967Z","updated_at":"2026-01-04T09:59:30.479Z","avatar_url":"https://github.com/frawau.png","language":"Python","funding_links":[],"categories":["Python","Tools"],"sub_categories":[],"readme":"# aioblescan\n\naioblescan is a Python 3/asyncio library to listen for BLE advertized packets.\n\n[![PyPI version fury.io](https://badge.fury.io/py/aioblescan.svg)](https://pypi.python.org/pypi/aioblescan)\n[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-licen)\n[![GITHUB-BADGE](https://github.com/frawau/aioblescan/workflows/black/badge.svg)](https://github.com/psf/black)\n[![Downloads](https://pepy.tech/badge/aioblescan/month)](https://pepy.tech/project/aioblescan)\n\n## Installation\n\nWe are on PyPi so\n\n     pip3 install aioblescan\nor\n\n     python3 -m pip install aioblescan\n\n## How to use\n\nEssentially, you create a function to process the incoming\ninformation and you attach it to the `BTScanRequester`. You then create a Bluetooth\nconnection, you issue the scan command and wait for incoming packets and process them.\n\nYou can use Eddystone or RuuviWeather to retrieve specific information\n\nThe easiest way is to look at the `__main__.py` file.\n\nYou can run the command:\n\n    aioblescan\n\nor you can run the module with\n\n    python3 -m aioblescan\n\nAdd `-h` for help.\n\nTo see the RuuviTag weather information try:\n\n    python3 -m aioblescan -r\n\nYou will get\n\n    Weather info {'rssi': -64, 'pressure': 100300, 'temperature': 24, 'mac address': 'fb:86:84:dd:aa:bb', 'tx_power': -7, 'humidity': 36.0}\n    Weather info {'rssi': -62, 'pressure': 100300, 'temperature': 24, 'mac address': 'fb:86:84:dd:aa:bb', 'tx_power': -7, 'humidity': 36.0}\n\nTo check Eddystone beacon\n\n    python3 -m aioblescan -e\n\nYou get\n\n    Google Beacon {'tx_power': -7, 'url': 'https://ruu.vi/#BEgYAMR8n', 'mac address': 'fb:86:84:dd:aa:bb', 'rssi': -52}\n    Google Beacon {'tx_power': -7, 'url': 'https://ruu.vi/#BEgYAMR8n', 'mac address': 'fb:86:84:dd:aa:bb', 'rssi': -53}\n\nTo check ATC_MiThermometer with [custom firmware](https://github.com/atc1441/ATC_MiThermometer) beacon\n\n    python3 -m aioblescan -A\n\nYou get\n\n    Temperature info {'mac address': 'a4:c1:38:40:52:38', 'temperature': 2.8, 'humidity': 62, 'battery': 72, 'battery_volts': 2.863, 'counter': 103, 'rssi': -76}\n    Temperature info {'mac address': 'a4:c1:38:40:52:38', 'temperature': 2.8, 'humidity': 62, 'battery': 72, 'battery_volts': 2.863, 'counter': 103, 'rssi': -77}\n\nTo check ThermoBeacon sensors\n\n    python3 -m aioblescan -T\n\nYou get\n\n    Temperature info {'mac address': '19:c4:00:00:0f:5d', 'max_temperature': 27.0625, 'min_temperature': 21.75, 'max_temp_ts': 0, 'min_temp_ts': 2309}\n    Temperature info {'mac address': '19:c4:00:00:0f:5d', 'temperature': 21.75, 'humidity': 49.5, 'battery_volts': 3234, 'counter': 2401, 'rssi': -67}\n\nFor a generic advertise packet scanning\n\n    python3 -m aioblescan\n\nYou get\n\n    HCI Event:\n        code:\n            3e\n        length:\n            19\n        LE Meta:\n            code:\n                02\n            Adv Report:\n                num reports:\n                    1\n                ev type:\n                    generic adv\n                addr type:\n                    public\n                peer:\n                    54:6c:0e:aa:bb:cc\n                length:\n                    7\n                flags:\n                    Simul LE - BR/EDR (Host): False\n                    Simul LE - BR/EDR (Control.): False\n                    BR/EDR Not Supported: False\n                    LE General Disc.: True\n                    LE Limited Disc.: False\n                Incomplete uuids:\n                        ff:30\n                rssi:\n                    -67\n    HCI Event:\n        code:\n            3e\n        length:\n            43\n        LE Meta:\n            code:\n                02\n            Adv Report:\n                num reports:\n                    1\n                ev type:\n                    no connection adv\n                addr type:\n                    random\n                peer:\n                    fb:86:84:dd:aa:bb\n                length:\n                    31\n                flags:\n                    Simul LE - BR/EDR (Host): False\n                    Simul LE - BR/EDR (Control.): False\n                    BR/EDR Not Supported: False\n                    LE General Disc.: True\n                    LE Limited Disc.: True\n                Complete uuids:\n                        fe:aa\n                Advertised Data:\n                    Service Data uuid:\n                        fe:aa\n                    Adv Payload:\n                        10:f9:03:72:75:75:2e:76:69:2f:23:42:45:77:59:41:4d:52:38:6e\n                rssi:\n                    -59\n\nHere the first packet is from a Wynd device, the second from a Ruuvi Tag\n\naioblescan can also send EddyStone advertising. Try the -a flag when running the module.\n\nTo check Tilt hydrometer\n\n    python3 -m aioblescan --tilt\n\nYou will see the regular Bluetooth beacons from any Tilt in range:\n\n    {\"uuid\": \"a495bb40c5b14b44b5121370f02d74de\", \"major\": 70, \"minor\": 1054, \"tx_power\": 31, \"rssi\": -58, \"mac\": \"xx:xx:xx:xx:xx:xx\"}\n    {\"uuid\": \"a495bb40c5b14b44b5121370f02d74de\", \"major\": 70, \"minor\": 1054, \"tx_power\": 31, \"rssi\": -74, \"mac\": \"xx:xx:xx:xx:xx:xx\"}\n    {\"uuid\": \"a495bb40c5b14b44b5121370f02d74de\", \"major\": 70, \"minor\": 1054, \"tx_power\": 31, \"rssi\": -57, \"mac\": \"xx:xx:xx:xx:xx:xx\"}\n\nHit `ctrl-c` to stop the scan.\n\n## Interpreting the Tilt Data\n\nThe information from the tilt plugin is returned as a valid JSON:\n\n    {\n    \"uuid\": \"a495bb40c5b14b44b5121370f02d74de\",\n    \"major\": 69,\n    \"minor\": 1056,\n    \"tx_power\": 31,\n    \"rssi\": -49,\n    \"mac\": \"xx:xx:xx:xx:xx:xx\"\n    }\n\nThese keys may be interpreted as:\n\n- **uuid**:  Tilt name.  The \"40\" in a495bb`40`c5b14b44b5121370f02d74de is an indication of the color.\n  - 10: Red\n  - 20: Green\n  - 30: Black\n  - 40: Purple\n  - 50: Orange\n  - 60: Blue\n  - 70: Yellow\n  - 80: Pink\n- **major**: Temp in degrees F.\n- **minor**: Specific gravity x1000.\n- **tx_power**: Weeks since battery change (0-152 when converted to unsigned 8 bit integer).  You will occasionally see `-59` which is there to allow iOS to compute RSSI.  This value should be discarded.\n- **rssi**: Received Signal Strength Indication (RSSI) is a measurement of the power present in the received radio signal.  A lower negative number is stronger.\n- **mac**: Media Access Control (MAC) address of the device.\n\n## FAQ\n\nWhy not use scapy?\n\n    Scapy is great and you can do\n\n        import scapy.all as sa\n        test=sa.BluetoothHCISocket(0)\n        command=sa.HCI_Cmd_LE_Set_Scan_Enable(enable=1,filter_dups=0)\n        chdr=sa.HCI_Command_Hdr(len=len(command))\n        hdr=sa.HCI_Hdr(type=1)\n        test.send(hdr / chdr / command)\n\n    to get things going. But... the great thing with Scapy is that there is so\n    many versions to choose from.... and not all have all the same functions ... and\n    installation can be haphazard, with some version not installing at all. Also\n    scapy inludes a lot of other protocols and could be an overkill... lastly it\n    is never too late to learn...\n\nWhat can you track?\n\n    aioblescan will try to parse all the incoming advertised information. You can see\n    the raw data when it does not know what to do. With Eddystone beacon you can see the\n    URL, Telemetry and UID\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrawau%2Faioblescan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrawau%2Faioblescan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrawau%2Faioblescan/lists"}