Looking for the ultimate beginners guide

Setup, Configuration and Use Beginners
15

"MQTT Binding

This binding allows openHAB to act as an MQTT client, so that openHAB items can send and receive MQTT messages to/from an MQTT broker. It does not provide MQTT broker functionality, for this you may want to have a look at Mosquitto or others. There are test servers available at m2m.eclipse.org and test.mosquitto.org."

This bit of text leads me to believe that a binding somehow attaches openHAB to MQTT and allow it to talk to the MQTT broker the same way the bit of code I wrote does, but what I am confused about is in paperUI > Addons > Binding I clicked install MQTT Binding and it now says uninstall (hinting that it is installed) however when I go to paerUI > Configuration > Bindings all I see there is a GPIO binding, so I don’t know what is going on and if it is bound or not.

16

In order to get a response by someone knowing mqtt I suggest to put that into a separate thread using a topic that points to the question. Is said before openHAB has an nearly uncountable number of bindings/addons, no single user will know them all!

17

But I don’t know if I am even up that stage yet… As I said before you don’t know what you don’t know and I don’t know if I am at the start of the process or the end. I think I am around the 80% mark (gut feeling) but I really don’t know, the point of this thread is to get a clear answer as to what order things should be done in (without looping me in circles) and then perhaps I can drill down into the individual diagnostic problems, but I am taking a shot gun approach at the moment blasting away at everything trying to find my way out of the woods.

I could be trying to configure a piece of software that is dependant on another piece of software being installed and I don’t have it installed, so without some logical step by step process I am in the dark here.

I have stumbled upon some of the stuff necessary to get a result (although have no idea if it is configured right) but I am no closer to knowing where I am at in the process. I am basically looking for a straight forward do A then B then C and by the time you get to Z everything will work.

18

Using openhabian you should have already setup the OS, openHAB itself and the samba shares in order to even connect to the config files via network-shared folders from another pc/mac or whatever.
At this stage you should be able to configure openHAB via the PaperUI and some cfg files (for OH1 bundings).
Everything beyond that is up to your specific needs. Looking at the topic a person with experience in using mqtt might not look into this thread at all, hence my suggestion.

19

Trying to get some lights on :wink:

openHABian?

ok for now, but please be aware that Smarthome Designer is outdated and won’t be updated anymore, instead please use VSCode with the openHAB plugin https://code.visualstudio.com/ VSCode is opensource under the MIT license.

:smiley: Well, in GNU/Linux ‘Everything is a file’ and there is one root for the file system:
This is the file system root: /
This is not the file system root, but the user directory of the user root: /root/

