[CLOSED] "Introduction" in docs: proposed rewrite

documentation
Tags: #<Tag:0x00007fe057c51a90>

(lipp_markus) #1

Edit: this discussion has been morphed into a pull request on github: https://github.com/openhab/openhab-docs/pull/850; please continue discussions there (if any)

I am starting this topic to propose an edit/rewrite of the Introduction section of the docs. This attempt has been triggered by many discussion here in the forum to lower the entrance hurdle to the docs.
A couple more remarks:

  • Happy if someone with more forum powers than me wants to change this to a wiki for communal editing if desired
  • Once it pleases the community, I can gladly morph it into a PR on github
  • I have included: https://github.com/openhab/openhab-docs/issues/845 and added a link to How to ask a good question / Help Us Help You
  • I am much in favor of to move the section on architecture elsewhere (https://github.com/openhab/openhab-docs/issues/838); but I left in here for now
  • Once a term was introduced, I have used hyperlinks rather extensively to maintain a consistency in formatting; just to assure the reader that it is referring to the same concept
  • Speaking about hyperlinks: I started with a copy of the intro section from github; only links that point NOT to doc sections, as I wrote all links in the format needed for github; this includes the link to picture of openHAB architecture, if not familiar you can access it here: https://www.openhab.org/docs/#architecture-overview; this architecture section has been renamed below but the content has been not been touched by me

So with this said, here the proposed text, looking forward to your comments:



About openHAB

The open Home Automation Bus (openHAB, pronounced ˈəʊpənˈhæb) is an open source, technology agnostic home automation platform which runs as the center of your smart home!

Some of openHAB’s strengths are

  • Its ability to integrate a multitude of other devices and systems. openHAB includes other home automation systems, (smart) devices and other technologies into a single solution
  • To provide a uniform user interfaces and a common approach to automation rules across the entire system, regardless of the number of manufacturers and sub-systems involved
  • Giving you the most flexible tool available to make almost any home automation wish come true; if you can think it, odds are that you can implement it with openHAB.

What you need to know before you start

When home automation just seems to work, it is always the result of hard work. Home automation is fascinating and requires a considerable investment of your time. Here are some key considerations especially for new users. To be successful, you will need to:

  • Start slowly and one step at a time.
  • Be prepared to learn
  • Remain flexible in how you want to achieve your goal
  • Celebrate all the small successes

Remember, openHAB is just a computer program. The computer will only do what you tell him to do.
openHAB can provide many default solutions that are easy to setup. On the flip side, the more you insist that everything should look and work exactly as you want it, the more work you will have to do. openHAB is fully customizable, but doing so will require substantial efforts from you.

After you have read the documentation for openHAB, you will have:

  • Identified on which computer you will run openHAB
  • Learned how to install openHAB, as well as all other software that is needed to run openHAB (e.g., JAVA)
  • Learned how your smart devices communicate with openHAB; how to make openHAB give commands to your smart devices; and how you can interact with openHAB

Keep your focus. For almost everything, there is more than one way in openHAB to achieve a goal or perform a task. Initially, this can be frustrating and confusing, but it also gives great flexibility and does not mandate the use of certain devices or tools.

You may need a desire to understand computers, but, then, this may be a given, as you are reading the documentation of how to do home automation yourself.

Lastly, be prepared to start a new hobby: home automation. Basic functions can be achieved in openHAB rather quickly, e.g., switch lights on at a certain time. Others will require much more efforts and thoughts, e.g., how do I determine that someone is home, including guests, but not counting pets? The openHAB forum is a great place to learn and discuss. But always remember: no one but you knows what you need and what you have as well as yourself. Give plenty of background information if you have a question. And please be courteous and respectful, this is an open-source community and everybody on the forum works with openHAB in their spare time.

A quick overview

openHAB communicates electronically with smart and not-so-smart devices, performs user-defined actions and provides web-pages with user-defined information as well as user-defined tools to interact with all devices. To achieve this, openHAB segments and compartmentalizes certain functions and operations. The following table gives a high level description of the most important concepts as well as a link to more information:

Concepts Meaning More Information
Bindings are the openHAB component that provides the interface to interact electronically with devices link to new section in Concepts
Things are the first openHAB (software) generated representation of your devices click for more info on Things
Channels are the openHAB (software) connection between “Things” and “Items” (see below) link to new section in Concepts
Items are the openHAB (software) generated representation of information about the devices click for more info on Items
Rules that perform automatic actions (in its simplest form: if “this” happens, openHAB will do “that”) click for more info on Rules
Sitemap is the openHAB (software) generated user interface (web site) that presents information and allows for interactions click for more info on Sitemaps

While the table above gives an overview, please remember that it is a simplification of openHAB for the sake of this overview. More elements will be introduced in later chapters of the documentation. All the above Concepts are explained in more depth on other pages that can be accessed either through the sidebar or the links in the table above.

Once you are getting a first overview, it is time to practice. Here a short list of the steps that you will need to consider to get openHAB up and running as your home automation system:

  1. Install openHAB
  2. You probably already own a device you wish to control, but even if you don’t, you can try out openHAB
  3. Install a binding (in openHAB)
  4. Define a “thing”
  5. Add a “channel” to the “thing” if not created by the binding
  6. Define an “item”
  7. Link the “channel” to your “item”
  8. Establish a sitemap

Most of the above can be done in openHAB through point-and-click processes in a graphical user interface. But remember, there is always more than one way to achieve your goal in openHAB.

A final word for the DIY enthusiasts. openHAB is very flexible and can support many DIY devices. However, you will quickly realize that DIY often literally means that you “do it yourself”. Working with DIY solutions often requires a deeper level of understanding, as well as more patience and perseverance than the integration of ready-to-use devices from commercial providers. The choice is yours of course, but you will need to be prepared spending either money or time (and sometimes both) to make your home automation goals a reality. And quite often, the investment will be significant.

Don’t give up, openHAB is very powerful and flexible and most likely can help you achieve your home automation goals, whichever they are. But it comes with a rather steep learning curve.

Getting Started

To all newcomers: please read the section New User Tutorial. That section provides you with a step-by-step instructions for your first easy setup.

OpenHAB runs on most popular platforms such as Linux, Windows and MacOS and on almost any
hardware ranging from Raspberry Pis to desktop computers and server PCs. You can find specific installation instructions for these and other platforms in the Installation Overview article. If you have a strong preference towards a particular platform, then that platform is probably your best choice.

You can install openHAB on your desktop computer for evaluation purposes if you already have any of these systems available for use, but we recommend using a dedicated system in the long run. If you feel serious about home automation it may be better to start with a dedicated system right away.

For anyone undecided, we suggest a Raspi and using openHABian to get things up and running quickly. Many people find that the simplest way to experiment with openHAB is to get a Raspberry Pi and install openHABian; a “hassle-free openHAB setup”. While openHABian offers a streamlined and simplified way to get up and running quickly, it is a complete openHAB home automation system easily capable of automating your entire home.

Once you have openHAB up and running, the Configuration article contains everything you need to know to get your openHAB installation talking to different devices around your home.

You will quickly discover that you may want to learn more about Things, Channels, Items, and more. To do so, we highly recommend that you read the next chapter titled Concepts. It provides a more in-depth descriptions of Things, Items, Bindings, etc. that will help you as you dive deeper into openHAB.

The amount of information provided here can be overwhelming, so please come back to these sections often as you develop your home automation system.

Along the way, you may have some questions; the openHAB community is here to help.

The openHAB Community

openHAB is not just software - it is also a community of users, contributors and maintainers, working together on an open-source, interoperable approach to home automation. The center of this community is the openHAB community forum. It is an active and responsive community of developers and maintainers who generally respond quite quickly to forum questions.

Remember that openHAB is an open-source development, driven exclusively by volunteers. Please be kind and courteous, it will be most appreciated by those that will try to help you.

In many occasions, you will notice that your problem has already been raised by others; and discussed and resolved by the community before. You can search previous conversations and issues to see if your question has already been answered. It is best practice and generally considered to be good etiquette to check fairly thoroughly before posting your own question.

If it is your first time posting a question, please read How to help us helping you for information on what information you will need to provide.

A deeper dive: openHAB Structure for advanced users

openHAB 2 is developed in Java and mainly based on the Eclipse SmartHome framework. It uses Apache Karaf together with Eclipse Equinox to create an Open Services Gateway initiative (OSGi) runtime environment. Jetty is used as an HTTP server.

openHAB is highly modular software that can be extended through “Add-ons”. Add-ons give openHAB a wide array of capabilities, from User Interfaces, to the ability to interact with a large and growing number of physical Things. Add-ons may come from the openHAB 2 distribution, the Eclipse SmartHome project Extensions, or from the openHAB 1 distribution.

The overall architecture of openHAB is shown in the figure below:

distribution overview

If you are new to openHAB, we suggest you continue to the Concepts chapter where we introduce many fundamental ideas that are used throughout openHAB.

Proposed updates to the concept section

Would suggest to add the following items to the Concept https://www.openhab.org/docs/concepts/ section of the docs.

Channels

Channels are for the logical link of a Thing to an Item. Channels originate from Things definition and define how your Thing can communicate with Item (and vice versa). You will create channels when defining your Thing.

During the definition of your Thing you will identify the channel to which your Item will be linked. These two steps ensure that openHAB can transmit the information from the Thing to the Item (and vice versa).

Bindings

Bindings are software packages that are installed by the user in openHAB. The main purpose of Bindings are to establish the connection between your device and your Thing. Bindings communicate with your device and translate all commands to and from openHAB between your device and your Thing.

Bindings are provided at the Add-on section of the openHAB website. Here you will find a searchable list of several hundred bindings to support as many devices as possible. New bindings are regularly added as developers integrate more devices into openHAB.

For each binding, detailed instructions and examples are provided that include guidance on configuration (if any) of the binding itself, the definition of Things supported by this binding and the Channels these Things provide. In most cases, the description also contains a fully worked out example that includes a definition of Things and its Channels, Items linked to those Channels and the use of these Items in a sitemap.

[Note: In the final docs, every occurrence of Channels will need to be linked to the text above]


(Vincent Regaud) #2

I would change the order a bit:

1 Install openHAB
2 Own a device you want to control
3 Install a binding (in openHAB)
4 Define a “thing”
5 Add a “channel” to the “thing” if not created by the binding
6 Define an “item”
7 Link the “channel” to your “item”
8 Establish a sitemap


(lipp_markus) #3

Done, thanks!


(Alex) #4

In my opinion, it is not necessary for a beginner to own his own device. I think of many bindings such as ntp, feed, astro, weather and so on. To get a first impression of Openhab, you can play around with these bindings. One could refer to the demo version or make a tutorial on the basis of the mentioned bindings. If a beginner likes Openhab, then he should decide to buy his own devices.

I would also recommend for a first impression that a normal Windows PC is sufficient. After a test phase or some messing around, you can still look for the right hardware.


(Markus Storm) #5

Yes it is. To truely convince a potential user, you must show that OH can control the devices he wants to use.
The number of people to decide based on virtual/abstract capabilities or docs only is a minority we should not focus on.

It is but as that’s no good choice for a long term use and people will keep what they start with (if and as that works) I would not recommend Windows to any starter. Listing it as an option is ok but to get a openHABian Pi as proposed in the text is a better option.


(Alex) #6

Almost everyone has a Windows PC and when they hear the word “Linux” only they run away screaming. And not everyone wants to buy a new mini calculator with Linux on it before the actual start.

Yes, it does not hurt to have devices already, but it’s not an absolute requirement to try out Openhab.

In the next step you can still point out that it is recommended to switch to a Mini PC.


(Andrew Rowe) #7

I would agree with both of you, it is not necessary for a beginner to own his own device but I believe most do. My own experience might be considered typical?
Like many new user (I believe, just my opinion) I bought a few smart home devices. I took them home, read the directions and installed some app on my phone and started playing with my new toy. It was the device’s inability to automate to the level of customization I wanted and the ability to interact with other devices (from other manufacturers) that led me to search for a solution which ultimately lead me to openHAB.

The discussion is on the suggested new documentation. As such, the new suggested documentation above states

You don’t ‘need’ to own a device to try openHAB. You probably do, but you don’t ‘need’ to

Better version might include something along the lines of…

you probably already own a device you wish to control, but even if you don’t, you can try out openHAB


(Andrew Rowe) #8

On the question of platform:

I strongly suggest no one single platform is suggested. (or emphasized)

Reason being, most people like certain platforms. If you say Windows to a Mac guy, prepare to get screamed at. If you suggest Mac to Windows users, prepare to have things thrown at you. If you suggest Linux to either group, prepare for a blank stare. I’ve been there and bear the scars. People like their platform.

Suggestion:

OpenHAB runs on many popular platforms such as Windows, Mac and Linux)

