Should I start with OpenHAB 3 now?

I am gradually getting started with OpenHAB 2. I can’t claim that my setup is very sophisticated yet so I’m wondering whether it makes any sense for me to continue learning and setting up v2 or whether should rather start off anew with v3 right away.

The tradeoff seems to be the flowing:

  • if I stick with v2 for another while, I benefit from the excellent documentation (one of the reasons I opted for openHAB in the first place) but I will eventually have to migrate and re-learn certain things.
  • if I start anew with v3, I will have to do without documentation (or use the old documentation and be confused) but save the hassle of migrating later.

I’m posting this question here because it’s very difficult for a beginner to estimate the costs and benefits in both scenarios. Could someone provide an indication what how big the differences between v3 and v2 are in practice?

This is a good question. As you mentioned there are a lot of documentation examples available for OH2 which are not available for OH3. So it will be easier to learn OH2. Also if you updsate to OH3 there is not a big migration needed. Most of your rules will still working (if you are not using special features like Joda Time for time calculation)

But from my point of view I would start with OH3. This is much more user friendly and allows you to configure nearly all options inside the web interface. Also there is a new feature “Model” wich allows you to create a semantic model of your house. This model will build some location and equipment pages out of the box for you. If you decide to move later to oh, you need to build the Model later and this might take some time.

Also if you want to write rules you will love OH3. It has support for JavaScript out of the box. Also there is a new rule designer BLOCKLY which allows writing rules by drag and drop some operators. So for small rules here is no deep programing knowlege needed for defining rules.

If you decide to change to OH3. Do not use the milestone 4 release because this one was buggy and should not be used. Use the Milestone 3 or Snapshot release instead


I came into OH when 2.0 was ramping up to become stable and had a steep learning curve as doco was for 1.8.x and some was for 2.x; some of my own issues were probably some bad hardware selections causing me other issues.

Eventually just went with 2 and started working on making things work to make things convenient for me.
I’ve done some testing in a VM and the missing documentation does make the newer features like Model confusing (to me) and how I can integrate it to what is working for me. I spent a couple of hours last night in the Dev section here reading up on the wiki posts.

I will probably wait until stable and then review the bindings I use to confirm they still function on the new OH release; which should also provide more time for the documentation to be flushed out with the new core features; getting my smart things to work in the bindings will probably the easy part of OH 3.

If I were brand new and asking for which version to go with, I would say go with OH 3; but read through how things/items and the various bindings work as most of what I have read through seems to be the same as OH 2.

If you are starting, I would jump directly to OH3, you’ll enjoy new GUI


I think there is more documentation than you think at

I think most of these are slated for inclusion in the official docs. Also, look at the PRs in the openhab-webui repo and there is a ton of great low level info for how to really customize pages and such.

Also, the vast majority of knowledge that you already possess and the vast majority of the existing OH 2 docs are still applicable.

But even at this point OH 3 is somewhat of a moving target with significant changes and new features being added almost daily. To keep up you need to be upgrading at least once a week. And sometimes those upgrades break things. And we would ask that if you do run OH 3 to please go to the links above and help us with the contents and to file issues.

That’s hard to answer and it largely depends on how you want to use OH 3. Do you want to continue doing stuff the same way you’ve done it in OH 2 on OH 3? If so the differences are pretty minor. PaperUI and HABmin are replaced with MainUI (which will have lots more options). There are some minor changes in rules and now JavaScript and Blockly (graphical programming of rules, similar to Scratch) is supported out of the box with an add-on for Groovy and another one for Jython on the way.

However, if you want to go all in for OH 3 the changes are quite significant. Now pretty much everything except for persistence policy files can be done through the UI, and the UI has lots of features that make working in much better and more efficient than PaperUI.

There is a new emphasis on the semantic model for your Items. If you spend the time building the model than MainUI will build most of your user’s interface for you.

Or if you don’t like the generated one you can build your own pages with all sorts of controls that were missing from sitemaps including stuff like the ability to enter text, date time pickers, etc.

