Home Lab Monitoring with a Raspberry Pi and Check_MK

 DHT22 ───────────► rack-dht22.service ───────┐
                                              ├─► /run/rack-monitor/   ──► rack-display.service ──► OLED
 Mi|Home adapter ─► rack-energenie.service ───┘     (files, in RAM)   └─► Check_MK agent plugin ──► Check_MK
   (radio, via Pi-mote)                                                      (value + age of each reading)

sudo raspi-config        # Interface Options: enable I2C and SPI, then reboot

sudo apt update
sudo apt install -y git i2c-tools python3-pip python3-pil python3-spidev python3-rpi.gpio fonts-dejavu-core
sudo pip3 install Adafruit_DHT Adafruit-SSD1306

sudo git clone --depth 1 https://github.com/whaleygeek/pyenergenie.git /opt/pyenergenie

sudo i2cdetect -y 1

rack-monitor/
├── install.sh
├── pi/
│   ├── opt/rack-monitor/           the Python programs
│   ├── etc/rack-monitor/           the config file
│   ├── etc/tmpfiles.d/             creates the RAM data folder at boot
│   ├── etc/systemd/system/         the three services
│   └── usr/lib/check_mk_agent/plugins/rack_monitor
└── server/rack_monitor.py          the Check_MK server-side plugin

unzip rack-monitor.zip
cd rack-monitor
sudo chmod +x install.sh
sudo ./install.sh

#!/bin/sh
# Installs the rack monitor on the Raspberry Pi. Safe to run again to upgrade;
# an existing /etc/rack-monitor/rack-monitor.conf is never overwritten.
#
#   sudo ./install.sh
#   sudo PYTHON=/usr/bin/python2 ./install.sh     # force a particular Python
set -eu

[ "$(id -u)" -eq 0 ] || { echo "Run as root:  sudo ./install.sh" >&2; exit 1; }
HERE=$(cd "$(dirname "$0")" && pwd)
SRC="$HERE/pi"

if [ ! -d "$SRC/opt/rack-monitor" ]; then
    echo "Cannot find $SRC/opt/rack-monitor." >&2
    echo "install.sh must sit next to the 'pi' folder from the zip, like this:" >&2
    echo "  rack-monitor/install.sh  rack-monitor/pi/...  rack-monitor/server/..." >&2
    echo "Unzip the whole archive and run it from inside the rack-monitor folder." >&2
    exit 1
fi

# Use the Python that already has the Adafruit libraries installed.
PYTHON=${PYTHON:-}
if [ -z "$PYTHON" ]; then
    for p in python3 python python2; do
        if command -v "$p" >/dev/null 2>&1 && "$p" -c 'import Adafruit_DHT' >/dev/null 2>&1; then
            PYTHON=$(command -v "$p")
            break
        fi
    done
fi
[ -n "$PYTHON" ] || { echo "No Python with Adafruit_DHT found. Install it, or set PYTHON=/path/to/python" >&2; exit 1; }
echo "Using Python: $PYTHON"

# Unprivileged user for the display service.
id rackmon >/dev/null 2>&1 || useradd --system --no-create-home --shell /usr/sbin/nologin rackmon

