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

Tags: #<Tag:0x00007faf7ee20600> #<Tag:0x00007faf7ee20498> #<Tag:0x00007faf7ee203d0>

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!


  • A basic understanding of how MQTT works (HiveMQ provides a good tutorial
  • An installed and configured MQTT Broker (e.g. Mosquitto)
  • 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

Scenario: 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 this 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.

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.

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.

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.

1 Like

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.

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: