19 Python BLE: Runtime Boundaries and Positioning

19.1 Start With the Decision

A Bleak client can scan, connect, or notify, but each role has a runtime limit. The design must keep those limits visible before it estimates position.

19.2 Route Overview

This is part 3 of 3. Review Python BLE: RSSI Smoothing and Zones for the preceding evidence.

19.3 Learning Objectives

• Separate Bleak scanner, client, and notification roles.
• Choose a BLE positioning method from measured runtime limits.

19.4 Chapter Roadmap

• Deep Dive: Bleak Role Boundaries and Runtime Limits
• Reference: BLE Quick Reference Card
• Indoor Positioning with BLE Beacons
• Summary
• Worked Example: RSSI-to-Distance Calculation and Zone Classification
• Decision Framework: Choosing BLE Python Library (bleak vs alternatives)
• Common Mistake: Not Handling BLE Disconnections in Long-Running Scripts
• Common Pitfalls
• 1. Not Awaiting bleak Coroutines
• 2. Scanning by Name in Noisy Environments
• 3. Blocking the asyncio Event Loop in Notification Callbacks
• 4. Assuming Consistent Service/Characteristic Handle Order
• What’s Next
• Key Takeaway

19.5 Deep Dive: Bleak Role Boundaries and Runtime Limits

Bleak is a Central/client API. A modern BLE controller can time-slice more than one role, but Bleak exposes the Python host as the scanner, initiator, and GATT client. If the same product also needs a phone to discover the Python host or read a characteristic served by it, that Peripheral/server role needs firmware support or a platform-specific peripheral stack.

The scaling constraint is usually scheduling, not Python byte throughput. A gateway subscribed to 12 peripherals sending one 20 byte notification each second handles only about 240 payload bytes per second, but the controller still schedules every connection event and the OS backend still delivers every callback. Keep notification callbacks short: decode the packet, attach a timestamp, enqueue the record, and return. File writes, MQTT publishes, and database retries belong outside the BLE callback path.

ATT framing also changes what a successful trace proves. With the default ATT MTU, a notification commonly carries up to 20 application bytes after overhead. A 38 byte sensor report needs MTU negotiation or application-level chunking with an order field and a missing-chunk timeout. Otherwise a clean connection log can still hide truncated data.

Disconnects are normal events. For a 2 second sample period, marking a sensor stale after 10 seconds means five missed samples; that explicit timing assumption is easier for the rest of the IoT pipeline to reason about than a generic “retry forever” loop.

19.6 Reference: BLE Quick Reference Card

19.7 Indoor Positioning with BLE Beacons

19.7.1 Start With the Story

Test One Doorway Claim Before Acting on It

Picture a cart reported on the wrong side of a fire door because a person blocked one beacon. A location estimate must carry its uncertainty into the decision.

Bluetooth Low Energy is the short-range radio system used by the beacons; it is shortened to BLE. Received signal strength means the radio power that arrives at a receiver. RSSI means received signal strength indicator, the radio’s reported estimate of that power.

Walk a marked route twice, then repeat it with a blocked beacon. Keep anchor positions, time, BLE readings, RSSI filter settings, estimated position, residual error, and the action that would follow.

This route test does not prove room-level accuracy everywhere. The deeper sections cover calibration, distance models, trilateration, filtering, error, and fallback rules.

A beacon signal near a doorway is not yet a position. RSSI, calibration, anchor placement, filtering, movement, walls, and uncertainty decide whether a location claim is useful or misleading.

Read this chapter from the final decision backward. Ask what the system will do with the position, then check whether the beacon evidence is strong enough for that action.

Phoebe’s Field Notes: Why A Few dB Becomes A Few Metres

The mathematical gist. Distance sits in an exponent: d̂/d0=10^(δ/10n). With n=2, an 8 dB weaker reading multiplies 2.00 m to 5.02 m, while an 8 dB stronger reading gives 0.796 m—not the chapter quiz’s 1.4 m. The linear shortcut predicts 92.1% at 8 dB, but the exact increase is 151%.

Math Bridge · guided foundationsWhy can 8 dB turn 2.00 m into 5.02 m?Let Radio Remi invert the logarithm and expose where the small-error shortcut breaks. Learn the maths

19.7.3 Build the Positioning System, Step by Step

Before writing the solver, inspect Figure 19.1 to see what three fixed beacons contribute and why one RSSI reading cannot produce a two-dimensional position. The picture frames the result as an estimate from noisy distance proxies, not as GPS-like ground truth.

Read Figure 19.1 from each known beacon position to its RSSI-derived range circle, then inspect the region where all three circles come closest to intersecting. A single beacon can only suggest “near” or “far”; three constraints allow a best-fit (x, y) estimate. The imperfect overlap is meaningful: multipath, body shadowing, antenna orientation, and the path-loss model create residual error, which the implementation must retain rather than hiding behind an exact coordinate.

System element	Role in the positioning lab	What the code uses
Beacon 1	Fixed anchor at (0, 0)	RSSI converted to distance d1
Beacon 2	Fixed anchor at (5, 0)	RSSI converted to distance d2
Beacon 3	Fixed anchor at (0, 5)	RSSI converted to distance d3
Mobile device	Unknown point being estimated	Best-fit (x, y) position
Residual error	Quality check for the estimate	Larger error means noisy RSSI or a poor path-loss model

Think of each distance as drawing a circle around a beacon. The estimated position is where the three circles overlap most closely.

import numpy as np
from scipy.optimize import least_squares

def trilaterate(beacons, distances):
    """
    Calculate position from beacon positions and distances.

    Args:
        beacons: List of (x, y) beacon positions
        distances: List of distances to each beacon

    Returns:
        (x, y) estimated position
    """
    def residuals(point, beacons, distances):
        return [
            np.sqrt((point[0] - b[0])**2 + (point[1] - b[1])**2) - d
            for b, d in zip(beacons, distances)
        ]

    # Initial guess: centroid of beacons
    x0 = np.mean([b[0] for b in beacons])
    y0 = np.mean([b[1] for b in beacons])

    result = least_squares(
        residuals,
        [x0, y0],
        args=(beacons, distances)
    )

    return tuple(result.x)

# Example usage
beacons = [(0, 0), (5, 0), (0, 5)]
distances = [1.78, 4.47, 2.82]  # From RSSI
position = trilaterate(beacons, distances)
print(f"Estimated position: {position}")

Try It: BLE Trilateration Simulator

Place 3 beacons and adjust the measured distance from each to see where trilateration estimates your position. The circles represent the distance measurement from each beacon — the estimated position is where they intersect.

Checkpoint: you should now be able to explain why three noisy distances produce a best-fit position rather than a guaranteed exact location. The residual error tells you whether the three circles agree.

19.8 Summary

This chapter covered production Python BLE implementations:

• Scanner with Filtering: RSSI thresholds and name pattern matching for targeted device discovery
• GATT Explorer: Enumerating services and characteristics on connected devices
• Beacon Management: Parsing iBeacon and Eddystone advertisement formats
• Proximity Detection: Zone-based presence detection with exponential smoothing
• Power Optimization: Decision framework for connection intervals and advertising parameters

alpha = 0.3  # EMA smoothing factor
rssi_samples = [-68, -72, -65, -70, -66]

smoothed = rssi_samples[0]  # Initialize with first sample
for rssi in rssi_samples[1:]:
    smoothed = alpha * rssi + (1 - alpha) * smoothed
    print(f"RSSI {rssi} → Smoothed {smoothed:.1f}")

RSSI -72 → Smoothed -69.2
RSSI -65 → Smoothed -67.9
RSSI -70 → Smoothed -68.6
RSSI -66 → Smoothed -67.8

import math

tx_power = -59
rssi = -67.8
n = 2.5