Don’t create further hurdles. Most, like me, may want to try it out on the platform they are using


(Andrew Rowe) #9

First big Thank You to @lipp_markus for starting this thread. I had considered creating forum versions of the individual pages of the documention to work on together as you have done so above. Great work!

Second point: As noted in the PR, I believe this actual doc resides in the ESH repository and as such may need further vetting before being included in the official documentation. (by the ESH team ect. not sure) This can be discussed in the PR thread

Edit to add:
I believe the ‘Introduction’ page is the landing point for many new users and as such is a vital target for improving the documentation for new users


(Markus Storm) #10

Agree. Maybe mention it does not have to be a classic HA device (actuator, sensor, gateway) but can be a Inet enabled TV or similar as well.

Agree, BUT we should give a recommendation how to proceed because otherwise many users feel lost in choices for the first time right away (those without IT affinity/knowledge for sure).
Something like

OpenHAB runs on most popular platforms such as Linux, Windows and MacOS and on almost any
hardware ranging from Raspberry Pis to desktop computers and server PCs.
You can install it on your desktop computer for evaluation purposes but we recommend using a dedicated
system in the long run. So if you feel serious about home automation better start with one right away.
If you already have any of these systems available for use or have a strong bias towards using any of them,
then it's your best choice to go with it.
Anyone undecided we propose to get a Raspi and use openHABian to get things up and running quickly.