Rules can be enabled, disabled, and call each other. You can import libraries into your rules (not Rules DSL).

Those are just a few of the new features and improvements.

Unless those examples are based primarily on PaperUI, they still apply in OH 3 with only very minor changes (maybe).

The changes between OH 1.8 and OH 2.0 were greater than those for OH 3.

Correct. And if you primarily use text based configs all that stuff applies as well. You could, if you wanted to, ignore all the new stuff and use OH 3 pretty much the same as you did in OH 2. That’s the primary reason why I push back just a little on the “there are no docs” arguments. There really are because the OH 2 stuff still mostly applies. The only things where docs are somewhat missing is for the stuff that’s new in OH 3 (Pages, having a UI to build the model, a working UI for rules, etc).

Having said all that, I’ll join the chorus. I’d recommend getting started or, if you haven’t invested too much in OH 2 yet moving to OH 3 now.



Please tell me it’s 30° F and not C :grinning_face_with_smiling_eyes:

1 Like

Yep, I live in the mountains of Colorado. It’s snowing right now. It’ll be down to 12 degrees F tonight. A pretty typical December. :slight_smile:

1 Like

For sure, and starting off with two light switches that would stop responding to OH if I restarted the OH service and to quickly fix was to walk to them and cycle them ON and then OFF. Switching to zwave hardware and then seeing a good example of how ‘Things’ work I was able to build my OH 2 system and to not read documentation that wasn’t pre-OH 2. :slight_smile:

I’ve also come to enjoy NodeRed with OH 2, while I am going to read up on the changes to the new rules style; I’m also hoping I can continue with it as I’ve come to really like it for my setup, but better to be prepared in case that day never comes.

I’ll play devil’s advocate on behalf of users who are less technically skilled.

I think this is a great question, because right now it’s difficult for a brand-new user who has no experience with OH to perceive the differences between OH2 and OH3. There’s lots of forum traffic with people figuring out OH3 problems, but in many of the posts it’s not clear that people are intentionally trying to work out bugs in the Milestone. For new folks, it just comes across as “I have an OH problem, please help me solve it”. That’s purely because they don’t have enough familiarity, and it’s confusing.

You also can’t install OH3 using the beginner-friendly openHABian image that is still based on OH2. Yes, you can use openHABian to upgrade, but that adds complexity to the installation process. I would say that I’m more technically savvy than the average person, but I had barely touched Linux before installing openHAB and I can tell you that was very daunting due to my inexperience.

We have lots of things written in various places about OH3, and if you’ve been keeping up on the development then I imagine it’s easy to grasp all of it. But as far as I’m aware, we don’t have simple, step-by-step instructions for onboarding a new user and quickly getting them to the eureka moment when they control a lightbulb through OH. Until that’s the case, I don’t think we should encourage brand-new users to make the jump to OH3. Yes, there are technical benefits, but it’s much harder to get to the point where you can appreciate those benefits.

I think this is really important to reinforce, and it’s a large part of why I think OH2 is the better starting point. In theory, the upgrade will be easy to do later on. The only thing I perceive that’s missing is some of the new ways to write rules. But again, I’m not sure that a new user should be tackling those until we have the ability to support their efforts. DSL may not be great, but we can at least help someone wrap their head around it. And then they can either use those DSL rules when they upgrade, or apply the logic they’ve set up with one of the new methods.

I do acknowledge that it’s not ideal to have people start out with PaperUI. That would actually be my biggest reason for pushing to OH3.

Again, I’m just trying to speak for the new users with minimal technical skills. I wouldn’t stop anyone from starting with the OH3 Milestone if they want to, but I think we need to recognize that recommending OH3 to new users at this point in time almost certainly makes it harder for them to get started. And if/when they run into problems, it’ll be harder to troubleshoot. That’s a recipe for frustration that may cause people to walk away.