The file system is way easier than in windows, as there is only one root / and everything is a child of /
All common users have their home directory in /home/ (just like C:\Users\ in Windows)
All common settings reside in /etc/ (and in question of openHAB2, you will find them in /etc/openhab2/

The syntax should be easy:

Switch      MySwitch    "My switch [%s]" <light> (myGroup) {binding=""}
  /\          /\            /\              /\      /\         /\
Item Type  Item Name    Item Label         Icon    Group(s)  Binding(s)

Everything except Item Type and Item Name is optional.
The Label may or may not contain an variable part [%s] (%s is ‘state as a string’)
If an Item belongs to one or more Group(s), the group will update its state in dependence of the item(s). If the group is used to send a command, this command will be sent to all group members. The group has to be defined independently in the items file.
Now to the binding: The definition of this part is dependent of the binding, so this part is the most complex part, and it should be described in every http://docs.openhab.org/addons/bindings.html documentation, so for mqtt this would be
http://docs.openhab.org/addons/bindings/mqtt1/readme.html#event-bus-binding-configuration.
There are two parts of communication, inbound and outbound. For mqtt these parts are independent, so you have to configure both parts, > for outbound, < for inbound. So you could use

Switch mySwitch {mqtt=">[mybroker:myhouse/office/light:command:ON:1],>[mybroker:myhouse/office/light:command:OFF:0],<[mybroker:myhouse/office/light:state:MAP(light.map,*)]"}

and a map file to transform the received state to ON or OFF.

20

The problem that everyone is trying to say is there is no straight forward a through z step-by-step process for OH because everyone’s steps are completely different.

openHABian does a fantastic job of doing automatically for you all the step by step tasks to get OH installed and running on a Raspberry Pi. If you start with the image, after about 30 minutes you will have a fully installed OH with samba and all the other settings necessary for OH to work with a variety of technologies.

It takes care of everything and includes installation and configuration of a lot of common ancillary software like Samba and Mosquitto for MQTT.

This is why we recommend openHABian so heavily for new users. Step 1 is just “install openHABian” image.

But after this point step 2 could be one of a thousand different steps depending on what exactly you want to build with OH.

So let’s assume you want to set up MQTT as your first step. If you used openHABian, you would already have Mosquitto installed and configured, or can do so now easily by running openhabian-config and browsing the menus until you find Mosquitto.

Now you need something in OH that can talk to the MQTT broker from OH. These add-ons are called Bindings and they serve as a bridge between OH and whatever technology or API you are interacting with. There are two flavors of bindings, 1.x version bindings which are older bindings written before OH 2 was released and which have not been rewritten to take advantage of 2.x concepts (i.e. Things, Channels, and configuration through PaperUI).

Most everything you need to know to create an Item config for a given binding is documented in the binding’s README. For MQTT you can find that here:

https://docs.openhab.org/addons/bindings/mqtt1/readme.html

You can also find a lot of information by searching the Forum. There are tons of examples. For MQTT, the best posting is MQTT Binding (v1.11) Getting Started 101.

But to make my point again, step 2 for me when I first set up openHAB was getting Zwave working. Other user’s step 2 could have been getting KNX working, or HomeKit, or something else. This is why there is no step-by-step process to provide. After step 1 everyone is on a different path. So the best I can offer is:

  1. Install using openHABian: http://docs.openhab.org/installation/openhabian.html, though even here, everyone will want to run different. I for one run in Docker on a VM.

  2. Review the Beginner’s Guide and Concepts section of the User’s Guide and make sure you understand some of the key concepts: Items, Things, Channels, Bindings, etc.

  3. Choose the binding you want to configure first. You have over 200 to choose from.

  4. Install the chosen binding.

  5. Configure the binding as documented in the readme

  6. Create or accept Things from the Inbox where applicable as documented in the binding README

  7. Create Items as defined in the binding README.

  8. Start to explore Rules, sitemaps, HABPanel. and Persistence as needed.

I can’t be more specific than this because step 4 onward is going to be specific to the chosen binding.

2 Likes
21

@HeadScratcher I totally agree with @rlkoshak

I want to add that as a beginner you might want your “step 2” to be something that teaches you about the possibilities of openHAB and how things like “items” and “rules” work. To that goals I’d suggest to look into one of the easier Tutorials and just play around with the results a bit. See here for a list: http://docs.openhab.org/tutorials/index.html#community

My personal favorite in terms of learning different aspects of openHAB without being dependent on certain hardware is: Speedtest-cli Internet Up-/Downlink Measurement Integration - however I have to state that it was written by myself, so I might be biased :smiley:

2 Likes
22

Thanks for the info on Linux that helped. I thought logging in as root would automatically take me to the root directory, and that was why I was confused when I typed ls and saw nothing, but that is just because the root user home folder is empty, and I had to type cd / to take me to the real file system root, and type ls where I found what was expecting to see.

Ahhh I think I see why my code went into an infinite loop causing MQTT.fx to produce hundreds of entries before I stopped it…
Switch Patio_Lights “Lights” (gPatio) {mqtt=">[myMQTT:FirstFloor/Patio/light:command:ON:1],>[myMQTT:FirstFloor/Patio/light:command:OFF:0],<[myMQTT:FirstFloor/Patio/light:command:ON:1],<[myMQTT:FirstFloor/Patio/light:command:OFF:0]"}

Yours only switches the command on the output, but appears to do a state change on the other through Transform (I came across and made a couple of those when experimenting with fan speed).

Switch mySwitch {mqtt=">[mybroker:myhouse/office/light:command:ON:1],>[mybroker:myhouse/office/light:command:OFF:0],<[mybroker:myhouse/office/light:state:MAP(light.map,*)]"}

Ok that makes much more sense. I did actually get my C# code to update the state of the switch in openHAB last night by creating a rule like this.

rule "TurnLightOn"
when
Item Patio_Lights changed
then
if((Patio_Lights.state as DecimalType) == ON){
sendCommand(Patio_Lights, ON)
}
else{
sendCommand(Patio_Lights, OFF)
}
end

I used a rule I found on Github and modified it until it worked.

23

Sometimes though you just want to have a play and may not have any devices to set up, so openHAB is less inclined to play nicely with you because nothing is found automatically.

To this end when I have some time I would like to fully develop the C# program I am writing to simulate some devices like light button, or windows / door contacts, so you can at least have a bit of a play with openHAB / MQTT without ever needing any hardware (other than one PC) to do it.

24

Take a look at the demo. If installing openHAB from scratch chose “demo” at the start page (http://openhabip:8080/)

25

This is of course true but it would be great if a consensus were reached acknowledging the basic tasks and scenarios commonly faced when setting up OpenHAB. For example, cookbook examples for controlling lights, setting up a mobile UI, setting up rules, Sonos integration, pitfalls to avoid etc. would be really helpful. For a beginner or casual user who doesn’t spend every day under the hood it can be challenging to stay on top of the elegant but complex abstractions that make up the OpenHAB environment. Being able to fall back on cookbook howtos (or some sort of wizard for lack of a better term) would greatly enhance the OpenHAB experience in my opinion.

1 Like
26

This is a side effect of the first binding you chose. MQTT is a 1.x version binding (a 2.x version is in work). Consequently, indeed, nothing is found for you. However, if you had chosen something like Zwave, Network, Wunderground, Astro or any number of other 2.x bindings you would have found that your devices more likely than not would have automatically been found and Things generated for you which you would have been able to select from the Inbox.

There are tons of just such cookbooks in the Tutorials and Examples section of the Forum.

We are open to any ideas and/or contributions you or anyone else may have on how exactly this sort of thing could/would be encorporated into docs. Right now the most popular and/or comprehensive tutorials are listed in the docs here:

http://docs.openhab.org/tutorials/

@ThomDietrich, I notice the MQTT 101 tutorial isn’t in the list. I’ve linked to is so many times maybe it is time to add it. WDYT?

1 Like
27

@rlkoshak I was under the impression the new MQTT Binding would arrive with openHAB 2.2, that is not the case. :disappointed_relieved: Hence yes I’ll add it to the tutorials list.

1 Like
28

Not entirely sure why I am having so much trouble following the logic of these tutorials but something is not gelling as well as I would like. Went back to the beginner tutorials and tried to follow the one that sets up the Network Binding (which is probably a reasonable start place for most people with a network) and I got it working to some degree.

I was trying to use the mobile phone presence information, since detecting if our mobile phones are on the network will eventually be part of the home automation system.

This time it found a heap of network devices and it put them in the Inbox. By turning on the Item Linking it created some Things (which appear to be physical devices, and may not be necessary) and then I somehow created some Channels (don’t know if I need them) on our mobile phones, with online and time as Items.

Turned Item Linking back off since it hides all the items I created manually, but I am well and truly lost as to how all these Things, Items, Channels, Groups etc etc interlink with each other.

I have lights semi worked out, but have no idea how to make something practical from this new information as I feel like the tutorial ended without any outcome. Kind of you have now built a car, but have no instructions on how to drive it.

If anyone can post some sections of code to paste into the relevant files to get it going that would be greatly appreciated. Please DO NOT link to more tutorials I can’t follow.

If you can just post this bit goes in this file and this bit goes in that file, once I see it working I should be able to reverse engineer the thinking behind it. Currently I have a mass of scrunched up mess in my head.

What I want it to do is recognise the mobile phones on the network. So obviously the Network Binding is the first step to doing that, but I don’t need the phone or any of it properties (Items?) to act as a switch (I tried to change the Switch to a Image or String but things got ugly).

Basically I want some kind of visual representation to know if the phone is on the network or not (no switch just an icon of full signal or no signal, BUT… if the phone is connected or not connected I want it to perform some kind of action (perhaps send a message to MQTT) to say it has connected or disconnected so that information can actually be used by the system.

Knowing the phone is connected without an outcome is kind of pointless. Hopefully someone can just give me a simple cut and paste without further confusion. TIA.

29

We could but it would be a link to the documents that we have spent so much time writing but you done want to read. So instead you want us to retype what has already been written much better here.

A simple examples of what to type in here and there will not help you because you don’t understand some really key concepts. Concepts which are documented in the Concepts section of the User Guide (funny that).

A Device is represented in OH as a Thing.

Each piece of information and reach control on a Device is represented as a Channel.

Channels get linked to Items.

Everything in OH, from Rules to sitemaps work with Items.

According to the Network Binding Readme, there is an online channel for a Thing which must be linked to a Switch Item. The state is this Item will be ON when the device is on the network and OFF when it is not.

The Items Documentation and myriad of examples show how to define an icon for an Item. You can see the list of available icons on the docs (use the search if you can’t find it). If defining items in a text file, the icon guess after the label inside <>, e.g <network>. If defined through PaperUI enter the icon name under Category.

As the Sitemap documentation says, you can put tab switch on your sitemap for use in BasicUI or ClassicUI using a Text element.

Now I could have just put a bunch of things and items and sitemaps in this posting but without the knowledge of the difference between a Thing and an Item it would have done you no good.

1 Like
30

I’ve come to the conclusion that the problem is not me, but the way the instructions are laid out. They simply are not intuitive, nor are they laid out in a way that flows.

For example you would typically arrive at the home page of a website and in this case the item that jumps out most for a beginner is the “Getting Started” right in the middle of the page, so you click that and it takes you to what is supposed to be a Tutorial (Beginner).

You are greeted with:

Overview
This part covers all the basics to use openHAB after you installed it: how to perform the first-time setup, add some bindings, discover and configure things for the first time and finally how to create a sitemap and some basic rules.

What is a binding? discover and configure things? are they talking generically about things in general or Things? If they are talking about Things what is a thing? sitemap and rules? huh what are they?

I’ve just arrived on this page as a “beginner” and don’t know the first thing about these things. Where is the page that precedes this page that gently and in very simple language pictures explains what each of these things are?

At this point I know nothing so what is the point of launching into how to configure a Network Binding when you don’t even know what a Network Binding even is.

It is fairly obvious that once you understand the fundamentals of openHAB a lot of the other stuff will fall into place, but within that first little Overview paragraph there are two hyperlinks to take you off to other information without even explaining the most simplest of things about how it all fits together.

There should be a section that in bold print state ‘DON’T PANIC’ in large, friendly letters on the cover.
Then with pictures and text in little words explain each of the individual components and how they relate to one another.

Only after having read that is a beginner ready to move onto the Overview. You will note in menu items
http://docs.openhab.org/tutorials/beginner/index.html that there is no Concepts for a newbie to get there head around, only from clicking through who knows how many hperlinks with the truly unknowing find it.

This is a common problem when written by people who know the system so well, they overlook what to them is the most basic of details, but for the completely newbie this is pivotal information.

31

When I started using OpenHAB, the steps I took to learn what was needed was read, read, read and read. Mostly in various part of the docs, but also here in the forum.

But reading only takes you so far, at some point you have to start doing something. So I started just playing around, first with simple bindings like Astro and the network binding, which don’t require any special hardware. Just click on everything you see until you understand what it does, at this point you can’t break anything if you do something wrong.

When you think you start to understand how things work (or don’t understand something), then go back and read some more to get a deeper understanding of the concepts. No one (I think) has said that OpenHAB is easy.

2 Likes
32

I find it very hard to read, not because I can’t (I read very well) just that my mind wanders off onto other tangents if left with too many unfinished ends. For programming I get the most out of reference books where I can just look up an example and work it out, then I do from a long drawn out verbal explanation.

Often the longer something goes on or the more tangents it takes the harder it is for me to follow because I am trying to process everything at once. That why I really like things that take a linear approach, especially on subjects that are hard to grasp.

1 Like
33

A glossary like this at the very beginning would make a world of difference to me.

Glossary
Glossary.jpg1143×979 155 KB

34

Hello @HeadScratcher, I don’t have much time to answer in length right now. I just want to say two things.

  1. Such a glossary exists here and here. I’m not saying they are perfectly placed, I just wanted to point you to them.

  2. The Beginners tutorial is not perfect. A volunteer just as you or me decided to contribute it. Sadly he did never invest more time for a second revised version. I am fully aware of the problems of the Tutorial but it is incredibly complicated to write a good documentation (as you’ve proven) and I (as the documentation lead) am concentrating more on the User Manual part of the documentation, as this is the area every reader will end up eventually when looking for exact details.
    With that said, I would encourage you to help improve the Beginners Tutorial! You could revise the whole article or simply note down all things that bothered you so someone else has a list to work through. “Someone else” is the tricky part as you can imagine.

In general I can only agree with the others. Read the User Manual and experiment with the Tutorials&Examples available. Many volunteers have contributed great things over the last 12 months to make those places a very good source of information for openHAB users.

I’d like to suggest the following example as a starting point to understand a few concepts. Speedtest-cli Internet Up-/Downlink Measurement Integration
Fun fact: It is my first Tutorial I’ve posted here in the community (I’ve improved it over time). The tutorial includes many basic concepts you should know about. Be aware that it does not address Paper UI, Things, Persistence or Transformations - as these are imho advanced topics you can learn after you’ve made your way through the basics. Here’s how you should go at it: Read the tutorial, every time a term comes up you don’t know: Study the respective documentation article about it. The Tutorial for example quickly introduces an Items file -> Read the Items article and make sense of the shown content.

Good luck!