API Reference

Complete API reference for BLE2WLED modules.

• ble2wled.config - Configuration Management
  • Config
  • Overview
  • Properties
  • Methods
  • Examples
  • See Also
• ble2wled.states - Beacon State Management
  • BeaconState
  • Overview
  • Key Classes
  • Classes
  • Examples
  • See Also
• ble2wled.colors - Color Calculations
  • estimate_distance_from_rssi()
  • lerp()
  • gradient_color()
  • ble_beacon_to_rgb()
  • Overview
  • Functions
  • Examples
  • See Also
• ble2wled.animation - Animation Loop
  • BeaconRunner
  • add_trail()
  • Overview
  • Functions
  • Animation Parameters
  • Examples
  • See Also
• ble2wled.wled - WLED Device Communication
  • LEDController
  • WLEDHTTPController
  • WLEDUDPController
  • Overview
  • Classes
  • LED Data Format
  • Examples
  • Choosing Between UDP and HTTP
  • Error Handling
  • Debugging
  • See Also
• ble2wled.mqtt - MQTT Beacon Listener
  • EspresenseBeaconListener
  • BeaconMQTTListener
  • Overview
  • Classes
  • Examples
  • Error Handling
  • Troubleshooting
  • Performance
  • See Also
• ble2wled.simulator - LED Simulator and Mock Beacons
  • LEDSimulator
  • MockBeaconGenerator
  • Overview
  • Classes
  • Examples
  • CLI Usage
  • Performance
  • See Also

Overview

BLE2WLED consists of several modular components:

Configuration Management

• ble2wled.config - Configuration Management - Load and manage configuration from environment variables

Beacon State Tracking

• ble2wled.states - Beacon State Management - Track beacon positions, signals, and lifecycles

Visualization

• ble2wled.colors - Color Calculations - Color mapping and HSV calculations

• ble2wled.animation - Animation Loop - Animation loop and LED rendering

• ble2wled.wled - WLED Device Communication - WLED device communication (HTTP/UDP)

Input

• ble2wled.mqtt - MQTT Beacon Listener - MQTT listener for beacon data

Testing

• ble2wled.simulator - LED Simulator and Mock Beacons - LED simulator and mock beacon generation

Module Dependencies

config.py
    └─> Loads environment variables and .env files

states.py
    └─> Tracks beacon state over time

mqtt.py
    ├─> Depends on states.py
    └─> Provides beacon data to states

colors.py
    └─> Converts distance/signal to LED colors

animation.py
    ├─> Depends on states.py, colors.py, wled.py
    └─> Main animation loop

wled.py
    └─> Communicates with physical WLED devices

simulator.py
    ├─> Depends on states.py
    └─> Mock WLED controller for testing

Usage Example

Typical application flow:

# 1. Load configuration
from ble2wled.config import Config
config = Config('.env')

# 2. Create beacon state tracker
from ble2wled.states import BeaconState
beacon_state = BeaconState()

# 3. Start MQTT listener (provides beacon data)
from ble2wled.mqtt import EspresenseBeaconListener
listener = EspresenseBeaconListener(
    beacon_state,
    broker=config.mqtt_broker,
    location=config.mqtt_location
)
listener.start()

# 4. Create WLED controller
from ble2wled.wled import WLEDUDPController
controller = WLEDUDPController(config.wled_host, config.led_count)

# 5. Run animation loop
from ble2wled.animation import run_wled_beacons
run_wled_beacons(
    controller,
    beacon_state=beacon_state,
    led_count=config.led_count
)