🔥🏠 Flame Connect for Home Assistant

A Home Assistant custom integration for controlling fireplaces via the Flame Connect cloud API.

Develop in the cloud: Open it directly in GitHub Codespaces - no local setup required!

Features

• Full fireplace control: Power, flame effects, heat, lights, timers, and more
• Multi-device support: Each registered fireplace appears as its own device
• Secure authentication: Email and password are used once during setup, then only OAuth tokens are stored
• Manual refresh: Data refreshes on demand via a button entity (24-hour automatic background refresh keeps tokens alive)
• RGBW light control: Media light, overhead light, and log effect with full color support

This integration sets up the following platforms:

Platform	Description
switch	Power, flame effect, pulsating effect, ambient sensor, timer
climate	Heat control with temperature and preset modes
light	Media light, overhead light, log effect (RGBW)
select	Flame color, brightness, media theme
number	Flame speed, timer duration, sound volume, sound file
sensor	Connection state, software version, error codes (diagnostic, disabled by default)
button	Refresh data on demand

Installation

HACS (Recommended)

1. Click "Download" to install the integration
2. Restart Home Assistant

Manual Installation

1. Download the custom_components/flameconnect/ folder from this repository
2. Copy it to your Home Assistant's custom_components/ directory
3. Restart Home Assistant

Setup

Or manually:

1. Go to Settings > Devices & Services
2. Click "+ Add Integration"
3. Search for "Flame Connect"
4. Enter your Flame Connect email and password
5. Click Submit

Your credentials are used once to authenticate with the Flame Connect cloud service. Only the resulting OAuth tokens are stored - your email and password are never saved.

Entities

Each fireplace device exposes the following entities:

Switches

• Power - Main fireplace power (on = manual mode, off = standby)
• Flame effect - Toggle flame visual effect
• Pulsating effect - Toggle pulsating flame effect
• Ambient sensor - Toggle ambient temperature sensor
• Timer - Enable/disable the fireplace timer

Climate

• Heat - Temperature control with preset modes (Normal, Boost, Eco, Fan only, Schedule). Only available when heat control is enabled on the fireplace.

Lights

• Media light - RGBW media accent light with theme effects
• Overhead light - RGBW overhead light
• Log effect - RGBW log effect light

Selects

• Flame color - Choose flame color (Yellow red, Blue, Red, etc.)
• Brightness - High or Low
• Media theme - Media light theme (White, Blue, Purple, Prism, etc.)

Numbers

• Flame speed - Flame animation speed (1-5)
• Timer duration - Timer duration in minutes (1-480)
• Sound volume - Sound volume (disabled by default)
• Sound file - Sound file selection (disabled by default)

Sensors (Diagnostic, disabled by default)

• Connection state - Fireplace connection status
• Software version - UI, control, and relay firmware versions
• Error codes - Fireplace error byte values

Button

• Refresh data - Manually refresh all fireplace data from the cloud API

Data Refresh

The integration automatically refreshes data every 24 hours to keep OAuth tokens alive. If a refresh fails, it retries every 5 minutes until it succeeds instead of waiting for the next daily poll. For on-demand updates, use the Refresh data button entity. Each fireplace has its own refresh button; it stays available even while the fireplace is unreachable, so you can always retry by hand.

Quality Scale

Evaluated against the Home Assistant Integration Quality Scale.

Bronze

Rule	Description	Status
action-setup	Service actions registered in async_setup	N/A
appropriate-polling	Polling interval is suitable	✅
brands	Branding assets provided	✅
common-modules	Common patterns in shared modules	✅
config-flow-test-coverage	Full test coverage for config flow	❌
config-flow	UI-based setup	✅
dependency-transparency	Dependencies documented in manifest	✅
docs-actions	Service actions documented	N/A
docs-high-level-description	High-level integration description	✅
docs-installation-instructions	Step-by-step installation instructions	✅
docs-removal-instructions	Removal instructions documented	❌
entity-event-setup	Events subscribed in proper lifecycle methods	N/A
entity-unique-id	All entities have unique IDs	✅
has-entity-name	Entities use has_entity_name = True	✅
runtime-data	Runtime data stored in ConfigEntry.runtime_data	✅
test-before-configure	Connection validated before config entry creation	✅
test-before-setup	Initialization checks before setup	✅
unique-config-entry	Duplicate config entries prevented	✅

Silver

Rule	Description	Status
action-exceptions	Service actions raise exceptions on failure	N/A
config-entry-unloading	Config entry unloading supported	✅
docs-configuration-parameters	Configuration parameters documented	✅
docs-installation-parameters	Installation parameters documented	✅
entity-unavailable	Entities marked unavailable when appropriate	✅
integration-owner	Active code owner designated	✅
log-when-unavailable	Logs when device/service becomes unavailable	✅
parallel-updates	PARALLEL_UPDATES set on entity platforms	❌
reauthentication-flow	Reauth flow implemented	✅
test-coverage	Above 95% test coverage	❌

Gold

Rule	Description	Status
devices	Integration creates device representations	✅
diagnostics	Diagnostics implemented with redaction	✅
discovery	Automatic device discovery	N/A
discovery-update-info	Discovery updates network info	N/A
docs-data-update	Data update mechanism documented	✅
docs-examples	Automation examples provided	❌
docs-known-limitations	Known limitations documented	❌
docs-supported-devices	Supported devices listed	❌
docs-supported-functions	Entities and functions documented	✅
docs-troubleshooting	Troubleshooting guidance provided	✅
docs-use-cases	Usage scenarios illustrated	❌
dynamic-devices	New devices added after setup	❌
entity-category	Appropriate EntityCategory assignments	✅
entity-device-class	Device classes applied where applicable	✅
entity-disabled-by-default	Less common entities disabled by default	✅
entity-translations	Entity names translated	✅
exception-translations	Exception messages support translation	❌
icon-translations	Icons defined in icons.json	❌
reconfiguration-flow	UI-based reconfiguration	❌
repair-issues	Repair flows for user intervention	✅
stale-devices	Stale devices automatically removed	❌

Platinum

Rule	Description	Status
async-dependency	Underlying library is async	✅
inject-websession	HA websession injected into dependency	✅
strict-typing	Strict type checking enforced	❌

Troubleshooting

Re-authentication

If your OAuth tokens expire, Home Assistant will display a repair notification. Click through the repair flow to re-enter your credentials and restore connectivity.

Debug Logging

Add to configuration.yaml:

logger:
  default: info
  logs:
    custom_components.flameconnect: debug
    # Log the underlying API library INCLUDING tokens
    # flameconnect: debug

Contributing

Contributions are welcome! Please open an issue or pull request.

Development Setup

Cloud Development (Recommended)

Local Development

Requirements:

• Docker or other container runner (docker-ce + WSL2, Lima VM, Rancher / Podman Desktop all recommended)
• VS Code with Dev Containers extension

1. Clone this repository
2. Open in VS Code
3. Click "Reopen in Container" when prompted

Validation

script/check   # Type-check + lint + spell
script/test    # Run tests

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

---

Made with care by @deviantintegral

---