Category Archives: IT

Integrating a Buderus boiler into openHAB

In search to connect our Buderus boiler (heating, warm water system, hot water solar panels) to openHAB, I stumbled over an EMS gateway developed by a dutch engineer.

1. Installing the EMS gateway

I ordered the Wifi edition and connected it via the mini-jack cable to the boiler system. The boiler system also delivers power to the gateway over this cable.

The connection to the WIFI network was straight forward (chapter 8.1 of the manual) and the gateway automatically detected all the devices connected to our boiler. It immediately started displaying live data from the boiler.

2. Setting up an MQTT broker

We will use MQTT to send the boiler data to the openHAB system: the EMS gateway will send the boiler data to the MQTT broker which relays it onto the network. openHAB then needs to listen to this telegrams and interpret them.

Installing Mosquitto in an ubuntu VM was straight forward:

sudo apt-get install mosquitto mosquitto-clients

If you run the MQTT broker behind a firewall, it might not be necessary to force authentication. Entering the IP address and port of the MQTT broker in the gateway was straight forward. Do not forget to define a base, a kind of a channel on which MQTT will broadcast your telegrams. I chose ems-esp. The gateway then immediately began sending the boiler data to the broker.

3. prepare openHAB to receive and treat the incoming data

3a: Go to openHAB’s administration settings, Add-ons: Bindings and install the MQTT binding.

3b. Go to openHAB’s administration settings, Add-ons: Other Add-ons, Transformation Add-ons and install the JSONPATH Transformation.

4. Configure openHAB to receive the MQTT telegrams

4a.1: From this step on, you can either add a “HomeAssistant MQTT Component” which auto-detects all EMS things. In order for this to work, you need to activate the “MQTT Discovery (Home Assistant, Domoticz)” in the MQTT settings in the EMS gateway.

4a.2: I decided to go the manual way to have full control over the things and items to add to openHAB.
You need to add an MQTT Broker bridge. Go to the things tab and add a thing based on the MQTT binding. Select MQTT Broker. Enter the IP address of the MQTT broker. Save.

4b. Then add a Generic MQTT Thing. I linked it to the above created bridge. To have a better overview, I created a generic thing for the boiler, one for the warm water and one for the solar data.

4c: Now you have to add the data points that you want to import into openHAB as items. If you don’t know which data points are available, use an MQTT Explorer to get a better insight into your data.

MQTT Explorer showing warm water telegrams

MQTT Explorer showing warm water telegrams (EMS-ESP version 3.7.1)

4d: For each data point, you need to define a channel in openHAB. Open the MQTT generic thing that you created, click on the channel tab, and click add channel. Add the channel identifier, the label and select the corresponding channel type. In our example, we select Number Value, as we want to catch a temperature value.

The MQTT State Topic‘s first part is the base that you defined in the MQTT broker settings in the EMS gateway. In our case: ems-esp. The second part of the topic gives more details about the object you want to catch. Your MQTT explorer will help you determine which information telegrams are available.

In order to precise which value of the current object you want to import, you have to click the Show advanced check box.

Second step to precise the value you want to catch

As the object information is received in JSON format, you have to use JSONPATH Transformation to catch the exact value that you need (do not forget to install the JSONPATH tranformation, see 3b above). In our case, enter JSONPATH:$.curflowtemp under Transformation Values: Incoming Value transformations. This will extract the value for the current flow temperature object in the ems-esp/boiler_data telegram. As this is a temperature, you can add the Unit of Measurement if you want. In our case it is in Celsius degrees, so we add °C here.
Click CREATE if you have entered all the necessary information.

Note: Since EMS-ESP firmware version 3.6.5, the data structure has partially changed. The boiler_data_ww does not stipulate WW anymore, but it adds a nested folder called DHW. Adapt the JSONPATH like this: JSONPATH:$.dhw.flowtempoffset .

Now you have to link the channel to an item (click: Add link to Item). This is standard openHAB procedure. As soon as you save the item that you created/linked, the value will show up!

You have to repeat the step 4d for each data point you want to import.

Apache2: create Let’s encrypt certificate for SSL

Leave a reply

Install the certbot:

apt install certbot python3-certbot-apache

Set the following in your vhost conf file:

ServerName mydomain.com
ServerAlias www.mydomain.com

Verify that your configuration is fine:

sudo apache2ctl configtest
sudo systemctl reload apache2

Make sure the dns entry in the external dns server points to your proxy server/web-server. Then launch the certification process:

sudo certbot --apache
sudo systemctl status certbot.timer
sudo certbot renew --dry-run

Note: nots ure about the last commands. Needs to be retested.

NGINX: create Let’s encrypt certificate for SSL

Leave a reply

