About the Hardware

The Marine Assistant Controller V3 is our most capable reef automation platform to date, bringing together everything we've learned from previous generations into a single, powerful controller. Designed specifically for reef keepers, it combines extensive monitoring capabilities, flexible equipment control, and seamless Home Assistant integration in a compact, DIY-friendly package.

Built around modern ESP32 technology, the Controller V3 features support for float switches, optical level sensors, leak detection, DS18B20 temperature sensors, PWM outputs, WS281x LED control, and isolated analogue inputs for monitoring parameters such as pH, ORP, EC, and TDS. Integrated Ethernet and Wi-Fi connectivity provide reliable communication with Home Assistant, while the onboard real-time clock allows critical automations to continue operating even if your network becomes unavailable.

The hardware is designed to be easy to assemble, highly expandable, and suitable for everything from simple monitoring tasks to fully automated reef systems. Whether you're controlling pumps, monitoring water levels, managing lighting, or tracking water quality, the Controller V3 provides a flexible foundation for building a smarter reef aquarium.

Please note: The Marine Assistant Controller V3 is currently under development. Hardware features and specifications may evolve as testing continues and new functionality is added.

Components

The Marine assistant v3 is still in the finalisation stage but what we can say is that it will be available as with all the other Marine assistant range as a Kit, Including the Main PCB and Separate components to complete the hardware. The final assembly will need to be done by yourself, the end user. build guides will be available to guide you through every step of the process.

As for the Sensors, the MA-V3 is compatible with an extremly wide range of sensors, you decide exactly the components used and are not tied into a closed selection of sensors.

This version of the Hardware has undergone extensive testing, we have gathered feedback from many users during the Beta testing phase and built this to be the very best it can be.

The Heart of the System

Why We Chose This Platform

✔ Reliable Ethernet and Wi-Fi connectivity
✔ Powerful ESP32-S3 dual-core processor
✔ Large memory capacity for future expansion
✔ Excellent ESPHome and Home Assistant support
✔ Wide range of available GPIO and peripheral interfaces
✔ Open-source ecosystem with long-term community support
✔ Ideal for advanced monitoring, automation, and data logging

This platform gives the Marine Assistant Controller V3 the performance and flexibility needed to become the central hub of a modern reef aquarium automation system.

Best sellers

Build guide.

The Marine Assistant V3 is simple to put together, here is a guide on how to build your own:

Print the Parts

Build Plates

So If you are printing your own parts here is a guide on each of the build plates, what they are and how to best print them. First download the Files from Makerworld: Here is the Link

I have designed and setup the print profiles for PETG on A Bambu LAbs X2D.

Plate 1:
This is the Wall mount and The ESP32 cover, Print both in PETG Black. Both need supports and On the X2D we use PLA for the interface Layer to get a smooth surface on the underside.

Plate 2:
This is the Main Body of the case, Print in PETG Black. Needs Support around the PI port openings and along the Top LED Slot. Again use PLA for the interface layer if possible for best results. This part alos has some "Fuzzy skin" features on the top and bottom surfaces.

Plate 3:
This is the LED cover for the "Alarm" Led along the top, Print in PETG Transparent. we have optimised the profile for clear PETG

Plate 4:
This is the GX16 Port Mounting plate and bottom of the Case, Print in PETG Black with Orange Text. No support needed.

Plate 5:
These are the side plates and are used to close the case , the left side has the indentation for the PI outlets if you would like to use them. Print in PETG Blue or your colour of choosing.

Plate 6:
This is the Front pannel with Backlit Logo detail, Print in PETG Black and PETG Transparent. The profile is optimised to let the LED light through. No support is needed.

If you are printing your own parts then Print the parts as described before moving forward with the next steps.

Step 1.

Threaded Inserts, there are a total of 25 in the kit, 21 need to be installed and 4 are for the Pi or other mounting options. The 4 optional inserts can be installed as you wish.

As for the other 21; There are 4 on each side, 4 along the bottom, 5 for mounting the PCB and finally 4 in the GX16 Mounting plate. You can easyly use a sodlering iron with an old tip to melt them into the holes.

Step 2.

The case is now finished, you can put all the parts together using the M3x8m screws and make sure it all fits together as it should. you can also glue the ESP32 cover onto the GX16 faceplate with CA Glue.

Assembly

PCBs

The Marine Assistant V3 Is made up of 3 PCB's. One holds the ESP32 and all the Logic components then there are 2 Boards that hold the GX16 ports. The assembly of the Main PCB is fairly simple and only requires soldering the Headers. As for the GX16 Port PCBs, they require a little more work. Heres what to do:

Step 1:
The Main PCB has Headers and sockets that need to be soldered, Start with the ESP32 Sockets there are 2 and they should be placed in from the top and soldered from the bottom. Its a good idea to actually put the sockets on the ESP32 itself then place the whole assembly onto the PCB, This will ensure all is aligned correctly. Once in place solder each ping from the bottom.

Step 2:
The remaining headers are all male, the is a 12 pin header on the top Left (Expansion port), two 3 pin headers on the top right (Case LEDs). Finally there is a 22 pin header and a 12 pin header along the bottom. You can solder all the headers going Pin by Pin until they are all done. Its a good idea to maybe start with one or two pins, check the Alignment then solder the rest.

Insert the Female sockets onto the 22pin and 12pin headers along to bottom in preperation for the next steps.

Step 3:
On the GX16 there are resistors and Leds that need to be soldered as well as the Conectors themselves. This can be a little tricky to line-up. The PCBs, components and 3d printed faceplate all come together to make one part.

Start with the smaller PCB....
First you will need to install the resistors onto the PCB, they are all 3k ohm. Take the resistors from the coresponding bag, place them through the holes as shown in the images below then solder from the back side. It does not matter which direction you place the Resistors, they are not polorised.

Once that is done you will need to take the 3d printed Faceplate and insert Four of the three pin GX16 Sockets, Each socket has a little notch and this should point towards the bottom as pictured. thread the nuts onto the back but do not tighten them down yet.
You can now insert the LEDs into the holes on the faceplate as shown. The LEDs ARE Polorized and need to be inserted the correct way, The have a long leg and a Short one. On the back side of the 3d print there is a small dimple next to each hole, this is the side with the long leg.

Now you will need to join the two parts. As the LED legs are longer they will need inserting first, lower the PCB slowly ensureing the pins line up with the holes on the PCB. The pcb needs to sit on the posts and be screwed into place with the M3x5mm screws. Once its screwed down you can solder each of the pins and cut the excess from the LED Legs.

The Larger PCB...
The assembly of this side is exactly the same as the smaller PCB, the only difference is a small reset button that is on the top right of the PCB. The reset button is simply "snaped" into the PCB and soldered from the rear, there are four pins to solder here.

Aligning the pins can be tricky and may take a while, start at an angle and work along the PCB pushing the pins into the PCB as you go.

Step 4:
Its now time to secure the Main PCB into the case. Use three of the M3x5mm screws, two in the top corners and one on the bottom right. There are also two 1mm standoffs that can be installed too.

Step 5:
You can now slide down the GX16 assembly into the case. The pads on the bottom of each PCB should align with the pins on the female headers previously prepaired..... these will need to be soldered.

Once these pins are soldered you should be able to remove the GX16 assembly if required. This Assembly is secure to the main body with 4 M3x8mm screws along the bottom.

Step 6:
Next come the LED strips, they are pre-cut to length but the wires will need to be soldered. The LED strip has three pads; GND, 5v and DATA.
Solder Black to GND, Red to 5v and White to DATA.

You can them install them into the case as shown below and make the Connections to the PCB.

At this point you can also now install the ESP32-S3 ETH, you may need to put it in at an angle to adapt for the cutout in the case.

Step 7:
Time to close the case. Insert the top LED cover from one of the sides. Place the front cover onto the front of the case, ensure the tabs from the GX16 assembly Line up along the bottom.
Secure the case by screwing on the side plates with 4 M3x8mm Screws each.

You now have the Main unit complete and ready for firmware, there are however two point that need to be mentioned.....

Raspberry Pi

Depending on your setup you may want to run Home assistant of a Raspberry Pi of your choosing, there is a space in the case for you to mount a pi if you wish.
There are also cutouts on the side should you wish to use the Ethernet and USB ports, you will need to cut through the side pannel along the indentation to open up the holes.

Wall mount

The Marine assistant V3 has been designed to be wall mounted with the cables coming out of the bottom. There is a wall mount that can be used for this, use the paper template provided to make the three holes and secure the mount to the wall of your choosing.

The case then "hooks" ontop of this mount, to remove the controller there are two tabs along the bottom... press these and push the case up to remove.

Firmware install