(Andrew Rowe) #11

excellent suggestions both


(Andrew Rowe) #12

OpenHAB runs on most popular platforms such as Linux, Windows and MacOS and on almost any
hardware ranging from Raspberry Pis to desktop computers and server PCs.
You can install openHAB on your desktop computer for evaluation purposes if you already have any of these systems available for use but we recommend using a dedicated system in the long run.
If you have a strong preference towards a particular platform, then that platform is probably your best choice.
If you feel serious about home automation it may be better to start with a dedicated system right away.
For anyone undecided, we suggest a Raspi and using openHABian to get things up and running quickly.


[CLOSED] New Docs Discussion: Should we recommend a platform?
[CLOSED] New Docs Discussion: Should we recommend a platform?
(Kim Andersen) #13

Small change…
You have identified which computer you want to start with. (This may change as you go through the learning curve and your system grow. Make sure to make regulare backups to avoid starting from scratch if changing computer).

Reason - I just realized that the computer I started with (Rpi 3B) does not fulfill my goals.


(Alex) #14

I would also like to point out that it is very difficult to write a documentation that corresponds to the different skills. A beginner is often overwhelmed because it seems too complicated and overloaded. An advanced or professional just gets bored because he already knows most of it.

You should possibly distinguish between several user groups: absolute beginner, advanced and professional.

