ESP32 controllers
Controllers are managed in Settings › Controllers (Configuration › Contrôleurs). For choosing the board and wiring, see the Hardware section.
Add a controller
Section titled “Add a controller”- Automatic discovery: ESP32s already running ESPHome on the local network are detected (mDNS).
- By hand: enter the controller’s name and IP address. This is the default in a Docker install, where discovery doesn’t cross the containers’ network.
Describe the pins
Section titled “Describe the pins”For each pin in use, set its role:
| Mode | Use |
|---|---|
| Output | An equipment relay, a PWM channel of an LED fixture |
| Input | An on/off sensor, such as a float switch |
| Sensor | 1-Wire bus (temperature probes), analog input |
For a relay, set its type and the contact used (NO, normally open, or NC, normally closed): AquasManager works out whether the signal needs inverting.
Forms replace writing YAML. For the curious, the generated ESPHome YAML can still be viewed.
Expansion modules
Section titled “Expansion modules”Each controller can take modules:
- PCF8574 / PCF8575: I²C I/O expanders, to add relays;
- battery-backed RTC clock: DS3231, DS1307, PCF8563 or PCF85063.
The RTC clock is required for time-based rules and lighting schedules: it keeps time even without a network.
Modules are numbered (“Module 1”…) and the Scan the I²C bus button checks what is actually wired. See Modules and RTC clock.
Technical names
Section titled “Technical names”Each piece of equipment and each sensor gets a technical name, in the form <name>_<aquarium>:
osmolateur_recif, niveau_decante_recif… It’s the identifier used in the firmware, on MQTT and in
the controller’s logs. It’s recomputed when you rename the item or its aquarium.
After a rename, the controller needs reflashing. Until then, AquasManager keeps talking to it under the old name: readings and commands keep working without interruption.
1-Wire temperature probes
Section titled “1-Wire temperature probes”Several DS18B20 probes can share one pin. In the sensor form, the search button queries the controller and lists the addresses of the probes on the bus: pick the matching one. Also set the measurement interval.
Restart
Section titled “Restart”The Restart button (Redémarrer) on the controller card restarts it remotely (the firmware must have been flashed once with this feature). For a few seconds, relays go back to their start-up state: avoid doing it during a top-off. After wiring a probe or a module, Restart and search and Restart and scan run the search again once it’s back.
- Start the flash from the controller’s page, or Flash all (Tout flasher) to update every modified controller.
- Progress is shown live.
Flashing goes over the network (OTA): the controller must be online. A new board must first receive a basic ESPHome firmware over USB: see Preparing a new board.
The first flash from AquasManager compiles the whole firmware: allow several minutes. Later ones are much faster.
Faults
Section titled “Faults”When a safety automation triggers, for example the ATO exceeding its maximum run time, a fault is shown. It stays active until you acknowledge it.
Home Assistant
Section titled “Home Assistant”Home Assistant finds the controllers on its own through its ESPHome integration: equipment, lighting channel intensity, temperature probes, level sensors and the restart button show up without any setup. AquasManager also generates the dashboard that lays them out, with one view per aquarium.
- In Home Assistant, add each controller with the ESPHome integration. It asks for the controller’s encryption key: copy it from Controllers → Home Assistant (managers).
- In AquasManager, open Controllers → Home Assistant and copy the YAML shown. If the controller is assigned to a Home Assistant area, enter it in the Area field: Home Assistant puts its name at the start of the entities.
- In Home Assistant: Settings → Dashboards → Add dashboard (a new dashboard, not a view of an existing one), open it, then ⋮ → Edit → ⋮ → Raw configuration editor. Paste the YAML and save.
The encryption key is specific to each controller and built into the firmware: only a Home Assistant that knows it can connect to the ESP and drive its relays. It only takes effect after a flash.
Each view groups the equipment (switches), lighting, temperatures and levels, with their 24-hour graph. A last view gathers the controllers’ restart buttons.