A Home Assistant custom component for Quilt mini-split HVAC systems.
Built on top of quilt-hp-python — a fully-async
gRPC client that communicates directly with the Quilt cloud API.
For protocol details, streaming behavior, and the full client feature set, see the
quilt-hp-python documentation.
- Climate entities — control HVAC mode and setpoints for each Quilt space (room)
- Sensor entities — ambient temperature, humidity, inlet/outlet temps, presence level, COP, HVAC power, compressor data, and per-space energy
- Light entities — toggle and dim indoor unit LED, set RGBW color and animation effect
- Select entities — fan speed (Auto / Quiet / Low / Medium / High / Blast), louver mode (Closed / Sweep / Fixed / Auto), and fixed louver angle
- Binary sensor entities — motion, presence, occupancy, and connectivity status per IDU
- Switch entities — pause or resume all Quilt schedules for a location
- Real-time updates — powered by Quilt's bidirectional gRPC stream with auto-reconnect
- Polling fallback — configurable interval fetch if the stream is unavailable
- A Quilt account with at least one configured system
- Home Assistant 2026.3 or newer
- Python 3.14.2 or newer (managed automatically by HA)
- Add this repository as a custom repository in HACS
(category: Integration, URL:
https://github.com/eman/homeassistant-quilt-hp). - Install Quilt Heat Pump.
- Restart Home Assistant.
Copy custom_components/quilt_hp/ into your HA config/custom_components/ directory
and restart.
- Navigate to Settings → Devices & Services in Home Assistant
- Click + Add Integration and search for "Quilt"
- Enter your Quilt account email address
- Check your email for a 6-digit verification code (arrives within 1-2 minutes)
- Enter the code in Home Assistant
Note: Verification codes expire after 15 minutes. Request a new code if needed.
If your account has multiple homes, you will be prompted to select which one to integrate. Each home can be added as a separate integration entry — just run the setup flow again and select a different home.
After setup, click Configure on the integration card to adjust settings:
| Option | Default | Range | Description |
|---|---|---|---|
| Polling interval | 5 min | 1–60 min | Fallback polling frequency when real-time stream is unavailable |
About real-time updates: The integration uses gRPC streaming for instant state changes. The polling interval is only used as a fallback when the stream is temporarily down.
To change your email or re-authenticate without removing the integration:
- Go to Settings → Devices & Services
- Find your Quilt integration
- Click ⋮ (three dots menu) → Reconfigure
- Follow the authentication steps
If your session expires, Home Assistant will display a re-authentication notification. Click the notification and follow the prompts to re-enter your email and a new verification code. Your devices and settings remain unchanged.
- Check internet connection: Verify your Home Assistant instance can access the internet
- Verify Quilt cloud status: Ensure the Quilt cloud service is online
- Network/firewall: Confirm gRPC traffic (HTTPS port 443) is not blocked
- Temporary outage: Wait 2-3 minutes and try again
- Double-check digits: Ensure all 6 digits were entered correctly
- Code expired: Codes expire after 15 minutes - request a new one
- Email delays: Check spam/junk folder if code doesn't arrive within 2 minutes
- Resend: Start the setup again to receive a new code
If you see a repair notification about stream degradation:
- The integration automatically falls back to polling every 5 minutes
- State updates may be delayed but will continue working
- The stream reconnects automatically when connectivity is restored
- Action: Check your internet connection; no manual intervention required
- Device offline: Verify your Quilt indoor unit has power and WiFi connection
- Recent setup: Allow 1-2 minutes after initial setup for devices to come online
- Cloud connection: Check that the Quilt app works on your phone
- Reload integration: Try reloading from Devices & Services
- Check logs: Go to Settings → System → Logs, search for "quilt"
- Re-authenticate: Remove and re-add the integration
- Restart Home Assistant: Sometimes resolves temporary issues
- Report issue: File a bug report on GitHub with relevant log entries
To enable debug logging, add to configuration.yaml:
logger:
default: warning
logs:
custom_components.quilt_hp: debugThen restart Home Assistant and check Settings → System → Logs for detailed information.
The following entities are created per device. Entities marked Disabled are off by default to reduce noise; enable them individually in the HA entity registry.
Device Naming: Indoor unit devices are named using their configured name (e.g., "Living Room IDU") or a fallback pattern like "{Room} Indoor Unit". This ensures device names clearly identify the physical hardware while the room is assigned as the area.
| Entity | Platform | Default | Notes |
|---|---|---|---|
| Schedules | switch |
Enabled | Pauses or resumes all Quilt schedules for the home. Off = paused. |
| Entity | Platform | Default |
|---|---|---|
| Climate | climate |
Enabled |
| Space temperature | sensor |
Enabled |
| Active comfort setting | sensor |
Enabled (diagnostic) |
The climate entity supports the following HVAC modes: Off, Cool, Heat, Heat/Cool (auto), Fan only, Dry. It also exposes an Away preset that mirrors Quilt's occupancy away state — set automatically when a room is unoccupied or from the Quilt app — and can be toggled from the thermostat. Turning Away off restores the room's normal (Active) target; Quilt may re-enter away automatically while the room stays unoccupied.
The Active comfort setting sensor reports which comfort profile Quilt's scheduler is
currently applying to the room (Active, Sleep, Away, Standby, or
Custom); the profile's configured name is available as its comfort_setting_name
attribute. It is read-only — comfort profiles are managed by Quilt's schedule, not
selected from Home Assistant.
The Fan speed select controls the indoor unit fan: Auto (the HVAC system chooses the speed) plus explicit Quiet / Low / Medium / High / Blast speeds. Quilt's fan has no "off" state — it is always in one of these modes.
| Entity | Platform | Default |
|---|---|---|
| Fan speed | select |
Enabled |
| LED | light |
Enabled |
| Louver mode | select |
Enabled |
| Louver angle | select |
Enabled |
| Temperature (IDU sensor) | sensor |
Enabled |
| Humidity | sensor |
Enabled |
| Motion | binary_sensor |
Enabled |
| Presence | binary_sensor |
Enabled |
| Occupied | binary_sensor |
Enabled |
| Inlet temperature | sensor |
Disabled |
| Outlet temperature | sensor |
Disabled |
| Presence level | sensor |
Disabled |
| HVAC capacity | sensor |
Disabled |
| HVAC power | sensor |
Disabled |
| Coefficient of performance | sensor |
Disabled |
| Calibrated temperature | sensor |
Disabled |
| Motion signal (radar) | sensor |
Disabled |
| Presence signal (radar) | sensor |
Disabled |
| Illuminance | sensor |
Disabled |
| Online | binary_sensor |
Disabled |
| Entity | Platform | Default |
|---|---|---|
| Outdoor temperature | sensor |
Enabled |
| Compressor frequency | sensor |
Disabled |
| High-side pressure | sensor |
Disabled |
| Low-side pressure | sensor |
Disabled |
| Entity | Platform | Default |
|---|---|---|
| Temperature | sensor |
Enabled |
| Online | binary_sensor |
Disabled |
| Wi-Fi signal | sensor |
Disabled |
Add the following to your config/configuration.yaml and restart Home Assistant:
logger:
default: warning
logs:
custom_components.quilt_hp: debugLogs are written to home-assistant.log in your HA config directory.
Entities become unavailable after a few hours
The gRPC stream disconnected and the reconnect failed. Check debug logs for
NotifierStream errors. Ensure your HA host has outbound internet access to the Quilt
cloud API.
Re-authentication loop Your refresh token has expired. Complete the re-auth flow from the HA notification. If the issue persists, remove and re-add the integration.
OTP not accepted The OTP expires quickly. Make sure you enter it within a minute or two of receiving it. If the config flow times out between the email and OTP steps, restart the flow.
Please open an issue at github.com/eman/homeassistant-quilt-hp/issues and include:
- Home Assistant version
- Integration version
- Relevant lines from
home-assistant.logwith debug logging enabled
- Room-by-room comfort — each Quilt space is a
climateentity with its own setpoints and mode, so bedrooms, offices, and living areas can follow different targets and schedules. - Presence-aware HVAC — every indoor unit exposes radar-based
motion,presence, andoccupiedbinary sensors. Use them to set back unoccupied rooms or as general-purpose occupancy sensors for lighting and security automations. - Energy tracking — the per-room Energy today sensors plug directly into HA's Energy dashboard (add them as individual devices) and reset at local midnight.
- Schedule control — the per-home Schedules switch pauses or resumes all Quilt schedules at once, e.g. while on vacation or during a party.
- Ambient signals — the indoor unit LED is a full RGBW
lightwith effects; use it as a subtle notification surface in rooms that have one.
Entity IDs below follow HA's generated names (climate.family_room,
binary_sensor.family_room_occupied, switch.<home>_schedules, …) — adjust to yours.
Set back an empty room, restore it when someone returns:
automation:
- alias: "Family room away setback"
triggers:
- trigger: state
entity_id: binary_sensor.family_room_occupied
to: "off"
for: "00:30:00"
actions:
- action: climate.set_temperature
target:
entity_id: climate.family_room
data:
target_temp_low: 17
target_temp_high: 27
- alias: "Family room comfort on return"
triggers:
- trigger: state
entity_id: binary_sensor.family_room_occupied
to: "on"
actions:
- action: climate.set_temperature
target:
entity_id: climate.family_room
data:
target_temp_low: 20
target_temp_high: 24Pause all Quilt schedules while nobody is home:
automation:
- alias: "Pause Quilt schedules when away"
triggers:
- trigger: state
entity_id: zone.home
to: "0"
actions:
- action: switch.turn_off
target:
entity_id: switch.home_schedules
- alias: "Resume Quilt schedules on arrival"
triggers:
- trigger: numeric_state
entity_id: zone.home
above: 0
actions:
- action: switch.turn_on
target:
entity_id: switch.home_schedulesTurn the room off entirely at night, on in the morning:
automation:
- alias: "Dining room off overnight"
triggers:
- trigger: time
at: "23:00:00"
actions:
- action: climate.turn_off
target:
entity_id: climate.dining_room
- alias: "Dining room on in the morning"
triggers:
- trigger: time
at: "06:30:00"
actions:
- action: climate.turn_on
target:
entity_id: climate.dining_roomNotify when a room's daily energy exceeds a budget:
automation:
- alias: "Primary bedroom energy budget"
triggers:
- trigger: numeric_state
entity_id: sensor.primary_bedroom_energy_today
above: 5 # kWh
actions:
- action: notify.mobile_app_phone
data:
message: >-
Primary bedroom has used
{{ states('sensor.primary_bedroom_energy_today') }} kWh today.Use the indoor unit LED as a doorbell flash:
automation:
- alias: "Flash family room LED on doorbell"
triggers:
- trigger: state
entity_id: binary_sensor.doorbell
to: "on"
actions:
- action: light.turn_on
target:
entity_id: light.family_room_led
data:
rgbw_color: [255, 120, 0, 0]
brightness: 255
effect: sparkle_fade
- delay: "00:00:10"
- action: light.turn_off
target:
entity_id: light.family_room_led- In Home Assistant go to Settings → Devices & services → Quilt.
- Open the entry menu (⋮) and select Delete.
- If no other Quilt entry uses the same account, the cached authentication tokens are removed from HA storage automatically.
To fully sign the host out of your Quilt account, also revoke the session from the Quilt mobile app if desired.
git clone https://github.com/eman/homeassistant-quilt-hp
cd homeassistant-quilt-hp
pip install -r requirements-dev.txtpytest # run all tests
ruff check . && ruff format --check . # lint + format
mypy custom_components/quilt_hp # type check
basedpyright custom_components/quilt_hp # type checkA docker-compose.yml is included for running a real HA instance against the
integration locally:
docker compose up -d # start
docker compose restart # pick up integration changes
docker compose down # stopHA is available at http://localhost:8124.
quilt-hp-python— installed automatically by HA.
MIT License. See LICENSE for details.
This project is not affiliated with or endorsed by Quilt.