Issue of the topic:
Hello, I’m fresh openHab user and I would like to learn how to create custom widgets to be able to customise my default layout page with custom widgets for my GREE air conditioners, Xiaomi Airpurifiers etc.
I was looking through openHab documentations, but sadly couldn’t find any step by step tutorial explaining different components, their properties and how to write customised widget from the begioning to the end.
Maybe some experienced users can point me in to the write direction? Thx
I’ve seen https://www.openhab.org/docs/tutorial/custom_widgets.html, but I think it’s to messy, trying to explain all things together. Another thing is that it uses examples from openHab tutorial which is difficult to follow without those “Smart things” they used.
I’ve been poking the https://www.openhab.org/docs/ui/components/ also, but having some problems to combine the knowledge from those two pages. That’s why I’m looking for step by step beginner tutorial for custom widgets.
Let’s try different approach. I’m trying to recreate the sitemap example from GREE bindings page using custom widget. I have two GREE air conditioners, so seems perfect scenario for using one custom widget for both of them.
Problems I have:
Where I should edit the widget: openHAB, VSCode, notepadd++? How to import/save it to openHab?
As with most things in OH, there will never be a ste-by-step tutorial because any such tutorial will be
that it uses examples from openHab tutorial which is difficult to follow without those “Smart things” they used.
The steps change depending on the Things and Items in use. Any such tutorial will look a whole lot like the Getting Started Tutorial.
As the Getting Started Tutorial page says:
Where to Create Custom Widgets
In MainUI under Developer Tools there is a “Widgets” option.
That’s where you create custom widgets. There is no mention of VSCode nor Notepad++ nor importing and exporting because OH doesn’t support any of those. You can create a custom widget in that one place. You can “import” a widget (for now) by copy and pasting the YAML code from an example into that Widget page.
It doesn’t use Frames. Widgets are 100% and completely separate from and works nothing like Sitemaps. If you have a complex widget in mind, you choose an appropriate container widget. For a stand alone widget F7-card might be a good choice. For a List widget an oh-listitem might be a good choice.
There is no such thing as Mappings in Page widgets. Again, Pages are completely different from Sitemaps. It’s entirely new concepts with very little to no overlap.
If you want a button, you can create an f7-card and put an oh-button on that card. You can use an expression to change the label of the button based on the state of an Item. Or you can use the Item metadata to define the mappings and use an oh-list widget to display and select from them.
Pages presents you with a big box of Legos. But to see some ways for how they can fit together your best bet is to look at examples like Hans-Jörg posted. Find something in an example that looks close to what you want and look at the code to see how it’s constructed.
Or stick with Sitemaps. There is nothing wrong with that either.
Just paste the full URL into message text gives a linke like I posted, but you can also mark a word and add a link via the edit buttons, which gives a link like @rlkoshak used …
The Widget builder will give relatively meaningful errors when you get it wrong which is nice. TAML is pretty straight forward. It’s hierarchical. Indentation indicates the hierarchy.
When looking at the reference for a given widget it starts with the widget type (e.g. component: oh-button). Under that you’ll have a config which will be any of the config parameters indicated in the reference page for that component.
There are additional advanced options that one can set which come from some of the upstream frameworks like f7 or CSS. But that’s really advanced stuff I can’t help with.
No but if you will be doing very fine tuned customizations learning a bit about F7 could help. F7 is the JavaScript UI framework upon which MainUI is built. The oh-components are simplified f7 widgets that do not require as much knowledge of F7 to use properly. But they are also more limited if they don’t work exactly like you want it to.
Yes. defaults is where the properties for the container widget are defined. slots are where you will add widgets to that container. You can have widgets embedded in widgets as deep down as necessary.
Note I’m far from an expert on custom widgets so I might misstate something here.
CSS can be used for some things but others can be achieved through expressions and the standad properties on the widgets. It depends on what you want to customize.
In addition to just searching, The Getting Started Tutorial states
NOTE: the conversion of the URL to title doesn’t always work as expected.
You can also embed the link like Hans-Jörg described. But I’m lazy and just paste in the URL and let the forum handle the rest.
If you post the link by itself on its own line it embeds the first few lines. E.g.
Pages - Item Widgets | openHAB talks a lot about Item metadata. The metadata that I mentioned above in particular is the State Description metadata. Navigate to the Item, click on “Add Metadata” and choose “State Description” from the list. Then populate the “Options” with your value=name pairs. Those pairs will be used as the command/label in the oh-list widget (and others I think).
Take note of the Default X Widget Item metadata. Here is where you would assign one of your custom widgets to be used by default for a given Item.
I don’t have buttons but an example three state expression to choose the color for an icon based on a battery Item’s state:
More examples can be found at Example Custom List Widgets (which is one of the pages you’ll find when clicking on the link in the Getting Started Tutorial). I really did try to give all the resources I could in the tutorial, so much so that the developer for MainUI indicated there was too much.
Widget defines all the channels separately. I would like to change this so I choose only let’s say Thing and widgets would use some hard coded channel names. Any hint?
On mobile phone widget tends to overlaps each other when I put two cells with them side by side. I would like to set minimal width of whole widget.
I’m having difficult to understand channel-link-item relation and the type definition on Item. For example I have two channels in my GREE aircon:
Wind speed (number)
Quiet mode (string)
I messed around when learning at the beginning so I have no clue are those default settings for them. But as You see in widget code first Item Wind speed stores state as number so I have to map numbers to state descriptions for setting text/icon/color properties of component.
On both Items I don’t see any metadata. And in Item channels area somehow I see channels with value definitions which I don’t know how they are already filled automatically.
I’ve missing some implicit conversion that’s going on under the hood. I wonder if I change data type on Item form string to number for example, how openHab manages to send proper command using that Item?
I’m also wondering how options action knows what options to show to user on those two channels/items and where it gets them from?
As always much appreciate any help and answers. Thanks in advance.
Btw. Sorry for any English mistakes, it’s my second language and I’m little rusty in using it.
It is really super important to use the proper terminology in OH. “Thing” has a really specific and technical meaning in openHAB. “Channel”, “Link” and “Item” too have very specific meanings. These terms are not generic nor are they interchangeable. To make the distinction between using the work “thing” generically or when specifically referring to openHAB Things I use the capital T for the latter. I try to avoid the former.
Why this is important is because widgets (and almost everything else in OH like Rules and Persistence) exclusively deal with Items, not Things and not Channels and not Links.
So you can never choose a Thing and the widget can never find the Channel names. Widgets can’t see Things and Channels, only Items.
But you have full control over how your Items are named. If you look at the example Chromecast widget in the Getting started tutorial you will see an “Item Prefix” is one of the Properties that can be set. Then each part of the widget constructs the name of the Item to refer to based on that prefix. For example, the Image Item is item: =props.prefix+"_Image".
When creating that Items using “create equipment from Thing” this sort of naming scheme will happen automatically with the prefix being the name of the Thing and the rest being the name of the Channel.
As discussed above, this is important to understand. The best place to start is https://www.openhab.org/docs/concepts/. The Concepts section of the docs is probably the most important to read and reread until you understand them. Not much will make sense in OH if you don’t understand the concepts.
But as a tl;dr:
Things represent a device. A device typically has one or more actuators or sensors. A special type of Thing represents a bridge to a given technology (e.g. Zwave controller, OpenWeatherMap Account, MQTT Broker etc.).
Each actuator and sensor on a given Thing is represented with a Channel. A Channel will have a type.
Channels can be linked to Items of the same type. So you can link a Switch Channel to a Switch Item but not a DateTime Item. (There is one exception to this that I’ll ignore for now.)
Items are the coin of the realm in OH. Widgets, Rules, Persistence, and everything else almost exclusively works with Items.
When you create Equipment from Thing, OH will choose the correct Item type for you.
Those are the types of Items those Channels can be linked to. Wind speed can be linked to a Number Item, Quiet Mode to a String Item.
Some bindings will apply some metadata to Items as hints for how to display that Channel. But most of the time all Item metadata is something you have to define yourself. Navigate to the Item under Settings and there is an “add metadata” option. The Metadata that handles things like mappings is State Description.
if I may:
