Tips from a Newb for any other total Newb

Hello all,
As a fresh newbie, I had an extremely rough time trying to figure out OpenHab.
As I couldn’t find a one-size-fits-all guide for newbs, I thought I might as well write something to help ease that path for complete rookies like myself.
I have very little programming experience (just scripting here and there), am a long-time user of ubuntu and have never played with smart home systems before now.

I jumped in head first with a Tesla solar system, ev charger, EcoWitt weather station and Shelly smart plugs.

Instead of describing my experience, what I will do is to provide an overview of what I’ve learned, and hopefully, put the facets of OH4 into perspective for anyone new. This isn’t a tutorial, per se, just a helpful guide to get someone started quick(er).

Before starting, it is highly recommendable to make sure you read through this helpful post on the Semantics of OpenHab. It is well worth the read.

HARDWARE:
I installed OpenHab 4 from scratch on a freshly installed ubuntu 23.04 micro ($120 cheapo on Amazon with 6GB RAM and a Celeron CPU, with 256GB SSD). I didn’t go the OpenHabian way because I wanted to be able to scale to more things on this little server in the future, if needed.

If you’re new, I recommend going the OpenHabian route: https://www.openhab.org/docs/installation/openhabian.html

INSTALL:
The guides are very straightforward. If you follow documentation here, you will have no problem setting up OH4. The trouble begins (at least it did for me) with understanding what the heck to do next!

SETUP:
OK, this is where it becomes vital. OH4 is extremely flexible and very Germanic in its configuration. Instead of the typical HomeAssistant -style of making everything easy and semi-automatic, OpenHab is really more like a framework for you to build a system almost however you like it.
Instead of having a bunch of GUI switches to make everything happen for you while you follow the 80% path created by others, OpenHab is a wide open field with a toolbench for you to make what you want and pretty much go where you want.

To get started, here’s what you’ll need to know:

1. THINGS - To make anything work, you have to create THINGS. While this is explained in the tutorials, I’ll give a brief explanation: a THING is the digital representation of what you plug in somewhere and want to connect to.

2. ITEMS are the configurable/readable parts of your THINGS. ITEMS can be a simple api where you GET data, or, they can be the way that you control your smart light switch. All your interaction will be with ITEMS and not THINGS.

  1. CHANNELS are the ‘middle-men’ which connect the control/view ITEMS to the real-world THINGS.
    Once you have things set up, you don’t often mess with Channels. You can think of them as being like the fiber network which connects the internet. Nobody ever messes with it once it’s installed, but we all use it every day… You’re interested in ITEMS, which are what you interact with directly in OH to control THINGS.

QUICKSTART
OK, so you’ve installed OH4, and are trying to connect to your THING.
There’s the easy way, and the hard way. The hard way, is to try to hack through it by making a new THING and then trying to configure it (without having a clue what you’re doing).

The easy way, is to use BINDINGS. These are the automated means of setting up your THINGS that you’ve been looking for! You should actually start here.
To install bindings, you need to know which bindings you want, (e.g. EcoWitt weather station in my case). Once you kind of know, then you need to go here:

Settings → Add-Ons → Bindings

Now, install your heart out, with all the BINDINGS (automation tools) you need. If you think you might need it, install it.

For most BINDINGS, there may be some settings you need to modify. Click on a binding you installed, and then find that tiny gear icon just off to the right (it’s the size of a ladybug, so look carefully :smiley: )
See this? This is the icon you didn’t know you needed!

OK, now that you have all the BINDINGS (automagic setup) tools ready, your OH4 system should start recognizing some of your THINGS!

Now, we go back to the main page in OH and celebrate some progress.

Sometimes you will be prompted that you have new things, and sometimes you have to go find them for yourself.
To find them for yourself, use the blue + icon at the bottom right side of the screen.
Then choose the BINDING (automagic tool) and walk through the process to find your THING(s).

Once you have some THINGS you’re ready to do some cool stuff.

