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

Stop any live streams and 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.

Internal transport hook (implements CurrentTokenProvider) — not intended for application use.

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.

Passing an explicit home different from the client's configured default resolves that system without touching the cached default — subsequent no-argument calls keep operating on the configured home.

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.

Single-flight: when several concurrent RPCs hit UNAUTHENTICATED at once, only the first waiter performs the Cognito refresh; the rest observe the already-updated token and return.

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 IndoorUnit object (no snapshot lookup needed) or an IDU ID string (snapshot is fetched to resolve the object).	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 IndoorUnit object or an IDU ID string.	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 Space object (no snapshot lookup needed) or a space ID string (snapshot is fetched to resolve the object).	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 Space object or space ID string.	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. ["hds/space/<uuid>"]).	required
max_reconnects	int	Maximum automatic reconnects per disconnect. -1 means unlimited (the default).	-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 disables debouncing.	0.0

Returns a NotifierStream. Stream events are sparse diffs — always merge them into a snapshot via snapshot.apply_* before use; a raw stream entity has empty names/controls for any field the diff didn't carry.

• Background task (for integrations)::

  snapshot = await client.get_snapshot() async with client.stream(snapshot.stream_topics()) as stream: stream.on_space_update( lambda space: on_change(snapshot.apply_space(space)) ) # stream runs in background, do other work here await asyncio.sleep(3600)

• Blocking (for CLI / scripts)::

  snapshot = await client.get_snapshot() s = client.stream(snapshot.stream_topics()) s.on_space_update(lambda space: snapshot.apply_space(space)) 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 ComfortSetting object (no snapshot lookup needed) or a setting ID string (snapshot resolves the object).	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.

Hardware info (model_sku, serial_number, firmware_version) is only populated at initial snapshot load from indoor_unit_hardware and is never present in stream diffs, so preserve it.

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_software_update_info(sui)

Patch a stream-updated SoftwareUpdateInfo into the snapshot.

Update records are replaced wholesale: an all-empty/zero record is a legitimate state ("no update pending"), so there is no absence sentinel to preserve against.

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 Space object or space ID string.	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 Space object or space ID string.	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.

indoor_units_for_space(space)

Return all indoor units linked to a space.

Parameters:

Name	Type	Description	Default
space	Space | str	A Space object or space ID string.	required

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, controllers, QSMs, remote sensors, and software-update records.

Note: comfort settings, schedules, and locations are not delivered over the notifier stream — re-fetch a snapshot to pick up changes to those (e.g. after editing presets in the Quilt app).

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, model_sku=None, serial_number=None, firmware_version=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.

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. 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: offline IDUs have stale controls data and must not be used for LED state.

from_proto(proto, hw_map=None) classmethod

Construct from a protobuf IndoorUnit message.

hw_map maps hardware_id → IndoorUnitHardware proto, built once from HomeDatastoreSystem.indoor_unit_hardware and passed in at snapshot load time. Stream diffs won't have it; hardware fields default to None.

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_bssid=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, local_comms_health=LocalCommsHealthStatus.UNSPECIFIED, local_comms_visible_devices=None, local_comms_expected_devices=None, local_comms_reason=LocalCommsHealthReason.UNSPECIFIED, local_comms_last_session_change=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). None when no state reading is available (e.g. unmerged stream diff).

is_online property

True if the controller is known to be online.

Uses ControllerState.updated_ts if available, with a 5-minute threshold.

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.

local_comms_expected_devices = None class-attribute instance-attribute

LocalCommsStatus.expected_devices_count (proto field 4) — the number of mesh peers expected on this system. APK-confirmed (1.0.29).

local_comms_health = LocalCommsHealthStatus.UNSPECIFIED class-attribute instance-attribute

Local mesh health (proto field 9). Available on app 1.0.26+.

Gate: mobile_local_control_health_enabled. UNSPECIFIED means the server has not yet reported a health value (pre-1.0.26 firmware or the gate is off).

local_comms_last_session_change = None class-attribute instance-attribute

LocalCommsStatus.last_session_change_ts (proto field 5) — when the local mesh session last changed.

local_comms_reason = LocalCommsHealthReason.UNSPECIFIED class-attribute instance-attribute

LocalCommsStatus.reason (proto field 6) — diagnostic reason for the current local_comms_health status (e.g. PARTIAL_VISIBILITY when some but not all expected peers are visible). APK-confirmed (1.0.29).

local_comms_visible_devices = None class-attribute instance-attribute

LocalCommsStatus.visible_devices_count (proto field 3) — the number of mesh peers this node currently sees. APK-confirmed (1.0.29).

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, fan_speed_mode_raw=0, fan_speed_percent_raw=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

Bases: IntEnum

Discrete fan speed labels (maps to mode + percent on the wire).

from_wire(mode, percent) classmethod

Decode wire fan_speed_mode/fan_speed_percent to FanSpeed label.

to_wire()

Return (fan_speed_mode, fan_speed_percent) for the wire protocol.

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, …).

load(email) async

Return cached tokens for email, or None if absent / invalid.

save(email, tokens) async

Persist tokens for email.

quilt_hp.tokens.CachedTokens(id_token, refresh_token, expires_at) dataclass

A Cognito IdToken plus its refresh token and expiry timestamp.

is_expired property

True if the IdToken has expired (with a 5-minute safety buffer).