API reference¶
Auto-generated from source docstrings. For a narrative walkthrough of QuiltClient with examples, see QuiltClient.
quilt_hp¶
quilt_hp.QuiltClient(email, *, home=None, environment=Environment.PROD, snapshot_ttl_s=0, token_store=None, token_refresh_hooks=None, token_refresh_policy=None)
¶
Async client for the Quilt HVAC cloud API.
Manages authentication, gRPC channel lifecycle, and exposes high-level methods for controlling Quilt mini-split systems.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
email
|
str
|
Quilt account email address. |
required |
home
|
str | None
|
Optional home name filter (substring match) for multi-home accounts. |
None
|
environment
|
Environment
|
API environment (default: PROD). |
PROD
|
snapshot_ttl_s
|
float
|
If > 0, cache the system snapshot for this many seconds. Useful for read-heavy integrations. Default: 0 (no cache). |
0
|
system_name
property
¶
Name of the resolved system after get_system_id() is called.
close()
async
¶
Close the gRPC channel.
create_schedule_day(space_id, name, events)
async
¶
Create a new schedule day program from domain schedule events.
create_schedule_week(space_id, days=None)
async
¶
Create a new schedule week from domain weekday mappings.
delete_schedule_day(schedule_day_id)
async
¶
Delete a schedule day program.
delete_schedule_week(schedule_week_id)
async
¶
Delete a schedule week.
get_current_token()
¶
Token provider callable for the transport interceptor.
get_current_user()
async
¶
Get the currently authenticated user.
get_energy(start, end, system_id=None)
async
¶
Fetch energy metrics for a time range.
get_snapshot(system_id=None)
async
¶
Fetch a full system snapshot.
If snapshot_ttl_s was set on the client and the cached snapshot is
still fresh, the cached copy is returned without a network round-trip.
Pass system_id to query a specific system (bypasses and does not
populate the cache for the default system).
get_system_id(home=None)
async
¶
Get primary system ID, cached after first call unless home changes.
get_user_attributes()
async
¶
Get current user's additional attributes.
invalidate_snapshot()
¶
Discard the cached snapshot so the next call fetches fresh data.
list_comfort_settings()
async
¶
List all comfort presets.
list_indoor_units()
async
¶
List all indoor units.
list_spaces()
async
¶
List all room-level spaces (excludes the root home space).
list_systems()
async
¶
List all systems the user has access to.
login(otp_callback=None)
async
¶
Authenticate with the Quilt API.
If cached tokens are valid, no OTP is needed. Otherwise, the otp_callback is called to obtain the OTP code sent to the user's email.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
otp_callback
|
OtpCallback | None
|
Callable that receives the email and returns the OTP. Can be sync or async. |
None
|
patch_user_attributes(*, declared_user_type)
async
¶
Patch current user's additional attributes.
refresh_token(context=None)
async
¶
Refresh the auth token without OTP when refresh token is valid.
set_indoor_unit(idu, *, fan_speed=None, louver_mode=None, louver_position=None, led_color_code=None, led_brightness=None, led_animation=None)
async
¶
Update indoor unit controls.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
idu
|
IndoorUnit | str
|
An |
required |
set_indoor_unit_settings(idu, *, fence_left_m=None, fence_right_m=None, fence_forward_m=None, radar_height_m=None, light_brightness_default=None)
async
¶
Update indoor unit settings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
idu
|
IndoorUnit | str
|
An |
required |
fence_left_m
|
float | None
|
Left boundary of presence detection zone in metres. |
None
|
fence_right_m
|
float | None
|
Right boundary of presence detection zone in metres. |
None
|
fence_forward_m
|
float | None
|
Forward boundary of detection zone in metres. |
None
|
radar_height_m
|
float | None
|
Radar sensor mounting height from floor in metres. |
None
|
light_brightness_default
|
float | None
|
Default LED brightness (0.0–1.0). |
None
|
All parameters are optional; omitted fields keep their current value. Set a fence value to 0.0 to clear it (returns to max-range detection).
set_schedule_execution(paused)
async
¶
Globally pause or resume all schedules for the primary location.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
paused
|
bool
|
True to pause all schedules, False to resume. |
required |
set_space(space, *, mode=None, heat_setpoint_c=None, cool_setpoint_c=None)
async
¶
Update a space's HVAC mode and/or setpoints.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
space
|
Space | str
|
A |
required |
set_space_settings(space, *, unoccupied_timeout_s=None, occupied_timeout_s=None)
async
¶
Update a space's auto-away / auto-return timeouts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
space
|
Space | str
|
A |
required |
unoccupied_timeout_s
|
float | None
|
Seconds of no-presence before auto-away. |
None
|
occupied_timeout_s
|
float | None
|
Seconds of presence before auto-return. |
None
|
stream(topics, *, max_reconnects=-1, reconnect_delay_s=1.0, debounce_s=0.0)
¶
Create a NotifierStream for real-time updates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
topics
|
list[str]
|
List of topic strings to subscribe to
(e.g. |
required |
max_reconnects
|
int
|
Maximum automatic reconnects per disconnect. |
-1
|
reconnect_delay_s
|
float
|
Initial back-off in seconds before reconnecting. Doubles on each attempt, capped at 60 s. |
1.0
|
debounce_s
|
float
|
Quiet period in seconds for coalescing updates by
entity before dispatching the latest event. |
0.0
|
Returns a NotifierStream that can be used as:
-
Background task (for integrations)::
async with client.stream(topics) as stream: stream.on_space_update(my_callback) # stream runs in background, do other work here await asyncio.sleep(3600)
-
Blocking (for CLI / scripts)::
s = client.stream(topics) s.on_space_update(my_callback) await s.run_forever()
update_comfort_setting(setting, *, name=None, hvac_mode=None, heat_setpoint_c=None, cool_setpoint_c=None, fan_speed=None)
async
¶
Update a comfort setting preset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
setting
|
ComfortSetting | str
|
A |
required |
update_current_user(*, first_name, last_name, phone_number=None)
async
¶
Update current user's first/last name and optional phone number.
update_schedule_day(schedule_day_id, space_id, name=None, events=None)
async
¶
Update an existing schedule day using domain schedule events.
update_schedule_week(schedule_week_id, space_id, days)
async
¶
Update an existing schedule week with domain weekday mappings.
quilt_hp.Environment
¶
Bases: Enum
Quilt API environment.
quilt_hp.QuiltError
¶
Bases: Exception
Base exception for all quilt_hp errors.
quilt_hp.QuiltAuthError
¶
Bases: QuiltError
Authentication failed (OTP rejected, refresh expired, Cognito error).
quilt_hp.QuiltConnectionError
¶
Bases: QuiltError
Could not connect to the Quilt gRPC API.
quilt_hp.QuiltNotFoundError
¶
Bases: QuiltError
Requested resource (system, space, IDU) was not found.
quilt_hp.models¶
quilt_hp.models.SystemSnapshot(spaces, indoor_units, outdoor_units, controllers, quilt_smart_modules, comfort_settings, schedule_weeks, schedule_days, remote_sensors, controller_remote_sensors, software_update_infos, locations, timezone)
dataclass
¶
Full system state from GetHomeDatastoreSystem.
primary_location
property
¶
The first (and typically only) Location for this system.
rooms
property
¶
Return only leaf/room spaces (those with a parent).
apply_controller(ctrl)
¶
Patch a stream-updated Controller into the snapshot.
Stream diffs are sparse — a temperature state diff omits settings (name) and hosted_wifi_state. Preserve existing non-empty values. Hardware info (serial, model_sku, firmware_version) is only populated at initial snapshot load and is never in stream diffs; always preserve it.
apply_controller_remote_sensor(crs)
¶
Patch a stream-updated ControllerRemoteSensor into the snapshot.
apply_indoor_unit(idu)
¶
Patch a stream-updated IndoorUnit into the snapshot.
Stream protos are partial — qsm_id, outdoor_unit_id, the
hvac_inputs/conditions sub-messages, and the state
sub-message may all be absent in a diff. Preserve existing values so
stream updates don't erase them.
In particular, a controls-only diff (e.g. LED toggle) omits state,
which would make state.updated_at=None and therefore
is_online=False, causing led_on and
effective_occupancy_state to report stale data.
apply_outdoor_unit(odu)
¶
Patch a stream-updated OutdoorUnit into the snapshot.
Stream diffs may omit state (only performance_data changed) or
lack hardware info (no hw_map available at parse time). Preserve any
existing non-default values so partial updates don't erase them.
apply_qsm(qsm)
¶
Patch a stream-updated QuiltSmartModule into the snapshot.
Stream diffs are sparse — a controls diff omits state (sensors) and wifi state sub-messages. Preserve existing non-None values.
apply_remote_sensor(rs)
¶
Patch a stream-updated RemoteSensor into the snapshot.
Stream diffs are sparse — a state-only diff (temperature/humidity update) omits controls, leaving control_mode=UNSPECIFIED. A controls-only diff omits state, zeroing all sensor readings. Preserve existing non-None values.
apply_space(space)
¶
Enrich and patch a stream-updated Space into the snapshot.
Resolves comfort-setting type (needed for is_away / is_off) then merges the diff into the existing Space, preserving sub-messages that were absent from the sparse proto diff. Returns the merged space.
Proto3 stream diffs are sparse — only changed fields are sent. A
settings-only diff produces a Space with
controls.hvac_mode=UNSPECIFIED and
state.ambient_temperature_c=None. Without merging, those defaults
would overwrite real data.
away_comfort_setting(space)
¶
Return the Away comfort preset for a space, or None if absent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
space
|
Space | str
|
A |
required |
The Away preset defines the setpoints used when occupancy automation
switches a room to away mode (space.is_away is True). Its
heating_setpoint_c and cooling_setpoint_c are the away
setpoints. Update them with::
away_cs = snapshot.away_comfort_setting(space)
if away_cs:
await client.update_comfort_setting(
away_cs,
heat_setpoint_c=16.0,
cool_setpoint_c=28.0,
)
comfort_settings_for_space(space)
¶
Return all comfort presets for a space, ordered by their list position.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
space
|
Space | str
|
A |
required |
Each space has up to five presets (Active, Sleep, Away, Standby,
Custom). This is the full set; filter by cs.type to find a
specific one.
enrich_space(space)
¶
Resolve active_comfort_setting_type on a stream-updated Space.
Stream updates deliver individual Space protos without the comfort settings context. Call this before using space.is_away / space.is_off on a space received from the NotifierStream.
from_proto(proto)
classmethod
¶
Construct from a protobuf HomeDatastoreSystem message.
odu_for_idu(idu)
¶
Return the OutdoorUnit connected to the given IDU, or None.
qsm_for_idu(idu)
¶
Return the QSM embedded in the given IDU, or None.
space_by_name(name)
¶
Find a space by name (case-insensitive).
stream_topics()
¶
Return the NotifierService topic strings for this snapshot.
Pass the result directly to client.stream(topics). Covers all
rooms, indoor units, outdoor units, and controllers.
quilt_hp.models.Space(id, system_id, name, parent_space_id, settings, controls, state, active_comfort_setting_type=None)
dataclass
¶
A Quilt space (room / zone).
ambient_temperature_f
property
¶
Ambient temperature in °F, or None if unavailable.
is_away
property
¶
True when occupancy automation has temporarily suppressed an active mode.
Determined by active comfort setting type AWAY. The room will re-activate automatically when someone enters.
When is_away is True, controls.heating_setpoint_c and
controls.cooling_setpoint_c reflect the Away comfort preset's
setpoints — not the user's normal occupancy setpoints. To read or
update the Away preset setpoints (regardless of current occupancy
state), use SystemSnapshot.away_comfort_setting(space).
Falls back to comparing controls vs state hvac values when no comfort setting type is available (e.g. raw stream updates).
is_off
property
¶
True when the user has explicitly set this space to STANDBY.
The room will stay off regardless of occupancy or schedule.
is_room
property
¶
True if this is a leaf space (room), not the root home space.
from_proto(proto)
classmethod
¶
Construct a Space from a protobuf Space message.
quilt_hp.models.IndoorUnit(id, system_id, space_id, outdoor_unit_id, hardware_id, qsm_id, settings, controls, state, hvac_inputs, conditions, performance_data, performance_metrics, presence, occupancy, firmware_update_info_id=None, commands=None)
dataclass
¶
A Quilt indoor unit (wall-mounted mini-split head).
effective_occupancy_state
property
¶
Occupancy state proto value, or None if the IDU is offline.
KMP reads presence/occupancy only from online IDUs (filterOnline()).
An offline IDU's last-known occupancy_state is stale and must not
be displayed as current. Returns None when offline or no occupancy data.
is_online
property
¶
True if the IDU has sent a state update within the last 5 minutes.
Matches KMP SpaceViewNode.isOnlineByUpdatedTimestamp. An offline IDU may have stale controls data — treat LED as off.
led_on
property
¶
True if the LED is currently illuminated.
Applies the online gate: KMP's getLight() calls filterOnline()
and returns Light.OFF for offline IDUs. An offline IDU's controls
data is stale and must not be used for LED state.
from_proto(proto)
classmethod
¶
Construct from a protobuf IndoorUnit message.
quilt_hp.models.OutdoorUnit(id, system_id, space_id, hvac_state, model_sku, serial_number, firmware_version, firmware_update_info_id, performance_data)
dataclass
¶
A Quilt outdoor unit (compressor).
from_proto(proto, hw_map=None)
classmethod
¶
Construct from a protobuf OutdoorUnit message.
quilt_hp.models.Controller(id, system_id, space_id, name, raw_thermistor_c, pcb_temperature_a_c, pcb_temperature_b_c, calibrated_ambient_c, wifi_ssid, wifi_ip, wifi_signal_dbm, wifi_freq_mhz=None, wifi_last_seen=None, ap_wifi=None, p2p_wifi=None, remote_sensor_mode=RemoteSensorControlMode.UNSPECIFIED, software_update_info_id=None, firmware_update_info_id=None, serial_number=None, model_sku=None, firmware_version=None, state_updated_at=None)
dataclass
¶
A Quilt controller (Dial thermostat).
ambient_temperature_c
property
¶
Calibrated ambient temperature used for system control.
Use this for display and logic. See also raw_thermistor_c for the
uncorrected on-chip reading (biased high by self-heating).
is_online
property
¶
True if the controller is known to be online.
Uses ControllerState.updated_ts if available, with a 5-minute
threshold matching KMP IS_ONLINE_THRESHOLD_MINUTES = 5.
The server does not currently send ControllerState.updated_ts
(confirmed from wire captures — field 1 always absent). When no
timestamp is available we assume the controller is online; we only
report offline when we have positive evidence of a stale timestamp.
wifi_band
property
¶
'5 GHz' or '2.4 GHz' based on frequency, or None if unknown.
from_proto(proto, hw_map=None)
classmethod
¶
Construct from a protobuf Controller message.
hw_map maps hardware_id → ControllerHardware proto, built once from
HomeDatastoreSystem.controller_hardware and passed in at snapshot
load time. Stream diffs won't have it; fields default to None.
quilt_hp.models.ComfortSetting(id, system_id, space_id, name, type, hvac_mode, heating_setpoint_c, cooling_setpoint_c, fan_speed, louver_mode=LouverMode.UNSPECIFIED, louver_fixed_position=0.0)
dataclass
¶
A named comfort preset (Active, Sleep, Away, etc.).
has_placeholder_setpoints
property
¶
True when setpoints are placeholder values, not user targets.
has_standby_sentinel_setpoints
property
¶
True when this preset carries the STANDBY 8°C/40°C sentinel pair.
has_unspecified_setpoint_sentinels
property
¶
True when an UNSPECIFIED comfort type carries the 0°C/0°C placeholders.
louver_position_is_placeholder
property
¶
True when fixed-position is the 0.0 placeholder for non-FIXED louver modes.
from_proto(proto)
classmethod
¶
Construct from a protobuf ComfortSetting message.
quilt_hp.models.ScheduleDay(id, name, space_id, events)
dataclass
¶
A named day program with time events.
from_proto(proto)
classmethod
¶
Construct from a protobuf ScheduleDay message.
quilt_hp.models.ScheduleWeek(id, space_id, days)
dataclass
¶
A weekly schedule for a space, mapping weekdays to day programs.
from_proto(proto)
classmethod
¶
Construct from a protobuf ScheduleWeek message.
quilt_hp.models.RemoteSensor(id, indoor_unit_id, mac, ambient_temperature_c, humidity_percent, battery_level_percent, signal_level_dbm, control_mode)
dataclass
¶
A standalone BLE remote sensor linked to an IndoorUnit.
from_proto(proto)
classmethod
¶
Construct from a protobuf RemoteSensor message.
quilt_hp.models.HVACMode
¶
Bases: IntEnum
HVAC operating mode.
quilt_hp.models.FanSpeed
¶
quilt_hp.models.LouverMode
¶
Bases: IntEnum
Indoor unit louver mode.
quilt_hp.tokens¶
quilt_hp.tokens.TokenStore
¶
Bases: Protocol
Async-first protocol for token persistence.
Implement this to integrate with any storage backend (filesystem, HA secure storage, database, keychain, …).