Introduction

BLE2WLED bridges the gap between Bluetooth Low Energy beacon detection and visual LED effects. It processes beacon data from MQTT and renders dynamic, real-time visualizations on WLED LED strips.

Overview

BLE2WLED is a Python package that:

  1. Receives BLE beacon data via MQTT (beacon ID and signal strength/RSSI)

  2. Converts signal strength to distance using RF propagation modeling

  3. Maps distance to colors on a gradient (yellow when near → red when far)

  4. Adds visual identity with hash-based hue shifts for each beacon

  5. Implements graceful fade-out for beacons that disappear

  6. Renders motion trails as beacons move along the LED strip

  7. Outputs to WLED via HTTP or UDP (DRGB protocol) for smooth real-time animation

Key Features

  • Real-time beacon visualization with distance-based coloring

  • Motion trails showing beacon movement across LED strips

  • Graceful fade-out when beacons disappear

  • Multiple output protocols (HTTP and UDP/DRGB)

  • MQTT authentication support for secured brokers

  • HTTP retry logic with automatic timeout recovery

  • CLI simulator for testing without hardware

  • Real-time statistics showing message rates and active beacons

  • Fully configurable via environment variables or code

Use Cases

  • Presence visualization in smart homes or offices

  • Occupancy detection showing active beacons in rooms

  • Proximity-based effects with beacons triggering LED changes

  • Development and testing of beacon detection logic

  • Interactive installations with real-time beacon feedback

Architecture

The system follows a modular architecture:

MQTT Broker
    ↓
EspresenseBeaconListener
    ↓
BeaconState (tracks active beacons)
    ↓
Animation Engine (processes visual effects)
    ↓
WLED Controller (HTTP or UDP)
    ↓
Physical LED Strip

Data Flow

  1. MQTT Reception: Beacon data arrives via MQTT from espresense devices

  2. State Management: Beacon state tracks each beacon’s position, signal strength, and lifecycle

  3. Distance Calculation: RSSI is converted to distance using RF propagation modeling

  4. Color Mapping: Distance is mapped to colors (distance → hue, strength → brightness)

  5. Trail Rendering: Motion trails are rendered showing recent beacon positions

  6. LED Update: Calculated LED values are sent to WLED via HTTP or UDP

  7. Animation Loop: This cycle repeats at configurable intervals (typically 5-50ms)

Signal Strength to Distance Conversion

The system uses Friis path loss model to convert RSSI (Received Signal Strength Indicator) to distance:

\[d = 10^{\frac{TXP - RSSI - A}{20n}}\]

Where: - TXP = Transmit Power (typically -59 dBm for BLE) - RSSI = Received Signal Strength Indicator (in dBm) - A = Environmental factor (typically 2.0 for line-of-sight) - n = Path loss exponent (typically 2.0)

Color Mapping Strategy

The system uses a sophisticated color mapping strategy:

  1. Hue Assignment: Each beacon gets a unique hue based on its ID (hash-based)

  2. Distance-based Saturation: Closer beacons are more saturated (yellow), farther are less (red)

  3. Signal-based Brightness: Stronger signal = brighter LED, weaker = dimmer

  4. Motion Trails: Recent positions are brightest, fade out over time

This creates a visually distinctive and informative display where you can: - Identify individual beacons by color - Gauge distance by color intensity - See movement patterns with trails

Next Steps