Aquamedic 🌊

Part of the ReefTech Project Ecosystem

Supported Languages:

Control your Aqua Medic pumps from Home Assistant via the Gizwits cloud API.

---

🎬 Demo videos

Aqua Medic demo

Related projects

The ReefTech projects fit together: the integrations bring your equipment into Home Assistant, the card displays and drives it, and the backup keeps it running through an outage. Each one also works on its own.

	Project	What it does	Works with
	🐠 ha-reefbeat-component	Red Sea ReefBeat devices, controlled locally with no cloud: ReefATO+, ReefControl, ReefControl-Power, ReefDose, ReefLed, ReefMat, ReefRun and ReefWave. alert blueprint for abnormal modes, calibrations and low battery.	ha-reef-card
	🌊 ha-aquamedic-component (this repository)	Aqua Medic pumps through the Gizwits cloud API: EcoDrift and SmartDrift wavemakers, DC Runner return and skimmer pumps.	ha-reef-card
	🐙 ha-reef-maintenance-component	Cleaning and wear tracking for the equipment Home Assistant cannot talk to: flow pumps, return pumps, skimmers, media reactors, anything you service by hand.	ha-reef-card
	🪸 ha-reef-card	Interactive graphical view of each device on your dashboard, and the only way to edit advanced schedules. Reads the three integrations above through the shared reef_role contract, with no card-side configuration. Also draws the power flows of reefbeatEnergyBackup. Its aquarium card brings your tank to life with ha-reeftank-component.	all three integrations, and ha-reeftank-component for the aquarium
	🐟 ha-reeftank-component	A living picture of your tank on the dashboard: your photo, lit by your real lamps, with animated fish and corals, and your devices and entities on it. Stores the aquariums and their livestock, records the feedings.	ha-reef-card
	🐡 reeftank-catalog	Fish, corals and textures of the aquarium card, downloaded and kept up to date by ha-reeftank-component.	ha-reeftank-component
	🐬 ha-reef-blueprints	Notification blueprints shared by the whole ecosystem: overdue maintenance found through the reef_role contract, and devices that went unreachable. Eight languages.	all three integrations
	⚡ reefbeatEnergyBackup	Battery backup for power outages. A 24V LiFePO₄ pack driven by a Raspberry Pi, with pump speed degraded progressively according to the state of charge.	standalone, or alongside ha-reefbeat-component and ha-reef-card

All of them are documented together on the ReefTech project page.

Supported Devices

Your device is not supported? Please contact me.

✅ Supported  |  🚧 In progress  |  🧪 Untested (may work)  |  ❌ Not yet supported

Device		Internal Name	Product Key	Status
Aqua Medic EcoDrift / SmartDrift x.1 / x.3		Current_Pump	63632f4902094055ab3fd994c0d612fa	✅
Aqua Medic DC Runner series — return pump		DC_Runner	00276aa006684c05805c297f60058c3d	✅
Aqua Medic DC Runner series — skimmer pump		DC_Runner	00276aa006684c05805c297f60058c3d	✅
Aqua Medic DC Runner (legacy / speculative)		DC_Runner	8879684725d14066922374e50889f893	🧪

The DC Runner return pump and skimmer pump share the same firmware and Gizwits product key. They expose an identical datapoint set (verified against two independent real-device captures) and are handled by the same code path — the two rows above are the same device with different pump heads. In Home Assistant they both appear as model DC Runner; use the device alias to distinguish which pump is which.

The 8879684725… product key is a speculative simpler variant that has not (yet) been observed on real hardware; the code path is kept in place in case a device advertising this key shows up.

All these devices use the Gizwits IoT platform (same backend as the official Aqua Medic app). Support for additional devices may be added in future releases.

---

Installation

Via HACS

The integration is now officially in HACS. Simply search for Aqua Medic in the Integrations tab and install it.

Or use the direct installation button:

Then restart Home Assistant.

---

Entities

EcoDrift / SmartDrift

Switches

Entity	Description
Power	Main on/off
Wave type	Pulse mode (off) / Tide mode (on)
Feeding mode	Activates feeding pause
Timer	Enables program mode
0-10V control mode	When on, disables the Flow rate slider (pump driven by external 0-10V signal)

Selects

Entity	Options
Wave mode	Classic wave · Sine wave · Random wave · Constant flow
Linkage	Independent · Master · Slave

Numbers

Entity	Range	Description
Flow rate	0–100 %	Motor flow (disabled in 0-10V mode)
Frequency	0–100 %	Wave frequency
Feeding duration	1–60 min	Duration of feeding pause

Binary Sensors (diagnostic)

Entity	Description
Overcurrent fault	Motor overcurrent / short circuit
Overvoltage fault	Motor overvoltage
Overtemperature fault	Motor temperature too high
Undervoltage fault	Motor undervoltage
Locked rotor fault	Motor jammed / blocked
No load fault	Pump running dry
UART communication fault	Module ↔ mainboard communication error

Button (diagnostic)

Entity	Description
Refresh	Forces an immediate data refresh without waiting for the next poll interval

DC Runner series (return pump and skimmer pump)

✅ Confirmed against two real device captures (return pump + skimmer). The two variants share the same firmware — Home Assistant displays them both as model DC Runner; the exact pump role (return / skimmer) is only distinguishable from your device alias.

A legacy simpler variant with product key 8879684725… (single Flow control, no scheduler) is also handled by the integration but has not been confirmed on real hardware.

Switches

Entity	Description
Power	Main on/off
Feeding mode	Activates feeding pause
Timer	Enables the timer / schedule program
0-10V control mode	When on, disables the speed slider (pump driven by external 0-10V signal)

Selects

Entity	Options
Timer mode	Stop · Auto · Feeding

Numbers

Entity	Range	Description
Motor speed	30–100 %	Pump speed (minimum 30 % — below this the motor may stall; disabled in 0-10V mode)
Feeding duration	1–60 min	Duration of the feeding pause
Timer speed	0–100 %	Speed used by the scheduled program
Timer feeding time	1–60 min	Feeding duration used by the scheduled program

Binary Sensors (diagnostic)

Entity	Description
Overcurrent fault	Motor overcurrent / short circuit
Overvoltage fault	Motor overvoltage
Overtemperature fault	Motor temperature too high
Undervoltage fault	Motor undervoltage
Locked rotor fault	Motor jammed / blocked
No load fault	Pump running dry
UART communication fault	Module ↔ mainboard communication error

Button (diagnostic)

Entity	Description
Refresh	Forces an immediate data refresh

About 0-10V control: every DC Runner controller has a physical 0-10V input for an external aquarium controller (Apex, GHL, …). It is a hardware port, not a cloud value, so it does not appear as a device attribute — the 0-10V control mode switch is a local Home Assistant flag that disables the speed slider while the pump is driven externally. Per Aqua Medic's manual, in 0-10V mode the pump must run at ≥ 60 %.

---

Time-slot schedule

Every pump with a scheduler (EcoDrift / SmartDrift and the DC Runner series) stores a program of up to 48 time slots. The pump follows it while its Timer switch is on.

Sensor

Entity	Description
Schedule	Number of programmed slots. The program itself is in the schedule attribute.

Each entry of schedule describes one slot, times being minutes since midnight:

- slot: 0
  start: 480        # 08:00
  end: 720          # 12:00
  mode: auto        # DC Runner series: stop · auto · feeding
  value: 60         # speed in %, or pause in minutes when feeding

A SmartDrift slot uses the wave modes (stop, classic_wave, sine_wave, random_wave, constant_flow, feeding) and also carries frequency (%) and tide (true for tide, false for pulse).

Service aquamedic.set_schedule

Replaces the whole program of one or several pumps. Target the Schedule sensor (entity_id) or the device (device_id).

action: aquamedic.set_schedule
data:
  entity_id: sensor.skimmer_schedule
  slots:
    - { start: "08:00", end: "12:00", mode: auto, value: 60 }
    - { start: "12:00", end: "12:15", mode: feeding, value: 10 }
    - { start: "22:00", end: "23:59", mode: stop }

• start / end accept "HH:MM" or minutes since midnight; slots are stored in chronological order and every unused slot is cleared, so an empty list erases the program.
• Slots must not overlap and must not cross midnight (write a night window as two slots).
• On the DC Runner series a running slot must be at 30 % or more, like the speed slider.
• Only the slots that actually change are sent to the cloud.

