How to Automate Your Aquarium with OpenClaw on Raspberry Pi

Poor water quality is the leading cause of fish mortality in home aquariums. Temperature swings of just 2-3 degrees Celsius stress tropical species. pH shifts outside a species' tolerance range suppress immune function within hours. These are not edge cases. They are the daily reality of fishkeeping, and they are why the global aquarium market, valued at over $4 billion annually, keeps growing alongside demand for better automation tools.

Most Raspberry Pi aquarium controller projects follow the same pattern: wire a DS18B20 temperature sensor and a pH probe to the Pi, write a Python script with hardcoded thresholds, and trigger relays when readings cross a boundary. If temperature exceeds 26°C, turn off the heater. If pH drops below 6.8, activate the dosing pump. These scripts work for a single-species tank with stable conditions.

They break down in real aquariums. A community tank with neon tetras (preferred range 20-26°C, pH 5.0-7.0) and cherry shrimp (preferred range 20-28°C, pH 6.5-8.0) needs overlapping parameter windows that shift based on breeding cycles, feeding schedules, and seasonal ambient temperature changes. A fixed threshold script cannot reason about these tradeoffs. It cannot look at the current pH trend and decide whether the shift is caused by overfeeding (needs a water change, not chemicals) or CO2 injection (normal and expected). It cannot recognize that a slow temperature rise over three days is ambient heat, not a heater malfunction.

OpenClaw adds a reasoning layer to the same hardware. Running on the Raspberry Pi alongside your sensor polling scripts, it receives the same readings a threshold script would, but it processes them through an LLM that understands species requirements, recognizes patterns across time, and makes decisions that account for multiple interacting variables at once.

The open-source reef-pi project has proven that Raspberry Pi hardware is capable of running sophisticated aquarium controllers. This guide builds on that foundation by replacing the fixed-rule decision engine with an AI agent that adapts to your specific tank.

The sensor stack for an aquarium controller uses the same I2C and analog interfaces documented in the OpenClaw Pi tutorial. Aquarium sensors (pH probes, temperature sensors, TDS meters) connect through the same Adafruit Blinka library that handles environmental monitoring in other OpenClaw projects.

Raspberry Pi (4 or 5, 4GB minimum, 8GB recommended): OpenClaw's minimum requirements are 1GB RAM and 1 CPU core, but running the agent alongside sensor polling, relay control, and optional local LLM inference benefits from the extra headroom. A Pi 5 with 8GB gives you room to run Ollama with a 7B parameter model for fully local, offline operation.

DS18B20 waterproof temperature sensor ($3-5): This is the standard for aquarium temperature monitoring. It uses the 1-Wire protocol on GPIO 4 with a 4.7kΩ pull-up resistor between the data line and 3.3V. The waterproof probe version comes with a stainless steel tip rated for permanent submersion. Accuracy is ±0.5°C, which is sufficient for most species. For reef tanks where 0.1°C precision matters, consider a PT100 RTD probe with an MAX31865 amplifier board.

pH sensor module ($15-40): Atlas Scientific makes the reference-grade EZO pH circuit that communicates over I2C, but budget-friendly options like the DFRobot Gravity Analog pH Sensor Kit work well for freshwater tanks. Analog pH sensors need an ADC (the ADS1115 at $3-5 connects via I2C: SDA to GPIO 2, SCL to GPIO 3). The pH probe itself sits in the tank water. Calibrate with pH 4.0 and pH 7.0 buffer solutions before first use, and recalibrate monthly.

Water level sensor ($2-5): A float switch is the simplest option for detecting evaporation. Mount it at your target water line. When the level drops, the float switch closes a circuit the Pi reads on any GPIO pin. For more precise level tracking, an ultrasonic sensor (HC-SR04) mounted above the tank measures the distance to the water surface and calculates volume.

TDS/EC sensor (optional, $10-15): Total Dissolved Solids sensors measure mineral concentration, useful for tracking fertilizer levels in planted tanks or salt content in brackish setups. Like pH, these typically output analog voltage and need the ADS1115 ADC.

Relay module ($3-8): A 4-channel relay board handles heater, lights, dosing pump, and auto-top-off pump independently. Use optically isolated relays to protect the Pi's GPIO from voltage spikes. Each channel connects to a separate GPIO pin.

Dosing pump (optional, $15-30): Peristaltic pumps are ideal for precise chemical dosing. They self-prime, handle corrosive liquids (like pH buffer), and deliver repeatable volumes based on runtime duration. A small peristaltic pump connected through a relay can dose fractions of a milliliter per second.

Total hardware cost: $50-120 beyond the Pi itself, depending on sensor quality and how many parameters you monitor.

Start with Raspberry Pi OS Lite (64-bit) for a headless setup that keeps system resources free for OpenClaw. The official OpenClaw installer handles dependencies and service configuration.

Adafruit Blinka setup: OpenClaw uses the Adafruit Blinka library to give Python access to GPIO pins through a CircuitPython compatibility layer. This means you can use the same sensor libraries on a Pi that you would use on a microcontroller. Install the base libraries, then add sensor-specific packages for your hardware.

