I’m hoping someone can point me at (or explain here) the subtle difference between the Basic UI and the Paper UI and most importantly the interplay with all the various text and GUI config methods (including Items, Sitemaps, Things, Channels, etc).

I’ve managed to install and run OH2 on my Pi3 and I’ve got some very basic controls working, but I’m ultra confused about the different systems. I was hoping to do a purely GUI basic setup process and end up with (1) mobile app controls via the official native application and (2) a web GUI, just in case. I’ve got a Zwave environment to start (and the proof of concept device, an Aeotec socket, is controllable), but I’ve also got a Logitech Harmony, Zigbee devices, an Ecobee, and an IP based security system via Synology that I’d like to eventually sync into the same system.

I think I’ve thoroughly read the official document, but I might have missed something. I’m sorry for the relatively general post, that’s why I put it in the intro forum here.

Anyone willing to take a stab at some very general help? Very much appreciated.

If you want an all-GUI setup, I would recommend habpanel for controlling your devices. It’s easy to set up and don’t require any textfile editing.

Management (adding new devices etc) is best done through paperui, but since you use z-wave you should also install habmin, which is better in most cases at managing z-wave devices (setting parameters and associations for example.

The biggest problem with an GUI-only setup is the rules. Simple ones (if this item changes, send a command to that item) can be made using the experimental rules engine, but if you want more complex rules (which is the whole point of HA, no?) imo you have to learn to use .rules-files.

Just my two cents at least.

PaperUI is I intended to be used as an adminstration interface. This is the UI you as the home automation developer use to do things like add devices (Things) decided how to represent those devices in your system (Items), install and configure add-ons, and do some minor testing of the controls on the devices.

BasicUI, ClassicUI and the phone apps require the creation of over or more .sitemap files. There is no getting around using text config files for this. See the Sitemap section of the docs for details and look at the Home Builder add-on which will automatically generate a skeleton sitemap for you. These are user interfaces, i.e. the interface for users of your house.

You don’t want to give the average user of your house the power to modify your system (e.g. added or delete items).

Habmin is a good adminstration UI but I would not recommend it for the users.

If you want to stick to gui only, you can use HABPanel which let’s you build the UI in the browser, but it is web only

Also, as had been said, you will encounter limitations when it comes to rules.

Awesome - I don’t feel like I fully understand yet, but both replies here are helpful for me. As frustrating as it feels right now, I think I need to just muck around more with the different systems to see how they work. Quite frankly I feel let down by the documentation so far (sure it has examples but it doesn’t come close to comprehensively explaining each detail, at lest not that I’ve found yet).

Overall I’m definitely interested in OpenHAB as the rules engine for my home with all the expected fun bells and whistles, so I’m certainly willing to get into manual modification and tweaking. I was just hoping to get the basics configured at first (a nice milestone) then slowly add complexity as I grasp the different systems.

i think its worth 1 hour to see this video
most of your answers will be answered

If you have any examples of where the documentation is lacking, post them here so they can be improved. It’s often hard for someone who knows OpenHAB well (i.e. the people who write the docs) to know what a newbie would need to get up and running. Plus, everyone starts with different things, so be aware that a detailed step-by-step guide is not possible to write.

But I’m sure any hints on what could be improved are welcome!

I’ll go watch that video (haven’t had time during the week) - I’m definitely willing to invest an hour to learn this kind of stuff.

As for missing documentation, I’m definitely a visual learner. Is there any sort of “object relation diagram” that explains how Things, Channels, Items, etc all interact? In a very similar vein, is there a dictionary page? It would be very helpful to have a description of what each aspect of OpenHAB is especially something that calls out “differential” between stuff. For example (I’m trying here, but I’m not sure if these are accurate):

  • BasicUI := a read-only web-interface to control Things. BasicUI reads from an internal database or a plaintext things file, depending on which is specified in openhab.conf
  • PaperUI := a read-write web-interface strictly for configuring OpenHAB. PaperUI edits the internal SQLite database or the plaintext files for Things, Items, and Devices, as specified in config.txt . PaperUI cannot activate or control any devices or routines, except for occasional debug capabilities to confirm blah blah blah…
  • HomeBuilder := this is a web-interface to generate the following plaintext config files: abc.txt and def.txt . With one exception, this interface is ephemeral and does not actually store output anywhere (instead it displays configs to the screen/web browser, leaving it to the operator to know where to place those files). The exception to this rule is the option to store Items in a SQLite database, which HomeBuilder can do. Notably, when choosing to store in SQLite, HomeBuilder changes the settings for abcSTORAGESTUFF in the config.txt . If you want to undo that storage, read DOCUMENTABC linked here.

After writing that mock (which I made as real as I possibly could) I have a real question: what’s a Dashboard? Is BasicUI (an interface) essentially a way to view Dashboards (preconfigured groups)? Maybe Dashboards are only visible from HABPanel? I might be getting lost in a UX paradigm I subscribe to: Dashboards should exclusively be groups of shortcuts for frequently used or commonly necessary information/controls and Dashboards are a strict subset of a Complete User Interface . Don’t start fresh users with Dashboards… start them with Complete UIs then remind them “hey did you know you can take pieces of this Complete System and put them on Dashboards to re-order and filter however you want?” (make sense?)

These are the only relevant drawings I’m aware of.

Almost. “A Home Automation Users Interface to control and see the state of Items. The content, structure, and appearance of the BasicUI is defined by a .sitemap file. BasicUI interacts with OH through the OH REST API.”

"A Home Automation Administrator’s User Interface to configure and manage an openHAB server. PaperUI includes the ability to:

  • set systemwide parameters like default persistence engine, location, timezone, localization, simple mode, etc
  • install/uninstall and configure add-ons
  • discover/create/configure Things
  • create/configure Items including linking Items to Channels on Things
  • perform some binding specific adminstration such as setting parameters on Z-Wave devices
  • if installed, the abilty to write Rules using the Experimental Rules Engine
  • the ability to see and control the Channels on Things that have Items linked to them"

The configuration is stored in various locations in the userdata folder (on a Linux apt-get install that is /var/lib/openhab2). Items and Things get stored in JSON formatted files in the JSONDB folder. Binding configs get saved to config files in the config folder."

I don’t know much about HomeBuilder except to say the intent is it will generate .sitemap and .items files which go in the conf folder (on a Linux apt-get install that is /etc/openhab2), .sitemap files go to the sitemap folder and .items files go to the items folder.

Not SQLite, JSONDB. Hombuilder will go the the OH REST API (just like PaperUI does) to create the Items the same as if you created them by hand using PaperUI.

When you go to http://my-oh-ip:8080 a page comes up with a list of all the UIs you have installed (PaperUI, BasicUI, HomeBuilder, etc). That’s the dashboard.

See above.

HABPanel is an alternative home automation user’s interface that can be used in addition to or instead of BasicUI. It gets built in the browser instead of using .sitemap files or HomeBuilder.

Very helpful! I’m about 15 min into the video and there’s a ton of useful info. It seems there is a slide deck used in the video that, frankly, I’d ask to just put on the website. It has the exact diagrams I’m looking for along with commentary that explains them (but they stand alone fairly well). I’m not done yet, but so far so good!

Also the corrective definitions here are helpful. I’m going to wait to ask any follow ups until I’ve finished the video, which may answer all my questions!

So I’ve finally come back to take another stab at configuration and I’m almost immediately right back where I was before (feeling super let down). The first thing I’m trying to get configured is an Ecobee3 thermostat. The documentation is super confusing:

  • Why isn’t there a binding in the Paper UI? Is this a binding that requires text config? That’d be nifty to mention, explicitly, if that’s the case.
  • The documentation talks about generating an appKey and links to the prerequisites but that’s a useless link - there’s a single screenshot that doesn’t explain anything about how to get a key (yes, I’ve tried everything I can think of over at my Ecobee dashboard… it’s not obvious).

I have no idea how to proceed.

There is. It’s a V2 binding that doesn’t require a *.cfg file. It would say so in the binding docs

The link is the developer work just above the screenshot!!

Register your hardware and key a key!!

Could you please point me at the binding, precisely? I wouldn’t have posted if I could find it. Saying “it exists” doesn’t add much value to the community. Saying “here’s a link, screenshot, or a more detailed description” is much more helpful (thank you in advance).

Also I can figure out how to generate a key. There’s no obvious method.

OK, go to the ecobee website, register your device and enable your developer dashboard.
Get the developer key: Use the following link and log in

Here you should have the possibility to generate an API key. Since i do not have Ecobee devices i can’t tell. But maybe the best way would be asking Ecobee support how to obtain an API Key.

For the binding:
I also see only the V1 binding available and haven’t found a v2. So you have to configure everything in .things/.items…files.

In the provided screenshot of the Ecobee OH manual, please make sure that your remove the “#” from the api key and so on, since “#” means “commented out”.

1 Like

My apologies it a v1 binding
In the paper ui in configuration enable v1 bindings
Then go to the addons, bindings and refresh
The ecobee binding should be there

Hi @qwenxuep

When I first starting using openhab I also only wanted a gui setup as I was petrified by the seemingly complex text files involved I did start with paperUI and the experimental rule engine

I quickly realised that text is far better than gui only the rules and item files are very easy too create and edit with some learning and alot of help from peple here you all know who you are (Thanks) I still haven’t got my head around SITEMAPS ect

My point is you will learn don’t be scared of the text files you build them slowly

I cannot code but so far I’m very happy with my setup

So welcome too openhab and goodluck


Ok, I’ve enabled “Include Legacy 1.x Bindings”, which is what I think you meant, right? Proof:

I closed my browser, re-hit the Paper UI, and I definitely see more bindings, but there’s nothing relevant here, again, proof:

What obvious step am I missing?

Looks like my problem was an entirely broken ecobee developer site AND slightly misleading instructions. Fixing those:

  • Use precisely one time, just to register your developer account. You will never again use that URL - that is not where the key comes from. That site takes you to a developer account creation workflow every single time (the name of the page is super misleading!).
  • After your developer account is created, use your consumer authentication credentials at to get to the normal web dashboard
  • Use the “person/menu” icon in the upper right to bring in the menu, then choose “Developer”
  • Create an app
  • The “Name and Summary” tab of the newly created app should show an API key.

I’m not sure why the helpdoc screenshot choose to select the wrong menu (“Authorization Method” is selected), but that specifically hides the API key!

I’m not scared of text files at all. I’m an engineer and quite comfortable with the format of the configuration. The problem for me is that all the actual values I need to make in the files feel like black voodoo. For example: I have an Onkyo receiver and a brand-name Tivo. When I use the Harmony remote system I tell it “I have an Onkyo Model ABC123 and a Tivo Model HD456” then the app has ~8 pages of buttons that do all the various functions for each of the two devices. Sure I could cut-and-paste a bunch of lines of code to create all the necessary buttons, but how am I supposed to know if I’m looking for command="Volume UP" or command="VolUP" or command="IncreaseVol" or whatever? What’s the code for the Tivo’s main button (literally called “the tivo button”)? What’s the code for the 30-second-skip button?

In the spirit of a good platform and community, we should be building Things/Items/Channels/Site/whateverthef*** they’re called and putting them in some sort of repository or wiki. I just can’t fathom I’m the first guy to try to get a Tivo remote configured. If a repository of premade Things/Channels/Items/whatever exists, I’m not aware of it. If I can figure out how to write my Tivo remote, I’ll gladly share what I made with the community, but where ?