The slot datapoints are documented by the device schema but their behaviour could only be validated against the local simulator: check the first program you write in the Aqua Medic app.

---

With ha-reef-card

ha-reef-card shows each pump on your dashboard: its speed on the picture, the faults it raises, the water it moves and its time-slot program, which is edited from the card (through aquamedic.set_schedule). A DC Runner is shown as a return pump or as a skimmer pump, following the role declared in the integration. See the Aqua Medic page of the card.

Maintenance

The integration tracks the cleaning and wear tasks of each pump. Every task comes with three entities: a button to record that the job is done, a slider to adjust the interval, and a switch to mute its alerts. Nothing is sent to the cloud — the state is stored locally, per config entry.

The DC Runner return pump and the DC Skimmer share the same firmware and the same Gizwits product key, so the API cannot tell them apart. Declare it once with the Pump role select: the task list follows (the integration reloads itself to apply it). As long as the role is Not set, a DC Runner carries no maintenance task. EcoDrift / SmartDrift pumps never ask.

Pump	Task	Default	Range
EcoDrift / SmartDrift	Clean impeller and filter basket	2	1–3
EcoDrift / SmartDrift	Descale pump	6	3–9
EcoDrift / SmartDrift	Replace impeller and bearings	18	12–24
DC Runner (return)	Clean suction strainer	6 w	3–9 w
DC Runner (return)	Clean impeller and pump chamber	4	2–6
DC Runner (return)	Replace impeller and bearings	18	12–24
DC Runner (skimmer)	Clean collection cup	2 w	1–4 w
DC Runner (skimmer)	Clean venturi and air line	4 w	2–8 w
DC Runner (skimmer)	Clean needle wheel	2	1–4
DC Runner (skimmer)	Descale skimmer body	6	3–12
DC Runner (skimmer)	Replace needle wheel and bearings	18	12–24

Values in months unless followed by w (weeks). Aqua Medic publishes no numeric interval, so these defaults come from reef keeping practice — every one of them is adjustable per pump.

Notifications

The integration never notifies by itself, on purpose. The Aqua Medic watch blueprint shipped with the repository does it, and also covers hardware faults and offline pumps. Click the button below and confirm the import in Home Assistant:

A French version is available as aquamedic_alerts.fr.yaml.

Tasks are also picked up by the maintenance view of ha-reef-card, next to the Red Sea ones: both integrations publish the same reef_role entity contract.

Configuration

Go to Settings → Devices & Services → Add Integration → Aqua Medic.

Field	Description
E-mail	Your Aqua Medic app account e-mail
Password	Your Aqua Medic app password
Gizwits server	Region server — select Europe for EU users
Refresh interval	How often device state is polled (5–300 s, default 30 s)

The correct server is pre-selected automatically based on your Home Assistant language.

After setup, options (refresh interval) can be changed via Settings → Devices & Services → Aqua Medic → Configure.

---

Development

Local simulator

A Gizwits cloud simulator (scripts/gizwits_simulator.py) lets you test the integration without real hardware or cloud access. It is configured via scripts/gizwits_sim_config.json:

Key	Description
username / password	Credentials the integration must use to log in
virtual_ip	IP the simulator binds to (127.0.0.1 skips virtual-IP setup)
interface	Network interface for the virtual IP (optional; if omitted, the default-route interface is auto-detected, falling back to eth0; can be overridden with -i/--interface)
port	Listening port (default 8080)
devices	List of { "type": ..., "count": N }; available types: smartdrift, dc_runner (legacy speculative variant), dc_runner_return (DC Runner series return pump), dc_skimmer (DC Runner series skimmer pump — same firmware as dc_runner_return)

Run it with sudo python3 scripts/gizwits_simulator.py (root is required to add the virtual IP).

To make the Simulator region appear in the config flow, create the local flag file (git-ignored, never commit it):

cp custom_components/aquamedic/simulator_enabled.example custom_components/aquamedic/.simulator_enabled

Restart Home Assistant, add the integration and select Simulator; you will then be asked for the simulator host URL (default http://localhost:8080) and the credentials from the config file.

---

License

MIT – see LICENSE.

---