← Guides

Home Assistant: Aquarium in the Smart Home, Logic in the Controller

Oquari integrates natively with Home Assistant: you enable one option in the panel, and aquarium entities appear in HA automatically—no configuration coding, no cloud, no third-party plugins. This guide shows how to set it up, what exactly you will see in HA, and where the boundary lies: HA supervises and adds convenience, but critical logic remains in the controller.

What is Home Assistant (in two paragraphs)

Home Assistant is the world’s most popular open-source smart home platform: free software that you install locally (on a Raspberry Pi, mini-PC, or NAS) to connect devices from different manufacturers into one system—with dashboards, historical graphs, automations, and push notifications to your phone.

For an aquarist, HA means one place where the aquarium meets the rest of the home: pH graphs next to living room temperature, a leak alert on the same phone as the home alarm, and a “feeding” button on the kitchen tablet.

Step 1: MQTT Broker

Oquari communicates with HA via MQTT—a lightweight smart home communication protocol. You need a broker (message intermediary) on your local network; in practice, this is a single installation:

  1. In Home Assistant: Settings → Add-ons → Add-on Store → Mosquitto broker → install and start.
  2. Create a user for the controller in HA (e.g., oquari)—the Mosquitto add-on will use HA accounts.
  3. Enable the MQTT integration in HA (it usually suggests itself after the broker starts).

Step 2: Enabling in the Oquari Panel

  1. Open the controller panel (oquari-XXXX.local) → Home Assistant tab.
  2. Enable integration and provide: broker address (mqtt://your-HA-IP:1883), username, and password for the MQTT user.
  3. Save—the controller will connect to the broker and announce its entities (MQTT Discovery).

Shortly after, in HA under Settings → Devices & Services → MQTT, an “Oquari” device will appear with a full set of entities.

The connection to the broker is unencrypted (local network). Use this integration only on your own LAN and assign a separate password to the MQTT user. This is the standard model for local smart home devices.

What Will Appear in HA

Entities correspond to your configuration—the controller reports them automatically, with correct units and classes (so HA immediately draws graphs and understands what is temperature vs. energy):

  • Sensors: temperature, pH, ORP, salinity, levels, flow rate (L/min), power and energy of each socket, counters for dosed fluids,
  • Binary Sensors: level sensors, flood sensors, alarms (overheating, ATO limit, empty bottle), “dosing in progress” status,
  • Switches and Lights: measured sockets as switch, lighting channels as light,
  • Numbers and Selectors: dosing doses as number, operating modes as select, feeding as button.

Plus an availability entity: when the controller disappears from the network, HA immediately marks its entities as unavailable—which itself is an excellent alarm (“aquarium offline”).

Example: Feeding Pauses Circulation for 5 Minutes

A classic convenience—an HA button that stops the circulation pump during feeding, with HA automatically restoring it:

alias: Feeding — Circulation Pause
trigger:
  - platform: state
    entity_id: input_button.feeding
action:
  - service: switch.turn_off
    target:
      entity_id: switch.oquari_circulation
  - delay: "00:05:00"
  - service: switch.turn_on
    target:
      entity_id: switch.oquari_circulation

In practice, you don’t even need to write this—Oquari has a built-in feeding mode (button.oquari_feeding) that automatically pauses pumps and restores them. But the example well illustrates the principle: Oquari entities behave like any others in HA.

Other useful automations: push notification for temperature or leak alarms, reminder to change the bottle when fluid usage counter exceeds bottle capacity, daily pH graph on dashboard next to CO₂ window.

Division Rule: HA Supervises, Controller Protects

The most important paragraph of this guide. Critical logic—heating hysteresis, emergency cut-offs, ATO limits, water changes, CO₂ window, dosing—executes in the controller, locally. HA is the supervision and convenience layer: dashboards, history, notifications, scenes like feeding.

This division is not accidental but a safety foundation:

  • When Wi-Fi, router, HA server, or internet fails—heating still maintains temperature, ATO still guards limits, CO₂ still closes outside light window. The tank won’t notice the network failure.
  • HA automation can toggle sockets, but cannot bypass the controller’s safety layer: overrides (overheating cut-off, flood lockout) are superior even to MQTT commands.

Do not move protective logic to HA, even if you can write it there. An automation “turn off heater at 27.5 °C” in HA ceases to exist with the HA server. The same rule in the controller always works. Use HA for what it excels at: seeing, knowing, and simplifying.

Najczęstsze pytania

Can I control Oquari from outside my home network?

No. Oquari is designed for local operation. All critical logic runs on the device itself, not in the cloud. While Home Assistant can be accessed remotely if configured by you, Oquari does not provide its own cloud service or remote access features.

What happens if my internet connection drops?

Nothing changes for your aquarium. Since all automation and safety logic reside in the Oquari controller, it continues to regulate temperature, water changes, CO2, and dosing without interruption. Home Assistant may lose connection, but the tank remains fully managed.

Do I need programming skills to use Oquari with Home Assistant?

No. Oquari uses presets instead of code. You set values like temperatures or times, not programs. The native MQTT Discovery means entities appear automatically in Home Assistant without manual configuration files, making it accessible even for users who prefer a no-code approach.

Is the system open to third-party integrations?

Yes. Oquari communicates via standard MQTT protocol and is designed to integrate seamlessly with Home Assistant. Documentation for connections and integrations is publicly available, allowing you to build custom automations or dashboards without restrictive ecosystems.

How does Oquari handle safety compared to cloud-based controllers?

Oquari prioritizes local safety. Critical functions like emergency heating cut-offs and flood detection are processed on the device hardware. This ensures that even if your network fails, your aquarium remains protected, unlike systems that rely on cloud servers for basic operational logic.

All guides Presets Editions