TLDR: How to Make a Simple Bluetooth Scanner with Python

3 min readMar 15, 2023

A condensed version of our Bluetooth scanner articles for Mac, Windows, and Linux.

This is the TLDR version of our “How to Make a Bluetooth Scanner” tutorials for Mac OS, Windows, and Linux.

If you are new to Python or Bluetooth, the original articles may work better for you:

Note: This code scans for Bluetooth LE devices, which are not the same as Bluetooth Classic devices. Devices like headphones tend to be Bluetooth Classic. Other wearables like heart rate monitors and smart watches use Bluetooth LE.

Requirements

Mac OS 12+, Windows 10+, or Linux
Python 3
Bleak (a Python Bluetooth LE library)
Bluetooth LE devices within 100 meters of you

Install Bleak and Pip

Pip is needed to install Bleak. It is the main package manager for Python. Installing it will make all of your future Python projects easier.

To install Pip on Mac:

python -m ensurepip --upgrade

To install Pip on Windows:

py -m ensurepip --upgrade

Then, to install Bleak (Pip required):

pip install bleak

Scanner Code

Put this code in a file named scanner.py. This is the complete scanner.

# scanner.py

import asyncio
from bleak import BleakScanner

async def main():
    devices = await BleakScanner.discover()
    for device in devices:
        print(device)


asyncio.run(main())

Read more about asyncio and asynchronous code here.

Run the Scanner

Run the scanner from the command line with python scanner.py (or python3, depending on your system).

The scanner gets us a list of MAC addresses (AB:CD:EF:12:34:56) and device names of Bluetooth LE devices near us. Below is what the output will look like on Windows or Linux computers.

The Bluetooth scanner outputs 13 devices, each with one MAC address and one name.

On a Mac OS computer, the output will have UUIDs instead of MAC addresses and will look like:

UUIDs and MAC addresses are used in the same way to connect to Bluetooth LE devices. (The use of UUIDs was a decision on Apple’s part.)

Why Does This Work?

Bluetooth scanning is made possible, because Bluetooth devices are shouting out their existence into the universe at all times.

They sound out messages that say, “Hey, I am Lisa’s smart watch, and I want to connect!” Our code is simply listening in on these messages.

Bluetooth devices are advertising that they’re available all the time, unless they’re already connected.

Troubleshooting

If you get a device not found error or something similar, make sure your computer’s Bluetooth is on.
If your script prints nothing at all, try running it again. Sometimes, there are so few devices near you that your computer won’t pick up any signals.
If you’re not finding a particular device, research the Bluetooth module on that device and make sure it is not Bluetooth Classic instead of Bluetooth LE. Bluetooth Classic and Bluetooth LE are not compatible.
Make sure your Bluetooth device itself is on. Some devices will sleep if they’re not connected to quickly enough.

Questions and Feedback

If you have questions or feedback, email us at protobioengineering@gmail.com or message us on Instagram (@protobioengineering).

If you liked this article, consider supporting us by donating a coffee.