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.

apply_fan_angle(angle, *, rooms=(), indoor_units=(), whole_house=False, system_id=None) async

Set the louver position (FanAngle.AUTO, CEILING … FLOOR).

apply_fan_speed(speed, *, rooms=(), indoor_units=(), whole_house=False, system_id=None) async

Set the fan speed.

apply_light(*, on=None, brightness_percent=None, color=None, animation=None, rooms=(), indoor_units=(), whole_house=False, system_id=None) async

Set the indoor units' LED ring: power, brightness (0–100), colour and animation.

color is a preset or a custom RgbwColor. Settings you leave out are unchanged.

apply_mode(mode, *, rooms=(), indoor_units=(), whole_house=False, system_id=None) async

Set the mode of rooms, indoor units or the whole house.

Accepts ClimateMode (including AWAY) or the familiar HVACMode (STANDBY means off).

apply_temperatures(*, heat_c=None, cool_c=None, rooms=(), indoor_units=(), whole_house=False, system_id=None) async

Set heating and/or cooling setpoints (°C).

cancel_self_test(idu) async

Cancel a running self-test started with start_self_test.

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_access_role(system_id=None) async

The signed-in user's role in the system (admin or member).

get_comfort_setting(comfort_setting_id) async

Fetch one comfort setting from the server.

get_controller(controller_id) async

Fetch one controller (Dial) from the server.

get_controller_remote_sensor(sensor_id) async

Fetch one Dial-paired remote sensor from the server.

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_data_sharing(system_id=None) async

Whether the system shares its data with an installer partner.

get_diagnostics(system_id=None) async

Fetch the installer-style diagnostic view for a system.

Convenience wrapper over get_snapshot().diagnostics(). Returns the per-indoor-unit fault/condition matrix (including outdoor-unit and refrigerant conditions surfaced through each IDU), refrigerant-circuit temperatures, and per-unit power — the diagnostic data the cloud plane exposes. The outdoor unit's own raw sensors are not included (see :class:~quilt_hp.models.diagnostics.OutdoorUnitDiagnostics).

get_energy(start, end, system_id=None) async

Fetch energy metrics for a time range.

get_indoor_unit(indoor_unit_id) async

Fetch one indoor unit from the server.

get_outdoor_unit(outdoor_unit_id) async

Fetch one outdoor unit from the server.

get_partner_details() async

The installer partner the signed-in user belongs to, or None for homeowners.

get_quilt_smart_module(qsm_id) async

Fetch one Quilt Smart Module from the server.

get_remote_sensor(sensor_id) async

Fetch one remote sensor from the server.

get_schedule_day(schedule_day_id) async

Fetch one schedule day from the server.

get_schedule_week(schedule_week_id) async

Fetch one schedule week from the server.

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_software_update_info(info_id) async

Fetch one software-update record from the server.

get_space(space_id) async

Fetch one space from the server.

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_system_version(system_id=None) async

Cheaply fetch the system's configuration version (a ~14-byte response).

The version advances whenever controls, settings or configuration are written — including automatic writes such as auto-away switching a comfort setting — but not on telemetry. If it differs from snapshot.version, the snapshot's configuration is stale; refetch it (or invalidate_snapshot() when using the snapshot cache).

get_user_attributes() async

Get current user's additional attributes.

invalidate_snapshot()

Discard the cached snapshot so the next call fetches fresh data.

list_certified_partners(system_id=None) async

Certified installer partners for the system's location.

Raises QuiltPreconditionError when the system has no address set.

list_comfort_settings() async

List all comfort presets.

list_indoor_units() async

List all indoor units.

list_pending_invitations() async

Invitations the signed-in user has received and not yet answered.

list_spaces() async

List all room-level spaces (excludes the root home space).

list_system_users(system_id=None) async

Administrators, members and pending invitations for the system.

list_systems() async

List all systems the user has access to.

list_user_tasks(system_id=None) async

Tasks the app would prompt about for the system, such as data-sharing consent.

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.

request_fast_updates(*, reason=FastUpdateReason.USER_ACTIVITY, system_id=None) async

