I needed to setup a test openHAB server running on a PI3 to test a new binding out, so thought I would document what the experience is like, pretending I am a new user with minimal knowledge. I also installed Home Assistant a week ago so can compare the experience between the two…
openHABian | openHAB The very first impression is that your greeted with an explanation of what TLDR means, which indicates the author knew the text was going to make people feel the way I did from reading it. I also get negative feelings from reading the text, like I am getting lectured and told off.
Confusing text like " Linux newcomers are challenged" but it does not make it clear that this is meant to be if you do not use openhabian(?), then the next lines are saying its easy and hassle free.
The openhab option to select an image from the rasberry Pi imager was hidden off the screen at the bottom of the list and needed to be scrolled to see, whilst Home Assistant is at the top of the list.
You get told too many URLs, Why can we not use the one url to do the installation that stays the same and teaches us the location to use later on? The URL auto redirects us to the 8080 port and a new user would not know where to go back later on. Using the old 81 port fails to connect later on.
https://yourIP:81/ The openhabian documentation recommends this URL and it fails with the below message, it appears it is serving non https, but the docs state to enter in https…
Secure Connection Failed
An error occurred during a connection to openhabian:81. SSL received a record that exceeded the maximum permissible length.
Error code: SSL_ERROR_RX_RECORD_TOO_LONG
The page you are trying to view cannot be shown because the authenticity of the received data could not be verified.
Please contact the website owners to inform them of this problem.
http://openhabian/ fails to open a web page, just times out and the docs do refer to this URL to use.
http://openhabian:8080/ Yet another URL the docs give you that fail (yes I know it will work afterwards)
http://openhabian:81/ This opens a webpage that stalls on this output which I finally worked out it was my firewall blocking internet. I got no useful info in plain English to help fault find, and was confronted with ugly Linux commands that would be scary to a new user. The text at first glance looks to say it got a 200 OK back which is very misleading in this case.
The installation log auto refreshes every 10 seconds and new text appears at the bottom and to read what is going on, you need to scroll down and quickly read before the page refreshes and take you back to the top. This really is annoying. Compare it to Home Assistant and it has a very flashy graphical page that gives you ads to read that promote the product while you wait. The URL does not change on you and stays the same.
My web browser (firefox) is warning me not to enter a password when creating a new user account as the site is insecure, since I am going in via http.
I then get asked “Would you like to share your home’s location?” but no explanation about whom I am sharing the information with. I’m guessing it does not leave my network, but this is very unclear and may turn new users away.
The retrieve from this device button does not work and does not pop any windows up to give permission. It gives me an error saying the user did not allow permission, but I was never asked. Using the map allows me to select a location and continue.
The suggested addons works great and allows multiple bindings to be installed and gives a progress bar, so I know I can leave and come back. Will be even greater when it detects more.
The developer sidebar used as a new user guide is great. Just maybe as a first step, tell the user it can be opened and closed with those keys and also found under developer tools from the left menu.
The website has some great new user guides that explain the model, The sidebar could give a link to go there for more help so people are aware it exists. Also if you click on SETTINGS>MODEL you get a page with a short description, perhaps place a link to the website and the tutorial for the model here.
Same idea for when you click on items, rules, pages and things. You just get a short blurb but no link on where to go to learn more.
Over the years people have ponded on the openHABian developers. I suspect the docs have become somewhat defensive as a result. I think it would be a good idea to go through it and see how to make the writing style more friendly. It’ll be a big effort though.
I’m not sure we have any control over that.
That only fixes the one URL. We still have Frontail (and others?).
Seems like using port 80 and 443 would be best overall. I never understood why openHABian doesn’t make that change. While there are other webservers running on the machine, openHAB is the primary one, why not make it the default?
Though then the question comes does one make it the default through nginx or by changing the OH configs. If changing the OH configs, does that break the reverse proxy config scripts in openHABian?
That’s definitely a bug in the docs and needs to be fixed.
Creating meaningful error messages for stuff like this is exceptionally challenging. Any volunteers to address that I think would be appreciated.
That’s a browser issue. I’m not sure there’s anything OH can do about it short of somehow trying to hide that a user is being created from the browser (I don’t know how it detects that in the first place). Switch to HTTPS only wouldn’t really help as then the browser will throw up an even more alarming warning and require the user to click through because the cert is not trusted. I can think of no way to ship with a trusted certificate as the certificate is tied to the DNS name of the machine.
Does HA use HTTPS? If so it would be interesting to figure out how they solved this certificate challenge.
Definitely should file a bug on that one. Maybe it only works on phones?
I think most of these are worthy of an issue. Some may be really hard to fix but most seem pretty doable.
I have done just done this (setting up a test instance of OH on a Windows laptop), and it worked for me. I was using Chrome. So I am sure it is not a general issue. Again, how permissions are set and how a request for a permission pops up is probably down to the browser.
EDIT: I just tried with Firefox, a popup appeared asking for permission to access my location, I confirmed and it populated the field with the location.
It would be interesting to understand what was different in your case.
Yes, that’s exactly why those docs today are the way they are. I’m not happy with that either.
I’ve quickly adressed some of your points, please check back against latest version which is here.
but I’ll be happy about anyone to take the ball and have a rewrite.
The :81 webpage is not meant to be a fancy installer but a debug tool.
But it’s bad luck and timing. Seems you used some image that has debugging enabled by default for whatever reason.
I’m about to release a new openHABian version anyway and will disable debugging there.
It’ll look much cleaner then.
Remains the refresh thing, I know. That one has been bugging me, too but to date I have not found a satisfying replacement. Help wanted. Anyone who knows how to present a simple logfile better, put up a PR please and I’ll happily include it.
I don’t get that point. Which “many” do you mean, the links to 3rd party software homepages ?
Other than that it’s 8080 for operations and 81 for debugging, plus 9001 if you want the logviewer, that’s about it.
If you’re okay with a complete rewrite, I’ll give it a shot. I spend my weekdays trying to make university policies and procedures make more sense to students, so I’ve got experience with this sort of thing.
Basically, I’ll take everything on the page (and in this discussion), break it down into the component parts, and then shuffle it into a new structure that’s more linear for new users. Then comes the most important part of the process: you tell me where I’ve made bad assumptions based on my lack of expertise. We can then post it here for additional feedback.
First up thanks heaps for your work on this, very dedicated and you have done it for longer then I have been around. It was late last night and just dumped my findings in here before going to bed so my wording may not be the best…
Regarding plain english text to read, you could add an ECHO line that states its going to use the internet. Different color if possible for the user info/prompts VS debug lines. Assuming you do not like to do ECHO OFF as you mentioned this may have been a debug build.
The documentation refers to many URLs, some of them indirectly by stating to just use the IP:
I am pretty sure these urls are in the docs as I was mousing over them to confirm and I was confused why it was https in the docs, but appears to not be https when you try the link.
Pretty sure it is HTTPS all the way and really that is the standard these days. You type in a non https url and the browser trys automatically to upgrade you to https. Browsers are more and more teaching users to not trust non https. I know you already know this, but I feel I have to raise this as a new user would not bother to bring this up, they would just go with another project that does not trigger security warnings.
I suspect it is from me choosing to always block websites giving out my location. Its probably saved in the browsers settings. Firefox does block more then a google created browser that likes to dial data back to google non stop.
Thanks for stepping up. I’ll have to look at this more in a few days (busy for 3+ days now) to file bug reports if any of that is needed. @rpwong I would make mention it needs the web to complete. Its an image of 900mb from memory, but still needs to download updates and will hang/endlessly retry(?) if it does not. When I unblocked the firewall, it continued and worked perfectly to the end even thou it was stuck for probably 45 minutes.
Port 8080/8443 vs. 80/443 → to use the well-known ports, openHAB would need special permission (root).
Automatic https when using http: it’s a redirection, but you have to run a web server on the default port to do that. Please don’t forget that openHAB is OS independent, one would need to install additional software to do this port forwarding dependent on the OS, I’m pretty sure that’s a no-go.
openHAB always provides http and https, but there will always be the non-valid certificate-issue (and to be fair, most software services share that issue with openHAB, maybe even Home Assistant (did not check yet)
That’s true on the Internet but rarely true for self hosted services because of that certificate challenge. I looked at the HA onboarding and indeed, they are using HTTP, not HTTPS.
It is really quite a hard problem to ship a web service with a trusted certificate and it’s hard by design. That certificate is a “proof of identity” for the server. If the URL in the certificate doesn’t exactly match the URL used to access the web server, the browser will simply refuse to open the page with a big scary warning. The second problem is that no currently trusted certificate authority will issue a certificate that gets deployed with software. Each instance of a service needs to have it’s own unique certificate. Therefore self signed certificates are used and in that case you get a different but equally as scary warning message from the browser.
I was really curious if HA figured a way around both of these problems but it looks like they too just use HTTP. As far as I know it shouldn’t even really be possible to ship a certificate with software that would automatically be trusted by the browser (I’m talking about web page HTTP certificates, not code signing certificates here), but I was open to someone having figured out how to do it.
I use Brave, better support than FF (which seems to becoming a second class citizen unfortunately) but less of the tracking nonsense. Though I switch back to FF periodically too just to see how it’s going.
Doh! Good point. But OH could continue to run as user openhab and openHABian could configure ngnx by default to reverse proxy it on the standard ports as a simple passthrough.
I think we are mainly talking about openHABian here so we have more options available to us in these sorts of things. Of course on a non-openHABian install 8080 and 8443 would still be the case.
On the current 4.2.0 snapshot, I have changed that sidebar help feature to load designated Main UI docs from the docs repo (before, the docs were hard-coded to the UI). These docs are also available on the website and I now have added links, e.g. model page docs: Settings - Model | openHAB
But not a good idea. It would just move the certs problem over to my shoulders.
nginx is merely a leftover from the days before myopenhab has become the standard solution for remote access, and it’s a nightmare to maintain a consistent config so it mustn’t become a default - that just increases complexity for no good.
Plus it’s somewhat incompatible with myopenhab.org (at least true when it comes to understanding things from a user pov).
The cert problem would still be unsolvable. From how HTTPS is designed and how PKIs work, there is no way to ship something like openHAB or openHABian with trusted certificates.
If a trusted root CA would sign a certificate for a software like openHAB, all instances would ship with the same cert and the same private key. This way, browsers would not complain anymore, but your HTTPS would be as unsecure as HTTP, because everyone would be able to get to know the servers private key and perform MITM.
The only thing I can imagine to improve the situation is, to explain in the docs why the browser does complain when using openHAB’s HTTPS and to provide an option (preferably in the UI) to download openHAB’s certificate and install it to your clients. This way you get “real” and secure HTTPS without warnings.
This would require a REST endpoint the get the certificate, something like Allow adding/changing Jetty server certificates via REST API by J-N-K · Pull Request #2905 · openhab/openhab-core · GitHub but only with read access.
Like @florian-h05 indicates, I’m not proposing we try to solve the certificate problem. Just use what ever self signed cert nginx uses, or cut off HTTPS support entirely and require the user to do something to set that up.
I’m only proposing it as a way to forward port 80 to port 8080. The juice may not be worth the squeeze on the openHABian side. It was just an idea.
Releases, features and docs on these are way more than just the user facing part.
There’s a lot more than users get to (and want to) see we devs have to cope with, particularly where we’re reliant on somebody elses work, and the dependency chain is deep in openHABian.
Note the differentiation feature vs task lead. Hard to get that consistent into one document, we should consider splitting into more docs, or at least to provide a split-view on both parts.
I must admit I feel with and sorta share the pov although it’s right that expert docs part that was (and I believe still is) missing in this RPi WiFi case.
Not to mention the frustration and additional test efforts this caused with the poster and myself, too.
The thread initially is about removal of capabilities to configure Wi-Fi in an automatable fashion as I have implemented and been using this in openHABian in years, too, so this also documents where my developer pain was in moving over to bookworm (cc @kai).
This somewhat mirrors my experience in universities, where the habit for many years was for divisions and units to talk about themselves and what they do for students. You end up with a lot of websites and documents that are twice as long as they need to be, because they detail a lot of things that students don’t need or want to know. It’s overwhelming.
This is also why I’ve suggested in the past that openHAB would benefit from defining expertise levels for different functionality, from novice through expert. It wouldn’t be about denying access to features, but communicating when a task is more challenging than a new user expects it to be (we do this a bit with the “Show advanced” toggle in Main UI). It also helps users gain confidence, because if they can do one intermediate task, they can probably do others. Of course, it’s easy to suggest this and much harder to actually define/implement.
So, I think the openhabian docs can definitely benefit from this feature/task differentiation. For example, it might be enough to explain to users how to set up Amanda and auto-backup for their first boot, then link to a separate page to explain how it actually works.
… that’s a bad example.
A fully resilient setup incl. a multi-level backup strategy clearly is for advanced users.
And even those users mustn’t be doing that from the cli before unattended install.
They are supposed to use the interactiveopenhabian-config tool which will lead them so those questions shouldn’t be popping up in the first place so they also need not be answered in the docs upfront.
Using Chrome I get this when clicking on “retrieve from this device” for setting the location.
Error while retrieving current position
Only secure origins are allowed (see: https://goo.gl/Y0ZkNV).
The documentation has already been changed from what it was when this thread was created, thanks however…
At this link and I quote…
The system will be accessible by its IP or via the local DNS name openhabian and you can watch the install progress in your browser at http://openhabian:81 (opens new window).
This is confusing. “accessible by its IP or via the local DNS name openhabian” this infers to me that you can type in http://ip:80 when this is not the case. Only the last URL with port 81 is correct and works. I know what it is trying to say, but not everyone will read it the way it was intended.
The docs state Connect to the openHAB UI at http://openhabian:8080 it should be made VERY very clear, that this only works AFTER the installation that takes up to 45 minutes has fully completed.
I will have to find some time to do a PR and look over the text, but as someone that wants to find the install instructions and get it installing and then come back and read whilst it is busy working, I find it difficult to find the install instructions quickly.
