The developer sidebar is one of the most powerful features of MainUI that people seem not to use.
So what is it? The developer sidebar is a swiss army knife of tools available on wider screens (sorry, no phones) that help with the development of your openHAB config.
How to access
There are two ways to access the developer sidebar.
- In MainUI navigate to Developer Tools → toggle on Developer Sidebar.
- There is a special key combo to show or hide the developer sidebar:
alt-shift-d.
Once enabled it will take up roughly ten percent of the right hand side of MainUI. You can resize it by dragging the border line as you would expect.
There are several tabs and subtabs. I’ll start with the “HELP”.
HELP
The HELP tab has four subsections: Page Help, Add-on Docs, FAQ, and Quick Start.
Page Help
This tab shows context sensitive documentation for the page that’s currently open. For example, here’s the contents when I have Settings → Things opened.
There is a high level description of what you are looking at, links to relevant docs, and step-by-step descriptions for how to do common things you might do from this page.
Especially if you are just learning of forgot how to do something this should be the first place to look for help.
Add-on Docs
This tab is not context-sensitive. It shows the same content no matter what page you have opened.
This tab has a link to the documentation for all your installed add-ons. You don’t need to open another page and search Add-ons | openHAB, or from MainUI navigate to Add-on Store → Add-on → Docs.
I find this particularly useful when I’m working on a rule that needs to call a Thing Action but I forgot all the arguments. I can quickly jump to the add-on’s docs with a couple clicks or I can’t remember how to do something in JS Scripting.
FAQ
This tab also is not context-sensitive.
This tab has a series of high level common activities one might need to do in OH like creating a configuration, configuring remote access through the cloud connector, etc. There is a brief answer inline with links to more detailed docs.
Quick Start
This tab presents a step-by-step tutorial for moving from installing an add-on → adding Things → creating Items → showing the Items.
TOOLS
Under TOOLS there are four tabs with tools to help with developing and debugging OH configs: Pinned Objects, Event Monitor, Code Tools, and Create Shortcuts.
Pinned Objects
This is the one tool I find the most useful and it’s even more useful in 5.1. On this tab you can search the ID, label, or through the contents of just about any entity in OH including:
- items
- things
- rules (rules, scripts, and scenes)
- widgets
- pages
- transformations
- persistence configs
So, for example, you can use this to find everywhere a given Item is used by name anywhere in OH.
For example, here I’m searching for anything that deals with “temperature”.
You’ll see three icons to the right of each entry. The first will copy the UUID of the entity. This is a great way look up and copy the UID for a Thing or a Rule that you need to interact with from another rule or a widget, for example.
The second icon will take you to that entity’s main page where it can be reviewed and edited. Note that doing so does not close the developer sidebar.
The last icon will “pin” the entity. Once pinned you can clear the search (little x to the right in the search box) and those pinned entities will remain, revealing even more you can do with them,
For example, if I were working on the config for my family room humidifier I might pin the following entities:
Once I searched and pinned everything (you can do this in multiple steps, previously pinned entities will remain pinned) the first thing I do is to save it. At the top of the tab you’ll see a “Saved Pins”. There you can name the current collection. This saves all the pinned entities locally to the browser’s cache. As long as the local cache remains, and you open MainUI in the same browser, you can recover your set of pinned entities. This can be really useful when you have more than one project going on at the same time or you have a project that will take longer than a single sitting to complete. It’s also helpful for when MainUI hickups and you need to reload the page (prior to OH 5.1. reloading reset the developer sidebar, losing all your pinned entities).
Now you will see that each pinned entity has some more information shown and some new icons in addition to the copy and edit icons. Clicking on the pin icon will unpin that entity.
The Items show their current state. Clicking on the Item will show that Item’s default card widget so you can interact with it.
Things have an enable/disable button and shows the current status fo the Thing.
Rules, scenes, and scripts have an enable/disable button and a play button to cause the rule to run manually. It also shows the current status of the Rule.
Pages have a “view” button (same as the rule’s play button) which will bring up the live view of that page.
With all the Things, Rules, Items and Widgets pinned like this, you can jump around between them, command them, copy their UIDs, enable/disable/trigger as needed all without leaving the developer sidebar or leaving the tab.
If you are used to an IDE or a text editor, this is like having all the files you are working on open and switching between the tabs, only you can do more than just edit, you can command Items, run rules, etc. too.
Event Monitor
This tool will show a live stream of all the events occurring in openHAB and sent to MainUI. Note that many of these events are suppressed in events.log. You’ll see a lot more here than you may be used to.
Events are listed from newest to oldest.
You can see the raw JSON for each event under the bolded text which has a little more information. This is the information MainUI uses to get live updates on what’s happening on the server (e.g. Item updates).
But there are so many events you will almost always want to filter them. Clicking on the little cog in the upper right will open the filter dialog where you can list one or more filters. The filters operate on “topics”. The text in bold is the topic.
A topic for an Item usually looks like: openhab/items/<name of item>/<event type>. So if you want all state updatessent to Item Foo your filter list would be
openhab/items/Foo/stateupdate
If you want the updates for all your Items you can use a wild card:
openhab/items/*/stateupdate
If you want all Item events for all Items use
openhab/items/*/*
I find it easiest to let the stream run a bit to find the types for the events I care about. I don’t know of a list anywhere for all the topics, but suspect it’s there somewhere in the developer docs. If you know about it ror find it, post it in a reply.
The event stream is a way to see what’s going on, or at least what’s going on that is reported to MainUI. This can be useful to correlate, for example, an Item update to a rule running when one is debugging something that might involve the event stream.
Code Tools
This tab has two tools, an expression tester and a link to -Scratchpad-.
Expression Tester
This is a tool one can use to test out a Widget expression. Especially for complicated expressions it can be useful to gradually build up the expression step-by-step, starting simple and adding to it.
Unfortunately it does have some limitations. There is no widget, so there’s no context or variables or other cool features like that which make writing expressions more modular and easier. But you can still hard code stuff while testing to see how the expression performs in that case.
You do have access to items in the expression builder. The following is an example about how one might gradually build up an expression, testing it step-by-step.
Scripting Scratchpad
This is a special Script that will be created if it doesn’t already. You can find it under Settings → Scripts → -Scratchpad- once it’s created. You will be given the opportunity to choose the programming language to use.
Once created this becomes a quick link to a Script whose sole purpose is to just try stuff out or write some rules code to test things. You will edit the code, save, and then run it and watch the logs or what ever to see what happens.
Here is the contents of my current -Scratchpad-
var {helpers, TimerMgr} = require('openhab_rules_tools');
//console.loggerName = 'org.openhab.automation.Scratchpad';
console.info('Running scratchpad.');
console.info('openhab-js version: ' + utils.OPENHAB_JS_VERSION);
console.info('OHRT version: ' + helpers.OHRT_VERSION);
//console.info(ruleUID);
//var itemChannelLinkRegistry = require('@runtime/provider').itemChannelLinkRegistry;
//var allLinks = utils.javaSetToJsArray(itemChannelLinkRegistry.getAll());
//allLinks.map(l => l.toString()).filter(l => l.startsWith('AdGuard_Protection')).map(l => l.split(' -> ')[1]).forEach(l => console.info(l.substring(0, l.lastIndexOf(':'))));
// http://10.10.1.112:8080/ipcamera/garage_camera/ipcamera.jpg
var logger = log('Test');
logger.info('Test log');
let events = actions.Exec.executeCommandLine(time.Duration.ofSeconds(1), 'cat', '/openhab/userdata/logs/events.log');
//items.OpenAI.sendCommand('Review this openHAB event log and summarize, in plain English and three sentences, what operational activity occurred around failures, automations, or user actions, excluding raw status noise. \n' + events);
console.info(Quantity('20 Wh').divide('1 m²'));
As you can see, it’s a random jumble of log statements and commands to figure something out or experiment with something. Usually I delete most of the stuff after I’m done, sometimes I just comment things out until I move the code somewhere else (I tend to save code snippets that took some time to figure out to a separate Script for later reference). But the main point is this Script is a playground. It’s not intended to be permanent nor functional. It’s a place to test and experiment.
Blockly is supported.
Create Shortcuts
These are quicklinks which will take you straight to the new entity page for what ever you want to create. You don’t need to, for example, navigate to Settings → Things → Inbox to accept a Thing from the inbox. You can click “Inbox” under Things to jump straight there. You don’t need to navigate to Settings → Things → + → MQTT → Generic MQTT Thing to create a new Thing. You can just click "Add Thing (quick) and select “Generic MQTT Thing” from the list.
As you can see there are links for Items, rules of all types, and pages of all types. You can even jump to create a custom widget or block library.
Conclusion
So much of the time people complain that they don’t want to use the UI to configure things because of all the excessive repetitive clicking. However, the developer sidebar is there to greatly reduce that problem. You are doing yourself a disservice if you are not using the developer sidebar.
Hopefully the above shows the power of the sidebar and convinces you to give it a shot.