OEG KMS data in Home Assistant

This page is a easy to follow step by step guide on how to install and use a Raspberry Pi or any other SOC Debian based system to port data from the USB port of a OEG KMS device to Home assistant using MQTT. The OEG KMS-D solar boiler system in this example is equipped with several sensors which we can all receive in Home Assistant:

• Roof / solar temperature
• Pump speed %
• Boiler High temperature
• Boiler Low temperature

OS installation

The steps in this installation guide are based on a RaspberryPi zero W which has Wifi functionality already integrated. Start by installing a Debian based OS to the RaspberryPi, I personally used the Raspbian Lite OS to keep the CPU usage low and because we don`t need desktop functionality for this project to work. At the time of writing the easiest way to download and write the OS to your SD card is by downloading the RaspberryPi imager from the official Raspberry website: RaspberryPi software

With the imager downloaded to your computer, insert the SD card and preferably use the official SD card formatter from the SD association (Yes this really exists) to format the SD card: SD association downloads Then open Raspberry imager, select the OS of your choise, For Pizero make sure to select a 32Bit version! Select the correct drive of your SD card. Now before clicking write! make sure to click the Cog icon in order to change some settings as this will speed up the rest of the process quite a bit. In the advanced settings menu do the following things:

• Set a recognizable hostname, e.g. something like EBUSPI will work to help you recognize the PI on your Wifi network later
• Tick the “Enable SSH” checkbox and enable password authentication
• Set a username and password, we will need these later to login into the Pi
• Tick the “Wifi settings” checkbox and fill in your Wifi SSID and Password so the Pi will automagically connect to your Wifi after booting is finished.

Now we are ready to click “Write” and wait for Raspberry Imager to write the OS and its presettings to the SD card. When it is finished eject the SD card and place it in the Raspberry Pi. Plug in the power adapter and wait for the Pi to boot, this can take several minutes for the first boot so be patient.

Finding the device on your network

With the PI booted you now have to find it on your network. The easiest way to to this is by logging into your router and check the connected devices list for the hostname you used in the previous step. If you cannot acces your router for some reason then AngryIP scanner is a simple program to map all the devices on your network: Angry IP scanner With Angry IP scanner open, click in the top bar on “IP^” and select the right ethernet adapter. The sanner will now automatically fill in the correct scanning range. Now click Start and wait for the scanner to finish, then search for the correct hostname in the results, mine is called OEGPI and got IP address 192.168.3.10 as shown below:

SSH into the Raspberry

For the next step we will use SSH to connect to the PI we just configured. In this example i will use the standard SSH tool which is integrated into windows CMD. Start by clicking on the start icon and type “CMD” this will open a new command prompt window. In this window we now type the following to connect using SSH:

SSH <Username>@<IPaddress> 

In my case this will result in:

SSH pi@192.168.3.10

If the username and Ip address are correct a message will popup asking you if you want to continue and accept the SSH security key of the raspberry PI, enter “yes” and hit enter. The Pi will now ask you to enter your password, this is the password you entered into the Raspberry Pi configurator in the first step. If everything is succesfull you should now see something like this:

With our computer now connected to the Raspberry Pi it is best to first update & upgrade our OS in order to have the latest sources list and install the latest update packages. Type the following command to update and upgrade:

Sudo apt-get update && sudo apt-get upgrade -y

This process wil again take a couple of minutes and maybe a bit longer if you are using a Pizero or RaspberryPi2. Wait for the process to complete before proceeding to the next step.

Cloning the repository

In order to clone the github repository we first need to install git, this can easily be done by typing the following command:

sudo apt-get install git-all 

After the installation of git is finished we can clone the repository to download all the neccesary files, do this by typing or copying the command below:

git clone https://github.com/Yannicflight/oeg_kmsd.git 

With the repository cloned we should now have a folder called “oeg_kmsd” in order to confirm this, type “ls” this will list all the folders and files in the current directory. Since we need Python to run the scipt it is neccesary to install Python 3, use the following command to install Python3:

sudo apt-get install python3

With Python3 installed we also need to install some additional packages,
Paho-mqtt and pyserial. To install these python3 packages use these commands:

pip3 install pyserial
pip3 install paho-mqtt

Now we need to modify the python script with the correct details of your network and MQTT server details. To open the file we can use the simple builtin text editor called nano:

sudo nano oegscan_mqtt.py

This will open the python script shown below in the text editor, fill in your MQTT broker ip address. in most cases this is the IP address of home assistant. Also fill in your MQTT username and password. Make sure to leave the quotes before and after each field. To save the file press ctrl+x and then type y and hit enter to save the edited file.

Now we need to move the Systemd service file “oeg_kmsd.service” which is also located in the oeg_kmsd folder to /lib/systemd/system so we can use the service. To move the file simply use the move “mv” command as shown below:

sudo mv oeg_kmsd.service /lib/systemd/sytem

With the file moved to its proper location we can now test if the service starts, Make sure to plug in the micro USB cable from the OEG KMS system into the raspberry pi first! To start a service we use systemctl start:

sudo systemctl start oeg_kmsd.service 

We can now check if the service was started succesfully by using systemctl again but instead of start we use the status function:

sudo systemctl status oeg_kmsd.service

This should return the service status as “active (running)” as shown in the screenshot below:

If the service does show up as active then the setup on the Raspberry Pi is done. Make sure to enable the service so it will run automatically everytime the PI boots. To do so use systemctl again and use the “enable” function:

sudo systemctl enable oeg_kmsd.service

If you want to disable the service use “disable” and if you want to stop or restart the service use “stop” or “restart” respectively. Now proceed by adding the OEG MQTT sensors to home assistant.

Adding the MQTT sensors to Home Assistant

In order to add and read the sensor data in home assistant add the sensors below to your configuration.yaml file under the “sensor” tab. Change the name of the sensors to your liking. In my case:

• OegT1 is the rooftop temperature sensor
• OegT2 is the low buffer temperature sensor
• OegT3 is the high buffer temperature sensor
• Oegpomp is the pump speed %

sensor:

#MQTT sensors
  - platform: mqtt
    name: "Dak T1"
    state_topic: "home-assistant/oeg/OegT1"
    unit_of_measurement: "C"
    
  - platform: mqtt
    name: "Boiler laag T2"
    state_topic: "home-assistant/oeg/OegT2"
    unit_of_measurement: "C"
    
  - platform: mqtt
    name: "Boiler hoog T3"
    state_topic: "home-assistant/oeg/OegT3"
    unit_of_measurement: "C"
    
  - platform: mqtt
    name: "OEG pomp"
    state_topic: "home-assistant/oeg/Oegpomp"
    unit_of_measurement: "%"

The sensors listed above should become available as entities after a restart of home assistant. Check if the sensor values correspond with the values shown on the OEG KMS display, if the values are correct then everything works as it should!