My first steps with OpenHab

The next transformation I added was to divide a number by 10 using a chunk of javascript. I copied an example to get the syntax-voodoo required:

    return parseFloat(i)/10.0;

but the result was missing the decimal places. I couldn’t work out how to fix that with a number item, so I just used a string item and took advantage to add the unit:

    var nTemperature = parseFloat(i)/10.0;
    return nTemperature.toFixed(1) + " ºC";

I managed to convert the bypass valve control and the control mode into switches, with a transformation to map the values. The values generated by the switch turned out to be ON and OFF (I expected 1 and 0). I learned this from the log. Okey-dokey. So my map for the bypass value looks like this:


I’m getting a ton of Modbus communication errors at the moment. Not sure why.

Also, I’ve lost openhabianpi. I have to use the IP to access PaperUI.

I’m now looking into how to move to use configuration files and how that fits/doesn’t fit with PaperUI. Apparently PaperUI uses a database, but it’s possible to manage items in files and things/bindings in PaperUI? This is all rather foggy.

There’s lot to say about Modbus. You’re not talking into the void here, but if you want to get into techy detail it feels like you might want to start another thread, and leave this one as your “experience diary”.

I will throw in a generalism - Modbus setup is a baptism of fire for non-techy folk. It’s an ancient low level protocol - meaning dimwitted. We have to supply the thinking when configuring, which is a very manual process. There is no consistency amongst target device behaviours.
Bottom line is that we have to get down among bits, bytes, and registers for success with Modbus. At heart it is simple, but requires care and background knowledge. At least we can share the last part!

Thanks. Yes, if I feel I need to open another thread I will. Everything still seems to be working, and it may be as simple as a congested network (the Modbus connection goes over IP) due to teleworking. No idea. It did seem to coincide with me connecting to my work VPN. It’s just a “that’s odd, I wonder what’s going on” rather than “HELP ME NOW!!”.

All my reads and writes are now working just fine, apparently, so I think I’ve figured out the registers, bits and bytes.


This is s great thread you’ve created.

I’ve got a couple of customers with ModBus kit that I’ve managed to steer clear of, having read your thread, I’m glad I have.

I am really pleased to read that you are mastering your setup and getting it to work how you want it to.

As Rich says, these kinds of threads are incredibly useful in all kinds of ways.

So here’s a common bit of confusion.

From what I understand…

The whole setup of openHAB2 Things, Items and their links are stored in JSON files.

Regardless of how the individual parts are created.

  • RestAPI
  • PaperUI
  • Text files
  • And others that access the RestApi

To start with, I restricted myself to PaperUI, because my needs were basic and it seemed to work well.

As I branched out into different bindings and third party connectivity (like Tagging & Metadata for Alexa & Google Assistant) it became clear that PaperUI can’t do everything.

Having read lots of other people’s thoughts and comments (for which I’m very grateful), I’ve adopted the following pattern

Add bindings through PaperUI wherever possible, as dependencies are taken care of there.

Create Bridge Things in a Text file (however I’ve recently learnt that the auto generated Thing ID can be set when created in PaperUi, which makes restoring / moving systems much easier)

Use PaperUI exclusively for adding Things, as getting the channel & trigger syntax right can be troublesome

Create Text file Items, which can be manipulated quite easily.
Adding groups, tags, metadata and secondary links to bindings (for example the amazingly useful Expire binding)

I’ve gone as far as to make one Item file template which has everything I could need, which I copy and trim / edit until I have all the items for a Thing in a corresponding Item file.

This way, I can quickly find and edit the Items.

(“Alt & Click drag” is an amazing editor feature that I discovered on this journey)

These threads show the evolution.

1 Like

Great info.

Yes, if I looked for a ventilation unit again, I would try to get one that uses Z-Wave. Modbus is teeth-grindingly difficult, and a compatibility nightmare. I’m close to the 5th anniversary of trying to get control via Modbus - on the Zipabox it’s still not working and I don’t see any reason to keep trying now that it’s up and running in OpenHab. I’m a programmer, but there’s no reason that Modbus’s function codes, registers and subtracting (or not subtracting) one from them are going to make much more sense to me than anyone else until I’ve become fully immersed in their weirdness.

Good info on PaperUI. So, am I to understand that the “database” is actually a collection of (editable?) JSON files? What would make sense to me is if you could use PaperUI and direct text file editing to manipulate the same configuration files - is that the case? I’ll actually go and hunt around in the file system and see what I can find. It might be the quickest sense to make sense of it.

That’s what it does, when you create or edit Things, channels, Items.

This is of course dangerous and can kill the system. It’s not very convenient, because you must stop system first. Needs must to fix a problem, but not day to day.

1 Like

So the suggestion is to keep a strict separation between the files managed by PaperUI and the files edited manually.

Incidentally, I disconnected the VPN and openhabianpi reappeared, and the Modbus communication errors vanished. So it’s definitely because of the VPN.

OK, I think I get it now. PaperUI stores its configurations here:


and manually created stuff goes here:


and PaperUI will read both and combine them…? Or not?

I should mention that to use transformations, you need to install the appropriate add-on from the transformations category (JS or map). I also stumbled on that in the forum.

Very nearly

Think of it more as PaperUI being an Admin front end for openHAB2.

I’m not sure how BasicUI / ClassicUI / HabPanel interact with the openHAB2 core, but I suspect it is via the RESTapi (I would welcome information on this, just to satisfy my curiosity)


openHAB2 works completely from the JSON database files (Avoid them like the plague)

  • PaperUI is a nice web interface for manipulating the JSON files by passing commands to the openHAB2 core.

  • Text files are read by the openHAB2 core and imported / deleted from the JSON DB on the fly (Changes to a Text file are normally reflected in a few ms, from my experience)

  • Using the RESTapi (UI or otherwise, which is what NodeRed does to interface with openHAB2) will also add / delete / read the JSON DB


Regularly running either of these commands when you’re editing will be the best system saver you ever do

openhab-cli backup

openhab-cli backup --full

you can specify the zip filename for a backup if you want to

If you use HabPanel and NodeRed, I would recommend backing them up seperately, as I had a major headache when a setup got hosed.

The openhab backup was fine, but it just didn’t like the HabPanel restore.
(Importing a seperate backup saved the day)

Obviously Node-red is utterly independant, so that needs to be backed up by itself, which is amazingly easy with the Export / Import feature, or the Node-RED projects method.

1 Like

Thanks Stuart, that’s very clear now. :+1:

I’ll try out the backup. I’m already at the point where losing it all would cause some significant amount of pain.

1 Like

If only it were as easy as “Ctrl+Shift+s” :wink:

1 Like

@Kim_Andersen You mentioned that you’ve got some Modbus kit, can you shine any light on this subject?

I can, but I see @rossko57 is already at it, and he´s the overaall expert in this :smiley:
However I would suggest keeping the modbus issues in its own/new thread, or at least LordLiverpool post some logs and setups/more info… “Getting tons of Modbus commenication errors” doesnt really help anything :slight_smile:

1 Like

Correct. PaperUI also interacts with OH core through the REST API.

I recommend modifying the JSON DB entries using the REST API. The REST API Docs addon (under the Misc tab) is fully interactive meaning you can make the same calls that PaperUI does when creating/editing stuff. At a high level it’s usually a:

  1. GET to get an example Thing/Item/Rule or get the JSON for the specific Thing/Item/Rule you want to edit.
  2. Edit the JSON as desired.
  3. A PUT (edit) or POST (create new) to apply your changes or create a new Thing/Item/Rule.

They can all be done through the API Docs or you can use curl

When you do it this way you get some error checking so if you mess up the JSON syntax or something it tells you before modifying the JSONDB. Also you don’t have to stop openHAB to make the edits.

Not quite. OH loads the config from the JSONDB first into memory. Then it loads the config from $OH_CONF into memory. From that point it operates off of the combined stuff loaded into memory. This is why anything that is in $OH_CONF will take precedence over anything done through PaperUI.

JSONDB is just a way for OH to write out the config changes made through the REST API (e.g. PaperUI) so it persists after OH is shutdown.

tl;dr: OH has two independent methods for defining and preserving it’s configuration: JSONDB and text files. JSONDB configs are read first and the text configs read next. Both are loaded into memory and available for use by OH, but it’s memory that OH is operating on. Configs in text configs are read second and therefore override those in JSONDB. Internally, OH encodes the information about Items/Things/Rules as JSON in response to REST API calls, but that does not mean that it’s all in the JSONDB. For consistency though, the same JSON format is used in the responses to the REST API calls as is used to store them in the JSONDB itself.


Thanks Rich

That makes perfect sense now and explains a few things I was misunderstanding.

The main one was (Which is obvious now) …

Why does openHAB need to shut down… BEFORE creating a backup, if everything is stored in the JSON & Text files.


While OH is running, the JSON files are dormant?
So a backup wouldn’t contain any recent changes

Also explains why an OH restart once in a while isn’t such a bad thing.

Pretty much. Periodically OH will write out to the JSONDB. I’ve not looked to see whether it’s every so often or just when something changes to the config (e.g. added a new Thing). But any operation you do through the REST API which results in a change that is stored in the JSONDB, it will immediately write that change out to the JSONDB. And when it does write out the JSONDB, it will create a backup in the $OH_USERDATA/jsondb/backups folder. I’ve not looked at them to try and correlate the backups with changes made to see if that is the only time it writes out or to the JSONDB or if it also periodically writes out stuff at other times too.

This is also why you have to stop OH if you manually edit the JSONDB files directly. OH might turn around and overwrite your changes. Also, I’m not sure if OH reads in the JSONDB files when they change, it might only read them in during startup.

If you attempt to make a backup while OH is actively writing to the JSONDB, the backup would almost certainly become corrupted. I think stopping OH before taking a backup is to ensure that doesn’t happen.

It’s not necessarily a bad thing for lots of reasons (I know Markus disagrees) but I don’t think the JSONDB is part of it. It is more for dealing with orphaned objects (i.e. memory leaks) and other cruft that builds up over time when there are minor bugs in the code. No one writes perfect code.

In fact, from a JSONDB perspective it could be a risky thing as if the machine loses power or otherwise stops before OH has finished closing down the JSONDB might be incomplete or otherwise corrupted. I personally have had cases where I got impatient and issued a kill -9 on OH and ended up with a blank JSONDB file. Luckily there was that automatically created backup to rescue me.

1 Like