Cluetooth Scanner Code the Cluetooth Scanner

Cluetooth Scanner

What's all this blue stuff?

Image for user johnpark
by John Park
published June 15, 2026, last edited June 15, 2026
posted in CircuitPython Breakout Boards/ Radio Internet of Things - IOT/ Bluefruit / BLE CLUE
Save Link Note Download
3
New
Intermediate
Project guide

Code the Cluetooth Scanner

The project uses a specific set of CircuitPython libraries, and the main code.py file. To get everything you need, click on the Download Project Bundle link below, and uncompress the .zip file.

We can do this in one go. In the example code block below, click the Download Project Bundle button to download the necessary libraries and the code.py file as a zip file. Extract the contents of the zip file, open the directory Cluetooth_Scanner/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

Download Project Bundle
Copy Code
View on GitHub

How it Works

Libraries and User Variables

First the program imports libraries. The BLE functions are handled by adafruit_ble and its Advertisement class, the display by displayio and adafruit_display_text, and inputs by digitalio and touchio. Also imported is gc (garbage collector) to help with memory management.

Download File
Copy Code 
import gc
import time
import displayio
import terminalio
from adafruit_display_text import label
from adafruit_ble import BLERadio
from adafruit_ble.advertising import Advertisement
import board
import digitalio
import touchio

Next are some user variables.

Copy Code 
SCAN_EVERY  = 12.0   # seconds between scan bursts
SCAN_WINDOW = 1.0    # how long each scan lasts
BUTTON_IDLE = 3.0    # wait this long after button activity before scanning
MAX_DEVICES = 30     # cap the device list here to protect memory

Lookup Tables

A big chunk of the file is lookup tables — Python dictionaries that map raw bytes to human-readable strings. There are four of them.

MFR_IDS maps 2-byte company IDs (the first two bytes of Manufacturer Specific Data, little-endian) to brand names. This is how we know 4C 00 means Apple and 83 01 means Walt Disney.

OUI maps the first three bytes of a public MAC address (the Organizationally Unique Identifier) to chip vendor names. This is how we know a device with MAC starting D0:EF:76 contains an Espressif ESP32.

GATT_SERVICES maps 16-bit service UUIDs to Bluetooth profile names like Heart Rate, HID, and Battery.

APPEARANCE maps the 16-bit appearance value from the 0x19 AD type to device category names like Keyboard, Heart Rate Belt, and Gamepad.

Display Setup

The CLUE's 240×240 display is set up at startup. displayio creates the visual elements — a header bar, a footer bar, a selection highlight strip, and eight rows of text labels for the device list. A separate overlay group holds the detail view.

Button and Touch Input

Physical buttons A and B are handled by a small Button class that distinguishes taps from holds by timing how long the pin stays pressed:

Download File
Copy Code

Each call to update() sets .tapped or .held for exactly one loop tick, then clears them. This means the main loop can check btn_A.tapped without worrying about debouncing or repeated firing.

The three capacitive touch pads are even simpler — it just compares the current value to the last tick's value and fires on the rising edge:

Copy Code 
touch1_val = _touch1.value
touch1_tap = touch1_val and not _touch1_last
_touch1_last = touch1_val

All five inputs reset a shared last_button_time timestamp. The scan only runs when this timestamp is more than BUTTON_IDLE seconds old, keeping navigation smooth.

Scanning

The do_scan() function runs a blocking scan burst. Before it starts, it calls gc.collect() to reclaim any heap memory that's no longer in use, then tries to allocate the scan buffer starting at 4096 bytes and falling back to smaller sizes if memory is tight:

Download File
Copy Code 
gc.collect()
for buf in (4096, 2048, 1024):
    try:
        scan = ble.start_scan(
            Advertisement,
            minimum_rssi=-100,
            timeout=SCAN_WINDOW,
            active=True,
            buffer_size=buf,
        )
        break
    except MemoryError:
        try:
            ble.stop_scan()
        except Exception:  # pylint: disable=broad-except
            pass
        gc.collect()