Click on a THING and it will open up a new window.
If you didn’t already, then you’ll want to make sure your settings for that THING is all good and dandy here.

If you make changes, be sure to hit the ‘Save’ button in the extreme top right corner of the page. It will often take a few seconds to actually achieve the save :wink:

OK, here is the most vital part. You have a THING, but you need to create ITEMS which are the control levers for your THING.

To do that, click on the ‘Channels’ tab at the top. It almost doesn’t look like a tab, but it is… and it’s vital.

Alright! Now you should see a list of the real-world parameters you really want to interact with, like statuses and controls, etc.
But not yet… not quite yet… you need to make some ITEMS!
(to ‘make’ ITEMS, you will only click ‘Link’ and this ‘Link’ will actually create your ITEMS, you’ll see…)

To do so, you need to click on a single Channel. It will expand.
Now you won’t see exactly the same thing as I’m going to show you, but don’t worry, just follow along.
'You need to click the ‘Add Link to Item’ button as shown here:

This will take you to a vital part in the process, where you are about to connect with the THING.
Select the ‘Create a new Item’ option.
You should see something like this, where there is a lot of information autopopulated:

Notice the Green Arrow at the bottom? You’ll need that later, when you want to set up Grafana and create custom graphs via an external InfluxDB database. Just remember that this green arrow is associated with Grafana and InfluxDB (which comes later). You don’t need to do anything with the ‘Parent Group’ option, other than to note it.

OK, You just click ‘Link’ at the bottom!

Now for the fun stuff.

Now, when you go back and if you click on the ‘Channels’ tab and then the channel you just created an ITEM link to, you should see some values that are populated from your THING in there (see my previous screenshot where the Temperature value is clearly visible).

If you DO see values from your THING, then you can hit the fast lane by clicking ‘Add Points to Model’ in blue text down below.

Check every box except for the one you already created in the previous step. Skip only that one, but check the rest of the boxes.
Hit ‘Add to Model’ and you now have a ton of ITEMS ready for fun.

Hit ‘Save’ in the top right to make sure you don’t lose what you just did.

Next, click ‘Pages’ on the left menu.
Then select the ‘Overview’ option.

Click on ‘Add Cells’.

You should see a blank box with a + symbol in it, like this:

Just click the + symbol and then select ‘Add from Model’ at the very bottom of the list in Blue.

Now pick your ITEM.

It should populate that cell you just made with some neato meaningful information (fyi, if it says, ‘NULL’, you have a problem).
image

Congratulations! You just connected to your THING, created an ITEM linked to a THING’s Channel by using BINDINGS! This is the magic sauce of OpenHab.

Play around with this page by adding ITEMS and messing with configurations.
If you have questions, use the OH Community… it’s really good and most likely your problem has already been encountered and solved.

THE CONCEPT

There is no right or wrong way to set up your OpenHab system. There are, however, some helpful key points which you should be aware of.
THINGS are real physical objects.
ITEMS are what you’ll generally be working with
BINDINGS are generally how you get things set up in the first place.

There are a few more key points to consider:

  1. GROUPS - these are how you set logging parameters for InfluxDB, so you’ll need to think about how you’re going to GROUP your ITEMS together. For instance, for my weather station, I used “gAtmospherics” as a group, and then I added all of my weather ITEMS to that group. My weather station has a battery status, which doesn’t necessarily fit into the same group though. I make a ‘gBatteryHealth’ group to monitor all my smart things batteries.
    GROUPS are key when you start making dashboards and graphs. You’ll want to be able to quickly sort out ITEMS and only show certain kinds all together and the easy way to do that, is with GROUPS.

  2. EQUIPMENT - this is a kind of a GROUP. The concept is that you may have something like a Smart Washer with voltage, cycle, temperature and a number of other ITEMS which may not all seem to go together, but you can GROUP them together with EQUIPMENT.

  3. Widgets - These look extremely tough. Don’t sweat it. Just borrow somebody else’s work by copy/pasting their code into your own Widget creator. The key to a properly developed wiidget, is that there is the ‘Set Props’ button on the bottom left. This is where you connect the widget gui elements with your ITEMS. This makes it pretty easy to use someone else’s widget. So long as the data format of your ITEM is the same as theirs, it should “just work”.

  4. Grafana - This is hell. It’s great once you understand it, but if you’re not a developer, this is just… it’s hard. There’s a tutorial from 2016 here which is helpful, but it has a few items in it which are obsolete for OH4 and you should know about them:
    a. Don’t update your influxdb persistence file. You don’t need to. Just use the GUI from the InfluxDB persistence addon. It’s enough.
    b. Make sure you use the right link “e.g. http://influx-ip-address:8086” and not “influx-ip-address:8086”. This will stifle the work.
    c. If you’re not a developer, I recommend staying in the home field and customizing Pages for a while. If you want long-term data, you’ll need to set up InfluxDB with Grafana, and there is a good tutorial here: InfluxDB+Grafana persistence and graphing

Make sure you use the forums. There are so many answers in here. This isn’t the ‘easy button’, it’s the advanced route to home automation and a lot of people are really helpful and informative here.

Hope this helps.

7 Likes

Excellent Excellent advice from a new user!!!
You really round up a whole bunch of the gotchas

There is an old saying about software documentation that it only make sense once you know what you are doing. Everybody screams ‘read the docs’ but they are written by somebody who already knows how it works.

Thank you and hopefully you stick around long enough to help us incorporate some of these ideas into the getting started tutorials. Great job and welcome to the openHAB community, glad you made it this far. Home automation is… hard, but when it works it’s like magic!

The developers and volunteers who work on this project have been making huge strides toward making openHAB accessible to less technically astute users but it is guys like you who power through it, keep notes as you go then write great tutorials like this who will give us that last little push toward wider uptake

2 Likes

Hey thanks Andrew!

The path was definitely brutal…
I’m with you, it helps to hear it from someone who just came out of the woods. :smiley:
I partly wrote this for myself as well. In case I’m able to get everything working and then don’t touch it for 2 years, I can come back to this.

Without bindings… I wouldn’t have made it. So much work has been done here, it is incredible. Totally opaque to a new user, but once up and running, you’re right, OH4 is pretty slick.

Thanks again.
If you have any additional pointers, I’ll gladly add them to this primer to help forge the path for total newbs like myself.

1 Like

Thanks for writing this down. I have a serious remark, though.
I’m speaking up as an openHAB maintainer as you’re adressing newbies.

To get non-standard hardware and not to use openHABian is really no good advice to newbies.
For one, this is a common misunderstanding. You will not need anything more powerful than a Raspberry 4 except in real special applications you shouldn’t bother about at this stage, not even and particularly so as an IT nerd. It has a number of advantages when it comes to operating your production-level system and even pros run on Raspi.

But the even more important point and this is why I’m speaking up here is that while strictly speaking not an openHAB issue in itself, setting up HW and OS are in fact the largest hurdle to most newbies, and non-standard HW and OS setups are almost a guarantee you run into issues in the future.

You really really should not be doing that as a newbie to have a serious interest in embarking on the home automation journey.

As a starter you should be using openHABian, and while you can use than on top of Debian, doing so is easiest on Raspi.

Just don’t use it. Standard charting and a standard database (rrd4j) are part of openHAB when you install it. You won’t be needing neither Influx nor Grafana except in special applications, and if you really do, you can still install it at a later stage.

1 Like

This is in reference to the gui comment and grafana.

OH does have an 80% path for configuring the GUI through the semantic model. If you configure the semantic model, locations, equipment (which you touched upon), and points, the Locations, Equipment, and Properties tabs of the Overview page in MainUI get populated automatically with reasonable display and control for the Items. It can be further configured and refined as desired.

I think you may have missed this feature based on your description of an Equipment Group. It’s more than just a way to group Items.

