OpenHab 2.5M3 MQTT from scratch

Setup, Configuration and Use Beginners
1

  • Platform information:

    • Hardware: RPi2B
    • Openhabian, updated to 2.5M~S1710-1
    • Also Sonoff Basic with Tasmota V6.6 running

  • As per the subject. How much can be done using PaperUI?

*Please, no comments about OH V1 bindings. Also no comments about text files unless there is ABSOLUTELY NO WAY to achieve without creating a text file.

  • Goal: Create a single switch that can be turned on and off remotely and a rule to turn the switch off at a given time.

Time of query: October 2019

Actions so far:

  1. Download disk image and write to Micro SD

  2. Insert Micro SD and boot RPi

  3. Point browser at RPi and select “Standard” setup

  4. Opened logs and made SMB connection from PC

  5. Made terminal connection to RPi

  6. Ran openhabian-config

  7. Performed “02” Upgrade System.

  8. Performed “40” , “41” to choose Release version

  9. Performed “10”, “11”, “12”, “13”, “14”

  10. Now into PaperUI: Turned Item Linking to Simple Mode

  11. Installed MQTT Binding (2.5.0 Snapshot)

  12. Installed Network Binding (2.5.0 Snapshot)

  13. Installed MQTT Broker Moquette (2.5.0 Snapshot)

  14. Went to Inbox and searched for new things and found:
    MQTT Broker:System MQTT Broker:embedded-mqtt-broker
    MQTT Broker:System MQTT Broker:MQTTBridge

  15. Added both as “Things”

  16. Used an app, “MQTT Explorer” to confirm that the broker is operating and that I could control the Sonoff Basic:
    Topic: cmnd/MBRLight/ payload of 0/1
    Topic: stat/MBRLight/RESULT
    Topic: tele/MBRLight/State

  17. And now to create an interface for my iOS device . . .
    *** I assume I have to create a sitemap, but how do I link that to the items I have created in PaperUI?***
    Thanks to comments below, it appears clear that the GUI root ends here and we are back to text files.

Notes:
A. The words between “sitemap” and “label” ARE the filename for the sitemap.
B. How to find the mqtt topic??? I found no documentation, but after some random clicking around, do the following in Paper UI:
i) Click on Configuration
ii) Select Items
iii) Click on the notepad (?) icon to the right of the item

shot2
shot2.png947Ă—102 9.63 KB

v)et wala! Useful information is copied to the clipboard . . .

mqtt_topic_b658979e_MBRL

   vi) Which finally gives me something I can put into the sitemap.

My sitemap file looks like this:

sitemap home label="Home" {
            Switch item=mqtt_topic_b658979e_MBRL label="Master Bedroom"
}
  1. “Automation”
    Hopefully back to GUI here.
    In Paper UI -went to Add-ons -> Misc and installed Rule Engine (Experimental).
    After clearing the cache in my browser and reloading PaperUI, I could see a “Rules” menu item on the left hand side.
    Clicked the “+” icon and presented with:
    Shot3
    Shot3.png978Ă—410 14.9 KB

(Very Promising)

  1. This link assumes text files.
    I found Rich’s documentation here

  2. So following Rich’s instructions . . .
    When:
    Shot4
    Then:
    “Publish an MQTT message” (seems reasonable as that is how the light is controlled)
    Shot%205

POW! I seem to have run out of documentation or even a clear way forward.

  1. Name and Description seem to be editable, but not sure why I should. Select thing gives me this dropdown:

Shot6

And again, my carer has to wipe the drool off my chin. . .Seems I should be using a Broker item that is the Bridge as the Bridge connects OH workings to the actual Broker???

So I pick the first item in the dropdown and click OK. And then a tick leaving me with this:

Shot%207
Shot 7.png767Ă—213 12.5 KB

The play button runs the rule and the logs confirm that the rule ran:

2019-10-08 07:32:47.630 [.event.RuleStatusInfoEvent] - 1972dda1-f4c1-4d03-b322-83c8f0c0851b updated: RUNNING

2019-10-08 07:32:47.637 [.event.RuleStatusInfoEvent] - 1972dda1-f4c1-4d03-b322-83c8f0c0851b updated: IDLE

But of course nothing happened because the rule did not know about the Item to be controlled.

Question: Is that the state of the ERE as of October 2019?