For each advertisement entry the scan receives, we pull out fields from entry.data_dict — a dictionary keyed by AD type number. This is the raw BLE advertisement structure, where each entry has a type byte and a payload. We look up types 0x02/0x03 for service UUIDs, 0x19 for appearance, 0x16 for service data, and 0xFF for manufacturer specific data:

Download File
Copy Code 
dd = entry.data_dict
msd = parse_mfr_data(dd)    # AD type 0xFF
svcs = parse_service_uuids(dd)  # AD types 0x02, 0x03, 0x06, 0x07
appearance = parse_appearance(dd)  # AD type 0x19
svc_data = parse_svc_data(dd)  # AD type 0x16

After scanning, stale devices are pruned — any device not seen in the last three scan cycles gets removed from the list, and selected is clamped so it doesn't point past the end of a shortened list.

Identifying Devices

Company identification works in two layers. The MSD bytes describes the brand, and the MAC address OUI describes the chip:

Download File
Copy Code 
def company_from_mfr(mfr):
    if not mfr or len(mfr) < 2:
        return None
    return MFR_IDS.get((mfr[0], mfr[1]))

def company_from_addr(addr_str):
    oui = addr_str.replace(":", "").upper()[:6]
    return OUI.get(oui)

For Apple devices, we go further. Byte index 2 of the MSD payload (after the 4C 00 company ID) is the Apple Continuity message subtype. We decode this into a readable label and then pass it to guess_apple_device() which returns a plain-language device type:

Download File
Copy Code 
def guess_apple_device(mfr):
    if not mfr or len(mfr) < 3 or mfr[0] != 0x4C or mfr[1] != 0x00:
        return None
    t = mfr[2]
    if t == 0x07:
        return "AirPods"
    if t == 0x09:
        return "AppleTV/HomePod"
    if t == 0x0C:
        return "iPhone/iPad"
    if t == 0x12 and len(mfr) >= 6:
        if mfr[4] != 0x00:
            return "AirTag? (separated)"
        return "iPhone"
    # ... and so on

The separated AirTag detection works like this: a non-zero status byte in the FindMy payload means the device has been away from its owner long enough to trigger Apple's anti-stalking detection threshold.

When an AirTag is within local Bluetooth range of its owner, it doesn't need to advertise because the owner's iPhone can find it directly. But when an AirTag has been away from its owner's devices for a period of time (Apple hasn't published the exact threshold, but it's in the range of 8-24 hours), it switches into a "separated" state and starts broadcasting a FindMy beacon more aggressively so that other nearby iPhones can anonymously detect it and relay its location back to the owner through Apple's FindMy network.

Filtering and Rendering

After each scan the device list is sorted by RSSI (strongest signal first). When a filter mode is active, filtered_order() returns a filtered subset without modifying the underlying list — the full device data is always preserved:

Download File
Copy Code 
def filtered_order():
    if filter_mode == 0:  # ALL
        return addr_order
    result = []
    for addr in addr_order:
        dev = devices[addr]
        msd = dev["msd"]
        is_apple = (msd and len(msd) >= 2 and msd[0] == 0x4C and msd[1] == 0x00)
        has_name = bool(dev["name"])
        # ... apply filter and append to result
    return result

render_list() takes a slice of the filtered list and updates the row labels. The selected row gets accent color; all others are colored by signal strength — green for strong, yellow for medium, red for weak. This lets you see signal at a glance.

Detail View and Paging

When you press B to get more details on a selected device, build_detail_lines() assembles the full content as a flat list of (text, color) tuples. render_detail() then slices this into pages:

Copy Code 
page_size  = len(det_lines) - 1   # reserve last row for nav hint
total_pages = max(1, (len(lines) + page_size - 1) // page_size)
start = detail_page * page_size
page_lines = lines[start : start + page_size]

The last row always shows a navigation hint that updates based on which page you're on — A:list B:next pg 1/2 on the first page, A:prev B:next pg 2/2 on subsequent pages, and just A: back to list when everything fits on one screen.

The Main Loop

On each tick, the main loop checks whether a scan is due, updates all five inputs, and dispatches actions based on what was pressed. The scan check includes both the time condition and the idle condition:

Download File
Copy Code 
while True:
    now = time.monotonic()

    if (now - last_scan >= SCAN_EVERY and
            now - last_button_time >= BUTTON_IDLE):
        do_scan()
        last_scan = time.monotonic()
        render_list()

    btn_A.update(now)
    btn_B.update(now)
    # ... touch pad edge detection
    # ... dispatch button and touch actions

Because the loop has no time.sleep() calls outside of the scan burst itself, button response is essentially instant — the only delay you'll ever feel is during the one-second scan window, which the footer signals with a ...scanning... message.

Page last edited June 01, 2026

Text editor powered by tinymce.

 CircuitPython on CLUE Assemble the Cluetooth 
Related Guides
An Adafruit CLUE microcontroller board with a small screen displays changing sensor information. It features buttons, labeled pins, and a USB connection.
Introducing Adafruit CLUE
By Kattni Rembor
beginner
105
3D-printed metronome case housing an CLUE electronic display showing 120 BPM.
Metronome CLUE
By John Park
beginner
9
A CLUE-based bike-mounted device displays speed and RPM on a screen, with buttons on either side for interaction. The background shows handlebars and a path.
Pyloton: CircuitPython Cycling Computer
By John Park
intermediate
44
A small robot car with glowing purple lights moves across a flat surface. It features a compact design made with a CLUE and has visible electronic components.
Bluetooth CLUE Robot Car using CircuitPython
By M. LeBlanc-Williams
beginner
25
Adafruit CLUE board displaying badge text on its screen, including "@circuitpython Blinka CircuitPythonista she/her." A pink connector is attached at the top.
CLUE Custom CircuitPython Badge
By Kattni Rembor
beginner
19
A hand holds a CLUE microcontroller board with a display showing altitude readings of 5436 and 5172. Snowy mountains are visible in the background.
CLUE Altimeter
By Carter Nelson
beginner
17
A hand holds a CLUE-based BBQ temperature monitor displaying 64.4°F and 168.8°F, in front of an oven with a red pot inside. Wires connect the monitor to a probe in the oven.
CircuitPython BLE Multi-Temperature Monitoring
By John Park
intermediate
15
A vintage TTY machine displays "ADAFRUIT 1234567890" on its screen. A CLUE board is connected, showing a circuit setup connected to an acoustic coupler.
CLUE Text Telephone Transmitter
By John Park
beginner
11
A CLUE microcontroller mounted on a glove displays MIDI control change messages while interfacing with a synthesizer app on a tablet. A finger points to the tablet's virtual piano keyboard.
CLUE BLE MIDI Glove
By John Park
beginner
26
Two Adafruit CLUE boards display sensor readings, one on a stand and another on a lanyard. Both show data on small screens and both have 3D printed clear cases.
CLUE case
By Ruiz Brothers
beginner
20
A teal robot with a single large eye and two legs holds a yellow flower on top. Electronic components, a yellow flower and wires are visible on its head.
Chauncey the Flower Care Bot with CLUE and Bonsai...
By John Park
intermediate
20
A pink purse displays a circular arrangement of colorful, animated LED lights. The LEDs are likely controlled by an internal CLUE microcontroller which shows a small image on a viewable display.
A colorful CLUE slideshow purse with Bright Wearables
By Anne Barela
beginner
19
A Clue microcontroller with a display is attached to a coffee machine, showing coffee and scale readings. Wires connect the microcontroller to sensors.
Clue Coffee Scale
By Jan Goolsbey
beginner
25
Silhouette of a person wearing two round LED "ears" on a headband, left ear showing red LEDs and right ear showing white LEDs. Background shows sparks and smoke from fireworks creating a blue-orange night scene.
BLE Beacon NeoPixels
By Ruiz Brothers
beginner
9
New
A hand holds a CLUE board displaying colorful text on a small screen. The board features buttons and labeled connections. Colored text says "make a VIDEO about SUCCESS BREAD".
Creative Inspiration Activity Generator
By Collin Cunningham
beginner
10
A cartoon snake with a magnifying glass is next to the "CircuitPython" logo. The snake's body features a circuit pattern. The snake, named Blinka, is the CircuitPython mascot.
Which CircuitPython Board is Right for You?
By Kattni Rembor
beginner
36
Search

Search

Categories