install -d -m 755 /opt/rack-monitor /etc/rack-monitor
install -m 644 "$SRC"/opt/rack-monitor/*.py /opt/rack-monitor/

if [ -f /etc/rack-monitor/rack-monitor.conf ]; then
    echo "Keeping existing /etc/rack-monitor/rack-monitor.conf"
else
    install -m 644 "$SRC/etc/rack-monitor/rack-monitor.conf" /etc/rack-monitor/rack-monitor.conf
fi

# The Energenie radio library. Kept in a root-owned folder (not a home folder)
# because the receiver service runs as root and must not execute code that a
# normal user can edit. Downloaded here only if the configured path is missing.
CONFIGURED_SRC=$(. /etc/rack-monitor/rack-monitor.conf; echo "${PYENERGENIE_SRC:-}")
if [ ! -d "$CONFIGURED_SRC/energenie" ]; then
    if [ "$CONFIGURED_SRC" = "/opt/pyenergenie/src" ] && command -v git >/dev/null 2>&1; then
        echo "Downloading pyenergenie to /opt/pyenergenie ..."
        git clone --depth 1 https://github.com/whaleygeek/pyenergenie.git /opt/pyenergenie \
            || echo "WARNING: could not download pyenergenie; see README.md" >&2
    else
        echo "WARNING: PYENERGENIE_SRC ($CONFIGURED_SRC) does not contain the 'energenie' package." >&2
        echo "         Install pyenergenie there (see README.md) or fix the path in /etc/rack-monitor/rack-monitor.conf" >&2
    fi
fi

install -m 644 "$SRC/etc/tmpfiles.d/rack-monitor.conf" /etc/tmpfiles.d/rack-monitor.conf
systemd-tmpfiles --create /etc/tmpfiles.d/rack-monitor.conf

for unit in rack-dht22 rack-energenie rack-display; do
    sed "s|@PYTHON@|$PYTHON|" "$SRC/etc/systemd/system/$unit.service" > "/etc/systemd/system/$unit.service"
    chmod 644 "/etc/systemd/system/$unit.service"
done

# Check_MK agent plugin.
PLUGINS=/usr/lib/check_mk_agent/plugins
if [ -d "$PLUGINS" ]; then
    install -m 755 "$SRC/usr/lib/check_mk_agent/plugins/rack_monitor" "$PLUGINS/rack_monitor"
else
    echo "WARNING: $PLUGINS not found - install the Check_MK agent, then copy the plugin by hand." >&2
fi

systemctl daemon-reload
systemctl enable --now rack-dht22.service rack-energenie.service rack-display.service

echo
echo "Installed. Check the services with:"
echo "  systemctl status rack-dht22 rack-energenie rack-display"
echo "  journalctl -u rack-dht22 -u rack-energenie -u rack-display -f"
echo "Then install server/rack_monitor.py on the Check_MK server (see README.md)."

systemctl status rack-dht22 rack-energenie rack-display
ls -l /run/rack-monitor/
cat /run/rack-monitor/energenie_0x354

# /etc/rack-monitor/rack-monitor.conf
#
# Shared settings for the rack monitor services and the Check_MK agent plugin.
# Plain KEY=value lines only (no spaces around "=", no "export"): this file is
# read by systemd (EnvironmentFile) and sourced by a shell script.
#
# After editing:  sudo systemctl restart rack-dht22 rack-energenie rack-display

# Where the live readings are kept. /run is a RAM disk, so the frequent
# updates never wear out the Pi's SD card. Contents are rebuilt after a reboot.
RACK_DATA_DIR=/run/rack-monitor

# DHT22: GPIO pin (BCM numbering) and seconds between readings (minimum 2).
DHT_GPIO_PIN=4
DHT_INTERVAL=10

# Energenie: folder containing the "energenie" Python package (the "src" folder
# of the pyenergenie library). install.sh downloads pyenergenie to /opt/pyenergenie
# if it is not there. It is kept outside any home folder because the receiver
# service runs as root. ENERGENIE_SENSOR_ID is the sensor ID of your Mi|Home
# Monitor adapter, as logged by the receiver, e.g. 0x354.
PYENERGENIE_SRC=/opt/pyenergenie/src
ENERGENIE_SENSOR_ID=0x354

# OLED display: 64 for a 128x64 panel, 32 for 128x32. Refresh in seconds.
OLED_HEIGHT=64
OLED_REFRESH=1
# Optional: path to a bold TrueType font for the large values. Leave unset to
# use DejaVu Sans Mono Bold (sudo apt install fonts-dejavu-core).
#OLED_FONT=/usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf

# The display shows "--" for any reading older than this many seconds.
MAX_DATA_AGE=120

# DEBUG logs every radio message, INFO (default) only logs problems and startup.
RACK_LOG_LEVEL=INFO

"""Helpers shared by the rack monitor scripts.

Settings come from environment variables, which systemd fills in from
/etc/rack-monitor/rack-monitor.conf. Works on Python 2.7 and 3.
"""

import logging
import os
import signal
import sys
import time

DATA_DIR = os.environ.get("RACK_DATA_DIR", "/run/rack-monitor")
TEMPERATURE_FILE = os.path.join(DATA_DIR, "temperature")
HUMIDITY_FILE = os.path.join(DATA_DIR, "humidity")


def env_int(name, default):
    try:
        return int(os.environ.get(name, default))
    except ValueError:
        return default


def get_logger(name):
    """Log to stderr; systemd stores it in the journal with timestamps."""
    level = getattr(logging, os.environ.get("RACK_LOG_LEVEL", "INFO").upper(), logging.INFO)
    logging.basicConfig(stream=sys.stderr, level=level,
                        format="%(name)s: %(levelname)s: %(message)s")
    return logging.getLogger(name)


def install_signal_handlers():
    """Turn SIGTERM (systemctl stop) into a normal exit so cleanup code runs."""
    signal.signal(signal.SIGTERM, lambda signum, frame: sys.exit(0))


def energenie_file(sensor_id):
    """Path of the data file for an Energenie sensor, e.g. .../energenie_0x354."""
    try:
        sensor_id = hex(int(str(sensor_id), 0))
    except ValueError:
        sensor_id = str(sensor_id)
    return os.path.join(DATA_DIR, "energenie_" + sensor_id)


def write_atomic(path, text):
    """Replace a file in one step so readers never see it empty or half-written."""
    if not os.path.isdir(DATA_DIR):
        os.makedirs(DATA_DIR)
    tmp_path = "%s.tmp%d" % (path, os.getpid())
    with open(tmp_path, "w") as f:
        f.write(text)
    os.rename(tmp_path, path)


def file_age(path):
    """Seconds since the file was last updated, or None if it does not exist."""
    try:
        return time.time() - os.path.getmtime(path)
    except OSError:
        return None


def read_first_line(path, max_age=None):
    """First line of a file, or None if missing, empty or older than max_age."""
    age = file_age(path)
    if age is None or (max_age is not None and age > max_age):
        return None
    try:
        with open(path) as f:
            return f.readline().strip() or None
    except IOError:
        return None

#!/usr/bin/env python3
"""Read the DHT22 sensor and publish temperature and humidity to the data dir.

This is the only program that talks to the sensor. The OLED display and the
Check_MK agent plugin just read the files it writes. A value is only written
when the reading is valid, so a file that stops being updated means the sensor
has stopped working (the Check_MK check alerts on that).
"""

import time

import Adafruit_DHT

from rack_common import (HUMIDITY_FILE, TEMPERATURE_FILE, env_int, get_logger,
                         install_signal_handlers, write_atomic)

log = get_logger("dht22")

SENSOR = Adafruit_DHT.DHT22
GPIO_PIN = env_int("DHT_GPIO_PIN", 4)
READ_INTERVAL = max(2, env_int("DHT_INTERVAL", 10))   # DHT22 needs >= 2 s

# Datasheet limits; anything outside is treated as a failed reading.
TEMPERATURE_RANGE = (-40.0, 80.0)
HUMIDITY_RANGE = (0.0, 100.0)

LOG_EVERY_N_FAILURES = 30


def valid(value, limits):
    return value is not None and limits[0] <= value <= limits[1]


def main():
    install_signal_handlers()
    log.info("starting: GPIO %d, every %d s", GPIO_PIN, READ_INTERVAL)
    failures = 0

    while True:
        try:
            humidity, temperature = Adafruit_DHT.read_retry(SENSOR, GPIO_PIN)
        except RuntimeError as e:
            humidity = temperature = None
            log.debug("read error: %s", e)

        temperature_ok = valid(temperature, TEMPERATURE_RANGE)
        humidity_ok = valid(humidity, HUMIDITY_RANGE)
        if temperature_ok:
            write_atomic(TEMPERATURE_FILE, "%.1f\n" % temperature)
        if humidity_ok:
            write_atomic(HUMIDITY_FILE, "%.1f\n" % humidity)

        # Log problems once, then every Nth time, so the journal is not flooded.
        if temperature_ok and humidity_ok:
            if failures:
                log.info("sensor readings recovered after %d failed attempts", failures)
            failures = 0
        else:
            failures += 1
            if failures == 1 or failures % LOG_EVERY_N_FAILURES == 0:
                log.warning("no valid reading from DHT22 (%d failed attempts in a row)", failures)

        time.sleep(READ_INTERVAL)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Receive Energenie Mi|Home radio messages and save each sensor's readings.

Every sensor that reports gets a file named energenie_<sensor id> in the data
directory, one "<name> <value> <unit>" line per record, for example:

    REAL_POWER 142 W

The OLED display and the Check_MK agent plugin read those files.
"""

import os
import sys
import time

# The pyenergenie library lives outside /opt/rack-monitor; add it to the path.
_src = os.environ.get("PYENERGENIE_SRC")
if _src and _src not in sys.path:
    sys.path.insert(0, _src)

from energenie import Registry, Devices, OpenThings, radio  # noqa: E402

from rack_common import (DATA_DIR, energenie_file, get_logger,  # noqa: E402
                         install_signal_handlers, write_atomic)

log = get_logger("energenie")


def format_records(records):
    """Turn decoded records into 'name value unit' lines."""
    return ["%s %s %s" % (rec["paramname"], rec.get("value"), rec["paramunit"])
            for rec in records]


def handle_message(msg):
    header = msg["header"]
    sensor_id = hex(header["sensorid"])
    lines = format_records(msg["recs"])

    log.debug("mfrid=%s prodid=%s sensorid=%s: %s",
              hex(header["mfrid"]), hex(header["productid"]), sensor_id, "; ".join(lines))

    # Messages without records (e.g. join requests) carry no readings, so keep
    # the previous values instead of overwriting them with nothing.
    if lines:
        write_atomic(energenie_file(sensor_id), "\n".join(lines) + "\n")


def receive_loop():
    radio.receiver()
    while True:
        if not radio.is_receive_waiting():
            time.sleep(0.05)       # do not spin a CPU core at 100%
            continue

        payload = radio.receive()
        try:
            decoded = OpenThings.decode(payload)
        except OpenThings.OpenThingsException as e:
            log.warning("could not decode payload: %s", e)
            continue

        handle_message(decoded)
        Registry.update(decoded)   # keeps pyenergenie's list of known devices current


def main():
    install_signal_handlers()
    log.info("starting: writing sensor files to %s", DATA_DIR)
    radio.init()
    OpenThings.init(Devices.CRYPT_PID)
    try:
        receive_loop()
    finally:
        radio.finished()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Show power, temperature and humidity on an SSD1306 OLED (I2C).

This program only reads the data files written by dht22_reader.py and
energenie_receiver.py, so it needs no root access and never touches the
sensors. Any reading older than MAX_DATA_AGE seconds is shown as "--".

Layout (128x64): three rows, each with a small label on the left and a large
value on the right, and a small date/time footer. Text is drawn with a
TrueType font and then thresholded to pure black/white, which keeps the
characters crisp on a 1-bit display.
"""

import os
import time

import Adafruit_SSD1306
from PIL import Image, ImageDraw, ImageFont

from rack_common import (HUMIDITY_FILE, TEMPERATURE_FILE, energenie_file, env_int, file_age,
                         get_logger, install_signal_handlers, read_first_line)

log = get_logger("display")

DISPLAY_HEIGHT = env_int("OLED_HEIGHT", 64)
REFRESH = max(1, env_int("OLED_REFRESH", 1))
MAX_AGE = env_int("MAX_DATA_AGE", 120)
POWER_FILE = energenie_file(os.environ.get("ENERGENIE_SENSOR_ID", "0x354"))
POWER_PARAM = "REAL_POWER"

# First font that exists wins. Set OLED_FONT in the config to use your own.
# On Raspberry Pi OS:  sudo apt install fonts-dejavu-core
BOLD_FONTS = [
    os.environ.get("OLED_FONT", ""),
    "/usr/share/fonts/truetype/dejavu/DejaVuSansMono-Bold.ttf",
    "/usr/share/fonts/truetype/liberation/LiberationMono-Bold.ttf",
    "/usr/share/fonts/truetype/freefont/FreeMonoBold.ttf",
]
# Small text is clearer in a regular weight; bold clogs up at 10 pixels.
REGULAR_FONTS = [
    "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
    "/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf",
    "/usr/share/fonts/truetype/freefont/FreeMono.ttf",
]


def load_font(size, bold=True):
    """A TrueType font of the given pixel size, or None if none is installed."""
    for path in (BOLD_FONTS if bold else REGULAR_FONTS + BOLD_FONTS):
        if path and os.path.exists(path):
            try:
                return ImageFont.truetype(path, size)
            except IOError:
                continue
    return None


def text_width(draw, text, font):
    if hasattr(draw, "textbbox"):                  # Pillow 8+
        left, _, right, _ = draw.textbbox((0, 0), text, font=font)
        return right - left
    return draw.textsize(text, font=font)[0]       # older Pillow


def read_number(path):
    text = read_first_line(path, MAX_AGE)
    try:
        return float(text)
    except (TypeError, ValueError):
        return None


def read_power():
    """Wattage from the Energenie sensor file, or None if missing or stale."""
    age = file_age(POWER_FILE)
    if age is None or age > MAX_AGE:
        return None
    try:
        with open(POWER_FILE) as f:
            for line in f:
                parts = line.split()
                if len(parts) >= 2 and parts[0] == POWER_PARAM:
                    return float(parts[1])
    except (IOError, ValueError):
        pass
    return None


def fmt(value, template):
    return u"--" if value is None else template.format(value)


class Screen(object):
    """Draws the rows and footer, sized to fit the whole display."""

    def __init__(self, width, height):
        self.width = width
        self.height = height
        self.canvas = Image.new("L", (width, height))   # grey canvas, thresholded on output
        self.draw = ImageDraw.Draw(self.canvas)

        footer_h = 12 if height >= 64 else 0
        self.footer_h = footer_h
        self.row_h = (height - footer_h) // 3
        value_font = load_font(max(8, self.row_h - 2))
        self.truetype = value_font is not None
        self.value_font = value_font or ImageFont.load_default()
        self.label_font = load_font(max(8, int(self.row_h * 0.6)), bold=False) or ImageFont.load_default()
        self.footer_font = load_font(10, bold=False) or ImageFont.load_default()
        self.degree = u"\u00b0" if self.truetype else u""

    def render(self, rows, footer):
        """rows: [(label, value)] x3; footer: (left_text, right_text) or None."""
        d = self.draw
        d.rectangle((0, 0, self.width, self.height), outline=0, fill=0)

        for i, (label, value) in enumerate(rows):
            top = i * self.row_h
            value_size = self.value_font.size if hasattr(self.value_font, "size") else self.row_h
            label_size = self.label_font.size if hasattr(self.label_font, "size") else 8
            d.text((0, top + (self.row_h - label_size) // 2 + 1), label,
                   font=self.label_font, fill=255)
            x = self.width - text_width(d, value, self.value_font) - 1
            d.text((x, top + (self.row_h - value_size) // 2 - 1), value,
                   font=self.value_font, fill=255)

        if footer and self.footer_h:
            line_y = self.height - self.footer_h - 1
            d.line((0, line_y, self.width, line_y), fill=255)
            y = self.height - 11
            d.text((0, y), footer[0], font=self.footer_font, fill=255)
            x = self.width - text_width(d, footer[1], self.footer_font) - 1
            d.text((x, y), footer[1], font=self.footer_font, fill=255)

        # Threshold to pure black/white instead of dithering, then 1-bit mode.
        return self.canvas.point(lambda p: 255 if p >= 128 else 0).convert("1")


def main():
    install_signal_handlers()
    if DISPLAY_HEIGHT == 64:
        disp = Adafruit_SSD1306.SSD1306_128_64(rst=None)
    else:
        disp = Adafruit_SSD1306.SSD1306_128_32(rst=None)
    disp.begin()
    disp.clear()
    disp.display()
    log.info("starting: 128x%d display", DISPLAY_HEIGHT)

    screen = Screen(disp.width, disp.height)
    if not screen.truetype:
        log.warning("no TrueType font found, using the small built-in font "
                    "(sudo apt install fonts-dejavu-core)")

    last_frame = None
    try:
        while True:
            now = time.localtime()
            rows = [
                (u"POWER", fmt(read_power(), u"{0:.0f} W")),
                (u"TEMP", fmt(read_number(TEMPERATURE_FILE), u"{0:.1f} " + screen.degree + u"C")),
                (u"HUMIDITY", fmt(read_number(HUMIDITY_FILE), u"{0:.1f} %")),
            ]
            footer = (time.strftime("%a %d %b", now), time.strftime("%H:%M", now))

            # Sending a frame over I2C is slow and CPU-heavy on an old Pi, so
            # only redraw when something on screen has actually changed.
            frame = (tuple(rows), footer)
            if frame != last_frame:
                disp.image(screen.render(rows, footer))
                disp.display()
                last_frame = frame
            time.sleep(REFRESH)
    finally:
        disp.clear()
        disp.display()


if __name__ == "__main__":
    main()

# Creates the RAM-backed data directory at every boot.
d /run/rack-monitor 0755 root root -

[Unit]
Description=Rack monitor - DHT22 temperature and humidity reader
After=local-fs.target
StartLimitIntervalSec=0

[Service]
Type=simple
# Adafruit_DHT reads the GPIO pin through /dev/mem, which needs root.
EnvironmentFile=/etc/rack-monitor/rack-monitor.conf
ExecStart=@PYTHON@ /opt/rack-monitor/dht22_reader.py
Restart=always
RestartSec=10
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full

[Install]
WantedBy=multi-user.target

[Unit]
Description=Rack monitor - Energenie Mi|Home radio receiver
After=local-fs.target
StartLimitIntervalSec=0

[Service]
Type=simple
# The radio is driven over SPI/GPIO by pyenergenie, which is run as root.
EnvironmentFile=/etc/rack-monitor/rack-monitor.conf
ExecStart=@PYTHON@ /opt/rack-monitor/energenie_receiver.py
Restart=always
RestartSec=10
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full

[Install]
WantedBy=multi-user.target

[Unit]
Description=Rack monitor - OLED status display
After=rack-dht22.service rack-energenie.service
StartLimitIntervalSec=0

[Service]
Type=simple
# Only needs the i2c group, so it does not run as root.
User=rackmon
SupplementaryGroups=i2c
EnvironmentFile=/etc/rack-monitor/rack-monitor.conf
ExecStart=@PYTHON@ /opt/rack-monitor/oled_display.py
Restart=always
RestartSec=10
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes

[Install]
WantedBy=multi-user.target

<<<room_temp>>>
23.2 0
<<<room_humidity>>>
52.8 0
<<<power_usage>>>
368 2

#!/bin/sh
# Check_MK agent plugin: /usr/lib/check_mk_agent/plugins/rack_monitor
#
# Sends one section per reading: the value, then the number of seconds since
# its data file was last updated, so the server can spot stale data:
#
#     <<<room_temp>>>
#     24.3 5          <- value, then seconds since the data file was updated
#
# A missing or empty data file is reported as a single "-".

RACK_DATA_DIR=/run/rack-monitor
ENERGENIE_SENSOR_ID=0x354
[ -r /etc/rack-monitor/rack-monitor.conf ] && . /etc/rack-monitor/rack-monitor.conf

emit_section() {
    section=$1
    file=$2
    value=$3
    echo "<<<$section>>>"
    if [ -n "$value" ]; then
        age=$(( $(date +%s) - $(stat -c %Y "$file") ))
        echo "$value $age"
    else
        echo "-"
    fi
}

TEMP_FILE="$RACK_DATA_DIR/temperature"
HUMIDITY_FILE="$RACK_DATA_DIR/humidity"
POWER_FILE="$RACK_DATA_DIR/energenie_$ENERGENIE_SENSOR_ID"

emit_section room_temp     "$TEMP_FILE"     "$(head -n 1 "$TEMP_FILE" 2>/dev/null)"
emit_section room_humidity "$HUMIDITY_FILE" "$(head -n 1 "$HUMIDITY_FILE" 2>/dev/null)"
emit_section power_usage   "$POWER_FILE"    "$(awk '$1=="REAL_POWER"{print $2; exit}' "$POWER_FILE" 2>/dev/null)"

sudo /usr/lib/check_mk_agent/plugins/rack_monitor

(5 h × 8.57 p  +  19 h × 28.12 p) ÷ 24 h  =  24.05 p/kWh

#!/usr/bin/env python3
"""Checkmk checks for room temperature, humidity and rack power.

Written for Check API v1, which Checkmk supports from 2.0.0 to 2.3.0. Checkmk 2.4
no longer loads plugins from this folder, so on 2.4 or later this file has to be
ported to Check API v2.

Install on the Check_MK server, as the site user, at
    ~/local/lib/check_mk/base/plugins/agent_based/rack_monitor.py
then reload with:  cmk -R

The agent plugin sends one line per section: "<value> <age in seconds>".
The age is optional; without it the stale-data check is skipped.
"""

from .agent_based_api.v1 import (
    Metric,
    Result,
    Service,
    State,
    check_levels,
    register,
    render,
)

# ---- CONFIGURATION ----------------------------------------------------------
# Levels are (warn, crit). Upper levels alert when the value rises to them,
# lower levels when it falls to them.
TEMPERATURE_UPPER = (30.0, 35.0)     # degrees C
TEMPERATURE_LOWER = (10.0, 5.0)      # cold-weather alert (suggested values)
HUMIDITY_UPPER = (75.0, 80.0)        # percent
HUMIDITY_LOWER = (25.0, 15.0)        # suggested values
POWER_UPPER = (480, 500)             # watts

# Time-of-day tariff, pence per kWh. The cheap rate applies from NIGHT_START
# up to (not including) NIGHT_END, in hours of the day (0 = midnight).
DAY_PENCE_PER_KWH = 28.12
NIGHT_PENCE_PER_KWH = 8.57
NIGHT_START_HOUR = 0
NIGHT_END_HOUR = 5
COST_LEVELS = (80, 100)              # per month; drawn on the graph only, no alert

# No fresh data for this long -> WARN / CRIT (seconds).
STALE_AFTER = (120, 300)
# -----------------------------------------------------------------------------


def _average_pence_per_kwh():
    """Blended price over a full day, so the estimate does not jump at the
    tariff changeover. It assumes the rack draws the same power all day."""
    night_hours = (NIGHT_END_HOUR - NIGHT_START_HOUR) % 24
    day_hours = 24 - night_hours
    return (night_hours * NIGHT_PENCE_PER_KWH + day_hours * DAY_PENCE_PER_KWH) / 24.0


def _to_float(text):
    try:
        return float(text)
    except ValueError:
        return None


def parse_reading(string_table):
    """[['24.3', '5']] -> {'value': 24.3, 'age': 5.0}; [['-']] -> value None."""
    if not string_table or not string_table[0]:
        return None
    row = string_table[0]
    return {
        "value": _to_float(row[0]),
        "age": _to_float(row[1]) if len(row) > 1 else None,
    }


def _no_reading():
    return Result(
        state=State.CRIT,
        summary="No reading available (sensor or data file missing)",
    )


def _freshness(reading):
    """Alert when the Pi is up but the sensor or receiver has stopped updating."""
    age = reading["age"]
    if age is None or age < STALE_AFTER[0]:
        return
    yield Result(
        state=State.CRIT if age >= STALE_AFTER[1] else State.WARN,
        summary="Data is stale, last update %s ago" % render.timespan(age),
    )


def discover_reading(section):
    yield Service()


# ---- Room temperature -------------------------------------------------------
def check_room_temp(section):
    if section["value"] is None:
        yield _no_reading()
        return
    yield from check_levels(
        section["value"],
        levels_upper=TEMPERATURE_UPPER,
        levels_lower=TEMPERATURE_LOWER,
        metric_name="Temperature",
        render_func=lambda v: "%.1f \N{DEGREE SIGN}C" % v,
    )
    yield from _freshness(section)


# ---- Room humidity ----------------------------------------------------------
def check_room_humidity(section):
    if section["value"] is None:
        yield _no_reading()
        return
    yield from check_levels(
        section["value"],
        levels_upper=HUMIDITY_UPPER,
        levels_lower=HUMIDITY_LOWER,
        metric_name="Humidity",
        render_func=lambda v: "%.1f%%" % v,
    )
    yield from _freshness(section)


# ---- Rack power and running cost --------------------------------------------
def check_power_usage(section):
    watts = section["value"]
    if watts is None:
        yield _no_reading()
        return
    yield from check_levels(
        watts,
        levels_upper=POWER_UPPER,
        metric_name="Wattage",
        render_func=lambda v: "%.0f Watts" % v,
    )
    average = _average_pence_per_kwh()
    cost = round((watts / 1000.0) * 24 * 30 * average / 100.0, 2)
    yield Metric("Cost", cost, levels=COST_LEVELS)
    yield Result(
        state=State.OK,
        summary="\N{POUND SIGN}%.2f p/m (avg %.2f p/kWh: %.2f day, %.2f night)" % (
            cost, average, DAY_PENCE_PER_KWH, NIGHT_PENCE_PER_KWH),
    )
    yield from _freshness(section)


# ---- Registration -----------------------------------------------------------
for _name in ("room_temp", "room_humidity", "power_usage"):
    register.agent_section(name=_name, parse_function=parse_reading)

register.check_plugin(
    name="room_temp",
    service_name="Room Temperature",
    discovery_function=discover_reading,
    check_function=check_room_temp,
)
register.check_plugin(
    name="room_humidity",
    service_name="Room Humidity",
    discovery_function=discover_reading,
    check_function=check_room_humidity,
)
register.check_plugin(
    name="power_usage",
    service_name="Power Consumption",
    discovery_function=discover_reading,
    check_function=check_power_usage,
)

cd ~/local/lib/check_mk/base/plugins/agent_based
cp /path/to/rack_monitor.py .            # the file is in the zip's server folder
cmk -R

cmk -nv hdc-room        # use your host's name in Check_MK

sudo systemctl stop rack-dht22

journalctl -u rack-dht22 -u rack-energenie -u rack-display -f