I’ll answer myself here . . .

  1. A new “then”
    Use “send a command”
    Under Configurations, select the item (Master Bedroom Light)
    Select the Command from the dropdown: OFF
    OK
    Big blue tick
    Run the rule and the light goes off

    A! maze! ing!

Conclusion:

  1. It is in fact possible to use only a GUI to create an MQTT connected item and then a rule to turn it off at a selected time.
  2. You still have to create a text file sitemap if you want to use something like the iOS OpenHab app.

Many thanks to those who contributed here and of course to the developers. The GUI does not make Home Automation simple enough for non-developers like me, but it IS getting to the point where I could run an introduction session (now) for newbies on this Case Study in less than an hour and leave them with a working system.

2

Did you already create a generic mqtt Thing with channels for your Sonoff Basic? The generic mqtt thing is bound to the “broker Bridge”. Each Channel of the generic mqtt Thing is one channel of your Sonoff Basic, e.g. for Switching ON/OFF, getting Information about your Sonoff Basic such as RSSI and so on…

As you switched on Simple Mode, this should result in a bunch of Items (you can take a look at Paper UI Control to see if the Switch is working like intended).

When all is working well, you have reached the point of Text configuration, as you can’t build a sitemap without a text file.
I strongly recommend to download VisualStudio Code (not! Visual Studio) as Editor. You can get it for Windows, Linux and MacOS. After installing, search for the openHAB plugin (the marketplace is builtin VSCode) and install it.
Configure the openHAB Plugin to use your openHAB server (host=“ip.of.your.openhabserver”)
Connect via SMB to the openhab2-config folder.
Ensure that you have permission to write.
Change to the sitemaps folder and create a file named my.sitemap.
Write the word sitemap into the file and chose to autocomplete to the code snippet. This will result in something like that:

sitemap name label="Sitemap" {
}

Insert my instead of name and change the label to whatever your sitemap should be displayed as.
Place the cursor between the curly brackets.

On the left side of VSCode, there should be an openHAB symbol. Click to get a list of Things and Items.
Right-click on the Item you want to insert in the sitemap, chose the option to insert into the sitemap.
Save the file.

Done.

Now you should be able to access the sitemap via http://<ip.of.your.pi:8080/basicui/app?sitemap=my or the iOS/Android apps.

3

Hi!
I suggest to disable Simple mode for item linking, this way when you manually create your Items via PaperUI you can see the name to use in sitemap.

And yes you have to create a sitemap file, by now you have to create a text file for it.

4

Thanks, Alexxio.

I like the idea of disabling Simple Mode. It will give me some of the required information.

Now I have to ask: Is your response based on the current state of OpenHab (V2.5) or are you referring to earlier versions?

While I absolutely appreciate the effort, I have been “burned” too often in these forums with well meaning advice that is behind the curve with respect to the software.

I am trying to see how far we can get with Gui only before I leap (back) into text files.

5

Hi Udo.

Many thanks for your reply.

I did indeed create the Generic mqtt thing.

Unfortunately, Simple mode did nothing about channels. I had to manually create the Command channel and next job is getting the Information channels to work.

Since you and Alessio have both stated that I need to create a text file for the site map, it begins to look like that is the way of it.

Part of this project is trying to understand where the intended limit is for PaperUI / other GUI in terms of getting a working system.

Now - you suggest a whole new tool set to write the text. (Remember - at this stage, I have ONE switch)

While I get that as a developer creating hundreds of lines of code, a decent tool set is important - I feel that it is likely overkill : )

How about the included HomeBuilder GUI? Is there enough documentation to let me build the sitemap in that tool?

Is there documentation somewhere that explains how the text based sitemap links to the database stored items and things? (I have not yet found it)

For example this starts by assuming items in text files.

Cheers!

6

Indeed I’m using OH 2.4 , But frequently this suggestion (about simple mode) was given by other more experienced user.

Let’s wait someone with 2 .5 to be more sure it has not changed.

About sitemaps, I can confirm you that writing a text file is the only way even with 2.5 (unless you want to use only habpanel or other alternative UI not sitemap based)

7

Hmmm . .

One of the reasons I went to the 2.5 Milestone release is that the MQTT binding / broker in 2.4 had faults according to the author (?) - and now I cannot find the discussion where I read this.

Are you using the embedded broker?

8

