Velair

Climate automation that adapts to your life.

Velair is a Home Assistant custom integration for managing clear, local-first climate schedules on top of standard climate.* entities. It provides a sidebar panel, an optional Lovelace card, schedule templates, Adaptive Preconditioning, Room Assist, Environmental Comfort monitoring, per-zone boosts, and automation-friendly services without depending on any thermostat vendor cloud.

Velair does not replace your thermostat integration. It works through Home Assistant entities, so it can manage any compatible climate device that is already exposed to Home Assistant.

Velair started from a practical Home Assistant use case: keeping climate control local and reliable while recovering scheduling features that were becoming harder to use from a vendor app because of subscription changes and rate limits.

The project is not intended to criticize or offend any brand. It is a community contribution for users who want local-first home automation, simple day-to-day workflows, and a scheduler that can work across different climate integrations.

Velair is maintained by Cristian Gonzalez Fernandez, a Home Assistant enthusiast who enjoys building software projects in his free time to solve practical everyday problems through automation and technology.

Contributions, testing, bug reports, and constructive feedback are always welcome. This project is maintained on a best-effort basis alongside work and daily life, so responses and updates may sometimes take a little time.

• Home Assistant sidebar panel registered automatically by the integration.
• Optional Lovelace card using the same bundled frontend.
• Visual schedule editor for managed climate.* entities.
• Weekly schedules per climate zone.
• Weekly continuity across midnight and empty days, with inherited periods identified in the timeline.
• Schedule blocks for temperature targets or turning a climate entity off.
• Optional HVAC mode per block. Keep current mode still applies the block target; stored compatibility is based on advertised HVAC modes, while runtime delivery preserves a compatible running mode or starts an off climate in a compatible mode before sending the target.
• Support for heating, cooling, dry, fan-only, and off modes where the climate entity supports them. Climate entities can use either a single target or separate lower and upper targets for range-based modes such as heat_cool.
• Drag and resize interactions on a 24-hour timeline.
• Day cloning to other weekdays or other managed climates.
• Editable schedule templates with import/export support.
• Climate profiles with coordinated per-zone schedules, in-editor day cloning, pauses, configurable Modes, and a native Home Assistant select entity for automations.
• Overview tab with scheduler status, active boosts, next events, and responsive zone cards that separate Velair intent from live device activity.
• Dedicated Adaptive preconditioning tab with per-climate controls and local learning status.
• Dedicated Room Assist tab for setups that need a separate room temperature sensor, including width-preserving assistance for native heat_cool ranges.
• Dedicated Comfort tab with readable temperature/humidity conditions, independent CO2 air quality, data-quality warnings, and responsive live visualizations.
• Optional climate controls per block where supported, including fan mode, preset mode, swing mode, horizontal swing mode, and target humidity.
• Settings tab with climate ordering, startup behavior, thermostat diagnostics, portability tools, and maintenance information.
• Global pause, stop, and resume controls, plus per-zone pause and resume.
• Velair-scoped services for activating climate profiles, starting and cancelling boosts, pauses, schedule application, schedule editing, day cloning, and schedule clearing.
• Automation events through velair_event for Profile changes, scheduler mode changes, Adaptive Preconditioning plans, cancellations and observations, Room Assist state and target changes, Comfort assessments, applied climate targets, boosts, and per-zone pause/resume lifecycle changes.
• Push updates through Home Assistant WebSocket events, without frontend polling.
• English, Spanish, German, French, and Dutch UI translations.
• Native Celsius and Fahrenheit workflows using Home Assistant's configured unit, including unit-aware defaults, explicit stored-data migration, and legacy backup conversion.

The following examples are captured from a real Home Assistant instance. See more screenshots for the complete screenshot set.

Desktop	Mobile

Velair is available in the default HACS store and can also be installed manually.

<home_assistant_config>/custom_components/velair

custom_components/velair

<home_assistant_config>/custom_components/velair

For development builds, see docs/developer/development.md.

1. Add the Velair integration.
2. Select the climate.* entities Velair may manage.
3. Open Velair from the Home Assistant sidebar.
4. Choose a climate and weekday.
5. Add schedule blocks.
6. Save the day.
7. Clone the day or create templates when useful.

See docs/user/usage.md for the full workflow.

