Getting Started with OH3: rewriting the tutorial - 5. Adding a Thing (advanced)

This Wiki topic’s goal is to serve as a working document, in order to provide an up-to-date tutorial for OH3 aimed at new users and novices. Everyone is welcome and encouraged to edit it, when we’re satisfied it will make its way to the official docs. You may reply for the specific purpose of improving the article are allowed, but please, this is NOT a support thread: if you’re stuck while reading this and are simply seeking support please open another thread. Thanks!
This tutorial has transitioned to the official docs. Please see Adding Things - Advanced | openHAB.

Some bindings and technologies simply do not support automatic discovery. These technologies tend to be the most complicated to understand, configure, and use. You the user will need to have at least a working understanding of the underlying technology to be successful. For example, if you will use the Exec binding with openHAB running on Linux, you will need a working understanding of how to run commands on the terminal, file permissions, users, etc.

This tutorial will use the MQTT binding as an example. Important note, the MQTT Binding also supports automatic discovery of Things for devices that use the Homie or Home Assistant standards in their topic structure and messaging. In those cases, the MQTT binding works more like the Intermediate Thing example.


  • A basic understanding of how MQTT works (HiveMQ provides a good tutorial
  • An installed and configured MQTT Broker (e.g. Mosquitto which can be installed through openHABian if that is how you installed openHAB)
  • A MiFlora device configured to connect to the MQTT Broker, or an MQTT client application (e.g. MQTT Explorer, MQTT.fx that allows one to publish and subscribe to MQTT topics


You have a MQTT-enabled plant sensor, and for the purpose of this tutorial let’s assume it doesn’t respect the Homie or Home Assistant convention, so it cannot be detected and configured automatically by the MQTT binding. Instead, it’s publishing metrics regularly in a simple JSON structure like the following on a preconfigured MQTT topic:

{"light": 5424, "moisture": 30, "temperature": 21.4, "conductivity": 1020, "battery": 100}

We need to manually create a generic MQTT Thing for this device.

Since we have to extract the values from the JSON object, we also need a transformation add-on to add this functionality to openHAB, specifically the JSONPath transformation add-on.

Install the Binding and Transformation

From Settings, click on Transformations under Add-ons.

Click on the blue “+” button, and find JSONPath Transformation. Click on it, then Install.

Wait for it to disappear from the list, then click back twice to go back to Settings.

Next, install the MQTT binding: click on Bindings, then the “+” button, find the MQTT Binding, click on it than Install. Wait for it to disappear from the list, then go back twice to return to the main Settings screen.

Create the Bridge Thing

First, we need to add the broker, which is a Bridge. Click on Things.

Click on the blue “+” button.

Choose “MQTT Binding”, then choose “MQTT Broker”.

Fill in the details to connect to the broker, you may also alter its ID and name. If you need credentials to connect to the broker, click on “Show advanced” to reveal additional options, including Username and Password.

Create the Generic MQTT Thing

Now we have to add the plant sensor itself as a generic Thing.

On the Things page, first verify that the broker is indeed present and online; if so, click on the blue “+” button then MQTT Binding.

Note that you might have results under “Discovered things” already appearing if you happen to have auto-discoverable devices publishing messages to the broker.

In our case, click on Generic MQTT Thing under “Add manually”.

Change the ID and label if you wish.

The important setting is to choose the Bridge that the new Thing will work with.
Click on Bridge and choose the broker that you configured above in the list. Then click “Add” in the top-right corner.

Back on the Things page, choose the Thing you created. It should be marked online, but it will not have any Channels on the Channel tab - you have to configure them yourself.

Click on Add Channel.

Let’s add the temperature first. Fill in the “channel identifier” and “Label” fields accordingly: for instance, temperature as the identifier and Air Temperature as the label.

This channel will provide numbers, therefore choose the Number value channel type for the new channel. Scroll down and enter the MQTT topic receiving the JSON message in the MQTT State Topic field. However, we don’t want this channel to provide the whole message, only the temperature part.

Click on “Show advanced” above MQTT State Topic to reveal more settings.

Scroll down, find the “Incoming Value Transformations” setting, and specify the transformation to apply there:


Click Done in the title bar to add the channel, it should now be added to the Channels tab.

Repeat the procedure for the other channels:

  • light (label: Light Intensity)
    Number value channel type
    Incoming value transformation: JSONPATH:$.light
  • moisture (label: Soil Moisture)
    Number value channel type
    Incoming value transformation: JSONPATH:$.moisture
  • conductivity (label: Soil Conductivity)
    Number value channel type
    Incoming value transformation: JSONPATH:$.conductivity
  • battery (label: Battery Level)
    Number value channel type
    Incoming value transformation: JSONPATH:$.battery

All channels should specify the MQTT topic where the JSON message is published.

If you want to check the configuration for a channel, or made a mistake while adding it, open the channel details by clicking on it, and choose Configure Channel.

Note that you cannot change the channel type if you picked the wrong one, in that case, remove the channel by clicking on Remove Channel and add it again.

This concludes the Thing discovery and creation examples. Next Items and the model.

Next -> The Semantic Model
Previous -> Intermediate Thing Creation

Next -> Semantic Model
Previous <- Adding Things - Intermediate


As this is ‘advanced’, what do you think to adding a nested level into the JSON output? This way the reader will also have a little experience walking the JSON tree to get the values they want.

1 Like

Personally I’d rather see that added to the documentation for the JSONPATH transform rather than in the Getting Started tutorial. That’s really a detail about using that specific transformation whereas this particular tutorial’s main focus is to demonstrate advanced Thing configuration, i.e. Things that require one to manually create Channels.

1 Like

Yeah, I can see that in general. There’s a balance to be made - not have to jump around between a bunch of pages, but not make one long page.

Specifically nested JSON, though, I think is so common for MQTT, and this topic is ‘advanced’, that personally I think it fits.

I’ll be happy either way though - all this effort can only improve things!

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.

Link to next article:

EDIT: Added some intro text and broke it up into sections. Added links to MQTTExplorer and MQTT.fx.

I really love this page. :smiling_face_with_three_hearts: really do. Some real juice there.
Sorry if I break into this.

My twoppence: I would have really liked to have, say, simply the term JSONPATH turned to a link to the JSONPATH documentation. That would be the best of the world: you first read the whole page, understand the basics, then go back and use the link for some drilldowns.
Now, I imagine the balloon popping up on your side: nice to have, but it’s a real pain have to turn words in hyperlinks. Aye.
BUT usually in documentation you have the chance of adding some markup to the text you can easily apply and then a bot processes the markup in overnight batches to format the term nicely and hyperlink the page automatically and the like. Since you are on the front line of doc, that’s a core perk you should enjoy and if not, well, ask Santa quickly :wink:

I’m not sure how rest that would be to add to the build but maybe when this calm down we can look into something like that. I think I may have added a link the first time it appears in the version I moved over to GitHub. If not I meant to.

Awesome - that was what I needed to make miFlora (finally) work!
Thanks a lot - much appreciated.