How to figure out how to do something in openHAB 3

Tutorials & Examples Solutions
1

I admit it. I’m getting grumpy. I’ve been somewhat appalled at the number of users who seem to turn off their brain as soon as they post on this forum and do not think to do even the most basic things to help solve their problems. The purpose of this post is to give you a jiggle and maybe reengage your brain.

When I have a chance to calm down a bit I’ll probably work this into a page in the Getting Started Tutorial, with edits of course.

How do I …

Everyone, from the expert to the first time user is going to encounter something they don’t yet know how to do in openHAB. There is no shame in not knowing how to do something. We all have to start somewhere. So how do you figure it out?

Look in the docs

Even if you think you know, look in the docs again. OH changes with every release and not every change gets announced, or you may have missed the announcement. So be sure to frequently return to the docs and look for changes. There may be a better way to do it now. There may be more information. Something may have been removed or the behavior changed.

So particularly if something worked before but doesn’t work now, the first place to look is the docs.

Text file users

Look in the UI. Set it up in the UI. Take note of the options that are presented to you. Pay attention to the notes under the fields. Look at the code that is generated when you set some fields. To some extent, the UI is self documenting and often that is much more effective than the written docs. The UI is also constrained. It won’t let you create an unsupported configuration (most of the time).

So if something isn’t clear or incomplete in the docs, especially when creating Things in .things files, look at how to do it in the UI. Frankly, if you refuse to use the UI even to learn you are basically cutting off your nose to spite your face.

What does this button do?

image

Channel your inner DeeDee. Push the button! In the time it takes you to ask on the forum and for someone to reply you could have just done it. Don’t be afraid to click around and try stuff. I promise, there is no self destruct button. Watch the logs as you do it.

I did X and it didn’t work

Before posting on the forum, look in the logs. I’ll be the first to admit that the errors in the logs don’t always make obvious sense, but often they get you pretty close to what the problem is. Sometimes the lack of logs is going to be informative.

Logs will be the first thing we will ask for, so save us all some time and look at the logs to begin with. Post the logs when you ask your question.

My Rule didn’t run, why?

First you need to make sure. If you haven’t added logging to your rule, unless you know where to look (more on that in the advanced section below) there will be no evidence in the either openhab.log and events.log if your rule ran or not. Only if there is an error or you added logging to the rule will there be any evidence that the rule ran.

Sometimes you can infer that the rule ran based on the events that take place in events.log.

Add lots and lots of logging to your rules

It is pretty frustrating when a user posts a bunch of code with basically “it doesn’t work” or “I get an error around line 12” or something like that. The first thing you need to know to figure out what is going on and the first thing we need to know to help you is what is going on in that rule at the time it runs. What are the states of the Items that are being used? What is being returned by that call to persistence? What was the result of that calculation? What are those variables set to?

The only way to definitively answer these questions is to log them out. Before opening a new thread asking for help, you will drop by more than half the amount of time it takes for us to get you to the answer if you add this logging and posted that in your original post. You will most likely figure out what is wrong on your own and not even need to post.

If you have a particularly thorny problem, every other line of your rule should be a logging statement.

Advanced Ways to See What’s Going On

OH 3 brings a number of new tools to see what’s going on that can be very helpful. But OH 2 and before also have a number of features.

Binding Trouble

Change the logging configuration to put the binding into debug or trace level logging. The easiest way is from the Karaf Console. See the docs for details. If there really is a problem with the binding, we on the forum and the developers will need those lower level logs to see what’s going on and help.

Following Events

events.log has all the Item changes, Item commands, and Thing events. In OH 3 the Developer Sidebar event stream will also include Item updates, and Rule events. So between the two you should be able to see every event that is taking place in OH over a period of time. Use these to answer questions like:

  • Did my Item update?
  • Did the rule run?
  • What state is my Item in?

Write throw away code

OH 3 has a --Scratchpad-- Script Rule accessible from the Developer Sideboard. Use this (or your own equivalent) to send commands, post updates, log out the states of important Items, and do any other exploration or testing necessary to figure out what is going on. A couple of lines of rules code can often tell you a ton of information.

Run the rule by clicking the play button in the UI and how ever you prefer to do so if using text based rules.

Developer Sidebar

Use this tool. This tool is probably the most useful and important new feature added to OH 3. From this you can:

  • See all the events your OH instance is generating (filterable)
  • See and set of Items, Things, or Rules that is relevant to what you are working on at the moment. This can be particularly useful to see the current states of the relevant Items.
  • Enter and test out Expressions used in MainUI widgets.
  • Access the --Scratchpad-- Script Rule
  • Create a custom menu of shortcuts to perform various activities.

Look at the JavaDocs

Every time you are interacting with openHAB from a rule, no matter what language it’s written in, you are interacting with a Java Object. All of the Java Objects that make up openHAB are pretty well documented at Overview (openHAB Core 3.1.0-SNAPSHOT API). So if you are wondering what you need to import in order to create a timer, search for “createTimer” there and you will see it’s in * org.openhab.core.model.script.actions.ScriptExecution. Want to know what all you can do with an HSBType (state from a ColorItem)? Search for HSBType and you’ll see everything it can do.

Especially if one is using JavaScript or Python and wants to do some of the more advanced stuff like mess with metadata, create rules, etc and do not want to use the Helper Libraries.

Helper Libraries

Speaking of the Helper Libraries, if using JavaScript or Python, even if you are not planning on using the Helper Libraries directly, you should always use them as the first place to look for how to do something .

When you do need to post to the forum

Please please please make sure to read all of the replies in their entirety. It’s no fun to have to type in the same answer over and over again. Definitely ask questions if you don’t understand something in a reply. But it is very frustrating when asking a question that is clearly answered in a previous reply.

26 Likes
2

Second

3

Full ACK of course. Rich please just change your saying.
Make it “shoot (in) your own foot (or knee)”, that’s well known to those many Germans to read this.

1 Like
4

There is a difference in idioms though. Shooting your own foot implies it was an accident.

From the Cambridge Dictionary:
" to do something without intending to which spoils a situation for yourself"

“Cutting off your nose to spite your face” is more deliberate. You are deliberating doing something that will cause yourself harm. It’s no accident.

If’ it’s too confusing I can remove it entirely, but changing to shooting your foot doesn’t capture my meaning. I’m mainly talking about those who want to be “pure” and don’t even install the UIs lest that pollute their pure text configurations.

2 Likes
5

This can’t be emphasized enough. To this day, I still feel a little oafish when I have to resort to this, but I do it anyway. When I do it, the odds are, I’ll have the problem solved in the next few minutes.

I think for many beginners (those less accustomed to thinking through code line-by-line) the hurdle here might be not quite understanding what the logging every other line can truly accomplish. Maybe if you include just a couple of example lines people hesitant to use logging can see the different kinds of troubleshooting that good logging can accomplish.

1 Like
6

Useful tips - read them twice to internalize.

Two bits of feedback - feel free to delete if at all objectionable:
1 - As an intermediate user, I think most of the time I post, it is out of frustration as I have already spent hours trying to figure it out (hitting most, if not all, of the points listed). Most of the time, I solve my own problem by typing out the issue and never submit.
2 - for the newbie, sorting out logging in linux/openhab is frustrating. I think it would attract more users if it was more UI configurable. Frontail in OpenHABian is what saved me from giving up on the platform.

6 Likes
7

This is so true. You gain a ton of perspective from trying to explain something to another person.

When you’re struggling to write something, one of the best strategies is toss out your first draft and start over from scratch. It gives you a clean slate, but with the benefit of having organized your thoughts. I think the same applies to solving problems in openHAB.

1 Like
8

I agree with you. I am not an expert and have just started using JavaScript and not knowing what command to search for is half the problem.
You only spent hours and got frustrated I have spent weeks trying to nut out how to do something. It is really hard just to find a working example on how to do something.
I still cant figure out how to do a widget, but that’s for later on. I have all my rules in JavaScript now and they work.

My latest frustration was trying to search through json data and find a key and then if any data for that key had dashes in it then replace it with an underscore. I eventually worked out a way to do it in one line of code (if you don’t count the function I had to do, and finding information about how to do a function was difficult as well. Wording the question in Google was also hard as I got a lot of irrelevant information.
If you are interested in how I did it…in case someone else may stumble across this here it is:

//More information here: https://openhab-scripters.github.io/openhab-helper-libraries/Guides/But%20How%20Do%20I.html
var OPENHAB_CONF = Java.type('java.lang.System').getenv('OPENHAB_CONF');

//need below to log to openhab.log file
var logger = Java.type('org.slf4j.LoggerFactory').getLogger('org.openhab.rule.' + ctx.ruleUID);
//below is if you are going to use the ececute command
var Exec = Java.type("org.openhab.core.model.script.actions.Exec");
//below is also neede for the execute command
var Duration = Java.type("java.time.Duration");

var HttpUtil = Java.type("org.openhab.core.io.net.http.HttpUtil");

//because icon names with dashes in them are reserved I replace the dash with underscore
function input(i) {
    return i.replace(/-/g,'_');
}

var DATA = HttpUtil.executeUrl("GET","https://api.weather.bom.gov.au/v1/locations/r659gg/forecasts/daily", 2000).replace(/icon_descriptor...\w+/g,input);

events.postUpdate("BOMdata", DATA);

I still don’t know if this is correct or not BUT it works.

I have used the forum and have received help and enough clues to get me going and that is greatly received.

Also with the helper libraries I don’t know what I am supposed to do with those? I copy them into the scratchpad and run them but they don’t work.

Apart from all that I am happy with Openhab 3 and the forum, and yes it can be frustrating but it is fun eventually when it works.

I have done a weather forecast page using Australian BOM data and I will put that up on the forum later or should it go onto github? Problem is I don’t know how to use github.

Thanks

9

Ha! The ‘helper library’ is a topic is something I skipped over addressing. So many times I try to do something and it doesn’t work and searching the forums there is a ‘better’ approach, different language or new version I should be using to achieve what I am trying to do. My reaction is usually ‘cool’! But then three hours later I still don’t have the new thing working and can’t remember what problem I originally tried to solve. Meanwhile the wife is like ‘how complicated can it be to turn off a light at a certain time?’

I agree that when you have success the endorphin release is great, and why I stick around.

Helper library added to my ‘to do’ list to investigate tomorrow.

1 Like
10

I’ve already an outline that talks about that will go into the Getting Started tutorial. But I’m waiting for the UI pages to finish going through review before I start in on the rules stuff. But there will be examples.

Then your brain hasn’t shut off and this post isn’t directed at you. You already know how to do some of the bare minimum steps to try to figure stuff out. As long as you tell us what you tried when you ask for help you’re a star.

What drove the post above is the growing number of posts from cargo cult programmers that always seem to be:

“This used to work in OH 2.5 but now it doesn’t work, what’s wrong?” followed by some code that never could have worked in any version of OH that has ever existed and no indication that the poster even bothered to look at any logs. And then we need to play 20 questions and extract the bare minimum amount of information like an infected tooth. It’s time consuming and frustrating.

But it’s not and until someone does something about that (which isn’t going to be easy as a whole new REST API needs to be created plus integration with third party libraries and such) we have what we have. But if looking at a file on the file system feels icky for some reason then maybe home automation isn’t for you. Home automation is hard. It requires working on the command line, even in OH 3.

The OP is mainly just a list of what should be the basic common sense first steps to figuring out how to do something in OH 3 or solve a problem. At least the stuff before the Advanced section is that. The Advanced section includes those things that I would expect an intermediate to advanced user to do. But they are not intended to be a way for all users to solve all problems. They don’t replace the forum. They are not a replacement for docs. If you do all of the above steps and still are stuck, please post to the forum and we can help. Just be sure to tell us what you did.

So what is driving you to use Java Script? Is there something you can’t do with Rules DSL? There is no reason one needs to move from .rules files if what you have works. There is no reason one needs to move from Rules DSL even if you move to the UI. So why go through this pain? Unless you have something that doesn’t work now and won’t work in Rules DSL there is no technical reason to change.

Even when the OH Docs are improved, it’s not going to cover the basics of the language like creating a function. Even for Rules DSL we point at the source language Xtend docs, we don’t teach you how to program in Xtend. If figuring out how to create a function is a challenge, perhaps some basic JavaScript tutorials would be in order. All you will find here is how to write JavaScript rules, not JavaScript basics of the language.

If it works, by definition it is correct. It may or may not be the best way, but if you are happy with it who cares if it’s the best approach. As long as it works and you understand how it works that’s all that really matters.

The readme at the link in the OP contains a link to the doc for the helper libraries.

The documentation is located at Helper Libraries for openHAB Scripted Automation — openHAB Helper Libraries documentation.

There are extensive docs for installation and use of them there.

image
image2368×1440 324 KB

Pay close attention to that “But how do I…” section.

And, as I said, you don’t want to use them, you should at least look at the actual code to see how to do something yourself. For example, I want to know how to set metadata on an Item in a Rule using JavaScript. I browse to openhab-helper-libraries/Core/automation/lib/javascript/core/metadata.js at ivans-updates · CrazyIvan359/openhab-helper-libraries · GitHub in the source code and see all the ways that the Helper Library interacts with Item metadata and from there how to write similar code for my use case.

But again, theses are not going to teach you the base language. If you don’t know JavaScript or Python already, you’re not going to find enough here to teach you the basics.

And here’s a big secret. I don’t know nearly as much about all this stuff as it appears. I just know where to look. And now so do you (and everyone else who reads the original post).

11

I agree

12

I admit it. I’m getting grumpy. I’ve been somewhat appalled at the number of users who seem to turn off their brain as soon as they post on this forum and do not think to do even the most basic things to help solve their problems.

Given that the current documentation is very OH2 focused I think you can maybe tone down the attitude a bit, and recognize that especially for newbies, learning from example and RTFM can be extremely confusing.

1 Like
13

My attitude is my own and I will keep it and present it as I choose. If I doth offend, block me and move on.

I’ve been taking every spare moment I can writing/editing the Getting Started Tutorial. I’ve been helping tons and tons of new users and trying to get as many useful examples on the forum. I have earned the right to “have an attitude.”

4 Likes
14

I won’t speak for Rich’s intention with the OP, but my interpretation isn’t that his frustration is with new users. It’s with any users who don’t put in a reasonable effort before posting questions to the forum. As a regular in this community, I’ve also perceived that this behaviour has increased lately, and it’s affecting how charitable I am with my responses.

OH3 being new isn’t an excuse for not trying. If you’re willing to show effort then we’re all happy to help you, and this post doesn’t reflect on you at all. But there are a lot of recent posts where it feels like the users just want us to provide personalized, step-by-step instructions.

As a fellow community member, I’m really hoping this won’t turn into a flame war. So with the friendliest of intentions, I’d ask for you to understand our perspective on trying to help others before making this more contentious. Thanks!

5 Likes
15

Yes, you have the right to your attitude. But assigning motivations to people who post questions to the forum, particularly by insulting them with phrases like “turn off their brain” is not the most productive way to engage with the community. And you’re clearly aware of that, given this:

When I have a chance to calm down a bit…

Sometimes people post basic questions because they are confused. Maybe they missed something obvious in documentation. Maybe they got frustrated trying to figure things out for themselves. Maybe they only have so much time to devote to “just trying to get X to work” because the dogs need to be fed, or there’s a stack of dirty dishes in the sink, or they still need to sit down and pay bills. Who knows?

Yeah, it’s frustrating answering the same basic questions over and over, especially when you’ve written documentation. I know. Believe me. I spent the last 10 years writing technical documentation, and the 17 years before that doing Linux systems administration which included a large stint as front-line support, for a company of highly competent engineers. In that time, I fixed users issues by plugging in monitors and powering on systems that were on their desks, and answered questions from the community that were clearly and explicitly stated in the documentation. It happens. Even smart people make silly mistakes, or fail to read a document.

But venting at the people you are trying to help is counter-productive. It may be your 100th time answering a question, but it may their 1st time asking it.

4 Likes
16

THIS

17

Moderators cannot be blocked.

Screenshot_20210319-161629~2
Screenshot_20210319-161629~2720×805 31.5 KB

4 Likes
18

Then this post isn’t for them. They’ve tried stuff. They’ve tried to do the obvious. In the past week I’ve seen several “what happens if I do X” posts. Just do it and see what happens! If you’re the type of person to just do it, this post isn’t directed at you.

I am happy to help people get past confusion and misunderstandings. But there has been a huge growth in people posting who don’t even try.

And maybe I have the exact same time constraints. This isn’t my job. This isn’t my life. So how is being rude here? The person who uses up my time asking questions they could easily answer themselves just by clicking on the button or the person who, despite knowing it’s not going to be appreciated bothers to answer?

That’s not the issue. I’m fine with that. All those Design Pattern posts and tutorials I’ve written were created to solve that exact problem. Instead of typing how to clear the cache over and over, just link to a tutorial. Easy peasy.

My problem is with users who don’t even try to do even the most basic things themselves. And these are not new users. These are people who claim “I’ve been using OH 2 for months/years. This code used to work but now it won’t in OH 3” and then proceed to post code that never could have ever worked. These are people who have experience with OH and should know better.

I do not fault new users for not knowing things and being confused. But if you’ve been using OH for awhile, I expect better. I expect you to at least know to look at the docs again. I expect you to know to look at the logs. To add logs to your rules when something doesn’t work. To experiment and try clicking on stuff to see what happens. They are not newbes any more, they should know better.

These are the users who have turned off their brain. The intermediate/experienced users who won’t do the bare minimum to help themselves and expect us to do all the work.

I didn’t know that. I’ll gladly give up my moderator status if it’s a problem.

1 Like
19

Please don‘t !!!

8 Likes
20

Rich, first up, thank you for everything you do to help those of us who don’t have the time and experience with openHAB.

In my experience, the biggest challenge around learning openHAB is the misalignment of the documentation with the current version. It feels almost impossible to know if the version you’re on matches what the documentation was written for. Take HomeKit in 3.0 as an example. Since the release, as far as I can tell, it spoke to a QR code being generated at the setup screen. Of course, my openHAB install didn’t start displaying this until one of the 3.0 milestones, but I spent countless hours trying to figure out why my HomeKit install was “broken” in vanilla 3.0. This same behavior occurred again regarding Color Temperatures in HomeKit. Apparently this functionality is broken - causing HomeKit to fail without any logging of the issue. The documentation doesn’t indicate this at all.

I don’t say this to point blame at the tools, but simply as an example of the challenge it presents. It feels like half of the time I run into a problem on openHAB, it’s my lack of understanding (maybe even as to how to name and troubleshoot the problem) and the other half it’s some kind of bug I have to wait to be resolved. But I never know which it is because I can’t know what I don’t know. These issues, for me, are exacerbated by the fact that things like the rules DSL aren’t standardized across versions. Rules that work in 2.0 may not work in 3.0, especially time/date related activities. Of course I understand this now, but the average newbie coming in, snagging code from web or forum sources and trying to learn is going to have a frustrating path before they figure this out.

I would also say the logging in openHAB, while it can be comprehensive, is difficult to understand. It can be hard for a newbie to figure out how to activate the proper logging levels and view the logs you need specifically. Further, openHAB errors can be opaque. Frequently errors are presented as stack traces that can be incredibly difficult to track to what is actually occurring. And one last comment on logging: I hope that better log management and viewing is on the roadmap to getting into the UI. It’s difficult to tell people “use the UI for everything” and follow that with “except logging, which is a series of arcane log level settings based on modules that you don’t even know exist until you find it in the forum somewhere or end up deep in GitHub”.

3 Likes