Project 10: Bluetooth LE Beacon and Scanner

Advertise as a BLE beacon and scan nearby devices with RSSI smoothing and timestamps.

Quick Reference

Attribute	Value
Difficulty	Intermediate
Time Estimate	1–2 weekends
Main Programming Language	Python (Alternatives: C, Go, Rust)
Alternative Programming Languages	C, Go, Rust
Coolness Level	High
Business Potential	Medium
Prerequisites	Linux CLI, Bluetooth basics
Key Topics	BLE advertising, scanning, RSSI filtering, BlueZ

1. Learning Objectives

By completing this project, you will:

Configure the Pi to advertise as a BLE beacon.
Scan for nearby BLE devices and log RSSI values.
Apply RSSI smoothing to reduce noise.
Understand privacy considerations in BLE.

2. All Theory Needed (Per-Concept Breakdown)

Concept 1: BLE Advertising, Scanning, and RSSI Interpretation

Fundamentals

Bluetooth Low Energy (BLE) is designed for low-power, short-range communication. Devices advertise small packets to announce their presence, and scanners listen for these advertisements. RSSI (Received Signal Strength Indicator) is a rough measure of signal strength, but it is noisy and affected by multipath and obstructions. A reliable scanner must smooth RSSI values and record timestamps to understand device presence. The Pi Zero 2 W uses the BlueZ stack to manage BLE operations.

Deep Dive into the concept

BLE advertising involves a device periodically broadcasting small packets on three advertising channels. The packet can include a device name, UUIDs, and manufacturer data. The advertising interval is configurable; shorter intervals improve discoverability but consume more power. For a beacon, you choose a stable identifier and a reasonable interval (e.g., 100–1000 ms). Scanners listen on the advertising channels and report discovered devices along with RSSI. Because BLE is subject to interference and reflections, RSSI values fluctuate rapidly. A single measurement is not trustworthy; you need smoothing such as a rolling average or median filter.

BlueZ is the official Linux Bluetooth stack. Tools like bluetoothctl can be used to configure advertising and scan. For programmatic control, you can use D-Bus APIs or libraries like bleak. The stack requires permissions and sometimes specific kernel parameters. On Raspberry Pi OS, you typically need to enable the Bluetooth service and ensure the interface is up. If advertising does not work, check hciconfig and system logs.

Privacy is an important part of BLE. Devices can use random addresses and rotate identifiers to avoid tracking. For a beacon project, you might choose a static identifier for simplicity, but you should understand that static identifiers can be tracked. In production systems, you would use rotating UUIDs or encrypted identifiers. For this project, include a note about privacy and implement at least one configuration option for the beacon name or UUID.

Power consumption is another factor. Scanning consumes more power than advertising, and continuous scanning can be expensive. On the Pi Zero 2 W, which is not a battery-optimized device, this is less critical, but still relevant for performance and heat. You can implement a duty-cycled scanner (scan for 5 seconds, rest for 5 seconds) to reduce load.

How this fit on projects

This concept is used in §3, §4, and §5.10. It is also relevant for field devices in the capstone.

Definitions & key terms

BLE: Bluetooth Low Energy.
Advertising: Broadcasting presence packets.
Scanning: Listening for advertisements.
RSSI: Signal strength indicator.
BlueZ: Linux Bluetooth stack.

Mental model diagram (ASCII)

Beacon -> Advertisements -> Scanner -> RSSI filter -> Log

How it works (step-by-step, with invariants and failure modes)

Enable Bluetooth interface.
Configure advertising data and interval.
Start scanning and parse results.
Smooth RSSI values and log.

Failure modes:

Interface down -> no advertising.
Permissions -> scan fails.
RSSI noise -> unstable readings.

Minimal concrete example

bluetoothctl advertise on
bluetoothctl scan on

Common misconceptions

“RSSI equals distance.” It is only a noisy proxy.
“BLE is always private.” Static identifiers can be tracked.

Check-your-understanding questions

Why is RSSI noisy indoors?
How does advertising interval affect discoverability?
What is the role of BlueZ?

Check-your-understanding answers

Multipath reflections and interference cause variability.
Shorter intervals improve discovery but increase power use.
It provides the Bluetooth stack and APIs.

Real-world applications

Asset tracking, proximity detection, indoor navigation.

Where you’ll apply it

This project: §3.2, §5.10.
Other projects: Project 17.

References

“Bluetooth Low Energy” — advertising chapters
BlueZ documentation

Key insights

BLE discovery is probabilistic; reliable systems require smoothing and time-based logic.

Summary

BLE scanning and advertising are simple APIs on top of complex radio behavior; smoothing is essential.

Homework/Exercises to practice the concept

Scan a room and log RSSI for 5 minutes.
Implement a rolling average filter.
Change advertising interval and measure discovery time.

Solutions to the homework/exercises

RSSI values vary by 10–20 dB even when stationary.
A rolling average reduces spikes.
Shorter intervals reduce average discovery latency.

3. Project Specification

3.1 What You Will Build

A BLE beacon and scanner that logs nearby devices with filtered RSSI and last-seen timestamps.

3.2 Functional Requirements

Advertise a beacon with custom name/UUID.
Scan and log nearby BLE devices.
Smooth RSSI values with a rolling filter.
Record last-seen timestamps.

3.3 Non-Functional Requirements

Performance: Scan loop < 5 seconds latency.
Reliability: Stable detection over 30 minutes.
Usability: Logs include device name, RSSI, and last seen.

3.4 Example Usage / Output

$ ./ble_scanner
Device: Phone-1234  RSSI: -58 dBm  Last seen: 10:22:01

3.5 Data Formats / Schemas / Protocols

Log line format:

name,addr,rssi,avg_rssi,last_seen

3.6 Edge Cases

Bluetooth adapter disabled.
Duplicate devices with rotating addresses.
RSSI spikes from interference.

3.7 Real World Outcome

The Pi appears as a beacon and logs nearby devices with stable RSSI estimates.

3.7.1 How to Run (Copy/Paste)

python3 ble_scanner.py --beacon-name sentinel --scan-interval 5

3.7.2 Golden Path Demo (Deterministic)

export FIXED_TIME="2026-01-01T11:30:00Z"
python3 ble_scanner.py --simulate --devices "Phone:-58,Tag:-72"

Expected output:

[2026-01-01T11:30:00Z] Phone RSSI avg=-60

3.7.3 Failure Demo (Deterministic)

python3 ble_scanner.py --simulate --adapter-down

Expected output:

[ERROR] Bluetooth adapter down

Exit code: 101

3.7.4 CLI Exit Codes

0: Success
100: Bluetooth init failed
101: Adapter down

4. Solution Architecture

4.1 High-Level Design

BLE Advertiser + Scanner -> RSSI Filter -> Logger

4.2 Key Components

4.3 Data Structures (No Full Code)

rssi_history = {addr: deque(maxlen=5)}

4.4 Algorithm Overview

Key Algorithm: RSSI Smoothing

Record raw RSSI.
Compute rolling average.
Log smoothed value.

Complexity Analysis:

Time: O(1) per device
Space: O(n) devices

5. Implementation Guide

5.1 Development Environment Setup

pip install bleak

5.2 Project Structure

project-root/
├── ble_scanner.py
├── rssi_filter.py
└── README.md

5.3 The Core Question You’re Answering

“How do low-power devices advertise and discover each other efficiently?”

5.4 Concepts You Must Understand First

BLE advertising packets and intervals.
RSSI noise and smoothing.
BlueZ permissions and tools.

5.5 Questions to Guide Your Design

What identifiers should your beacon expose?
How will you avoid tracking concerns?

5.6 Thinking Exercise

Map a room and predict where RSSI will be strongest.

5.7 The Interview Questions They’ll Ask

How does BLE differ from classic Bluetooth?
Why is RSSI noisy indoors?
How do you reduce scanning power usage?

5.8 Hints in Layers

Hint 1: Start with scanning only.

Hint 2: Add beacon advertising.

Hint 3: Add rolling average for RSSI.

5.9 Books That Will Help

| Topic | Book | Chapter | |—|—|—| | BLE architecture | Bluetooth Low Energy | Ch. 2–3 | | Wireless context | 802.11 Wireless Networks | Ch. 4 |

5.10 Implementation Phases

Phase 1: Scan (3 hours)

Discover nearby devices.

Phase 2: Beacon (3 hours)

Advertise custom UUID/name.

Phase 3: Smoothing (3 hours)

Add RSSI filter and logs.

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

Beacon visible in phone scanner app.
RSSI log includes timestamps.
Adapter down -> exit 101.

6.3 Test Data

Devices: Phone:-58, Tag:-72

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

7.2 Debugging Strategies

Use bluetoothctl to check status.
Log raw RSSI before filtering.

7.3 Performance Traps

Continuous scanning increases CPU usage; use duty cycles.

8. Extensions & Challenges

8.1 Beginner Extensions

Add a whitelist of device names to track.

8.2 Intermediate Extensions

Export logs as JSON for dashboards.

8.3 Advanced Extensions

Implement rotating beacon identifiers.

9. Real-World Connections

9.1 Industry Applications

Asset tracking and proximity alerts.

BlueZ and bleak examples.

9.3 Interview Relevance

BLE advertising and scanning are common questions.

10. Resources

10.1 Essential Reading

BlueZ documentation.

10.2 Video Resources

BLE scanning tutorials.

10.3 Tools & Documentation

bluetoothctl and hciconfig.

Previous: Project 9
Next: Project 11

11. Self-Assessment Checklist

11.1 Understanding

I can explain BLE advertising and scanning.
I can explain RSSI noise and smoothing.

11.2 Implementation

Beacon and scanner operate reliably.
Logs include last-seen timestamps.

11.3 Growth

I can discuss BLE privacy in an interview.

12. Submission / Completion Criteria

Minimum Viable Completion:

Scanner logs at least one device.

Full Completion:

Beacon + scanner with RSSI smoothing.

Excellence (Going Above & Beyond):

Rotating IDs and privacy-preserving design.