homebridge-hypervolt-charger

A Homebridge plugin that exposes a Hypervolt Home 3 / Home 3 Pro EV charger to Apple HomeKit.

HomeKit has no native EV-charger accessory, so the charger is represented as up to three tiles:

• An Outlet — On toggles charging on/off. On is mapped to the charger's release state (whether charging is enabled), not the moment-to-moment "current flowing" flag, so it stays stable for HomeKit automations. When no car is connected the outlet shows Off and refuses to turn On (you can't charge nothing).
• A Lock (optional) — the charger's cable lock.
• A Charging sensor (optional) — an occupancy sensor that is Detected only while current is actually flowing.

Together the outlet and the Charging sensor let you read every state in the stock Home app:

| Outlet | Charging sensor | Meaning | |---|---|---| | On | Detected | Charging | | On | Clear | Ready — waiting for car (e.g. the car is full) | | Off | Clear | No car connected, or you stopped it |

The Hypervolt API (like the Hypervolt app) can't distinguish "car full" from "plugged in and waiting" — both appear as ready, waiting for car.

Automation example

The main use case this was built for:

When the charger's Outlet turns On, turn it Off after 3 hours.

Create this in the Apple Home app: add an automation triggered by "Hypervolt turns On", add the Hypervolt Outlet as the accessory to control, set it to Off, and set a 3-hour turn-off delay.

Requirements

• A Hypervolt V3 charger (Home 3 / Home 3 Pro). V2 chargers are not supported.
• Your Hypervolt app account email and password.
• Node 18.17+, Homebridge 1.6+.

Install

npm install -g homebridge-hypervolt-charger

Or search for Hypervolt in the Homebridge UI.

Configuration

Via the Homebridge UI, or in config.json:

{
  "platforms": [
    {
      "platform": "HypervoltCharger",
      "name": "Hypervolt",
      "email": "[email protected]",
      "password": "your-hypervolt-password",
      "exposeLock": true
    }
  ]
}

| Field | Required | Description | |---|---|---| | email | yes | Hypervolt account email. | | password | yes | Hypervolt account password (stored in plaintext in config.json). | | chargerId | no | Only needed if your account has multiple chargers and you want a specific one. Leave blank to auto-discover. | | exposeLock | no | Expose the cable lock as a HomeKit Lock (default true). | | exposeChargingSensor | no | Expose a read-only "Charging" occupancy sensor (default true). |

How it works

• Authenticates via OAuth2 (Keycloak) using your Hypervolt account.
• Opens the Hypervolt /sync WebSocket and receives live state (charging, lock, current) via push, with a light 30-second poll for session data.
• Reconnects automatically with exponential backoff and refreshes the access token before it expires.

Development

npm install
npm run build
npm run lint

Test connectivity against your real charger without running Homebridge:

npm run build
HYPERVOLT_EMAIL='[email protected]' HYPERVOLT_PASSWORD='secret' node scripts/test-connect.mjs

This lists your chargers, connects, prints live state for ~30 seconds, and exits. It never sends commands.

Credits

API protocol reverse-engineered from the excellent home-assistant-hypervolt-charger integration by @gndean.