🔥 Flame Connect for Python

Async Python library for controlling Dimplex, Faber, and Real Flame fireplaces via the Flame Connect cloud API.

🏠 Looking for a Home Assistant integration? Try the flame_connect_ha custom component.

Installation

uv add flameconnect

To include the interactive terminal dashboard (TUI):

uv add flameconnect[tui]

Quick Run (no install)

You can also run flameconnect directly without installing it as a project dependency:

uv tool run flameconnect

To run the TUI without installing:

uv tool run flameconnect[tui]

Quick Start

import asyncio
from flameconnect import FlameConnectClient, MsalAuth

async def main():
    auth = MsalAuth()
    async with FlameConnectClient(auth=auth) as client:
        fires = await client.get_fires()
        for fire in fires:
            print(f"{fire.friendly_name} ({fire.fire_id})")

        # Turn on the first fireplace
        await client.turn_on(fires[0].fire_id)

        # Read current state
        overview = await client.get_fire_overview(fires[0].fire_id)
        for param in overview.parameters:
            print(param)

asyncio.run(main())

Authentication

Flame Connect supports two authentication modes depending on your use case.

Standalone (CLI / TUI)

Uses the built-in MsalAuth provider, which runs an interactive Azure AD B2C login through your browser. On first run a browser window opens for you to sign in with your Flame Connect account credentials. Subsequent runs reuse the cached token stored at $XDG_CACHE_HOME/flameconnect/token.json (defaulting to ~/.cache/flameconnect/token.json), refreshing it automatically when it expires.

from flameconnect import FlameConnectClient, MsalAuth

auth = MsalAuth()
async with FlameConnectClient(auth=auth) as client:
    ...

Integration (Home Assistant, etc.)

Use TokenAuth to inject your own bearer token or an async token provider function. This avoids any interactive browser flow and lets your integration manage tokens externally.

from flameconnect import FlameConnectClient, TokenAuth

# With a static token string:
auth = TokenAuth("your-bearer-token")

# Or with an async token provider:
auth = TokenAuth(my_async_token_func)

async with FlameConnectClient(auth=auth) as client:
    ...

You can also pass an existing aiohttp.ClientSession to share a session with your application:

async with FlameConnectClient(auth=auth, session=my_session) as client:
    ...

CLI Usage

The flameconnect command provides a straightforward interface for controlling your fireplace from the terminal. Add -v to any command for verbose logging.

All examples below use flameconnect directly, but you can substitute uv tool run flameconnect if you haven't installed the package (e.g. uv tool run flameconnect list).

List registered fireplaces

flameconnect list

Show current status

flameconnect status <fire_id>

Turn on / off

flameconnect on <fire_id>
flameconnect off <fire_id>

Set parameters

# Fire control
flameconnect set <fire_id> mode manual          # standby, manual

# Flame
flameconnect set <fire_id> flame-effect on       # on, off
flameconnect set <fire_id> flame-speed 3         # 1-5
flameconnect set <fire_id> flame-color blue       # all, yellow-red, yellow-blue,
                                                  #   blue, red, yellow, blue-red
flameconnect set <fire_id> brightness low         # low, high
flameconnect set <fire_id> pulsating on           # on, off

# Media lighting
flameconnect set <fire_id> media-theme prism      # user-defined, white, blue,
                                                  #   purple, red, green, prism,
                                                  #   kaleidoscope, midnight
flameconnect set <fire_id> media-light on         # on, off
flameconnect set <fire_id> media-color 255,0,0,80 # R,G,B,W (0-255) or preset name

# Overhead lighting
flameconnect set <fire_id> overhead-light on      # on, off
flameconnect set <fire_id> overhead-color dark-blue # R,G,B,W or preset name

# Ambient
flameconnect set <fire_id> ambient-sensor on      # on, off

# Heat
flameconnect set <fire_id> heat-status on         # on, off
flameconnect set <fire_id> heat-mode eco          # normal, boost, eco, boost:<min>
flameconnect set <fire_id> heat-temp 22.5         # target temperature

# Timer & units
flameconnect set <fire_id> timer 120              # minutes (0 to disable)
flameconnect set <fire_id> temp-unit celsius      # celsius, fahrenheit

Launch the TUI

flameconnect tui

TUI

flameconnect tui launches an interactive terminal dashboard built with Textual. It requires the TUI extra:

uv add flameconnect[tui]

Or run it directly without installing:

uv tool run flameconnect[tui]

The dashboard displays the current fireplace status. Refresh is manual — press r to poll the latest state. Key bindings:

API Coverage

The table below lists all known Flame Connect cloud API endpoints and their implementation status in this library.

From a semantic versioning standpoint, the upstream API is not versioned and can change at any time. In general, we will not consider fixes around the API itself to be breaking changes, even of those change the data or methods exposed. Where possible, we will provide wrappers to translate API changes to preserve compatibility.

Fireplace Control (Core)

Fireplace Management

Identity

Favourites

Schedules

Guest Mode

Notifications

Hubs

Contributing

# Clone and install with dev dependencies
git clone https://github.com/deviantintegral/flameconnect.git
cd flameconnect
uv sync --dev --all-extras

# Install pre-commit hooks
uv run pre-commit install --install-hooks

# Lint and type-check
uv run ruff check .
uv run mypy src/

# Run tests
uv run pytest

# Mutation testing (protocol layer)
uv run mutmut run --paths-to-mutate=src/flameconnect/protocol.py

Please follow Conventional Commits for commit messages.

Do you work at Dimplex, Faber, or Real Flame, or support the underlying web services?

This library and app aims to follow the same patterns as the official apps to minimize load on back-end infrastructure. We avoid making API calls whenever possible, and mirror the app by making data refreshes a specific user action. This library implementation is a last resort. We're glad to implement improvements if this library is causing any challenges on the back-end servers.

But really... making these remote calls is laggy and complex! As a comparison, take a look at the Lennox iComfort S30 and similar line of themostats. They have a cloud API, but also have a fully local API that works even when the internet is down. And, it's way, way faster to respond. If a local API is made available, I'd be glad to drop this library in favour of it. Let's talk!

License

Apache-2.0