Please use this place to enter the info you would like to see added in the new Documentation section.
Any suggestion is welcome!
Read more here.
I’d like to help with adding documentation. Right now it looks like there’s some on the crowdsupply website (e.g. wiring diagrams), some on hestiapi.com and some on the GitHub wiki. As a user, I’d like an instruction manual that I can easily access while offline (e.g. a PDF).
I’d be happy to contribute content or collect existing content into a single location. I’d prefer LaTeX because it’d provide a unified place to keep the documentation that can be exported to whatever format is needed (HTML for the website, PDF for offline use, etc.). LaTeX is a text based format, so it’s very friendly with version control systems like git. That’s handy for contributions, pull requests, reviewing changes before they make it into official docs, and a CI job can be set up to automatically regenerate the PDF on merge. I’d be happy to help with that as well.
If there’s an easy way to export GitHub wiki pages to a nicely formatted, offline-friendly format, I can do that too. In any case, I suggest committing the PDF to the GitHub repo so people can see the manual without having to get any software or do any conversions.
If there’s a consensus about where the best place is to store the documentation, let me know and I’ll get started. Thanks.
First of all, thank you for the
This is an old post but the need is still present. We have tried (and we are in a much better place now) to bring everything together in the GitHub’s wiki. We haven’t thought of the PDF/offline aspect you mentioned but sounds like a reasonable point. I believe it is only the wiring diagram missing from the wiki and the “Quick Start Guide”.
Can we use LaTex but still host on GitHub so that anyone can contribute?
Yes, it is friendly to GitHub. I took a stab at it and submitted a pull request. Here’s what the PDF version looks like by default: https://github.com/anon8675309/hestia-touch-openhab/blob/docs/docs/hestiapi-one.pdf
The formatting can be made prettier, I just wanted to get all the content in there as a first pass. I also added the wiring diagram in the place where I thought it was reasonable.
The trouble will be keeping everything in sync, I’m afraid. I’m not sure of any way to automatically get the /docs content onto the wiki or vice versa. It can be exported to HTML, but it looks like that’s an entirely separate GitHub repo, so that seems like it’d get cumbersome to keep in sync.
Let me know what you think of what I’ve done so far and let me know if you have any suggestions on how to make it better. 
I know this is an old post but you say the need is real. This is rlkoshak from the openHAB Forums so I’d consider myself to be a fairly capable. But it also means I may do a brain dump here so please tell me to open a new thread if I veer too far off topic.
I just got my HestiaPi One in the mail and managed to get it installed. Except for the fact that those little black plastic rivets are worse that useless (seriously, I want to burn them all with fire until there is nothing left) the installation was pretty painless (beyond accidentally burning out a fuse but that is on me). Good job on that!
But now I’m up and running and looking around for some basic docs. But after installation I’m not really finding anything. For example, what exactly do all of these settings do? For example, what is the threshold for 2nd stage heating? What hysteresis is used to turn on/off the heater? Is there any? Stuff like this is either missing or hard enough to find that I couldn’t find it.
I know I can look in the code and probably will but not all of your users will be able to do so quite so easily.
I have to say that I’m a little surprised that settings are not being persisted with restoreOnStartup. If it’s restored some other way than openHAB Persistence maybe I’m not waiting long enough for a reboot before opening BasicUI. Watching openhab.log shows that having the UI opened generates a lot of Asynchronous processing no supported exceptions and it does seem to block anything useful from happening. It seems counter intuitive to have all my configs like whether or not the heater is on return to OFF on a restart. How would I set that persistence up (obviously I know the answer but that’s besides the point).
What exactly is backed up and restored when I click those buttons in BasicUI? Just openHAB configs or does it include everything important (e.g. Mosquitto? config).
Should I only update through the UI? Or is it safe to do an apt update? It appears to be running OH 2.4. What if I’d like to run 2.5? Is it safe. Is that what the upgrade button does on BasicUI?
These are the sorts of questions I would expect to be answered in the docs. I’m sure I can answer many or all of these by reviewing the rules and scripts but not everyone will be able or want to do that. And honestly it would save me a good deal of time if it were documented.
Ultimately I would like to get rid of the Mosquitto running on this RPi 0 to free up some resources and use a plain old MQTT event bus (requires OH 2.5 though). It would be interesting to see how/whether the boot and runtime performance changes or improves if the Rules were written with Scripted Automation and the NGRE on 2.5. I’ve seen significant performance improvements but I’m running on stuff much more powerful. Anyway, I digress.
The above questions are the sorts of things I would expect to be answered in the documentation.
1 Like
@hestia_hacker thank you for your input! I spotted a few issues here and there but I didn’t spend too much time on it yet. The 2 reasons why the documentation is on the wiki is a. anyone can contribute and b. it has a structure so that people can jump right into the section they want.
If a. is still covered, can we do something about b. ?
Wow @rlkoshak on our forum!? A warm welcome from our community!
Give me some time to respond properly to that and thank you for communicating all these questions without simply finding the answers yourself. I totally get your points and your effort to help.
P.S.: The rivets… its a story on it own…
I’ll reply to your other thread so that we keep everything in one place as I want to address all the very important points you made these 2 days.
1 Like
The PDF produced has a navigation menu which is very similar to the wiki. Screenshot attached:
I’ve also experienced the rivets and my answer was a tiny drop of superglue. I plan on expanding the section on installation in the foreseeable future. I made a great deal of mistakes in mounting it to the wall: forgot to thread HVAC wires through wall plate, had the wall plate backwards, tried to install the wall plate with the pi and wiring attached, etc. Apparently some people (namely me) need more detailed instructions. I plan on taking it apart and adding some photos to make it easier to follow.
I’m not sure where @rlkoshak found any option to back things up, but I found ~pi/scripts/backup.sh which only backs up openhab stuff (as can be seen here: hestia-touch-openhab/backup.sh at ONE · HestiaPi/hestia-touch-openhab · GitHub ). The script could be expanded to backup additional things (and I plan on doing just that), but it currently doesn’t handle things like network configurations, changes to ~pi/scripts/raspberry-pi-turnkey/startup.sh, wpa_supplicant.conf or any others. When updating the backup script I’ll either modify ~pi/scripts/kiosk-xinit.sh to also restore the other files, or I might split it out into its own script to keep things better organized.
I started documenting usage, starting with the touchscreen interface. As I was writing this section, I found out that boost doesn’t actually turn the heat on for 10 minutes as I was expecting! I thought the feature was for the “yeah, it’s the right temperature, but I want it a bit warmer for just a little while” situations. I found Heating Boost problems - #2 by HestiaPi saying that’s not what boost means and I have updated the (newly created) documentation to explain this. Since this thread is about documentation, I’ll save my “but this isn’t the feature I want” comments for another thread.
My next task will be to document the usage of the mobile app and webpage interface. This should help address @rlkoshak’s question of “what exactly do all these settings do?” I’m new to OpenHAB, so this task may take me a while, but I want to learn how these things work anyway, so I might as well document it for the people of the future (which will almost certainly include “future me”).
As I was digging around in the scripts trying to understand how the startup process worked so I could set a static IP address (which I still haven’t managed to do yet), I’ve started to get a feel for what software is needed (mosquitto, hciuart, dhcpcd, and openhab2). I plan on documenting the software components as well as how they interact for those who are completely unfamiliar with openhab. I’m also going to eventually figure out the best way to set a static IP address. I tried running systemctl restart networking from a screen session (without modifying any configs) and I lost my DHCP address. I’m glad I did this test because the next step I was going to take was to run a command to sleep for a couple minutes, then restore the old config and restart networking. That way if I messed up the config, it’d automatically recover in a few minutes and I’d be able to try again. Once I figure out how to set a static IP, I’ll document that along with the software components and boot process.
My plan for now is to just document how things work right now. If the design changes to use OH 2.5 and Mosquitto is done away with, I’d be happy to update the software diagram of how things work (or better yet, review someone’s change to that documentation!). I’ll be happy to document the upgrade process as well. Again, if I’m going to go through the process, I might as well document it if that has not already been done.
At some point in the more distant future, I might re-organize things to be based on use case rather than hardware/software architecture. For example, have a section called “Setup” which will cover hardware setup, then software setup, then first boot. I think this will make it easier for new users to find what they’re looking for.
If I go this route, I’ll probably move things like the hardware and software component diagrams and boot process to a “Reference” section. That way it still has a place and if people understand what’s going on and they see top level sections of “Setup, Usage, Reference, Troubleshooting and FAQ” hopefully they will know where to go.
1 Like
Is there an option to be added to the printable version at the top and dynamically update to changes?
Settings>Maintenance (app or web UI) 
Please do start a thread to see how many people feel the same as expected behaviour on the Boost buttons. Either way it is a very easy modification if we decide to go there but it can go wrong if it runs say for an hour without any temperature setpoint.
There is no UI for setting a static IP yet during provisioning. To set static IP, think out of the box and ignore the fact that OH is running. It is a “standard” Stretch Raspbian OS so here is one solution:
Alternatively (my personal choice) is to bind Pi’s desired static IP to its MAC address from your DHCP server (your modem/router most likely)
Your router should have a “Lease time” setting at the DHCP section that had expired. This value (in hours usually) means that if an IP is not used for that period is released and becomes available to another device that may request a DHCP lease.
As a rule of thumb, especially for something like HestiaPi that may act as a hub in a smart home environment, it is always to have bound to a static IP. Even better use a round number (like .100 or .200) that you can memorise and of course in the same subnet.
If your router’s IP is 192.168.1.1, choose for HestiaPi something like 192.168.1.100 or 192.168.1.200. Not 192.168.2.100 as most likely you will not be able to communicate with it at all (no ping, no SSH, no web)
An additional advice is to choose this IP outside your DHCP pool, that is the range of IPs your router has setup to choose from. Again this should be specified in your router’s DHCP settings section.
I don’t think Mosquitto will be done away with… Upgrading to OH 2.5 shouldn’t affect anything on the documentation on its own.
One question and one request…
How do I produce the PDF if I change the text files?
Can you make the PR again for the ONE branch which is now the default branch (just reorganised the branches). The default branch was an old one when you tried your PR and it would end up in the wrong place so I haven’t merged it.
I’ve merged in the ONE branch to my “docs” branch and submitted another PR with more documentation on usage, and a table of contents to make it easier to find things in a printed version of the manual. In the course of these changes I found that backup button you mentioned too.
To produce a PDF, you should be able to just run make from the /docs directory (and you can look at the Makefile if you want to see the commands that will run).
If it complains about “pdflatex” not being installed, and you are on a Debian-based distribution, run make deps and that will install the texlive package. If you’re on another distro (e.g. Fedora) then you’ll have to install texlive manually (at least, until I get around to spinning up a Fedora box and updating the code for make deps to automatically detect the distro and run the right installer command).
Thanks for the static IP pointers. I expected to have to do it this way. I’m just a little nervous about changing it and then having something go wrong and it never get a DHCP nor static IP address again. Those mistakes are no big deal if I can just go to the machine and connect a keyboard and monitor to fix it, but in this case it’d mean pulling the thing apart, mounting the SD card, fixing it, and then putting everything back together again to try again. It’s a very similar problem to remotely updating firewall rules that might inadvertently lock you out of the box you’re SSHed into. 
As long as everything is done perfectly the first time, it’s no problem at all!
I wish I had thought of the superglue idea.
I’ve something else to add to the list of issues. Don’t choose a screw with a large head. I was lazy and didn’t want to install a wall anchor and I’ve a box of random screws so I picked a larger diameter screw. That was great for attaching the plate to the wall but the head was also bigger and now the case won’t seat properly at the bottom. Guess I need to install that anchor after all.
In BasicUI it’s under Settings → Maintenance.
NOTE, I’ve got my instance configured with restoreOnBackup and Last Backup is one of the Items that is restored which is why this screen grab is showing something there. I’m rebooting so Items like the version Items haven’t been populated yet.
The Rule that runs to call that script is defined at around line 800 (I’ve made a bunch of changes so can’t be precise, the Rule name is BackupCommandChanged.
From there I was able to discover that backup script (after creating the above post) where I could see that it just calls openhab-cli backup). I would like to see the Mosquitto config and the UI config added to that script. I’d also like to see it save to another folder and keep the last X backups, but baby steps. 
From looking at the Rule, it turns the heat on for 10 minutes or until the target temp is reached, which ever occurs first. It’s entirely possible that you can push boost and nothing happens if you are already at or above temp. I don’t think this is expected behavior (at least it wasn’t for me) but the change would have to occur in the rules. I expected exactly what you did, that it would turn on for 10 minutes regardless of the current temp.
If you have any questions ask away. I am somewhat of an OH expert so I can probably answer any question you have to ask except for “why” questions (e.g. why is it done this way instead of that way). Start by reviewing the Concepts section of the OH docs though. It will give you a bit of a foundation to understand what you are looking at and where stuff is defined.
If at all possible it is best to set that at the router by defining a static lease for the HestiPi’s MAC (which is nicely displayed both on the screen and in BasicUI). Failing that, look on an RPi forum and I’m sure you can find a tutorial to help.
That’s really what I was after as well. I can figure it out (and mostly have at this point) by looking at the OH configs. Many users will not so gotchas like how Boost seems to work and the behavior of the Fan mode needs to be described in docs.
No, don’t use the embedded broker if/when updating to OH 2.5. Moquette is no longer maintained by upstream. It might work just fine for this application or it might not. If not there’s nothing anyone can do about it. So stick to Mosquitto. A 2.5 instance of HestiaPi should look exactly like it does currently, from a functional perspective.
Once I have hysteresis working right that’s going to be pretty high on my list to try out.
Note, in answer to one of my questions above, running an apt upgrade will upgrade OH to 2.5, so don’t do it, at least for now.
That’s what I expected at first. As it was written in the Rules though, it’s was kind of pointless if you are in the US mode. There is no hysteresis so the temp is always going to be within 1 degree F of the target (assuming it’s cold and you need to run the heater to maintain temp). Because Boost cuts out once you reach the target temp it pretty much only does what AUTO is already doing so there is really no point. I expected it to just run for the boot time or until it was set back to AUTO or OFF.
Having a Pi 3 or so with both ETH and WLAN would be the best approach, but you knew that already ;). Also if you plan on experimenting, the same SD card can run on a Pi 2/3 for speed purposes. LCD, relays, temp sensor don’t cause much of a problem if missing on your dev setup.
I guess it makes more sense for houses where heating is not ON most of the time so that it turns OFF after x minutes. If AUTO was already the previous state, then yes, it makes no sense. I totally see your point and it is getting more supporters
Added an issue to myself for this:
Another day, another PR. 
I got the static IP address documented and started in on getting TLS set up. Life is going to get busy for me this week, so it might be a while before I get any more updates written up. When I get to updating the section on physical installation, I’ll mention the bit about a dab of superglue to keep the rivets in place.
I realize that setting up DNS and TLS on a HestiaPi is not a very common use case, but the nice thing about volunteer work is that I can work on whatever is important to me. 
If there’s an open issue on GitHub about improving the backup scripts, let me know. That’s on my list of contributions to make in the future. If someone beats me to it, I’d be happy to do code review.
Hey, thank you for your PRs! I just merged it.
We are focusing on optimising our hardware for (mass) manufacturing right now so our time on coding, new features etc is limited for about a month too 
but it is for a good purpose (hint: no superglue will be needed any more). I’m happy to review and merge your work whenever you get time!
P.S.: Can you please change your username as it may confuse people about who is who?
I’m working on setting up TLS for the service running on port 8443 (not Mosquitto, which appears to be the service which deals with MQTT messages). I’m having trouble finding the configuration which stores the password for the Java keystore. Let me explain what I’ve found so far and I’m hoping someone can point me in the right direction for where to find this password.
The OpenHAB docs explain that a self-signed certificate is used by default. This is good and will work for the vast majority of people, but some people might want to change it. It identifies the location of the keystore as $OPENHAB_USERDATA/etc/keystore. The variable is defined in /usr/lib/systemd/system/openhab2.service as being /var/lib/openhab2 and there is a keystore at /var/lib/openhab2/etc/keystore. So far so good.
Next, I wanted to take a look at what is in there before I go messing around with things. The Java keytool is not in $PATH nor is it in a standard place (which is fine, and I’ll just document these things). I wanted to list the keys, so I ran this:
/opt/jdk/zulu8.40.0.178-ca-jdk1.8.0_222-linux_aarch32hf/bin/keytool -list -v -storepass changeit -keystore /var/lib/openhab2/etc/keystore
The password changeit is the default password for Java keystores, and I even found a closed issue reporting that openhabian didn’t change it from the default and it was effectively closed as WONTFIX because the tiny security gain isn’t worth the effort. However, when I run the command above, it says the password is incorrect.
Surely this password must be in a configuration file somewhere, because the webserver on 8443 is reading its certificates from somewhere, but I can’t find it. I found /usr/share/openhab2/runtime/etc/jetty.xml that contains a value for jetty.ssl.password, but that password doesn’t work, and it also points to /etc/myKeystore which doesn’t actually exist, so I’m guessing this config file isn’t being used?
The OpenHAB docs say that Jetty is included as the HTTP server, so it seemed promising. I think I’d be able to troubleshoot this far more effectively if I understood how OSGi, Apache Karaf, Eclipse Equinox, Jetty, Mosquitto, and whatever other components make up OpenHAB fit together. The OpenHAB docs mentions the technologies, but then the “concepts” section of the docs do not mention any of these components. I also checked the Developer Guides and Developer Appendix and couldn’t find a software architecture diagram for all of OpenHAB there either.
Another way I might be able to piece together these things would be to build an image myself and flash it onto a pi. I see that is described on the wiki now, but I’d really rather wrap up the task of getting TLS set up on my system (and documented).
P.S.: I like my new username
openHAB runs on Karaf which in turn uses OPS4J Pax Web to configure the web server. Beyond that though I hit a dead end. I can’t figure out where and what the password for the existing keystore is.
But do not confuse the Karaf keystore with the JVM keystore which that issue you linked to refers to. Karaf has it’s own keystore independent from the JVM so changeit would almost certainly not be the correct password. There is supposed to be a property in org.ops4j.pax.web.cfg with the password but it’s not there. I also saw some activity where the password has been moved and encrypted so it doesn’t have to exist in plain text. Without spending more time I don’t have right now I’m afraid I don’t have any other ideas except to look at the environment variables that OH set up.
That is all a whole lot of to learn. OSGi isn’t a thing so much as it is a way to package and develop modules that can be combined into an application. Karaf is the OSGi container that takes all the OSGi parts that make up openHAB and runs them. Much of what makes up OH is actually just inherited from Karaf, including Jetty, so for this stuff you need to be looking at the Karaf docs for the information you are after and the sorts of architecture data you are after.
Mosquitto is a wholly separate program and it is not part of openHAB. It’s one and only job is to be an MQTT broker.
I’ve started putting together some scripts which will automatically SSH into a fresh Rasbian system, and make it into a HestiaPi. This is from SSHing in and changing the default password, to downloading and building websockets and mosquito, installing systemd scripts… the whole thing.
In order to make this be easier to test, I set up a Rasbian image under QEMU so it’s easy to test the script without having to fiddle with hardware. Obviously this has its limitations, but it’s able to find things like “compilation errors” very quickly. I’m also attempting to use newer versions of software where I can (e.g. buster instead of stretch, which forces using the latest mosquitto, and so on). That might be a mistake, but if I get it working, then we will have a path forward on getting things updated. It wouldn’t address the ability for one to update their own HestiaPi, but it would at least make fresh images easier to build.
…and I’m doing all of this, so I can figure out how to add TLS to my HestiaPi and then document that.
I’ll keep plugging away. Here’s where you can see how far I’ve gotten: https://gitlab.com/hestiahacker/raspberrypi-automation/-/tree/hestiapi