Velair uses the temperature unit configured in Home Assistant. New installations receive matching defaults automatically. If you are upgrading older Velair data or importing a backup created in another unit, read Temperature Units and Migration before changing stored thermal data.

The sidebar panel is the main Velair experience. The Lovelace card is optional.

Before adding a card, install and configure the Velair integration first. The Lovelace resource is served by the integration, so it is available after Home Assistant has loaded Velair.

1. Open Home Assistant.
2. Go to Settings > Dashboards.
3. Open the three-dot menu.
4. Select Resources.
5. Select Add resource.
6. Use this URL:

/velair_frontend/velair-card.js

7. Select JavaScript module as the resource type.
8. Save the resource.
9. Reload the browser or the Home Assistant companion app.

The resource can also be represented as YAML:

url: /velair_frontend/velair-card.js
type: module

1. Open a dashboard.
2. Select Edit dashboard.
3. Select Add card.
4. Select Manual.
5. Paste this example:

type: custom:velair-card
view: overview-status

6. Save the card.

This first card shows the scheduler status and pause/stop/resume controls. You can add more Velair cards to the same dashboard by changing the view value.

The Active setup card can allow changes through Modes, direct Profiles, or both. The visual card editor exposes the same choice. Omit active_setup_controls to keep both:

type: custom:velair-card
view: active-setup
active_setup_controls: modes

Supported values are modes, profiles, and both. The current Mode and applied Profiles remain visible in every variant. Directly activating a Profile replaces every previously active Profile and changes the Mode to Manual. Zones not covered by that Profile return to their Default schedules instead of keeping the previous Mode's configuration. To activate additional non-overlapping Profiles together, create and select a Mode. The profiles variant also keeps a Default schedules action available.

You can also limit a Lovelace card to specific thermostats. This only changes what that card displays; it does not change the scheduler or stored schedules.

type: custom:velair-card
view: overview-events
entities:
  - climate.living_room
  - climate.bedroom
zone_order:
  - climate.bedroom
  - climate.living_room

Comfort cards can also hide configuration or individual live graphs:

type: custom:velair-card
view: comfort
entities:
  - climate.living_room
show_comfort_configuration: false
show_comfort_temperature: true
show_comfort_humidity: false
show_comfort_co2: true

Supported view values:

• overview-status: scheduler state and pause/stop/resume controls.
• overview-boosts: active boosts.
• overview-events: next events.
• overview-timeline: today's timeline.
• overview-zones: zone overview.
• active-setup: current Mode and Profiles, with optional controls.
• schedules: full schedule editor.
• sensors: Room Assist configuration and live status.
• comfort: environmental comfort configuration and status.
• preconditioning: adaptive preconditioning configuration and local learning status.

If Home Assistant shows a custom element error, confirm that Velair is installed, the resource URL is exactly /velair_frontend/velair-card.js, and the browser or companion app has been reloaded after adding the resource.

• Documentation index
• Usage guide
• Climate Profiles
• Automation Events
• Adaptive Preconditioning
• Room Assist
• Resilient climate delivery
• Environmental Comfort
• Temperature Units and Migration
• Installation
• Troubleshooting

• Architecture
• WebSocket API
• Adaptive preconditioning internals
• Room Assist internals
• Climate delivery internals
• Environmental Comfort internals
• Temperature unit internals
• Frontend development
• Development guide
• Manual testing

• Screenshot capture

custom_components/velair/     Home Assistant integration
frontend/                     TypeScript/Lit frontend source and build tooling
docs/                         User, developer, and project documentation grouped by topic
tests/                        Unit tests
screenshots/                  Real screenshots for public documentation
hacs.json                     HACS metadata

Contributions are welcome. The project especially benefits from:

• Testing with different climate platforms.
• Reports about unsupported HVAC modes or thermostat capabilities.
• Mobile and tablet UX feedback.
• Documentation improvements.
• Pull requests that keep the code maintainable and aligned with Home Assistant conventions.

Please read docs/developer/development.md before opening a pull request.

Velair is a community project maintained in free time. If Velair helps simplify your Home Assistant climate setup and you want to support future development, donations are welcome:

Donations are optional and do not change the best-effort support model, but they are always appreciated.

MIT. See LICENSE.