homebridge-hilo-challenge

A Homebridge plugin that exposes Hilo (Hydro-Québec) demand response challenge phases as HomeKit contact sensors.

Two sensors are created:

• Hilo Preheat — opens during the pre-heat phase
• Hilo Reduction — opens during the reduction (peak demand) phase

When a sensor opens, it can trigger HomeKit automations — for example, automatically disabling EV chargers during a reduction event.

Seasonal operation: The plugin only polls the Hilo API during challenge season (December 1 – March 31). Outside of that window it makes no API calls and the sensors remain inactive.

Requirements

• A Hilo account with at least one enrolled device (thermostat or water heater)
• The homebridge-hilo plugin already installed and working (this plugin reuses the same refresh token)
• Homebridge v1.6.0 or later
• Node.js v20 or later

Installation

Search for Hilo Challenge in the Homebridge UI, or install manually:

npm install -g homebridge-hilo-challenge

Configuration

Configure via the Homebridge UI, or add to your config.json:

{
  "platform": "HiloChallenge",
  "name": "Hilo Challenge",
  "refreshToken": "your-hilo-refresh-token",
  "locationId": "urn:hilo:crm:XXXXX-XXXXX:0",
  "pollInterval": 60
}

| Field | Required | Default | Description | |-------|----------|---------|-------------| | refreshToken | ✅ | — | Your Hilo refresh token — copy from your homebridge-hilo plugin config | | locationId | ❌ | auto | Your Hilo location URN. Found in homebridge-hilo logs: Subscribed to updates for location urn:hilo:crm:... | | pollInterval | ❌ | 60 | How often (in seconds) to poll during challenge season (30–300) |

Getting Your Refresh Token

1. Open your Homebridge config.json
2. Find the homebridge-hilo platform entry
3. Copy the refreshToken value into this plugin's config

Finding Your Location ID

If you leave locationId blank, the plugin will attempt to auto-discover it. If auto-discovery fails, you can find your location ID in the homebridge-hilo logs — look for a line like:

Subscribed to updates for location urn:hilo:crm:12345-abcde:0

Copy that full URN into the locationId field.

How It Works

During challenge season (December–March), the plugin polls the Hilo GraphQL API every pollInterval seconds. It checks the gDState field on enrolled devices (thermostats, water heaters) to determine the current phase:

| gDState value | Sensor state | |---|---| | PRE_HEAT | Hilo Preheat opens | | ACTIVE | Hilo Reduction opens | | RECOVERY | both sensors closed | | OFF / absent | both sensors closed |

Automations

Use the Hilo Reduction sensor to automatically manage energy-intensive devices during peak demand:

• When Hilo Reduction sensor opens → Turn off EV charger(s), electric heaters, etc.
• When Hilo Reduction sensor closes → Turn on EV charger(s)

Pairs well with homebridge-grizzl-e for automatic EV charger control.

Issues & Support

Please open an issue on GitHub.