How to add a Zigbee device in a .things file?

Hi all,

I’m using the Zigbee Binding and the CC2531 coordinator and want to define all my things in configuration files.

The documentation describes how to define the coordinator in the .things file, but what I’m missing is how to define a thing which communicates through the coordinator (e.g. zigbee plug or zigbee motion sensor)

From documentation:

Thing zigbee:coordinator_cc2531:stick1 "Zigbee USB Stick" [zigbee_port="/dev/ttyACM0", zigbee_baud=38400]

Please can somebody give an example how to define a zigbee coordinator and things which are using the coordinator.

Additional question:
What exactly are the required steps/sequence to add a zigbee device?
I know after the discovery has been started, the paring needs to happen within one minute. But what exactly needs to happen within one minute? Just step 1 and 2 or also steps 3 (the configuration in the file)

  • Start discovery from inbox and select the zigbee binding
  • Bring the device in pairing mode
    –> device appears in the inbox
  • Add device to config file


1 Like

Most bindings are designed to auto-discover things.
For zwave, for instance, I have no Things file. Just Items, Rules, Sitemaps

I don’t use the zigbee binding, but i guess it’s something like the homematic binding. You need to define the thing-type-id and the thing-id. Both can be read from the discovered thing.

I have an empty jsondb and i’m feeling fine. :wink:

I don’t want to mix things, it means configuring some things in files, other things in the UI/Json DB.
So at all I want to have a “clean” system.
Currently my Json DB is empty, beside the zigbee device I’ve added through the UI.

I think so too, but I’m not 100% sure, thats why I’m asking.

For homematic it looks like this:

Bridge homematic:bridge:ccu [ gatewayAddress="..." ]
  Thing HM-LC-Dim1T-Pl-2    JEQ0999999

For hue it looks like this:

Bridge hue:bridge:1         "Hue Bridge"                    [ ipAddress="" ] {
    0210 bulb1              "Lamp 1"        @ "Kitchen"     [ lightId="1" ]
    0220 bulb2              "Lamp 2"        @ "Kitchen"     [ lightId="2" ]
    0106 light-level-sensor "Light-Sensor"  @ "Entrance"    [ sensorId="3" ]
    0107 motion-sensor      "Motion-Sensor" @ "Entrance"    [ sensorId="4" ]
    0302 temperature-sensor "Temp-Sensor"   @ "Entrance"    [ sensorId="5" ]
    0820 dimmer-switch      "Dimmer-Switch" @ "Entrance"    [ sensorId="6" ]

So it’s not all time the same syntax.
For sure I could trail and error, but I guess somebody in the community had already the same requirement to add a zigbee device within a config file.

Thank you very much for your support,

Can you show a discovered thing in paperui? You can hopefully read the definition from that.

Both definitions are the same, it’s always

Thing thing-type-id thing-id "thing-name" @ "thing-location" [ thing-attribute-list ]

But you may omit everything but thing-type-id and thing-id if these are not needed. (hue needs the lightId to identify the light, the homematic binding uses the thing-id for that.)

Thats a very helpful information. I was not clear on that.

The discovered device looks like this in the PaperUI:

Thing zigbee:coordinator_cc2531:stick1 “Zigbee USB Stick” [zigbee_port="/dev/ttyACM0", zigbee_baud=38400, zigbee_panid=1111, zigbee_extendedpanid=“1111”, zigbee_networkkey=“1111”]{
device 00158d00041105f6 “Aqara Motion Sensor 2”

In the log I got the following error:

2019-12-16 18:43:30.098 [WARN ] [core.thing.internal.ThingManagerImpl] - Disposing handler for thing ‘zigbee:coordinator_cc2531:stick1’ takes more than 5000ms.
2019-12-16 18:43:38.302 [WARN ] [el.core.internal.ModelRepositoryImpl] - Configuration model ‘zigbee.things’ has errors, therefore ignoring it: [2,2]: missing ‘}’ at ‘device’
[3,1]: extraneous input ‘}’ expecting EOF

And yet we spend tons and tons of time here on this forum helping people who have nothing in their JSONDB and don’t feel just fine. When you use auto discovery:

  • you don’t need to know the syntax
  • you can never make a syntax mistake
  • in cases like MQTT where you have to manually configure a Thing because auto discovery is not possible, it is obvious and documented right there in front of you what the options are and what they do.

Frankly, the reason why you see and keep seeing all the “why not use auto discovery” from so many people who spend a lot of time on this forum is because it wastes a ton of our time. And frankly, it wastes a ton of your time too.

1 Like

I thought it was because it goes against the way developers are developing the bindings to make it simpler for the user. :wink:

I have some sympathy. Both PaperUI and xxx.things files are currently supportable by bindings. So far as I can tell, Zigbee binding does support text configuration files. All the poster wants to know is the format for xxx.things file for this binding. Very often that is the readme for a binding

PaperUI is not especially helpful for this - while it suggests the kind of parameters expected, you may not see the actual keywords needed in a text file.

That’s because the coordinator is not a bridge but a thing. I guess, you need to define the devices alongside the coordinator something like the following:

Thing zigbee:coordinator_cc2531:stick1 “Zigbee USB Stick” [zigbee_port="/dev/ttyACM0", zigbee_baud=38400, zigbee_panid=1111, zigbee_extendedpanid=“1111”, zigbee_networkkey=“1111”]
Thing zigbee:device:stick1:00158d00041105f6 "Any Name" @ "Any location"

All devices are of type zigbee_device. I’m not sure about the attributes.

I have used the HABmin UI to define a coordinator though

1 Like

@rlkoshak Does that mean you would use the UI/Json DB whenever its possible and use the config files just when it’s necessary?

Here just the coordinator itself is described.

@job makes sense. I will check that and let you know.

My recommendation is the same as the recommendations in the docs. All Things are auto discovered, where available, and created through the REST API where not (note I did not say PaperUI).

Everything else is managed through text configs for now. Though I suspect when OH 3 comes out I will change my recommendation to moving at least Items and Rules to the UI, potentially everything. It depends on how the UIs mature. It’s faster and there are fewer startup problems with JSONDB defined stuff than text configs.

I’m not against consistency, but Things and Items and Rules are all different things with different syntax. Forcing yourself to struggle through manually writing .things files just because you have your Items in .items files is, IMHO, a poor use of your time. Especially when for the vast majority of add-ons, the Things are just automatically created for you. When when that happens, it is done right every time.


I tried different configurations in the .things file, but I was not able to make it work.
Regardless, it’s not an issue for me as it works in the Paper UI as expected.

In general I will try to use the Paper UI more often if there is no .things file required by the binding.

Thanks to everyone and best regards,

In search of another problem I read this thread and the millionth discussion, PaperUI or text files.

Let me ask a question.

My production system, a RasPi with Openhab 2.4, MQTT, ccxxx dongle and textfiles is running 90% stable for almost a year. Xiaomis, HUEs, IKEAs, Osrams, Shellys, etc. all work fine. I have automated many processes with rules.

On my test system, a RasPi, Openhab 2.5, ZigBee Binding, BitronVideo USB Dongle and PaperUI I can’t even come close to what I have on the PROD system.

So how do people keep recommending using PaperUI?
I can not understand this. When I use the PaperUI everything is in JSONDB and I can’t access it from textfiles. So how should I implement a nested rule with PaperUI? Or have I missed something?

I am also looking for ways to use the zigbee binding with .things, .items and .rules. The documentation is good, but not sufficient.

In what ways?

Because it saves their time and it saves our time here on the forum supporting people trying and failing to figure out the proper syntax for .things files. And there are some things you simply cannot do when you have .things files like setting parameters on Zwave devices.

sudo nano /var/lib/openhab2/jsondb/org.eclipse.smarthome.core.thing.Things.json

It’s just a text file using JSON to structure the data.

What do you mean by a “nested rule”?

Also, keep in mind, the recommendation is to use JSONDB (I’ll not say PaperUI because that isn’t the only way to manage Things) only for Things. For everything else: Items, Persistence, Rules, Sitemaps, etc, text configs are the only option or text files are the best options.

No one is recommending using PaperUI to create Rules. It’s still labeled “Experimental” for a reason.

1 Like

Trying out the proper syntax is a failure to define clear rules and standards. Why are there not rules that everyone should follow? One of many problems why such projects have little success on the market. Sorry :frowning:



if (xcddd)


if (fkfkf)



Ok. If i configure a thing in PaperUI, have an item for it, can i now build a rule in .rules to use the things?


Please don’t misunderstand me. I enjoy working with OpenHab very much. Everything is based on text files that I can customize quickly and easily. They are also easy to backup.

PaperUI is too cumbersome and slow for large environments. Far away from an easy to use user interface.

A few days ago I installed my test system to test the new OpenHab 2.5. At the same time I started a second attempt to do everything with PaperUI. I started with the Zigbee binding. Here I see the first problems coming up. I have things but no items, etc…

But I like to be taught a better one and I also like to learn more. My goal is to use OpenhHab as an umbrella to control the different systems like HUE, Ikea, Shelly, etc. The potential is there, the way to the goal difficult :wink:

Because .things files were always and ever only a stop gap. It was never intended to be the way.

That’s just a rule with an if statement. Pretty straight forward. There are literally thousands of examples in the forum.

The over all structure of a time is documented in and that page has links to documentation for the programming syntax.

rule "Test Rule"

Or using Scripted Automation an Python (Rules DSL will be deprecated on OH 3)

from core.rules import rule
from core.triggers import when

def test(event):
    if xcddd:

Or, if you do want to use PaperUI to define Rules, you define the trigger in the “When…” section, then add a “Script Action” then the “then…” section where you put in

    if xcddd:

if using Python or

    else {

Use the Items, yes. There are only limited use for Things in Rules.

None if this had changed fundamentally since OH 1.6. How ever you are doing roles in OH 2.4 is exactly the same as well work in 2.5 as worked in 2.0. small details have changed but nothing at the Hever you are talking at.

You don’t have to use PaperUI to create and manage Things in JSONDB.

You’ve been using OH for awhile but your comments indicate you don’t really know how OH works. If you really want Items aromatically created you can turn on simple mode. I don’t recommend that though. You should create the Items. Items if where you give the devices meaning and context in your home Automation system. And items is what everything in OH operates on.

Perhaps a refresh if the docs or reviewing some of the resources in How to get started (there is no step-by-step tutorial) would do you good.