Before enabling SSL, make sure your vhost has been activated ( see instructions here: https://gilbert.busana.lu/?p=165 ).
If let’s encrypt’s certbot is not installed, proceed here:

sudo apt install certbot python3-certbot-nginx

To install the let’s encrypt certificate, you need to have your external DNS server pointing to your reverse-proxy/web-server. To install the certificates and have certbot modify your vhost config file for you, do:

sudo certbot --nginx -d www.mydomain.com

If failed, try:

certbot install --cert-name www.domain.com
nginx -t
systemctl restart nginx

If everything went well, your certificate is saved at: /etc/letsencrypt/live/www.mydomain.com/fullchain.pem
The key is saved at: /etc/letsencrypt/live/www.mydomain.com/privkey.pem
Certbot also modifies your vhost vonfiguration file and adds SSL on port 443 and redirects unencrypted (http) traffic to secure sockets (https). Check your configuration file here: /etc/nginx/sites-enabled/www.mydomain.com

NGINX: display reverse proxy headers

Leave a reply

If you are having trouble with a web application sitting behind a reverse proxy, debugging can be facilitated by having your (backend) web-server displaying the headers that it receives.

<?php
echo “<h1>Headers received from the reverse proxy</h1>";
$headers =  getallheaders();
foreach($headers as $key=>$val){
  echo $key . ': ' . $val . '<br>';
}
?>

Command	parameter 1	parameter 2	output
proxy_set_header	X-Real-IP	$remote_addr;	IP Address of client
proxy_set_header	X-Forwarded-For	$proxy_add_x_forwarded_for;	IP Address of client
proxy_set_header	X-Forwarded-Host	$server_name;	called vhost
proxy_set_header	X-Forwarded-Proto	$scheme;	https or http
proxy_set_header

Header commands and outputs

If you want to test how your page and headers look like from outside, call it from a site like https://testlocal.ly .

NGINX: HTTP basic authentication

Leave a reply

The ngx_http_auth_basic_module module allows limiting access to resources by validating the user name and password using the “HTTP Basic Authentication” protocol.
Access can also be limited by address. Simultaneous limitation of access by address and by password is controlled by the satisfy directive.
Add the following to the vhost config file to limit access:

location / {
    auth_basic           “Restricted access";
    auth_basic_user_file /etc/nginx/passwords/passwords;
}

This enables validation of user name and password using the “HTTP Basic Authentication” protocol. The specified parameter is used as a realm. The special value off cancels the effect of the auth_basic directive inherited from the previous configuration level.
Specifies a file that keeps user names and passwords, in the following format:

# comment
name1:password1
name2:password2:comment
name3:password3

The following password types are supported:

encrypted with the crypt() function; can be generated using the “htpasswd” utility from the Apache HTTP Server distribution or the “openssl passwd” command;
hashed with the Apache variant of the MD5-based password algorithm (apr1); can be generated with the same tools;

Create password for first user:

htpasswd -c /etc/nginx/passwords/passwords paul

To add an additional user:

htpasswd /etc/nginx/passwords/passwords pierre

To allow per adddress:

location / {
    deny  192.168.1.1;
    allow 192.168.1.0/24;
    allow 10.1.1.0/16;
    allow 2001:0db8::/32;
    deny  all;
}

Allows access if all (all) or at least one (any) of the ngx_http_access_module, ngx_http_auth_basic_module, ngx_http_auth_request_module, or ngx_http_auth_jwt_module modules allow access.

location / {
    satisfy any;
    allow 192.168.1.0/24;
    allow 10.0.X.0/24;
    deny  all;

    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}

Source: https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html
Source: https://nginx.org/en/docs/http/ngx_http_access_module.html

NGINX: enable configuration

Leave a reply

After creating a website or a reverse proxy vhost through the configuration file, the vhost has to be enabled:

ln -s /etc/nginx/sites-available/my.domain.com /etc/nginx/sites-enabled/my.domain.com

You can test the configuration file using the following command:

nginx -t

Do not forget to restart NGINX for the changes to be applied:

systemctl restart nginx

ATTENTION:
Always activate the vhost before generating the let’s encrypt SSL certificates. Failure to do so will result in having the default configuration file to be used which might result in the creation of two different vhosts using the same domain name. This will lead to one configuration being skipped on NGINX startup.

NGINX: limit access from IP range

Leave a reply

To limit access to a website / subfolder to certain IP addresses:

location / {
    allow 10.0.X.0/24;
    allow 10.123.123.123;
    allow 10.0.Y.0/24;
    deny  all;
#   proxy_pass http://$http_host$uri$is_args$args
}

Ubuntu: user management

Leave a reply

Add user

sudo adduser paul

Change root password

sudo passwd root

Ubuntu: enable root access from SSH

Leave a reply

Connecting to a server via SSH as root user is disabled by default. To enable this, edit the sshd configuration file:

nano /etc/ssh/sshd_config

Find the following line:

#PermitRootLogin prohibit-password

Change it to this.

PermitRootLogin yes

Now restart the ssh service:

systemctl restart sshd

Time zone adjustment

Leave a reply

To check if the server is in the same timezone than your workstation:

date

To modify the time zone:

sudo timedatectl set-timezone Europe/Luxembourg

Change timezone:

dpkg-reconfigure tzdata