Home Assistant Custom Integration

Install the hydroqc-ha custom integration for Home Assistant (Recommended)

Recommended for Home Assistant Users

The hydroqc-ha custom integration is the recommended way to integrate Hydro-Québec with Home Assistant. It provides a native integration built directly into Home Assistant.

Why choose hydroqc-ha?

Native integration: Runs as a Home Assistant custom component
Easy configuration: Setup entirely through the Home Assistant interface
Full feature support: Consumption, billing, winter credits and dynamic pricing
Multiple contracts: One device per Hydro-Québec contract
Diagnostic entities: Optional entities for troubleshooting and advanced automations

Installation

Via HACS (Recommended)

Prerequisites

Make sure HACS is installed on your Home Assistant instance. If not:

Follow the HACS installation guide
Restart Home Assistant after installing HACS

Install the integration

Option A: One-click installation

Click the badge above to add the repository to HACS, then:

Click “Download” (or “Install”)
Restart Home Assistant

Option B: Manual installation via HACS

Open HACS in Home Assistant
Click on Integrations
Click the three-dot menu in the top right corner
Select “Custom repositories”
Add the repository URL: https://github.com/hydroqc/hydroqc-ha
Select category: Integration
Click “Add”
Search “Hydro-Québec” in the HACS integrations list
Click on the Hydro-Québec integration
Click “Download” (or “Install”)
Restart Home Assistant

Note: after restarting, you still need to configure the integration (see the Configuration section below).

Manual installation

Download the latest release from GitHub Releases
Extract the hydroqc folder into your custom_components directory
Restart Home Assistant

Configuration

The first step asks which connection mode to use: Portal Mode (requires login) for a Hydro-Québec account, or OpenData Mode (no login required) for public peak data without credentials.

Local Calendar Required

For DPC (Flex-D) and DCPC (Winter Credits) rates, you must create a dedicated local calendar in Home Assistant before configuring the integration. All peak sensors (status, next peak times and preheat) read their data from calendar events. Do not use a shared calendar.

Option 1: Portal Mode (Hydro-Québec account)

Go to Settings > Devices & Services
Click + Add Integration
Search Hydro-Québec
Select Portal Mode (requires login)
Enter your credentials:
- Username: Hydro-Québec email
- Password: Hydro-Québec password
- Contract name: a friendly name (e.g., “Home”, “Cottage”)
Select the contract to monitor
Choose how many days of consumption history to import (0-800). Set 0 to sync only the last 30 days
Enable or disable consumption synchronization
For DPC (Flex D) and DCPC (Winter Credits), select a dedicated calendar
Done! Entities appear shortly

Features with an account:

Current and historical consumption data
Balance and billing information
Current rate and rate option
Winter credits and peak events
Outage information
Energy Dashboard statistics

Consumption Sync

Consumption sync imports hourly consumption as long-term statistics for the Home Assistant Energy Dashboard. You can disable it if you don’t need historical consumption tracking or want to reduce API calls. This can be changed later in the integration options.

Option 2: OpenData Mode (no account required)

For users who only want peak period information without logging in:

Go to Settings > Devices & Services
Click + Add Integration
Search Hydro-Québec
Select OpenData Mode (no login required)
Choose your customer sector (residential or commercial)
Select your rate plan (the available plans are fetched from Hydro-Québec’s public API)
Enter a contract name and a preheat duration (0-240 minutes)
For DPC (Flex D) and DCPC (Winter Credits), select a dedicated calendar
Done! Entities appear shortly

Features without an account:

Peak event information
Dynamic pricing information
No consumption tracking
No billing information

Preheat Duration

The preheat duration can be configured during setup and changed later in the integration options. It determines how far in advance the preheat period starts before a peak event (default: 120 minutes, range: 0-240 minutes).

Multi-contract setup

To monitor multiple contracts (e.g., home and cottage):

Add the integration multiple times
Use a different contract name for each one
Select a different contract during each setup

Changing contract or password

Hydro-Québec assigns a new contract number whenever the person responsible for a consumption site changes, even if the site is already linked to the account. You don’t need to remove the integration to update it:

Go to Settings > Devices & Services > Hydro-Québec
Open the three-dot menu of the entry and select Reconfigure
Confirm your email. Leave the password empty to keep the current one, or enter a new one
Select the contract

Entities keep their entity_id and the consumption history is preserved.

Email verification (MFA)

Hydro-Québec may require an email verification code after the password.

During initial setup, reconfiguration or reauthentication, the integration shows the Email verification step.
Enter the code you received. Leave the field empty to request a new code. If the code has expired, the login is restarted and a new code is sent automatically.
The portal session (refresh token and Azure AD B2C cookies) is kept in Home Assistant storage. On restart, the integration tries a silent login before asking for credentials again. The session obtained during initial setup is reused: no second code is requested right after adding the integration.

No code requested in the background

Automatic logins stop at the verification step: no code is sent and the login is not retried in a loop. Home Assistant shows Reauthentication required in Settings > Devices & services. Click Reauthenticate to enter a new code.

Session valid for about 24 h

The Hydro-Québec portal keeps the session for about 24 hours. During that time, restarts require neither a password nor a code. After that, a new login with an email code is mandatory: expect to reauthenticate roughly once a day.