Simple Mode is only to auto create Items per Channel.
generic mqtt does not support automatic configuration. You can enable home assistant auto-discovery (SetOption19 1 at Tasmota, 6.4.1 and later) and after that you should be able to autodiscover the thing via mqtt home assistant thing (I don’t remember the correct name…).

Please be aware that Paper UI will be deprecated in OH3. (But there will be another UI…)

For a quick test, you can use an editor like nano at your RaspberryPi and create the sitemap manually.

/etc/openhab2/sitemaps/my.sitemap:

sitemap my label="My Sitemap" {
    Default item=MySwitch
}

But now the name of the Item must be MySwitch… (No, Simple Mode ON will never result in such simple Item Names)
At least, you can change MySwitch to the correct Item Name. You can get the Item name via Paper UI, by taking a look at the Channel you want to use at the sitemap, click at the up/down arrows right from the channel name, then a list will appear with the Items linked to the channel. There should be a “Copy to Clipboard” symbol to get the Name to the Clipboard.

I still recommend VSCode though, as it makes the whole life a lot easier… :wink:

The HomeBuilder is… well… I don’t want to be rude… doesn’t make any sense to me (did a check and couldn’t get a result that satisfied my needs).

In question of items (text based vs. json based), there is no difference. Items are Items are Items. You can simply use them, no matter which way they were created…

9

The Concepts section of the Docs should mostly cover this. The tl;dr is Things represent devices. Each sensor reading or actuator on that device is represented by a Channel. Items link to Channels. Everything else in OH (Rules, Sitemap, HABPanel, HABap, Persistence, etc) work with Items.

As documented in the Sitemap page in the docs, each sitemap element has an “item” tag where you supply the name of the Item you want to display or control using that sitemap element.

10

Hi Rich. Appreciate the reply. Unfortunately, I had to get the binoculars out to measure how far over my head your reply was : )

I am very much down in the mud, randomly clicking on things and my carer occasionally wipes the drool off my chin.

11

I’m sorry, but without reading the documentation you will never get out of the mud.

1 Like
12

As others have said, turn off Simple Mode. It’s far more trouble than it’s worth.

You do have to create a .sitemap file unless you want to use HABPanel.

What you found is not the MQTT Topic. What you copied to the clipboard is the Item name that was automatically created for that Channel.

You didn’t actually explain yet how you created that Channel. I think you are missing some steps in your description.

At this time the default recommended Rules engine is Rules DSL which get written to files.

Which is out of date and incomplete. One of the reasons it’s called “Experimental” is because there is not yet adequate documentation for it and it’s undergoing significant changes every day.

“Experimental”

Because some people have hundreds of Rules. Without a name and description how do you tell one Rule from the next in the list?

image
image915Ă—633 36.6 KB

Without the name and description all you get is that random string of numbers of letters.

Are you running the latest snapshot or at least running 2.5 M3? Then yes, that’s the state of the ERE right now. “Experimental”

But here’s the thing, even once the ERE gets to prime time, it does not free you from needing to gain at least a basic understanding of OH and MQTT (Introducing the MQTT Protocol – MQTT Essentials: Part 1 is a good getting started tutorial on MQTT) to successfully use it. While MQTT isn’t the hardest binding/technology to use successfully in OH, it is certainly not something you will be successful at just randomly clicking around without at least a minimal background in both OH and MQTT.

This is a pet peeve of mine. This is actually a horrible name for a rule. Why?

  • How do you distinguish between this Rule that controls the living room lamp and some other Rule that sends messages to an MQTT topic to control some other lamp?
  • The Rule doesn’t need to know and shouldn’t care that the end device is controlled by MQTT in the first place. That’s what Items are for. You could change the Link in that Item you created to point to a Zwave light and never have to change this Rule (note: you need to turn off Simple Mode).

All names, be they the names of Items or the names of Rules should be descriptive and meaningful in your home automation context. Note that they must be unique as well. If that Sonoff controls the living room lamp, name the Item “LivingRoom_Lamp”. Have a Rule that turns that lamp off at 10:00pm? Name the Rule “Turn off LR lamp at 10pm”.

13

Gotta say, Opus. I would read the documentation if it existed and if I could be sure it referred to a similar version of the software to what I am dealing with.

I’m not trying to put you and the other developers down in any way, here. I really appreciate the efforts you guys put into helping dumb mugs like myself.

As has been mentioned by others, these issues are the nature of open source. I am assuming you want your software to become more mainstream over time. (I could be wrong :slight_smile: ) More mainstream means idjits like me.

14

Hi Rich.

Again many thanks for taking the time to deal with my dumb issues.

Some of your responses suggest you had forgotten what this post was about:

Goal: Create a single switch that can be turned on and off remotely and a rule to turn the switch off at a given time

  1. Simple mode - happy to bow to superior knowledge here. I did indeed need to turn it off during this process. It was turned on because of “something I read somewhere here” ™

  2. Sitemaps - I am beginning to understand the nature, purpose and state of play of some of the GUI’s. Habpanel is a project for another session when I have enough free time . . .

  3. MQTT Topic / Items - I freely admit to not understanding this. Hopefully a little better now. In a previous incarnation, dealing with MQTT required reference to topic and payload in items file and things file. I’m now understanding that once the thing is created, some of it’s properties are the MQTT topics and payloads. Most OH tasks involving that thing, just refer to the thing and let it’s properties do the deed. (e.g. automation)

  4. ERE and documentation -Rich, I was able to get there in the end based on your documentation, and I would have to be even dumber than I think I am to have missed the experimental nature of this beast. Still, it’s been in there for years (??) and I wanted to have a play.

  5. Naming and describing rules. What can I say? In a production environment, of course we name things. In this case, there is one switch and one rule. I didn’t feel the need.

  6. Version? I thought I covered that at the beginning of the post and in the title?

  7. “Publish an MQTT message” is actually not my words. It’s an option in ERE when creating an action in the “Then” section. And on your pet peeve? Again, point 5 above.

Documenting this little journey and having the valuable input from developers has certainly helped my understanding of the state of the art of OH. Even though I don’t have a lot of time to put into this and am not even a poor man’s programmer, OH is an impressive and exciting tool. Many thanks!

15

This is an incorrect understating. The Item is an abstraction. It knows nothing about and has no MQTT properties. An Item had zero or more links to a Channel on a Thing. The Thing is what knows about MQTT and topics and all that stuff.

Items and Things are coequal concepts in openHAB. A Thing isn’t just a property on an Item.

No, but when I see something that is incorrect or demonstrates an openHAB antipattern I am compelled to respond. Your post will remain up forever and many hundreds of users will happen upon it and try to follow it. And if the antipatterns are not addressed in this thread, I’ll be spending hours down there road correcting them when those users do follow this example. So no matter what you intended, my intent is to save us work down the road by at least bringing up the antipatterns and providing an alternative.

As I often have to say, most of my responses to posts like these have more to do with the OP and more to do with the future readers.

16

Are you aware of the selection box at the top rigth corner of the documentation where you can select the version?
See here:

Screenshot_20191009-091607_Chrome
Screenshot_20191009-091607_Chrome720Ă—1280 209 KB

17

Rich

I have edited my earlier reply (item 3) from item to thing. You are, of course, correct.

Cheers!

18

Hi Opus.

Yes, I am. I assume that this screenshot is indicating that info is about the MQTT binding V2.4? Again, not blaming. I understand that someone has to write the documentation and that the latest builds easily get past the documentation.

I believe I read a post from the author of the binding (David ??) stating that there was an issue with the 2.4 version that prevented the PaperUI from working properly, but that the 2.5 snapshot did work. That was my reason for going to the snapshot and hence beyond the documentation.

And my experience seems to have borne that out. Amazing that bug fixes . . . fix bugs : )

Cheers and again, thanks for the info!

19

The maintainers are really good at making sure the docs for the bindings are kept up to date. If the binding changes in a way that the docs need to be changed, that update b is not accepted until the change in the docs is also made. So the binding docs are almost without exception always up to date.

The point of the screenshot opus showed is that you can and should select the version of the docs for the version of OH you are running. When you select “latest”, you are literally getting the docs from the latest changes merged into OH in the hat 24 hours.

The main docs are a little more prone to fall behind but even those are kept pretty up to date. At most there may be some new feature that was added recently that hasn’t been documented yet. The OH cute doesn’t really change that much so the docs remain pretty stable. You can see that by noticing how few changes there are between versions of, for example, the Items page.

If you do find something not up to date or incorrect or not clear on any of the docs, please at least fine an issue. There is a link at the bottom of every page though that will take you straight to the file if you are willing to edit it yourself.