distance = 10 ** ((tx_power - rssi) / (10 * n))
print(f"Distance: {distance:.2f} meters")

def classify_zone(rssi):
    if rssi > -55:
        return "immediate", "< 0.5m"
    elif rssi > -70:
        return "near", "0.5 - 3m"
    else:
        return "far", "> 3m"

zone, range_desc = classify_zone(-67.8)
print(f"Zone: {zone} ({range_desc})")

import asyncio
from bleak import BleakScanner

async def scan():
    devices = await BleakScanner.discover(timeout=10)
    for dev in devices:
        print(dev.address, dev.rssi)

asyncio.run(scan())

import asyncio
from bleak import BleakClient

async def monitor_temperature():
    address = "A4:CF:12:34:56:78"
    async with BleakClient(address) as client:
        while True:
            # Read temperature characteristic
            temp_bytes = await client.read_gatt_char("0x2A6E")
            temp = int.from_bytes(temp_bytes, 'little') / 100.0
            print(f"Temperature: {temp}°C")
            await asyncio.sleep(60)  # Read every minute

asyncio.run(monitor_temperature())

import asyncio
from bleak import BleakClient
from bleak.exc import BleakError

async def monitor_temperature():
    address = "A4:CF:12:34:56:78"

    while True:  # Outer loop for reconnection
        try:
            async with BleakClient(address, timeout=20) as client:
                print(f"Connected to {address}")

                while True:  # Inner loop for reading
                    try:
                        temp_bytes = await client.read_gatt_char("0x2A6E")
                        temp = int.from_bytes(temp_bytes, 'little') / 100.0
                        print(f"Temperature: {temp}°C")
                        await asyncio.sleep(60)

                    except BleakError as e:
                        print(f"Read error: {e}, will reconnect")
                        break  # Exit inner loop to trigger reconnect

        except BleakError as e:
            print(f"Connection failed: {e}, retrying in 5s")
            await asyncio.sleep(5)
        except KeyboardInterrupt:
            print("Stopped by user")
            break

asyncio.run(monitor_temperature())

retry_delay = 5
max_delay = 60

while True:
    try:
        async with BleakClient(address) as client:
            retry_delay = 5  # Reset on successful connect
            # ... reading loop ...
    except BleakError:
        print(f"Retrying in {retry_delay}s")
        await asyncio.sleep(retry_delay)
        retry_delay = min(retry_delay * 2, max_delay)  # Exponential backoff

19.9 What’s Next

Prioritize these follow-up chapters based on the implementation problem you are solving:

• BLE code examples: bt-impl-code-examples.html for foundational scanner, GATT client, and notification patterns.
• BLE hands-on labs: bt-impl-labs.html for complete projects that combine scanning, services, proximity, and mesh concepts.
• Bluetooth security: bluetooth-security.html for pairing, bonding, encryption, and threat modeling before production deployment.
• BLE pairing methods: bt-security-pairing-methods.html for authenticated subscriptions and bonded devices.
• BLE encryption keys: ble-key-management.html for LTK, IRK, CSRK, and re-connection behavior.
• Bluetooth applications: bluetooth-applications.html for deployment scenarios that use BLE gateways, beacons, and wearables.
• UWB positioning systems: ../rfid-nfc-uwb/uwb-positioning-systems.html when BLE RSSI zones are not accurate enough.
• Bluetooth fundamentals and architecture: bluetooth-fundamentals-and-architecture.html to connect Python API behavior back to GAP, GATT, ATT, and link-layer concepts.

19.10 Key Takeaway

Python BLE code must handle asynchronous discovery, connection loss, notification callbacks, and platform differences. Keep scripts event-driven and defensive rather than assuming every peripheral behaves like a stable serial port.

19.11 Continue Your Route

This final part closes the route from Deep Dive: Bleak Role Boundaries and Runtime Limits through Key Takeaway. Return to Python BLE: RSSI Smoothing and Zones or continue from the bluetooth-ble module index.