Configuration

BLE2WLED is configured using environment variables and .env files. This guide covers all configuration options.

Configuration Methods

Configuration can be specified in three ways (in order of precedence):

  1. Environment variables - Highest priority, override everything

  2. .env file - Project-level configuration

  3. Default values - Built-in defaults

Using .env File

The recommended approach is to use a .env file:

  1. Copy the template:

    cp .env.example .env

  2. Edit .env with your settings:

    WLED_HOST=wled.local
LED_COUNT=60
MQTT_BROKER=localhost

  3. Load configuration in your code:

    from ble2wled.config import Config
config = Config('.env')

Using Environment Variables

Set environment variables directly:

export WLED_HOST=192.168.1.100
export LED_COUNT=60
export MQTT_BROKER=localhost

Then access them:

from ble2wled.config import Config
config = Config()  # Reads from environment

Configuration Reference

WLED Device Configuration

WLED_HOST (string, required)

IP address or hostname of WLED device

Example: 192.168.1.100 or wled.local

LED_COUNT (integer, default: 60)

Total number of LEDs in the strip

Valid range: 1-1024

Example: 120

WLED_HTTP_TIMEOUT (float, default: 1.0)

HTTP request timeout in seconds (for HTTP mode)

Valid range: 0.1-10.0

Example: 2.0

WLED_HTTP_RETRIES (integer, default: 3)

Number of HTTP retry attempts on timeout (for HTTP mode)

Valid range: 0-10

Example: 5

WLED_UDP_PORT (integer, default: 21324)

UDP port for DRGB protocol (for UDP mode)

Standard WLED UDP port is 21324

MQTT Broker Configuration

MQTT_BROKER (string, required if using MQTT)

MQTT broker hostname or IP address

Example: 192.168.1.100 or mqtt.example.com

MQTT_PORT (integer, default: 1883)

MQTT broker port

Standard MQTT port is 1883

Example: 1883

MQTT_LOCATION (string, required if using MQTT)

Location/room identifier for beacon subscription

Subscribes to topic: espresense/devices/{MQTT_LOCATION}

Example: living_room or office

MQTT_USERNAME (string, optional)

Username for MQTT authentication

Leave empty or unset if broker doesn’t require authentication

Example: mqtt_user

MQTT_PASSWORD (string, optional)

Password for MQTT authentication

Leave empty or unset if broker doesn’t require authentication

Example: secure_password_123

Animation Configuration

ANIMATION_UPDATE_INTERVAL (float, default: 0.05)

Time between animation updates in seconds

Lower values = smoother animation but higher CPU usage

Valid range: 0.01-1.0

Examples: - 0.02 (50fps animation) - 0.05 (20fps) - 0.1 (10fps)

ANIMATION_TRAIL_LENGTH (integer, default: 8)

Number of LEDs in motion trail

Valid range: 1-100

Example: 15

ANIMATION_FADE_FACTOR (float, default: 0.7)

Trail fade factor (brightness multiplier per segment)

Valid range: 0.1-1.0

  • 0.9 = slow fade (bright trails)

  • 0.5 = medium fade

  • 0.1 = fast fade (dim trails)

Beacon Configuration

BEACON_TIMEOUT_SECONDS (float, default: 6.0)

How long before a beacon is considered gone

Valid range: 1.0-60.0

Example: 10.0

BEACON_FADE_OUT_SECONDS (float, default: 4.0)

How long to fade out after timeout

Valid range: 0.5-30.0

Example: 2.0

Complete Configuration Example

Here’s a complete .env file with all options:

# WLED Device
WLED_HOST=192.168.1.100
LED_COUNT=60
WLED_HTTP_TIMEOUT=1.0
WLED_HTTP_RETRIES=3
WLED_UDP_PORT=21324

# MQTT Broker
MQTT_BROKER=192.168.1.50
MQTT_PORT=1883
MQTT_LOCATION=living_room
MQTT_USERNAME=mqtt_user
MQTT_PASSWORD=secure_password

# Animation
ANIMATION_UPDATE_INTERVAL=0.05
ANIMATION_TRAIL_LENGTH=10
ANIMATION_FADE_FACTOR=0.75

# Beacon Detection
BEACON_TIMEOUT_SECONDS=6.0
BEACON_FADE_OUT_SECONDS=4.0

Validation

Validate your configuration programmatically:

from ble2wled.config import Config

config = Config('.env')
try:
    config.validate()
    print("Configuration is valid!")
except ValueError as e:
    print(f"Configuration error: {e}")

Export Configuration

Export configuration as JSON for debugging:

import json
from ble2wled.config import Config

config = Config('.env')
print(json.dumps(config.to_dict(), indent=2))

Output:

{
  "wled_host": "192.168.1.100",
  "led_count": 60,
  "mqtt_broker": "192.168.1.50",
  "mqtt_port": 1883,
  "mqtt_location": "living_room",
  "mqtt_username": "mqtt_user",
  "animation_update_interval": 0.05,
  "animation_trail_length": 10,
  "animation_fade_factor": 0.75,
  "beacon_timeout_seconds": 6.0,
  "beacon_fade_out_seconds": 4.0
}

Default Values

If a configuration value is not specified, defaults are used:

from ble2wled.config import Config

config = Config()

# These have defaults
print(config.mqtt_port)              # 1883
print(config.led_count)              # 60
print(config.animation_update_interval)  # 0.05

Type Conversion

Configuration automatically converts types:

# These all work:
config.led_count = 60              # int
config.led_count = "60"            # str -> converted to int
config.animation_fade_factor = 0.75      # float
config.animation_fade_factor = "0.75"    # str -> converted to float

Optional Values

Some configuration values are optional (MQTT credentials):

config.mqtt_username      # None if not set
config.mqtt_password      # None if not set

# These are always required (no default)
config.wled_host          # Required
config.mqtt_broker        # Required if using MQTT
config.mqtt_location      # Required if using MQTT

Troubleshooting Configuration

.env file not being read:

Ensure the file exists and contains proper syntax:

# Good syntax
KEY=value
KEY=value with spaces
KEY="quoted value"

# Bad syntax
KEY = value         # Extra spaces
KEY:value          # Wrong separator
value              # Missing key

Type conversion errors:

Ensure values can be converted to expected types:

LED_COUNT=60        # OK (can convert to int)
LED_COUNT=abc       # ERROR (cannot convert to int)
ANIMATION_FADE_FACTOR=0.75   # OK (can convert to float)

Missing required values:

Call validate() to check for missing required values:

config.validate()  # Raises ValueError if required values missing

Next Steps