Sensor reading scripts: Each sensor gets its own Python script that OpenClaw calls as a system command. A read_temperature.py script reads the DS18B20 over the 1-Wire bus and returns the current temperature in Celsius. A read_ph.py script queries the ADS1115 for the pH probe's voltage and converts it to a pH value using your calibration curve. A read_water_level.py script checks the float switch GPIO state or reads the ultrasonic distance sensor.

The key design principle: keep hardware interaction in dedicated scripts, and let the agent handle decisions. OpenClaw never touches GPIO registers directly. It runs read_temperature.py and gets back "24.8°C." It runs set_heater.py on and the relay activates. The agent focuses on reasoning, the scripts handle the electrical interface.

LLM provider selection: OpenClaw supports Claude, GPT-4, Gemini, and local models through Ollama. For an aquarium controller that runs 24/7, consider the cost implications. Cloud APIs (Claude, GPT-4) provide the strongest reasoning but accumulate API charges over months of continuous polling. A local 7B model via Ollama on a Pi 5 with 8GB RAM runs inference without internet or per-query costs, though its reasoning about complex multi-parameter tradeoffs will be less sophisticated. A hybrid approach works well: use a local model for routine threshold checks and escalate ambiguous situations to a cloud API.

Species profile configuration: Before the agent can make species-aware decisions, it needs a reference file describing each species in your tank. This is a plain text or YAML file listing preferred temperature range, pH range, hardness preferences, lighting needs, and any special notes (breeding triggers, sensitivity to chemicals). The agent loads this profile as context for every decision cycle.

Here is an example species profile the agent might reference:

Species: Neon Tetra (Paracheirodon innesi)
Temperature: 20-26°C (optimal 24°C)
pH: 5.0-7.0 (optimal 6.0-6.5)
Hardness: 2-10 dGH
Lighting: moderate, prefers shaded areas
Notes: sensitive to pH swings greater than 0.5 per day

The agent uses these profiles to find the safe overlap zone when multiple species share a tank, and flags conflicts when species requirements are incompatible.

Store Your Aquarium Data Where Any Agent Can Query It

Upload sensor logs, water parameter trends, and maintenance records to a Fastio workspace. Intelligence Mode indexes everything for semantic search, so you can ask questions about your tank's history without parsing raw CSV files. generous storage, no credit card required. Built for openclaw raspberry aquarium fish tank controller agent workflows.

Start 14-Day Trial

This is where OpenClaw separates an AI-driven aquarium controller from a threshold script. The agent does not just compare a reading against a number. It considers the reading in context: what species live in the tank, what time of day it is, what the trend looks like over the past 6 hours, and whether a parameter shift is caused by something that needs correction or something that is working as intended.

Temperature management with seasonal awareness: A fixed threshold heater controller turns on at 23°C and off at 26°C. The agent does more. In summer, when ambient room temperature climbs, it recognizes that the heater is not the issue and does not keep cycling it. Instead, it might suggest adding a fan to increase evaporative cooling, or it adjusts the lighting schedule to reduce heat output from the tank light during the hottest part of the day. In winter, it accounts for overnight temperature drops and pre-heats the tank before dawn rather than reacting after the temperature has already fallen.

pH trend analysis instead of point-in-time reactions: A threshold script sees pH 6.4 and doses alkaline buffer. The agent checks whether pH has been declining steadily (suggesting biological acidification from waste buildup, which means a water change is needed, not more chemicals) or whether it dropped suddenly after a CO2 injection cycle (normal and expected in planted tanks). Dosing buffer into a tank that needs a water change masks the real problem and can harm fish with sudden mineral content changes.

Lighting schedules aligned to species behavior: Many freshwater species respond to photoperiod changes. Gradually dimming lights over 30 minutes rather than switching them off instantly reduces stress. The agent can manage a dawn-dusk lighting cycle through PWM-controlled LED strips, adjusting the ramp duration and peak intensity based on plant growth needs and fish activity patterns. During an algae outbreak, the agent might reduce the photoperiod from 10 hours to 7 hours and increase the ramp speed.

Dosing with restraint: Chemical dosing is the most dangerous automated action in an aquarium. Overdosing pH buffer, fertilizer, or water conditioner can be lethal. The agent enforces per-dose maximums and daily cumulative limits regardless of what the LLM suggests. If pH is still low after the maximum daily dose, the agent logs a warning for human review rather than adding more chemicals. This is the same defense-in-depth principle used in OpenClaw irrigation controllers: the agent makes decisions, but the control scripts enforce hard safety boundaries.

Multi-parameter correlation: The agent can detect situations that single-parameter monitoring misses entirely. If temperature rises, pH drops, and TDS increases simultaneously, that pattern suggests decomposing organic matter (a dead fish, uneaten food, or rotting plant material). A threshold script would try to fix each parameter independently. The agent recognizes the correlated pattern and alerts the owner to check for a source of contamination rather than masking symptoms with chemistry.