That’s what [wiki] Getting Started with OH3: rewriting the tutorial - 1. Introduction is supposted to be. If you can contribute, even if by highlighting sections or passages that are not clear, please do so. They are wikis so you can edit them as well.

OP isn’t a brand new user though. He’s has some experience with OH 2.5 already. My answer was for him, not the generic new user. I’m ambivalent about truly new users. Selfishly, I’d like to get some truly new users to start “testing” the Getting Started tutorial. And even with the challenges with installation right now, I think that tutorial is already better than the OH 2 getting started tutorial (that was never finished) so in a lot of ways, the docs for OH 3 are even better than they currently are for OH 2, as incomplete as they may be right now. For references, the old OH 2 docs are still mostly if not completely valid.

I personally have been using OH 3 as if I were a new user. I’m not migrating my config to it, I’m recreating it on it. Everything that can be done in MainUI I’m doing through MainUI (and I’ve filed lots of issues as I go, most of which Yannick has been very quick to address :smiley: ). I’m even rewriting my rules as JavaScript though MainUI. And I have to say that the way that MainUI presents things and the stuff it does for you certainly pushes one to approach, think about, and implement the home automation in a different way. As a result, I fear that some users who are just getting started now will have a hard time moving to OH 3 later because the mental model that was built up of their configuration isn’t quite presented in the same way.

The semantic model is a really big part of that. If one approaches their config from the model first everything goes soooo smoothly. Things are discovered, we create equipment or points from the Thing and all the Item stuff and the UI stuff just happens. I’m not even going to port my sitemap over to OH 3, there is no need. Switching to that kind of approach is going to be hard for many users, especially us old timers. But it’s so worth it.


Oh my! This is turning out to be a more difficult decision to make than I thought… But I’m happy you agree that it’s a relevant question and were able to provide equally relevant information.

I’m a bit torn between continuing this topic in a way that is useful for others (i.e. keeping questions it generic) and introducing parameters that are more specific to my own situation. So I guess I’ll do a bit of both.


How about docker? I’ve containerized (almost) all my stuff so for a moment I thought (hoped?) this might be the dealbreaker that makes the decision easier for me, but from what I can see, running OH3 M3 in a docker container is is just as easy as with OH2. Please add any caveats that my superficial judgement may have missed!

If dockerizing OH3 is not a problem (for beginners), then this may actually open up for a third solution: running both (each in their container, of course). I suppose it’snt a good idea to run both at the same time (though why not, actually, as long as I don’t set up rules for the same things - wrong terminology! Should probably be “items” - twice?), but I was thinking of switching between the two, so that my current OH2 installation becomes a kind of fallback option…


Several have mentioned rules as the locus of significant changes. Rules are important to me. I can do lots of automation without OpenHAB (e.g. with the built-in functionality of my Shelly devices), so rules is really a key reason to for using a system like OpenHAB.

One important principle I learned in OH2 is that I should use Visual Studio Code (VSC) to edit my rule files and I really like it (the code completion is just excellent and helps so much when you’re not yet familiar with the syntax). If I remember correctly, the reason for using VSC was that it’s both more robust and more flexible to go via the rule files rather than the web UI.

So, for me, a big part of continuing with OH2 would mean to familiarize myself with how to write rules. From what I read above, however, that may not be the smartest investment to make. I understand that the rules will continue to work, but with blockly being available in OH3, I don’t see the point in learning the old way. In fact: one of the things that originally troubled me with OH2 was that Blockly (or a similar visual rule engine) was not available. And if I need to code rules as text, I’d rather learn javascript, for obvious reasons. Doesn’t Blockly actually produce javascript so that the question of UI based configuration vs file-based config becomes somewhat obsolete?

Documentation (and technical skill)

Thanks for the pointers to the emerging documentation. It’s good to know where to turn to, even if it may be incomplete. I will have to take a closer look to tell how helpful it will potentially be for me.