And I agree with @mstormi on the charting. The charting in MainUi is pretty good and works out of the box on a default first setup with rrd4j. I wouldn’t suggest jumping straight to InfluxDB and Grafana until you’ve proven to yourself that you need it. In MainUI’s Overview pages you’ll see an “analyze” button which will generate a chart of what ever you are looking at. You can also create your own custom chart pagesright in MainUI.

A lot more gets done automatically in OH than it appears.

Great post, thanks for taking the time! I’m going to move this to the Tutorials and Solutions category as I think it will be easier to find there.

1 Like

Great point, thanks. I didn’t intend to advise others to do the same as I did, but I see how I worded that doesn’t make it cleat that they should stay on the OpenHabian path.

I haven’t seen the same capabilities in OH4, but I’m new, so I’ll double back and look, thanks for pointing this out.

Thanks Rich, so strange, I have no idea where/how I missed the Semantic Modeling aspect.
In fact, I’ve only seen it reference in one post here, where someone mentioned that they had 'finally set up their Semantic Model, so they could now begin."
Which made me curious, but I didn’t know enough to know.

There’s a lot of docs to read, and with the OH versioning, it gets a little crazy for someone who isn’t familiar.
I’ll try to figure out the Semantic Modeling aspect, thanks.

I gave this a go at the beginning, and it is great, but I really needed to overlay charts for my use-case. Trying to optimize multiple inputs without having cross-correlation was tough.
Great point though, if someone is starting out, they should avoid the Grafana stuff until later.

Thank you, I appreciate that.
If it is possible to edit the post in the future, I’ll keep revising it to reflect things as I learn.
I’ll try to keep it succint, as brevity brings clarity.

1 Like

I suppose it depends on what exactly you are looking for in charts. But most cases are covered out of the box.

The above is an automatically generated chart I got from clicking on “Analyze All” from one of the cards on the Properties tab of the Overview page. I had to do absolutely nothing to create that chart beyond clicking the button. It’s using the default rrd4j with the default persistence strategy. Note that it’s charting two different types of values, in this case VOC in ppm and Radon in Bq/m3 and charting was smart enough to create two Y axis, one for each.

I cannot stress strongly enough that all “newbs” should first read the Concepts sections of the docs followed by the Getting Started Tutorial. Much of what you discuss above is also covered in those docs.

There is a whole page dedicated to the semantic model in Getting Started here and the page in Getting Started for the Overview Page further describes how it’s built from the semantic model and how to customize it.

For more information than you need about the semantic mode, see A Deep Dive into the Semantic Model.

1 Like

I admit that I may not be the brightest in the room.
I read the Concepts section before starting and was not a lot further ahead at the start. In fact, I was a bit baffled, as I wanted to ‘play’ with OH before committing to it. I wasn’t sure if it would be great or not, and with several other options, I figured I’d give it a test, and if it didn’t work, I’d just go elsewhere.
So I read that section and could not figure out how to get my weather station connected. :facepalm:

I left it out of my intro, because it was too complicated for me at the start.
I was committed to OH because I like open source software, understood the architectural limitations of HomeAssistant, and didn’t believe NodeRed would do what I wanted, and be as stable.

So I pressed ahead until i was able to make a simple http thing and read something from a smart device I have which has an api.
I’m not a developer, so maybe that’s the limitation…

The point of the Concepts section is to level set. OH has a number of terms of art: Item, Thing, Channel, Rule, etc. The concepts section of the docs is the only place where these are fully defined and described.

But the Getting Started Tutorial is supposed to be that “hands on” set of instructions that show you how to “play”. If you skip either or both, you will spend a whole lot more time and whole lot more of that time in frustration and confusion.

I’m not saying that either sections are perfect and cannot be improved. But given the complexity of OH and the limited set of volunteer hours devoted they are currently the best we can do.

I also want to point out that it’s more efficient to click “create equipment from thing” at the bottom of the Channels tab. That will create the parent Equipment Group, place it in the desired Location, and let you create Items for up to all of the Channels for that Thing all in one go.

2 Likes