Skip to content

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 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 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 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.

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 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.

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

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