Which leads me to the question of “technically skilled” vs “technically less skilled” users. Define “technically skilled”. I guess anyone who starts to use OH is already rather technically skilled. So, for me (no formal technical education or vocation), it’s more a question of how much of a bobby I want home automation to be. And for me it is clear that while home automation is fun, I don’t want to spend more time than necessary with it. And by necessary I mean: necessary to get stuff working exactly how I want them to work. So I’m willing to invest some time, but not for fun, just for good results.

So this is why documentation is important to me. If there is a ready-made solution that I can adopt, I’ll do exactly that. So it’s not only the official documentation but also forum content. It looks like with OH2 I have a good chance of finding copy & paste solutions whereas with OH3 I see myself posting questions to the forums rather than reading existing ones…

Bindings and setting things up

The other kind of task that I will be working on in OH is adding things (I think the terminology is correct here). Judging by the replies above, I will not encounter more (but probably less) problems doing that in OH3 than in in OH2., i.e. all bindings supported in OH2 are supported in OH3. Is that correct?

So? If each of my four headings pushes me either towards OH2 or OH3, where do I end up? (And don’t say: it depends where you start off, LOL)

Rich, so the mew semantic model is replacing sitemap? Would it look good on an Android app? I like sitemap because it allows creation of UI that looks good vertically on a small screen. Does sitemap syntax get some more love in OH3? Thanks.

I think your approach is a good one. I just thought it important to bring context for the benefit of truly new users who might come across this thread and think that it applies to them. Actually, I suppose that’s what I’m really trying to say: new users don’t know enough about OH to know which information applies to them (or not).

Yeah, I also have this concern, which I alluded to when I mentioned PaperUI. And again, I haven’t used OH3, so this statement definitely moves me in that direction.

The thing about the wiki posts are that they present as work in progress, not as documentation that’s ready for prime time. I don’t think it’s an obvious starting point for a new user, but maybe I’m wrong about that.

Perhaps what we need at this time is a sticky post that condenses this and other discussions into the pros and cons of starting with OH2 or OH3, written for the brand-new openHAB user (and still valuable for people with prior OH experience)? I think it would probably lean people toward starting with OH3, and that’s fine if they know what the challenges will be going in. I’m less concerned about new users being confused and frustrated if we can get them pointed in the right direction right off the bat.

Really, this is just change management, which is hard enough when you actually have someone responsible for managing the change.

Yes, I run both in docker and it’s the same as it ever was.

Official images for OH 3 are available on dockerhub, though I find the snapshots tend to lag a bit at times.

As long as they are configured to use different ports and only one instance attaches to hardware like Zwave controllers at a time it runs just fine with both at the same time. Or you can stop one and start the other pretty easily. I have mine running on a separate VM but that was just because it was more convenient and I had a VM to host OH 3 on while I develop.

Yes and no.

First of all, you can write rules in JavaScript and Groovy now and Jython soon in addition to Rules DSL and Blockly. And indeed, Blockly does generate JavaScript.

But there are two ways to write rules. One is through text based files which is like the .rules files only with different syntax of course. There are helper libraries for those which make writing and editing easier. You can find lots of examples on the forum. All of these files get parsed when OH starts up or the files change and any rules they define get recreated. In MainUI they will be read only. You cannot change them.

The second way I often called JSONDB rules. These are rules that are stored in the JSONDB. That is where Blockly rules will be stored. Any language supported by text based rules are also supported as JSONDB rules. But these rules have differences. They are only created/updated through the REST API which means you’ll be creating them in MainUI for the most part. They tend to load faster I find (my OHI 3 reboot time right now is about 15 seconds). There are some bugs that only crop up with text based configs as well. These rules have a “but only if…” conditional clause that can let you avoid even running the rule unless certain conditions are met (I put error correcting code in there too). And these rules will be editable through the web based UI.

People were warned off of using rules this way with PaperUI because PaperUI is horribly broken. MainUI is working quite well though and getting better all the time.

NOTE: I don’t know if the Blockly implementation is complete so caveat emptor.

The old way of writing rules (Rules DSL or any of the other languages in 2.5) are still supported. But I’m finding writing rules through MainUI quite nice and productive. And I love how fast my boot times are. Though I’ve only moved about 20% of my config over so far.

So file based vs UI based is still applicable. You’ll have to choose. I will be recommending UI based to all from this point forward.

Not necessarily true at all. There are lots of people who jump in with little to no technical skills. I would define “technical skilled” as someone who does computer type stuff for a living or hobby. Software developers, systems administrators, and the like. These users already have a lot of skills and knowledge that is applicable to openHAB and home automation in general. Non-technical skilled would be someone who has never used a command prompt. Obviously it’s a spectrum with most people falling somewhere in the middle.

First thing to know is all those OH 2.5 examples still work! We are not starting over from scratch. There will likely be a couple of rules of thumb to watch out for but that’s it. Also I will say that “get stuff working exactly how I want” and cargo-cult programming (“finding copy & paste solutions”) tend to be mutually exclusive. If you want it to work exactly how you want, you need to know exactly how it works.

And with OH 3 we will start to see more and more ready made examples that you can just install and use. For example Eventually these will be installible just like add-ons.

All 2.x version bindings (those that support Things) are supported. Older 1.x version bindings are still supported in OH 2.5 but support is dropped in OH 3.

I can’t answer that for you. All I can say is were it me I’d use OH 3. But you are not me.

It’s not replacing the sitemap but, at least for me, the semantic model and the Pages in MainUI that get automatically generated from the model replaces the sitemap for me. I’ve no use for the sitemap now. Pages are less work, more flexible and the functionality is more complete than sitemaps so I don’t see myself going back to use them.

However, MainUI does have the ability to build a sitemap in the browser so you don’t have to continue to write .sitemap files by hand if you choose to continue to use them. And of course .sitemap files themselves are still supported.

I find it to look better but I never liked the look of BasicUI or ClassicUI in the first place. It was functional but not pretty. but as with sitemaps, the “cards” that make up the widgets presented by Pages get listed in one column. The only complaint would be that the information is a little more sparse than is presented in sitemaps, at least be default. You have much more ability to customize how everything appears in Pages though, even with the automatically generated Pages.

No, it continues to be supported but I don’t expect there to be any more additions or new features added to them going forward. It’s just too hard because any new feature or change requires changes to:

  • ClassicUI
  • BasciUI
  • Android App
  • iOS App

That’s because they are not. But that doesn’t mean they are worthless. And like code, docs need to be tested. And it’s sooooo much easier to involve the community in testing and contributing to the docs when they are wiki posts on this forum than it is when we have to force everyone to use Github to file issues and create pull requests.

If you want to wait for fully baked, complete, and excellent docs, you’ll be waiting for quite a long time indeed. I point you to the never completed, incorrect/inaccurate in some places, and only half done getting started tutorial for 2.5. IMO those wiki pages are already better than that.

I think focusing this on some random new user who happens along is mistaken. If they are not on this forum they will not necessarily even become aware of OH 3. OH 2.5 is going to be the only thing they find docs about. So we are talking about people who are at least reviewing this forum. And as such, I’ve posted the link to those getting started pages at least a dozen times just today. It’s posted in each and every one of the milestone release discussion threads. It may not be obvious just browsing around, randomly but if they read almost any OH 3 related thread they will find a link to them.

All I can really offer at this point is if no one else steps up and uses the docs as they exist right now in those wiki pages, and tell us where they are confusing or missing information, those wiki pages are going to get no better. Sure they might look “professional” once they get moved to pages. But the content is going to be no better, and at the end of the day, it’s the content that matters most.

If history is any indication, OH 3.1 will be out before such a discussion reaches a conclusion, if it ever resolves to a conclusion. And it’ll be 200+posts long that no one will read.


