Build a Bioactive Terrarium Controller with ESP32: Misting, Lighting Schedules, and Climate Automation

A bioactive terrarium — one with a living substrate ecosystem of microfauna and plants rather than paper towels and a water dish — depends on holding a stable humidity and temperature cycle far more tightly than a basic reptile enclosure does, and doing it by hand with a spray bottle twice a day gets old fast and produces exactly the kind of wild humidity swings that stress both the animals and the substrate's microfauna. This project builds a standalone ESP32 controller that runs a scheduled and humidity-triggered misting cycle, manages a day/night UVB lighting schedule, and reports climate data to Home Assistant, turning a terrarium from a thing you maintain into a thing you monitor.

This is distinct from the general "3D printing for aquariums and terrariums" material guidance covered elsewhere in this library, which is about choosing waterproof, fish- and reptile-safe materials for printed terrarium components. This project is the electronics and automation layer that sits inside whatever enclosure you've built or bought — the controller logic, sensors, and actuators that actually run the climate.

Sensing: don't trust one humidity reading

Mount at least two SHT31 or DHT22 sensors — one near the substrate/floor level where bioactive microfauna and most dart frogs or small geckos actually live, and one higher in the enclosure near the canopy or basking area — because terrarium humidity stratifies badly, especially in a taller bioactive build with live plants transpiring near the top and a drier substrate-adjacent airspace near any ventilation. Averaging a single sensor's reading across a whole enclosure's automation leads to either a chronically damp substrate (if you aim for the humidity the upper sensor would need) or chronically dry air near the canopy (if you aim for what the lower sensor needs). This build reads both, logs both, and lets the misting trigger reference whichever zone is the actual target for the humidity-sensitive inhabitants.

Misting logic: scheduled base, humidity-triggered boost

Run misting on a scheduled base cycle (a short mist a few times a day, timed to roughly mimic a dawn/dusk humidity spike for the species being kept) rather than purely humidity-reactive control — purely reactive misting tends to either run constantly in a naturally humid room or barely run at all in a dry one, neither of which is the actual multi-peak humidity cycle most bioactive setups are trying to replicate. Layer a humidity-triggered boost mist on top of the schedule only if humidity falls below a floor threshold between scheduled cycles, which catches unusual dry spells (a heater kicking on nearby, a dry cold front) without turning the whole system into a simple threshold toggle.

TriggerActionTypical durationSafety interlock Scheduled mist time (e.g. 7am, 7pm)Run fogger + optional mist pump30-90 seconds, tunable per enclosureMax daily mist budget prevents runaway cycling Humidity below floor threshold between cyclesTrigger a short boost mist15-30 secondsMinimum cooldown between boosts (e.g. 20 min) Reservoir float switch lowDisable all misting, send alertN/A — hard lockoutPrevents dry-running the fogger/pump Humidity sensor reads implausible value (stuck/disconnected)Fall back to schedule-only, flag faultN/APrevents a bad sensor from causing constant misting

Lighting and heating schedules

Drive the UVB/UVA fixture and any supplemental basking heat source through relay channels on a day-length schedule matched to the species being kept, with a gradual approach rather than a hard on/off where the hardware allows it — a simple 4-channel relay module switching mains-rated lighting is fine for most setups, but keep high-voltage relay wiring fully enclosed and away from any misting components, since the one thing worse than a terrarium that's slightly too dry is a terrarium with water dripping onto an energized mains relay. Route all wet-side components (fogger, pump, tubing) and all mains-voltage components (lighting ballast, heat emitter socket) to opposite sides of the enclosure box with the ESP32 and low-voltage logic physically separated from both.

Thermostat safety for heat sources

Never rely on the ESP32 alone as the sole safety cutoff for a heat emitter — add a mechanical or dedicated electronic thermostat/thermal-fuse-rated lamp socket in series with any heating element, the same way a commercial reptile heat setup always includes an independent thermostat separate from any smart automation layer. A firmware bug, a WiFi hang, or a relay that welds itself closed should never be the only thing standing between a ceramic heat emitter and a thermal runaway inside an enclosure with a living animal in it. This build's ESP32 layer handles scheduling and logging; the hard safety limit lives in dedicated hardware underneath it.

Home Assistant integration and logging

Publish temperature, humidity (both zones), and misting events to Home Assistant over MQTT, and graph humidity over a few weeks to find the setup's actual baseline swing before tightening the automation — bioactive terrariums are slow systems, and a controller tuned against a single day's data will often be wrong once the substrate's own moisture-buffering capacity settles in over the following weeks. A simple Home Assistant automation that alerts if humidity in either zone sits outside the target range for more than an hour is a far better early-warning system than physically checking the enclosure once a day.

Once dialed in, this kind of controller does for a terrarium what the chicken coop door project elsewhere in this library does for a flock — it takes a chore that depends on remembering to do it at the right time of day and turns it into something that happens reliably whether or not you're home.