This plugin adds explicitly configured EcoFlow WAVE 3 units to Apple Home and other compatible Matter controllers through Homebridge. Each unit appears as a Matter Room Air Conditioner with controls for power, temperature, operating mode, and fan speed.
- Homebridge 2.2.1 or newer
- Node.js 24 or newer
- An EcoFlow account with each WAVE 3 already added in the EcoFlow app
- The serial number of each WAVE 3 you want to add
- An internet connection
This is a Matter-only Homebridge plugin. It does not publish a legacy HAP accessory.
Important
The plugin uses EcoFlow's private, app-facing cloud service rather than local control. It requires your EcoFlow account credentials and may need updates if EcoFlow changes that service.
The plugin is not published to npm yet. Install the current development build from GitHub:
npm install -g github:jmissig/homebridge-ecoflow-wave3Run this with the same account and npm installation used by Homebridge. npm builds the plugin from source and installs a packaged copy, not a development symlink. Run the same command again to update to the latest default-branch code.
To install local checkout changes with full verification, use the helper:
./npm-install-dev-build.shDo not use npm install -g .; installing a checkout directory creates a symlink
that can load a different Matter.js runtime from Homebridge.
Restart the EcoFlow child bridge after installing or updating.
In Homebridge UI, add the EcoFlow WAVE 3 platform and enter:
- Your EcoFlow account email and password.
- The API region used by your account.
- A display name and serial number for each WAVE 3.
Each configured unit becomes its own Matter air-conditioner accessory.
If you edit config.json directly, use this shape:
{
"platform": "EcoFlowWave3",
"name": "EcoFlow WAVE 3",
"email": "you@example.com",
"password": "your-ecoflow-password",
"apiHost": "api-a.ecoflow.com",
"devices": [
{
"name": "Bedroom WAVE 3",
"serialNumber": "YOUR_WAVE_3_SERIAL"
}
]
}Keep your Homebridge configuration private: it contains your EcoFlow account password.
The advanced optional freshnessTimeoutMinutes setting controls how long live
EcoFlow state remains current without supporting telemetry. It defaults to 5
minutes and accepts whole values from 1 through 60. Evidence categories are
tracked independently, so an electrical-power update does not keep climate
control authority alive.
api.ecoflow.com— Globalapi-a.ecoflow.com— Americasapi-e.ecoflow.com— Europe
Choose the same region your EcoFlow account uses. Authentication usually fails if the region is wrong.
If you power down a WAVE for months at a time, enable Seasonal Storage for
that unit in Homebridge UI, save, and restart the EcoFlow child bridge. In JSON,
set "seasonalStorage": true inside that unit's entry in devices.
The plugin keeps the same paired accessory and presents it as Off while it is offline. Room temperature, humidity, and power readings become unavailable, not frozen or zero. All controls are blocked, and commands are never saved for later. Enabling storage does not turn off the physical appliance.
If the WAVE comes online, its actual state is displayed read-only. Storage
does not end automatically. Uncheck the option (or set it to false), save,
and restart the child bridge to restore normal operation. Controls also need
fresh device state; disabling storage while offline restores No Response.
No removal, re-pairing, or accessory-cache reset is needed.
This is an opt-in presentation workaround: the plugin reports the stored accessory as reachable even though the appliance is offline. Homebridge itself must remain running. Apple Home may still show a transient error if you try a blocked control. The Off/unknown-readings presentation is covered by Matter runtime tests; its exact Apple Home tile and summary behavior still needs household acceptance testing.
Run the plugin as a Homebridge platform child bridge with Matter enabled and HAP disabled:
- Enable Child Bridge for the EcoFlow WAVE 3 platform.
- Open the child bridge's settings.
- Enable Matter, then disable HAP. Homebridge requires at least one protocol to remain enabled while editing.
- Save and restart the EcoFlow child bridge.
- Open its Matter pairing screen.
- Scan the QR code in Apple Home or another compatible Matter controller.
You pair the child bridge once. Every configured WAVE 3 then appears as a separate air-conditioner accessory.
Homebridge's Matter implementation is uncertified, so Apple Home may show an uncertified-accessory warning during pairing. Matter accessories also do not appear in Homebridge UI's legacy HAP accessory screen.
The equivalent child-bridge protocol configuration looks like this:
"_bridge": {
"username": "AA:BB:CC:DD:EE:FF",
"port": 30141,
"hap": { "enabled": false },
"matter": {
"enabled": true,
"name": "EcoFlow WAVE 3"
}
}Keep the username and port generated by Homebridge; the values above are
placeholders.
- Power on and off
- Cooling and heating modes
- Target temperature
- Five fan-speed steps
- Current room/input-air temperature reported by the WAVE 3 ambient sensor
- Ambient humidity
- Current AC active power through Matter's standard Electrical Power Measurement cluster
- Celsius/Fahrenheit display preference through Matter's standard thermostat UI configuration
- Live changes made in the official EcoFlow app
- Device reachability and firmware revision in Matter metadata
The WAVE 3 stores separate temperature, range, fan, and preset values for its operating modes. The plugin preserves those saved profiles when switching modes.
The plugin maps Fan Only, Dry, and Sleep/Night to standard Matter thermostat system modes. As of the iOS 27 beta, neither Apple Home nor Eve presents those values as selectable modes for this accessory, so their controller and real-device behavior remains unverified.
Sleep/Night means the WAVE 3's quiet operating preset; it is not a sleep timer. Other Matter controllers may present these standard modes differently.
Automatic heat/cool is temporarily not advertised through Matter. In live A/B
testing, Apple Home correctly wrote SystemMode=Auto to a plain Matter
Thermostat but wrote SystemMode=Cool when Auto was selected on the production
Room Air Conditioner. The plugin retains the WAVE's real Auto profile
internally and presents app-initiated Auto as Cooling at its upper threshold.
This preserves the Room Air Conditioner's integrated fan controls while the
Apple Home interoperability bug remains unresolved.
Apple Home also does not currently display the published firmware revision. Its UI may hide the standard Celsius/Fahrenheit preference even though the attribute remains available to Matter controllers.
Eco, Boost, drainage, battery telemetry, cumulative energy, timers, display brightness, beeper controls, Pet Care, and charge limits are not currently exposed.
Allow up to about a minute after startup for the WAVE 3 to send authoritative state. The last confirmed state may remain visible during that interval, but the plugin will not send commands until the current cloud session has fresh device state.
See Troubleshooting and recovery for help with:
- pairing and re-pairing
- No Response after startup
- EcoFlow authentication and API regions
- command confirmation messages
- child-bridge cache and recovery
- collecting safe diagnostic logs
For deeper setup and validation guidance, see the commissioning runbook.
Enable Debug Mode in the EcoFlow child bridge's settings to show MQTT routing, decoded state summaries, command confirmation, and reconnect details without enabling verbose logging for the rest of Homebridge.
Credentials, account identifiers, serial numbers, full MQTT topics, and raw payload bytes are redacted from normal and debug logs.
Original work is licensed under the BSD 3-Clause License.
Protocol-derived files retain their Apache 2.0 licensing and attribution; see
THIRD_PARTY_NOTICES.md.
Made with Codex and OpenClaw.