Just a quick clarification that I didn’t mean to suggest the docs-in-progress are worthless. I’m grateful to everyone who’s finding time to contribute and make this happen, so I don’t want to sound critical of anyone’s efforts. :wink:

1 Like

A quick reaction also from me (lots to think about otherwise, but that will have to wait until tomorrow (or rather: later today)

Of course. I should have said: “finding copy, paste & adopt solutions”. Example: I wanted the bathroom lightswitch to turn on the hotwater circulation, but only before noon and not before 5. I found this (if I remember correctly):

and turned it into this

rule "bathroom lights turn on VVC between 5 and noon"
  Item Shelly25_bathroom_light1 changed from OFF to ON
if(now.isBefore(now.withTimeAtStartOfDay.plusDays(1).minusHours(12)) && now.isAfter(now.withTimeAtStartOfDay.plusHours(5))){

I know the basic logic according to which it works but I don’t know if this is the best way of doing this or what other consequences this may have but it works and so I stop there. Hence “copy & paste” (plus X).

I see nothing wrong with that rule as written. It’ll have to change just a little bit in OH 3 though. now is probably the biggest change between the two that will hit people. In OH 2 it’s a Joda DateTime but in OH 3 it’s a ZonedDateTime and the methods are slightly different. It would be

if(now.isBefore(now.withHour(12).withMinute(0)) && now.isAfter(now.withHour(17).withMinute(0)))

NOTE: I’m going from memory, it might be of instead of with.

But in JSONDB rules you wouldn’t even need any code.

You can create the changed trigger with the from OFF to ON. Add a but only if conditional for “a certain time of day” and define the start and end time. And then use a send a command action.

The code view looks like

  - id: "2"
      previousState: OFF
      state: ON
      itemName: aTestSwitch
    type: core.ItemStateChangeTrigger
  - id: "1"
      startTime: 12:00
      endTime: 17:00
    type: core.TimeOfDayCondition
  - id: "3"
      itemName: aTestSwitch
      command: ON
    type: core.ItemCommandAction

Obviously you would use different Items. But for a simple rule like that you don’t even need to mess with Blockly level code. In my mind, this lowers the barrier to entry for “non-technical users” significantly.

1 Like

My view on this is it depends on the type of person you are.

If you are someone that has some time and can help with the OH3 documentation holes then 100% go with 3 as long as you can ask questions when you have problems. It is free to ask a question and the more effort and information the better the answer will be.

The new OH3 UI is very easy for someone with knowledge of openHAB workings to develop on. I think for a new user that is starting for scratch it will be the same amount of effort to learn the terminology and how it fits together.

So if you are someone who wants to help increase the OH3 documentation to make it easier for the next person. Document your problems from the beginning. What you or I can’t do is purge the information out of our brain to start again so we need intelligent people that are beginners to help.

There are many ways to contribute to openHAB and in my eyes every contribution has its caveat.

I can’t tell you how to contribute but know as a newbie like myself I do small chunks of changes and try and help people on the forums.

Within months you will be doing things like pulling apart a smart kettle to flash the MCU to free yourself from the cloud.


I consider myself a strong openhab 2 user, and excited for 3 but if Im honest and I know its not ready for prime time but I just cant work out OH3 - ive looked at the wiki tutorials and they all make sense but to get a sensible page with icons that do something I have not been able to - all the examples seem to skip over the bits to make them functional and screnshots show amazing things but all mine are groups or items that show a big NULL on them.

Id love some more beginner guides - im across adding items and coming to terms with the new terminology and seantic stuff its the UX thats stumping me.

How is a newbie going to dive into this?

  1. Continue to use sitemaps or HABPanel
  2. If you’ve built your semantic model, a ui is built for you in the Overview page’s tabs. You can customize how the lists and cards on that page look by setting the default widget metadata.
  3. Wait for new docs to be written. With the number if people contributing that might be a bit of a wait. We are all volunteers and there are not to many actually volunteering to help with the docs. Just yesterday I added about 20,000 words and a couple dozen screenshots.