You could also start with a small and short questionnaire (for example 3-5 questions). Depending on how the reader answers them, you can steer the further sequence accordingly in the right direction.

Possible questions could be:

Do you already have experience of home automation systems?
Do you already have home automation devices in use?
Do you know better with Windows, Linux or macOS?
Are you ready to invest in new PC?
Would you prefer a graphical user interface or would you rather write texts or small scripts?
Do you like DIY or do you prefer ready-to-use?


(lipp_markus) #15

@Celaeno1 @mstormi @Andrew_Rowe thanks much!!
My intent has been to keep this simple and an easy read and not to overwhelm the new user too much.


I don’t think the latter two will read much of the introduction anyway. I attempted to write it in a way, that advanced and professionals can just glance through it and get in a second that they will not learn anything. So, I would suggest to keep it rather simple and easy, without many choices to make as this can easily overwhelm the novice and the more advanced groups will not learn anything new anyway.

For me, this would add complications as all questions would require more definitions to be meaningful. For example: does experience of linking a Hue system to Alexa qualify as “experience with home automation?”
Would it help much to know that the user has a TADFRI system in use?
Personally, knowing that a RPI sets me back only $50 or less, would make a difference when asked if I am ready to invest this amount. But then, is a RPi a PC or not? And what if I have a supported NAS?
etc.


adding it above, thank you both


Much agree. Most users will desire to influence actuators. Adding this to the text above.


Indeed, the docs live here: https://github.com/openhab/openhab-docs; Ultimately, a PR will need to be raised, but I was advised in earlier revisions that it might be best to discuss any major additions first in the forum to gather broad input. On github will be a second round of comments.
Part of this proposed revision, however, will also affect the “Concepts” section, which seems to be pulled straight out of the ESH doc repo. At a later point we will need to have to figure this one out.


I understand completely, however, these are the OH docs and in particular this is an intro for new users. This behoves and I believe mandates us to make a recommendations for all brand new newbies. I would want to believe that the text above is worded mildly enough so that even the strong believers will see their favorite choice mentioned. BUT I also believe that we need to make a statement/recommendations to those that do not follow pre-ordained routes. OpenHABian is definitely the easiest choice for all non computer experts, at least just reading the forum, this seems to be the recommendation frequently given.


(Andrew Rowe) #16

Agree strongly
I believe the introduction is an important section of the documentation for new users and as such is a good place to start with in regard to improving the documentation for new users.


(Alex) #17

For me, this would already be a slightly advanced user!

It is not just about the minimum cost, but the question of whether I have to assemble something, install the OS itself, there is already pre-installed everything, so ready-to-use! Do I really need that to start? If you have the impression that you absolutely need it, but you are shy of learning something new, then you would not even start with it!


(Andrew Rowe) #18

Agree
If I know zip diddly about OpenHAB, I’m supposed to go buy a Pi?
If I can’t figure out what platform I want to give openHAB a test drive, I probably don’t even know what a Razberry PI is (I didn’t and I’m a kind of geeky guy)

@lipp_markus please join in separate discussion about recommended platform here:
https://community.openhab.org/t/new-docs-discussion-should-we-recommend-a-platform/62822/2


(Maurits) #19

Great work @lipp_markus ! Good introduction where you take an interested reader through the step-by-step process, learning them some basics along the way.
I would not complicate it as per Alex’s suggestions, it needs to stay an introduction.
Thanks.


(Jerome Luckenbach) #20

Good work. :slightly_smiling_face:

Waiting for your PR. :+1: