top of page

KH Guardian Integration

The KH Guardian is an automated alkalinity monitoring and control system used in reef aquariums. It's designed to help maintain stable carbonate hardness (KH)—also called alkalinity—which is a critical water parameter for the health and growth of corals, especially in SPS (small polyp stony) coral-dominated tanks.

The KH Guardian is a device that:

  • Automatically tests your tank's alkalinity at set intervals (e.g., every 2–12 hours).

  • Displays the KH readings on a digital screen.

  • Optionally doses alkalinity buffer (via the KH Guardian Doser, if connected) to maintain stable levels.

The data can be sent to Home assistant and used to set alarms or controll a dosing pump, Special Thanks to Nathan for all the work he has put into getting this working!

Khguardiab.png

Step by Step guide.....

This guide explains how to integrate your KH Guardian with Home Assistant, allowing you to display alkalinity (DKH) readings on your dashboard and create automations based on them.

Requirements:

- A working Home Assistant setup

- AppDaemon 4 installed (via Add-ons)

- KH Guardian connected to your local network (set to a static IP, as per the KH Guardian manual)

- The local static IP address and port of your KH Guardian (e.g., http://192.168.0.xxx:8090)

Step 1: Create an input_number Helper

  1. In Home Assistant, go to Settings → Devices & Services → Helpers

  2. Click Create Helper

  3. Select Number

  4. Name it "KH Guardian DKH"

  5. Set the following:
    - Minimum: 0
    - Maximum: 20
    - Step: 0.1
    - Unit of Measurement: dKH

  6. Optionally, rename the entity ID to input_number.kh_guardian_dkh for consistency

Step 2: Install AppDaemon and Studio Code Server

These are needed to run the Python script and edit files:

  1. In the Add-on Store, install and start AppDaemon 4

  2. Install and start Studio Code Server, then click Show in Sidebar

  3. Open Studio Code Server from the sidebar

  4. Click the three horizontal lines → File → Open File

  5. Navigate to /addon_configs/a0d7b954_appdaemon/. You should now see the app folder. Under that create the 2 files below:

  6. - apps.yaml
    - kh_guardian_app.py

  7. It should look like this once done

It should look like this:

Step 3: Add the Python Script

Open the kh_guardian_app.py file and paste the code that is available in the downloads section of the website. The File is called KH_Guardian_Int.txt

 Be sure to replace the password and IP address with your actual KH Guardian details.

The Code Looks like this: 

import requests
import re
import appdaemon.plugins.hass.hassapi as hass

class KHGuardianApp(hass.Hass):
def initialize(self):
# Run every 15 minutes
self.run_every(self.get_kh_data, self.datetime(), 15 * 60)

def get_kh_data(self, kwargs):
PASSWORD = "ADD YOUR KHG PASSWORD HERE"
KHG_IP = "192.168.0.149"
ENTITY_ID = "input_number.kh_guardian_dkh"

try:
with requests.Session() as s:
# Login
login_url = f"http://{KHG_IP}:8090/Login"
payload = {"password": PASSWORD}
r = s.post(login_url, data=payload, timeout=10)
r.raise_for_status()

# Get the data page
default_url = f"http://{KHG_IP}:8090/Default"
r = s.get(default_url, timeout=10)
r.raise_for_status()
text = r.text

# Parse KH and pH
kh_match = re.search(r'<p class="dKH-T1">([\d.]+)</p>', text)
ph_match = re.search(r"<p class='T_PH GB6'>([\d.]+)</p>", text)

if not kh_match or not ph_match:
raise ValueError("Could not find KH or pH in the page")

kh_val = float(kh_match.group(1))
ph_val = float(ph_match.group(1))

self.log(f"✅ KH = {kh_val} dKH, pH = {ph_val}")

# Push to Home Assistant
self.call_service("input_number/set_value", entity_id=ENTITY_ID, value=kh_val)

except Exception as e:
self.log(f"🚨 Error getting KH data: {e}", level="ERROR")

It should look like this:

Step 4: Configure App in apps.yaml

Open the apps.yaml file and add the following configuration:

kh_guardian:
module: kh_guardian_app
class: KHGuardianApp

should look like this, make sure you dont have any extra spaces or it wont work !

Step 5: Test the Integration

  1. Restart the AppDaemon add-on from the Add-ons menu

  2. Open the AppDaemon Logs

  3. Wait 15 minutes and check for a log entry showing the KH and pH values

  4. Confirm the input_number.kh_guardian_dkh value in Home Assistant has been updated

  5. you can now play around with cards you want !

You're All Set!

Your KH Guardian is now integrated with Home Assistant, giving you real-time alkalinity data right on your dashboard. From here, you can build automations, alerts, or simply keep a closer eye on your reef’s stability.

 

Need help or want to share your setup?


Join our community on Facebook: Marine Assistant Users Group – we’re always happy to help! 

bottom of page