An aquarium controller runs 24/7 for months or years. Sensor data from last Tuesday is just as valuable as today's reading when you are diagnosing a slow parameter drift or evaluating whether a tank change (new fish, different substrate, adjusted CO2) had the intended effect.

Polling frequency: Temperature and pH change slowly in a healthy aquarium. Polling every 5 minutes gives you 288 readings per day per sensor, enough resolution to catch trends without wasting compute cycles. During active events (water change, dosing, lights-on transition), the agent can increase polling to every 30 seconds to track the response curve, then return to the normal interval.

Alert escalation: Not every out-of-range reading needs a notification. A temperature that bounces 0.3°C above the target for one reading and returns to normal is noise. A temperature that climbs 0.3°C every hour for four hours is a trend worth alerting on. The agent distinguishes between transient fluctuations and sustained trends, reducing false alarms that train owners to ignore notifications.

Local logging: Store raw sensor data in a SQLite database on the Pi for immediate access. Each reading gets a timestamp, sensor ID, value, and the agent's decision (if any) at that polling cycle. SQLite handles millions of rows on a Pi without issues, and you can query it locally for quick diagnostics.

Cloud storage for historical analysis: For long-term data and remote access, Fastio workspaces give you a practical destination for aquarium logs. The agent can upload daily summaries, weekly trend reports, and alert logs to a shared workspace using the Fastio MCP server. With Intelligence Mode enabled, those uploaded logs become searchable. You can ask questions like "what was the average pH in March" or "show me all temperature alerts from the past 60 days" without writing database queries.

The Business Trial includes generous storage and monthly credits during the trial with no credit card required. Daily aquarium log files are tiny (a few kilobytes each), so 50GB covers decades of data from multiple tanks. If you run several aquariums or share tank management responsibilities with family members, workspace sharing lets everyone view the same dashboards.

Alternatives include pushing sensor data to Home Assistant (if you already run it), InfluxDB with Grafana for time-series visualization, or a simple MQTT broker feeding a custom dashboard. Fastio is simpler for the agent-to-human handoff scenario: the OpenClaw agent builds the data workspace, and you can transfer ownership or share access with other people who help maintain the tank.

Data-driven stocking decisions: After a few months of logged data, you have an empirical picture of your tank's parameter stability. If pH fluctuates within 0.2 units and temperature holds within 1°C, that is a stable environment suitable for sensitive species. If parameters swing widely despite the controller, the tank is better suited for hardy species. This kind of data-driven decision-making is where long-term logging pays for itself.

Aquarium controllers operate in a humid, salt-spray environment that is hostile to electronics. Plan for sensor degradation, connection failures, and the inevitable moment when something goes wrong at 2 AM on a Sunday.

pH probe maintenance: pH probes are consumable. Even high-quality probes drift after 12-18 months and eventually need replacement. The agent can detect calibration drift by comparing the probe's reading against known reference points during scheduled water changes. If you measure the water change water with a handheld pH meter and it reads 7.0 but the probe reports 7.3, recalibration is overdue. Budget $15-30 per year for probe replacement in freshwater systems, more for saltwater where probes degrade faster.

Sensor waterproofing: The DS18B20 waterproof probe is rated for permanent submersion, but the cable entry point is the weak spot. Seal it with aquarium-safe silicone. For pH and TDS probes, follow the manufacturer's submersion guidelines. Some probes are designed for continuous immersion, others should only be dunked during readings and stored in electrode storage solution between measurements.

Relay clicking and lifespan: Mechanical relays click audibly every time they switch, which gets annoying in a living room. Solid-state relays (SSRs) switch silently and last longer since they have no moving parts. For lighting and heater control where you switch once or twice per hour, mechanical relays last years. For a dosing pump that runs dozens of short cycles daily, an SSR is worth the extra cost.

Power failure recovery: When the Pi reboots after a power outage, the agent should read all sensors before taking any action. A tank that was at 25°C when power failed may have cooled to 22°C overnight. The agent needs to bring the heater on gradually to avoid thermal shock rather than slamming the heater to full power. Configure the agent's startup behavior to enter a "recovery assessment" mode: poll all sensors, compare readings against the last known state from the database, and ramp any corrective actions over 15-30 minutes.

Condensation on the Pi: Mount the Pi above the tank, not beside or below it. Warm humid air rises from open-top tanks and condensation on the Pi's circuit board causes corrosion and short circuits. A basic enclosure with ventilation slots, mounted on a shelf above the tank, is sufficient. For fully enclosed canopy setups, consider placing the Pi outside the canopy with sensor cables running through grommets.

Failsafe valve on dosing pumps: If a dosing pump relay sticks closed, the pump runs continuously and overdoses the tank. Add a check valve (one-way valve) on the dosing line to prevent siphoning, and keep the chemical reservoir small enough that emptying it entirely would not be lethal. If your alkaline buffer reservoir holds 100ml and a full dump would only shift pH by 0.3 units, the worst-case failure is manageable. If it holds a liter, the worst case is catastrophic.