Now that your hardware is complete, it’s time to move on to the setup process.

The code provided with the Marine Assistant is designed as a starting point for setting up your own system. It includes the basic details of how each port is connected, giving you a foundation to build upon.

From here, you can choose how you want to create your automations:

Option 1: Use Home Assistant, which offers a very user-friendly interface for building automations without coding.

Option 2: Modify the included code to “hard-code” your automations directly into the Marine Assistant. While this option is a bit more advanced, it’s still surprisingly straightforward once you get the hang of it.

Benefits of Hard-Coding

When your automations are hard-coded, they take full advantage of the onboard Real-Time Clock (RTC). This allows them to keep running even if the connection to your main Home Assistant system is lost — ensuring your essential functions continue to operate reliably.

Here, we’ll start by walking through how to install the basic code. Then, we’ll explore each of the options mentioned above and show you how to get started with each one.

What You Need and Where to Get the Files

This guide assumes you already have Home Assistant running and ESPHome installed.
If not, follow the [setup guide here] (link) to get everything ready.

You can download the Marine Assistant V3 code from the Downloads section on this website.

ESPhome Install...

Click on ESPhome in your sidebar then add device and follow the on screen instructions.

You will need your to input your Wi-Fi name and password, be sure to set the name to something appropriate and the board type to "ESP32-s3".

Click new Device

Set the name

Select ESP32-S3 as your Board

You’ll then be asked how you’d like to upload the code to the board. The first time, this must be done using a USB cable connected to your computer.
Once the ESPHome code is successfully running on your board, you’ll be able to upload updates wirelessly over Wi-Fi from then on.

Once everything is installed correctly, the sensor module should appear in ESPHome with the status “Online” shown in the corner.
You can open the logs at any time to see what’s happening behind the scenes or to check for any errors.

Keep in mind that there are several ways to install ESPHome onto your device — this is just one of them.
If you’d like to explore other methods, there are plenty of great guides available online.

Your Marine Assistant V3 should now be successfully installed in your Home Assistant system — all that’s left is to add the custom code.
As mentioned earlier, you now have two options, depending on how you’d like to set up your automations.
Let’s take a look installing the code then each of the options.

Installing the Code.

The custom code for the Marine Assistant V3 includes everything needed for the internal PCB to work correctly — such as the configuration for the inputs, outputs, and the real-time clock.

Feel free to modify or customize the code to suit your own setup and preferences!

Download the Marine assistant V3 code from the downloads section here.
Open the code with notepad++ (Or Chrome)
In ESPHome click on "edit" under the device.
Copy the code from notepad++ and paste it into your Marine assistant V3 device below the code that is already there. Simply add a few spaces below and paste it in.
Click on save and install (Wirelessly), wait for the code to upload.

The code file includes setup details for each of the ports. Take a moment to read through it!
It’s short, easy to understand, and contains a lot of helpful information about how the hardware works internally.

Once you’ve installed it successfully, you can make simple changes if you’d like.
For example, you can rename your inputs or outputs — give your temperature sensors meaningful names like “Sump Temperature” instead of “Temp1.”

Option 1.

This is the easiest way to create your automations — it uses Home Assistant’s built-in automation menus and structure.
Creating automations in Home Assistant is straightforward and beginner-friendly.

Here’s an example of an automation that turns on “12vOutput1” when “FloatSens1” goes low:

Step 1 – Open Automations

In Home Assistant, go to Settings → Automations & Scenes → Automations.
Click “+ Create Automation”, then choose “Start with an empty automation.”

Step 2 – Add a Trigger

Click “Add Trigger.”
Under Trigger Type, select “State.”
In Entity, select your sensor (for example: binary_sensor.floatsens1).
Set:
- From: on (or “high,” depending on your setup)
- To: off (or “low”)
  (You may need to check how your Float Sensor is reported — often “on” means active and “off” means low.)

Step 3 – Add an Action

Click “Add Action.”
Choose “Device” or “Call service.”
- If using Device, select your device and the action “Turn on 12vOutput1.”
- If using Service, choose:
  - Service: switch.turn_on
  - Target entity: switch.12voutput1

Step 4 – Name and Save

Give your automation a clear name, e.g., “Turn on 12vOutput1 when FloatSens1 is low.”
Click Save.
You’re done!

How Automations Work in Home Assistant

Automations in Home Assistant let your smart devices react automatically to specific events or conditions — no manual control needed.

Each automation is built from three parts:

Trigger – What starts the automation.
- Example: A sensor changes state, a button is pressed, or a time is reached.
Condition (optional) – Rules that must be true for the automation to run.
- Example: Only run if it’s nighttime or a specific mode is active.
Action – What happens when the trigger (and conditions) are met.
- Example: Turn on a light, activate a relay, or send a notification.

Automations can be created using Home Assistant’s visual editor (easy for beginners) or written directly in YAML for more advanced setups.

Pros and cons of Home Assistant Automations (GUI-based).

Pros:

✅ Very flexible – changes can be made instantly via the GUI.

✅ Easy for beginners – no coding required.

✅ Centralized management – all automations visible in HA dashboard.

✅ Can integrate multiple devices and cloud services easily.

✅ Supports complex conditions and triggers without YAML editing.

Cons:

❌ Dependent on Home Assistant – automations fail if HA or Wi-Fi is down.

❌ Slight delay in execution due to network communication.

❌ Less reliable for time-critical tasks if network issues occur.

❌ Harder to move or replicate automations to a new board without exporting.

Option 2.

You can also hard code the Automations into the Marine assistant mini, this requires modifying the code to your own use case

As before Here’s an example of an automation that turns on “12vOutput1” when “FloatSens1” goes low:

Adding a Hard-Coded Automation in ESPHome

Step 1 – Identify the Entities

Determine which sensor will trigger the automation (e.g., binary_sensor.float1).
Determine which output you want to control (e.g., switch.output1).
Make sure your switch has an id so it can be referenced in YAML:

switch: - platform: gpio pin: 4 name: "Output1" id: output1

switch:
- platform: gpio
pin: 4
name: "Output1"
id: output1

Step 2 – Add the Automation Section

Use the automation: block in your YAML.
Set the trigger (when the sensor goes low).
Set the action (turn on the switch).

Example:

automation: - alias: "Turn on Output1 when Float1 is low" trigger: platform: state entity_id: binary_sensor.float1 from: 'on' to: 'off' action: - switch.turn_on: output1

automation:
- alias: "Turn on Output1 when Float1 is low"
trigger:
platform: state
entity_id: binary_sensor.float1
from: 'on'
to: 'off'
action:
- switch.turn_on: output1

Step 3 – Save and Upload

Save your YAML file.
Compile and upload the firmware to your ESP32-S3 board using ESPHome.
Once uploaded, the automation will run automatically on the board, independent of Home Assistant.

Pros and cons of Hard coding your automations.

Pros:

✅ Runs independently of Home Assistant – works even if HA or Wi-Fi is down.

✅ Faster response time, as logic runs directly on the ESP32.

✅ Full access to onboard hardware features like Real-Time Clock (RTC).

✅ Reliable for critical tasks (pumps, relays, feeders).

✅ Easy to backup and move between devices (all in the YAML file).

Cons:

❌ Less flexible – changes require editing YAML and reflashing the device.

❌ Requires basic coding knowledge (YAML syntax).

❌ Automations aren’t visible or manageable from Home Assistant.

❌ Advanced logic can be more complex to implement.

❌ Mistakes in YAML can break automations until corrected and reflashed.

Conclusion: Choosing Between Hard-Coded and Home Assistant Automations

When deciding how to set up your automations for the Marine Assistant Mini, consider the purpose and criticality of each task:

Home Assistant Automations are ideal for flexible, complex, or non-critical tasks.
- Use the GUI to quickly create, edit, and manage automations.
- Perfect for integrating multiple devices, cloud services, or advanced conditions.
Hard-Coded Automations are best for essential functions that must run reliably, even if Home Assistant or Wi-Fi goes down.
- Examples: float switches controlling pumps, scheduled feeders, or critical 12V outputs.
- Hard-coding ensures these actions execute directly on the board, with minimal delay and full use of onboard hardware like the Real-Time Clock.

The best approach is often a mix-and-match strategy:

Hard-code time-sensitive or safety-critical automations directly into ESPHome.
Use Home Assistant for more complex, flexible, or non-critical automations that benefit from centralized management and easy editing.

By combining both methods, you get the reliability of hard-coded logic with the flexibility of Home Assistant, creating a robust and highly functional Marine Assistant system.

Ready to go...

Time to customise to your setup...

At this point its now up to you to setup your sensors and automations as you wish. Be sure to add sensors one by one, testing them as you go before adding more.