The Cielo Home integration lets you control your Cielo Breez Edge Pro directly from Home Assistant using the cloud-based Cielo Connect API. Once set up, you can change mode, adjust temperature setpoint, and manage your home climate alongside the rest of your smart home.
In addition to these features, the Cielo Home Assistant integration also allows the user to:
- Build powerful climate automations tailored to your lifestyle.
- Integrate with the smart home devices you already use, such as lights, locks, and more.
- Create routines that keep your home comfortable while helping reduce unnecessary energy use.
Before You Begin
Before integrating the Cielo Breez Edge with Home Assistant, ensure that:
- Your device is registered and active in the Cielo Home app.
- The device has a configured remote (set up automatically or manually).
- Your Home Assistant server has active internet access.
Understanding API Key Rules
Cielo enforces the following security restrictions to protect user accounts and prevent unauthorized access. Read these guidelines carefully before generating an API key.
- Each API key can be used only once.
- A new API key cannot be generated until the current one is revoked.
- You may generate a maximum of 3 API keys per month.
- Once a new API key is generated, wait for at least 60 seconds for it to display on the screen.
- Revoking an API key will disconnect Home Assistant immediately or within about a minute.
Obtaining an API key
1. Visit the Cielo Web Portal. Open the Menu by selecting the hamburger menu icon at the top left side.
2. Select Home Assistant from the sidebar.
3. The API key will be displayed. Copy the API key from the dialog.
Tip: If the message 'This key is already used' appears, you must first revoke the old key before generating a new one.
Revoking an API Key
You can revoke your current API key if you want to generate a new one or disconnect the integration.
- Go to the Cielo Web Portal
- Click on the menu icon at the top-left side of the screen and select 'Home Assistant'
- Click on 'Revoke Key'
🚨 Note: Revoking your API key will disconnect Home Assistant immediately.
Configuration
To add the Cielo Home hub to your Home Assistant instance, use this My button:
Manual Configuration
If the above My button doesn’t work, you can also perform the following steps manually:
Browse to your Home Assistant instance.
1. Go to Settings > Devices & Services.
2. In the bottom right corner, select +Add Integration button.
3. From the list, select Cielo Home.
4. Paste the API key generated in the Cielo web app in the dialogue box of Home Assistant and click 'Submit'.
Note: If the message 'This key is already used' appears, you must first revoke the old key before generating a new one.
5. Assign a name to the device and click on Finish.
6. If the authentication succeeds, Home Assistant will automatically appear in the integrations.
📢 Note
If you add or set up a new Cielo device after configuring the integration in Home Assistant, you must reload the integration:
- Go to Settings > Devices & Services.
- Select Cielo Home, then, in the top-right corner, select the three-dot
menu.
- Select Reload.
Supported Functionality
Each supported device exposes at least one climate entity.
📢 Note: Depending on device support, some entities might not be available as the device does not support them.
Climates
The climate platform integrates compatible Cielo Breez Edge into Home Assistant, enabling control through the Home Assistant user interface.
- HVAC modes: Heat, Cool, Dry, Fan, Auto, Off.
- Temperature control: Provide a target temperature.
- Fan modes: Provide a fan speed if applicable.
- Vertical swing position: Provide a vertical swing position.
- Presets: Home, Away, Sleep & Wake.
Note: Availability of some modes, fan speeds, or swing positions depends on the device’s remote configuration.
Actions
This integration does not provide any custom service actions. All controls are performed using the standard Home Assistant climate services.
Troubleshooting
This integration relies on an active internet connection and access to the Cielo Home API. Here are a few things to check before raising an issue:
"This key is already used" message
Your current API key has already been assigned to a Home Assistant instance. Revoke the existing key first, then generate a new one.
Integration not appearing in Home Assistant
Ensure your Home Assistant server has active internet access. The Cielo integration requires a cloud connection to function.
Device not showing after setup
Wait a few minutes after completing the integration — device sync can take up to 2–3 minutes. If the device still doesn't appear, try removing and re-adding the integration.
Not displaying HVAC modes
Ensure that the device’s remote configuration is complete. Devices without remotes will not display HVAC modes.
Home Assistant disconnected unexpectedly
This typically means the API key was revoked, either manually or because a new key was generated. Obtain a fresh API key and reconnect.
If devices still fail to load after these steps, please contact Cielo Tech Support.
Removing the Integration
To remove an integration instance from Home Assistant, follow these steps:
- Go to Settings > Devices & Services and select the integration card.
- From the list of devices, select the integration instance you want to remove.
Next to the entry, select the three dotsmenu. Then, select Delete.
[[related:28756989798935]]