Compass Pool Heater – Home Assistant Integration

A Home Assistant custom integration for Gulfstream, Aqua Comfort, Built Right, and other pool/spa heat pumps that use the ICM Controls Compass WiFi module and the Compass mobile app.

• A pool/spa heat pump with the ICM Controls Compass WiFi module
• An active Compass app account (email + password)
• The heat pump registered and working in the Compass mobile app

1. Open HACS in Home Assistant
2. Go to Integrations → three-dot menu → Custom repositories
3. Add https://github.com/cjam28/compass-pool-heater-ha as an Integration
4. Click Download
5. Restart Home Assistant

Copy the custom_components/compass_pool_heater folder into your Home Assistant config/custom_components/ directory and restart.

1. Go to Settings → Devices & Services → Add Integration
2. Search for Compass Pool Heater
3. Enter your Compass app email and password
4. If you have multiple heat pumps, select which one to add
5. Done — entities appear automatically

The main thermostat entity with:

• HVAC Modes: Off, Heat
• Presets: Pool, Spa
• Temperature range: 50-104°F (setpoint of 0 = Off)

This integration communicates with the ICM Controls cloud API at captouchwifi.com — the same backend used by the Compass mobile app. The heat pump connects to WiFi and maintains a persistent connection to the cloud; commands are relayed through it.

Polling interval: 30 seconds (configurable).

Any pool/spa heat pump using the ICM Controls Compass WiFi module, including:

• Gulfstream (confirmed working)
• Aqua Comfort
• Built Right
• Other ICM Controls-based units with the Compass app

This blueprint automatically coordinates your pool pump with the heater to prevent "No Flow" faults and handle stale temperature readings (the water temp sensor at the heater reads stagnant pipe water when the pump is off).

Three behaviors:

1. Auto-Start — turns the pump on when heating is activated
2. Periodic Check — every N minutes, if the heater wants to heat but the pump is off, starts the pump, waits for a fresh reading, and decides whether to keep it running or shut it back off
3. Auto-Stop — optionally turns the pump off after a configurable delay when the heater is turned off

The blueprint works with any pump controller — njsPC-HA, Pentair ScreenLogic, Hayward OmniLogic, a simple relay switch, or anything else in Home Assistant. You define exactly what "start pump" and "stop pump" mean for your setup via the action selectors.

The blueprint is automatically installed when you add the integration. After installing or updating via HACS and restarting Home Assistant, you will see a persistent notification prompting you to configure it.

1. Go to Settings → Automations & Scenes → Blueprints
2. Find Compass Pool Heater – Pump Coordination
3. Click Create Automation
4. Configure the inputs (see below) for your pump setup
5. Save and enable the automation

https://github.com/cjam28/compass-pool-heater-ha/raw/main/blueprints/automation/compass_pool_heater/pump_coordination.yaml

An all-in-one blueprint for pump scheduling with optional occupancy-based speed control and heater guest/vacant temperature management. Occupancy sensors are not required — without them the blueprint works as a pure time-based pump schedule. Use it alongside the Pump Coordination blueprint above.

Three usage tiers:

What it does:

1. Pump Schedule — runs the pump at low speed overnight and default speed midday (times are configurable)
2. Heater-Aware Pump Control — at schedule boundaries, if the heater is in heat mode the pump drops to low speed instead of turning off, preventing No Flow faults
3. Pool Occupancy Override (optional) — when the pool area is occupied, the pump switches to max speed; when guests leave, it returns to the scheduled speed
4. Heater Occupied/Vacant Mode (optional) — when the house is occupied, the heater is set to the occupied temperature (default 86°F); after no occupancy for a configurable period (default 12 hours), it drops to the vacant temperature (default 78°F)
5. Dashboard Toggle (optional) — a Pool Occupied Mode input_boolean (ON = Occupied, OFF = Vacant) can be toggled manually from the dashboard to override occupancy detection

If using occupied/vacant temperature mode (Tier 2 or 3), create one helper:

• Settings → Devices & Services → Helpers → Create Helper → Toggle
• Name it Pool Occupied Mode (entity: input_boolean.pool_occupied_mode)
• ON = Occupied (heater at occupied temperature), OFF = Vacant (heater at vacant temperature)

For time-only mode (Tier 1), no helpers are needed.

1. Go to Settings → Automations & Scenes → Blueprints
2. Find Compass Pool Heater – Smart Schedule
3. Click Create Automation
4. Configure the required inputs (Pool Heater, pump actions, schedule times)
5. Optionally fill in Pool Occupied Mode Toggle, House Occupancy Sensor, and/or Pool Area Occupancy Sensor for additional features
6. Save and enable

https://github.com/cjam28/compass-pool-heater-ha/raw/main/blueprints/automation/compass_pool_heater/pool_smart_schedule.yaml

Leave Pool Occupied Mode Toggle, House Occupancy Sensor, Pool Area Occupancy Sensor, and Pump Max Speed Action blank.

The Pump Coordination and Smart Schedule blueprints are designed to work together. Smart Schedule manages the pump timetable and heater setpoints; Pump Coordination acts as a safety net to ensure the pump runs whenever the heater needs water flow.

Recommended Pump Coordination settings when using Smart Schedule:

How they interact: Smart Schedule controls the pump schedule, but if the heater is in heat mode it keeps the pump at low speed instead of turning it off at schedule boundaries. Pump Coordination's periodic check catches any remaining case where the pump is off but the heater needs flow, starts the pump, checks the temperature, and either keeps it running or shuts it back off.

• "Invalid email or password": The API uses your email as the username field. Make sure you can log in to the Compass mobile app with the same credentials.
• Stale data: The cloud API is polled every 30 seconds. If the heater is offline, the last known state is shown.
• "No Flow" fault: This is reported by the heat pump itself when it detects insufficient water flow. Check your pool pump.

Extracted from the Compass app source:

Only CHGF=8 has been confirmed via live testing. The other fault codes exist in the app but their exact CHGF values haven't been mapped yet. If you encounter a different fault code, the raw value will be shown — please report it so we can complete the mapping!

MIT