Ask the cloud to raise the telemetry cadence for a system.

Calls CommandService/RequestFastUpdates — the same lever the mobile app pulls when the user is active or a device's local mesh is degraded. The effect is a faster stream of state updates over the NotifierService stream; there is no return value.

Parameters:

Name	Type	Description	Default
reason	FastUpdateReason	Why fast updates are being requested (default: USER_ACTIVITY).	USER_ACTIVITY
system_id	str | None	Target system; defaults to the client's resolved system.	None

set_controller(controller, *, name=None, uses_dial_temperature=None) async

Rename a Dial and/or choose which sensor its room is controlled to.

Parameters:

Name	Type	Description	Default
controller	Controller | str	A Controller object or controller ID string.	required
name	str | None	The Dial's new name.	None
uses_dial_temperature	bool | None	True to control the room to the Dial's temperature (the app's "Temperature sensor" setting); False to use the indoor unit's sensor.	None

Returns the updated Dial as the server reports it (hardware fields are None).

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

start_self_test(idu) async

Start an indoor unit's diagnostic self-test (the app's "Run diagnostic test").

The test takes up to 30 minutes, and the unit's room can't be heated or cooled meanwhile. Quilt (and the home's certified partner, if any) sees the results; the server returns none. Follow progress with IndoorUnit.is_under_test.

Observed live (2026-10-06): the unit entered HEALTH_CHECK within 15 s, with EXCLUSIVE coordination (it was alone on its outdoor unit), ran cooling and then heating (state.hvac_state), and returned to normal after about 20 minutes. test_state.test_phase stayed NONE throughout.

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)) s.on_delete(snapshot.remove) # deletions never reach the update callbacks 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, version=None) 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).

version_at property

version as a UTC datetime (when the configuration was last written).

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.

diagnostics()

Assemble the installer-style diagnostic view from this snapshot.

Returns per-indoor-unit fault conditions (including the outdoor-unit / refrigerant conditions surfaced through each IDU), refrigerant-circuit temperatures, and power, plus a coarse per-outdoor-unit entry. The ODU's own raw sensors are not on the cloud plane; see :class:~quilt_hp.models.diagnostics.OutdoorUnitDiagnostics.

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.

remove(kind, entity_id)

Drop a deleted object (see NotifierStream.on_delete); True if it was present.

kind is a StreamEvent attribute name: "space", "indoor_unit", "outdoor_unit", "controller", "qsm", "remote_sensor", "controller_remote_sensor" or "software_update_info". Later apply_* calls for the removed object are ignored (they return the diff without re-adding it).

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, occupancy=None, created_at=None) dataclass

A Quilt space (room / zone).

ambient_temperature_f property

Ambient temperature in °F, or None if unavailable.

created_at = None class-attribute instance-attribute

When this room was added to the system.

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.

occupancy_state property

The room's auto-away occupancy (DETECTED / UNDETECTED), or None if not reported.

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, climate=None, test_state=None, unit_serial_number=None, smart_module_serial_number=None, manufactured_at=None, created_at=None) dataclass

A Quilt indoor unit (wall-mounted mini-split head).

created_at = None class-attribute instance-attribute

When this indoor unit was added to the system.

dew_point_c property

Dew point at the unit's air inlet, or None when unknown or flagged invalid.

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.

effective_test_mode property

The unit's current test mode, from test_state or state, whichever is newer.

The server reports the mode in both places, and a snapshot merged from sparse stream diffs can hold an older copy of one of them, so the more recently updated source wins. A source that reports UNSPECIFIED (absent) is ignored.

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.

is_under_test property

True while the unit runs a health check, commissioning or another test.

During a test the unit's behaviour is driven by the test, not by the room's controls. Uses effective_test_mode, so it works when only state.test_mode is reported.

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.

manufactured_at = None class-attribute instance-attribute

IndoorUnitHardware.production_ts.

presence_detected property

Realtime room presence — True if either radar channel detects someone.

