External REST control API for an Enervent Pingvin Kotilämpö residential heating/ventilation unit via RS485 bus using the Modbus protocol. Designed for Home Assistant integration
Go to file
Jarno Rankinen 5a1f0d298f
Update README.md
Install instructions 1
2023-04-04 21:53:06 +03:00
.github/workflows Update add_to_project.yml 2023-02-08 19:55:28 +02:00
homeassistant Squashed commit of the following: 2023-03-14 09:37:36 +02:00
pingvin Configuring the serial path actually does something now 2023-03-20 20:55:20 +02:00
static/html Moved Go files under repo root 2023-03-15 21:20:48 +02:00
.gitignore Combined .gitignores 2023-03-15 21:19:28 +02:00
LICENSE Create LICENSE 2023-03-30 15:05:41 +03:00
README.md Update README.md 2023-04-04 21:53:06 +03:00
coils.csv Moved Go files under repo root 2023-03-15 21:20:48 +02:00
go.mod Renamed packages 2023-03-15 21:29:57 +02:00
go.sum Moved Go files under repo root 2023-03-15 21:20:48 +02:00
main.go Configuring the serial path actually does something now 2023-03-20 20:55:20 +02:00
registers.csv Moved Go files under repo root 2023-03-15 21:20:48 +02:00
test.sh Moved Go files under repo root 2023-03-15 21:20:48 +02:00

README.md

Enervent-control

External control of an Enervent Pingvin Kotilämpö residential heating/ventilation unit via RS485 bus using the Modbus protocol.

Provides a REST API for integration into Home Assistant, with measurements and basic control over Pingvin functions.

Template YAML configurations for Home Assistant are included in the homeassistant folder, intended to be simple to copy-paste into Home Assistant's configuration.yaml with minimal necessary modifications. These include sensor configurations, helpers and automations for button functions and a ready made basic dashboard. No custom components are necessary.

image

The daemon is designed to run on a Linux host that has some sort of RS-485 connector attached. For development a RPi Zero W 1 with a connected Zihatec RS 485 HAT has been used.

Building

  • clone or download the repo
  • static/html/index.html is symlinked to coils and registers for development purposes, the symlinks need to be dereferenced before building the binary on filesystems that support symlinks
    • Replace symlinks with copies of the files or use e.g. tar -h
  • Build for the correct architecture, e.g. for Linux 32-bit ARM (Rpi Zero W 1):
    cd /path/to/repo
    env GOOS=linux GOARCH=arm go build -o BUILD/enervent-ctrl-linux-arm32
    

Configuration:

  • CLI flags:
  -cert string
        Path to SSL public key to use for HTTPS (default "~/.config/enervent-ctrl/certificate.pem")
  -debug
        Enable debug logging
  -enable-metrics
        Enable the built-in Prometheus exporter (default true)
  -httplog
        Enable HTTP access logging
  -interval int
        Set the interval of background updates (default 4)
  -key string
        Path to SSL private key to use for HTTPS (default "~/.config/enervent-ctrl/privatekey.pem")
  -logfile string
        Path to log file. Default is empty string, log to stdout
  -password string
        Password for HTTP Basic Authentication (default "enervent")
  -regenerate-certs ~/.config/enervent-ctrl/server.crt
        Generate a new SSL certificate. A new one is generated on startup as ~/.config/enervent-ctrl/server.crt if it doesn't exist.
  -serial string
        Path to serial console for RS-485 connection. Defaults to /dev/ttyS0 (default "/dev/ttyS0")
  -username string
        Username for HTTP Basic Authentication (default "pingvin")

On first run, the daemon generates ~/.config/enervent-ctrl/configuration.yaml with default values. Configuration options are the same as with CLI flags. CLI flags take precedenence over the config file.

  • serial_address: Path to RS-485 serial device
  • port: TCP port for the REST API to listen on
  • ssl_certificate: Path to SSL certificate for HTTPS
  • ssl_privatekey: Path to SSL private key for HTTPS
  • username: Username for REST API HTTP Basic Auth
  • password: Password for REST API HTTP Basic Auth
  • interval: Interval of background updates from Modbus
  • enable_metrics: Enable the built-in Prometheus exporter
  • log_file: Path to log file, default logging is to STDOUT
  • log_access: Enable HTTP Access logging to logfile/STDOUT
  • debug: Enable debug logging

Running

  • Upload the built executable along with coils.csv and registers.csv to the target host. The files should be placed in the same folder.
  • Run the binary as a regular user. Adding the user to the correct group for serial access may be necessary
  • To run persistently, you can use screen, tmux, or generate a user systemd service unit file.
  • Example systemd service file (named e.g. enervent-ctrl.service):
[Unit]
Description=Enervent-ctrl
After=network-online.target

[Service]
Type=simple
Restart=on-failure
RestartSec=30
ExecStart=/path/to/enervent-ctrl-executable

[Install]
WantedBy=default.target
  • Replace paths in the file and place it under ~/.config/systemd/user. Create the folder if it doesn't exist.
  • systemctl --user daemon-reload
  • systemctl --user enable --now enervent-ctrl.service
  • To let user services continue running after logging out:
    • sudo loginctl enable-linger $USER

Connecting to the Pingvin unit

  • Connect an RS-485 adapter to the computer you intend to run the daemon on
    • Tested only on a RPi 4B and Zero W 1 with the Zihatec RS-485 HAT
    • You may need terminating resistors in your adapter, see documentation
  • Ensure the user has read/write privileges to the serial device.
    • No need to run the daemon as root, and it is not recommended

Disclaimer:

I am not responsible of possible damage to your device if you choose to follow these instructions The manufacturer may void your warranty if you choose to follow these instructions

  • Shut down the main power of the unit
  • Disconnect the device from mains, discharge any static electricity before proceeding
    • A new motherboard seems to cost close to 1000€ + labour
  • Open the cover in which the power switch is attached to. No need to disconnect the switch, there should be enough length in the wires to move the lid with the switch connected out of the way
  • Locate the green RS-485 connector on the motherboard

Work is part of my Bachelor's Thesis at Oulu University of Applied Sciences.

Pingvin and Kotilämpö are registered trademarks of Enervent Zehnder Oy.