Mirrors the vendor app's combinedSensorPresence (OR of the two channels). Flips within seconds; use :attr:effective_occupancy_state for the debounced auto-away decision instead. Returns None when the IDU is offline, has no presence data, or neither channel has reported (both UNSPECIFIED).

smart_module_serial_number = None class-attribute instance-attribute

The serial of the Smart Module built into the unit (QS1-…).

unit_serial_number = None class-attribute instance-attribute

The indoor unit's own serial (QN1-…). serial_number is its Smart Module's.

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, port_count=None, manufactured_at=None, created_at=None) dataclass

A Quilt outdoor unit (compressor).

created_at = None class-attribute instance-attribute

When this outdoor unit was added to the system.

manufactured_at = None class-attribute instance-attribute

OutdoorUnitHardware.production_ts.

port_count = None class-attribute instance-attribute

How many indoor units the outdoor unit can serve (OutdoorUnitHardware.num_ports).

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, description=None, 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, view_state=ControllerViewState.UNSPECIFIED, screen_brightness=None, radar_target_detected=None, radar_phase_detected=None, ambient_light_lux=None, orientation=ControllerOrientation.UNSPECIFIED, humidity_percent=None, power_w=None, main_board_temperature_c=None, power_board_temperature_c=None, accelerometer_raw=None, hosted_wifi=None, manufactured_at=None, created_at=None) dataclass

A Quilt controller (Dial thermostat).

accelerometer_raw = None class-attribute instance-attribute

Raw accelerometer X/Y/Z counts.

ambient_light_lux = None class-attribute instance-attribute

Calibrated ambient light at the Dial, in lux (als_illuminance_calib_lx).

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

created_at = None class-attribute instance-attribute

When this Dial was added to the system.

description = None class-attribute instance-attribute

ControllerSettings.description; None when settings was absent from a diff.

display_on property

True unless the display is asleep; None when the view state is unknown.

hosted_wifi = None class-attribute instance-attribute

The home-network Wi-Fi link in full (the wifi_* fields are the common parts of it).

humidity_percent = None class-attribute instance-attribute

Relative humidity from the Dial's SHT4x sensor; None on Dials that don't report it.

is_online property

True if the Dial has reported its state in the last 5 minutes.

Uses ControllerState.updated_ts (proto field 15), as the app does (Controller.isOnline). Online Dials report state about every 10 seconds; an offline Dial's timestamp stops advancing. A Dial with no state timestamp at all is offline, again as in the app: the server sends an offline Dial with an empty state. (A sparse stream diff without state keeps the previous timestamp through SystemSnapshot.apply_controller.)

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

manufactured_at = None class-attribute instance-attribute

ControllerHardware.production_ts.

orientation = ControllerOrientation.UNSPECIFIED class-attribute instance-attribute

Wall-mounted (VERTICAL) or lying flat (HORIZONTAL).

power_w = None class-attribute instance-attribute

The Dial's own power draw (power_meter_w), ~0.85–1.2 W observed.

presence_detected property

True if the Dial's radar sees someone (target or phase channel).

None when no state reading is available. Independent of the indoor unit's radar (see IndoorUnit.presence_detected).

radar_phase_detected = None class-attribute instance-attribute

The Dial radar's phase channel (mmwave_phase_detect); not yet seen true live.

radar_target_detected = None class-attribute instance-attribute

The Dial's own mmWave radar reports a target (mmwave_target_detect).

This radar is separate from the indoor unit's (IndoorUnit.presence).

remote_sensor_mode = RemoteSensorControlMode.UNSPECIFIED class-attribute instance-attribute

Whether the room is controlled to this Dial's temperature (the app's "Temperature sensor" setting); DISABLED means the indoor unit's own sensor is used.

screen_brightness = None class-attribute instance-attribute

Display brightness, 0.0–1.0 (0.0 while asleep).

uses_dial_temperature property

True when the room is controlled to this Dial's temperature; None if unknown.

view_state = ControllerViewState.UNSPECIFIED class-attribute instance-attribute

What the display is showing: SLEEP, GLANCE, ACTIVE or INTERACTING.

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