Trying to understand Thing Channel definitions and use

Setup, Configuration and Use Beginners
, ,
1

I am trying to understand how best to define and use Things and their Channels. As an example:

Thing zwave:device:controller:node12:tDenMotionSensor
    "Den Motion Sensor" (
        zwave:serial_zstick:controller
    ) @ "Den" [
        node_id=12,
		category="Sensor"
    ] {  Channels:
            State Number : cBattery "Motion detector battery level"
		"zwave:device:controller:node12:battery-level"	
		[category="BatteryLevel"]				
            Number : cTemperature "Motion sensor Temperature"
		"zwave:device:controller:node12:sensor_temperature"
		[category="Temperature"]
    }

What is the purpose of the thing name, tDenMotionSensor, with the Z-Wave binding? It is not used to define related items. I understand that a name is needed with some other bindings as the way to identify a specific device.
What is the purpose of the channel name, e.g., cBattery or cTemperature and where is it used? When I create an item and its channel, I must define it as, for example, "zwave:device:controller:node12:battery-level".
Neither "zwave:device:controller:node12:cBattery" nor "tDenMotionSensor:cBattery" will work.
What is the difference between, for example, State Number and Number?

2

For Z-Wave is it best to define the Controller Thing through the UI and then let the binding automatically discover all the other device Things.

Manually configuring Thig files for Z-Wave is too trouble prone and not recommended.

2 Likes
3

Did you start with the documentation? Your questions let me assume you might not have read the concepts part yet. Your questions might be answered there.

Also, I strongly suggest to follow Bruces advise to define Z-Wave Things using the GUI instead of manually via a file. It is much smoother to do and you will have easier success.

1 Like
4

I will clarify that I currently define all my items and rules by text files. That was my choice as a systems administrator. Things can be too error prone to define in text files unless the binding requires it.

5

Thanks for your help. I am reconciled to using the UI for Z-Wave things. I’ve read the documentation and community posts multiple times but have been either unable to find answers to my questions or unable to understand the documentation. Again, I do not understand the purpose of non-Z-Wave binding thing and channel labels or descriptions and where to use them.
On a separate issue, I have a Z-Wave device that is discovered but does not associate with the proper device type, which exists in the database. I have excluded it multiple times, but it always get re-discovered as an unknown device. It also keeps be assigned the same node id , which makes me think that is is not actually being excluded. Is there a method for forcing the exclusion (Rust API?) or for forcing the proper device association?
Thanks again for your help.

6

I found another thread a month old where you asked similar questions. But I found no information about your level of knowledge or background with technical things, so it is a bit difficult for me to describe it properly for you. I’ll try anyway:

The “things” are the physical devices that contain at least one sensor or actor, most times there are several of them inside a device.
You already saw that it is difficult to write a things file (at least for Z-Wave devices), I discover the things via PaperUI. That way, a (Z-Wave) thing is discovered, and as long as there is an approriate entry in the database, it will be recognised and all the available sensors and/or actors are pre-defined as channels. A channel is the way of communication between the physical sensor/actor and the binding that OH uses to communicate with the thing or more accurate with the “endpoints” within the thing, each endpoint is one sensor or one actor.
When you click on a thing in PaperUI you will see the channels with some information about each channel:

  • a description (e.g. sensor luminance)
  • the channel definition (which can be copied to the clipboard and as it is a long string I recommand to use that feature)
  • the type of item you will need to link the channel to (Switch, Number, Contact etc.)
    As long as no item is linked to the channel, you will see a white circle in the blue circle. That means “no item linked”.
    I define my items in text files. Without an item (which is on the software level to be used within OH) linked to the channel (and thus a sensor or actor on the physical level) you can’t make use of the thing (or its components).
    So take the information from the GUI, create a file with file extension “.items” inside the “items” folder of the OH configuration and define an item for a channel.
    As an example I have a door/window sensor with a channel of type “Contact” that is described in a file “bad.items”:

Contact Bad_Fenster_Kontakt “Bad Fenster” (gBad,gFT) { channel=“zwave:device:abcdefgh:node50:sensor_door” }

PaperUI told me, the channel is of type “Contact”. Hence I define an item of type “Contact” (the first word in the item definition).
The next part is the item name (in this case "Bad_Fenster_Kontakt "). The item is referenced by this “technical” name throughout OH, e.g. in rules. Basically this is the name on OH level for the sensor/actor that YOU define. Think about a naming convention, you will find suggestions for that in various posts.
The next part is a label that you give the item, which will appear in a GUI.
An icon name and group assignements are optional.
The last entry is important as it links your item to the channel. It is the string you can copy from PaperUI using the small clipboard sign besides the zwave-channel information.
If everything went right and you save the file wath PaperUI (you still have the thing definition open?). After a few moments you will see a change in the blue circle: An additional white dot appears inside the white circle. This means an item is linked to the channel. Click on the double arrows to the right of the channel description. Additional information will be shown: You see the linked item now. The label and the technical name of the item are displayed.

Now you have everything ready:

  • a thing with various sensors/actors inside is defined in OH
  • the appropriate channel definitions are available (coming from the Z-Wave database)
  • an item with a technical name and a label visible in a GUI (sitemap) representing one of the sensors/actors linked via the according channel to the real world outside OH

Hints:
When you click on the pencil symbol (white pencil on blue circle) above the thing definition, you can amend the thing name (which just helps you to know what it is with no further consequences) and you can define a location for it. That further helps in knowing later on what you are dealing with, in case your naming scheme is not covering that good enough. When you have defined a location and saved the change, click in PaperUI on “Control” in the upper left corner. You will see the things now grouped according to the locations you defined for your things.

Addendum:
If you have choosen “simple mode” in “Configuration” and then “System”, items will be prefined for you. I did never use this facility and can’t really help with that.

7

As for your seperate issue: I suggest to install HABmin to explore this thing a bit more. It gives a better “grip” on Z-Wave things than PaperUI.
Click in the HABmin GUI on the thing you want to examine and look for the data at the bottom of the things page. You see data about the vendor, the IDs and firmware version. You can cross-check this information against the Z-Wave database to see whether there is a suitable entry for your thing. If not, it needs to be created, otherwise the thing will not be fully recognised by OH and thus not useable.

8

Thanks you Stefan for the detailed explanation and guidance. It is not only helpful for me, but should be valuable to others too. Thinking about what I have tried and what you have written, I have come to a couple of conclusions. First is that I read too much into the documentation and make false assumptions of how the system operates. When I try something based on these assumptions and it does not work, I am assuming that I made an error rather than misinterpreting the documentation. I will be more careful in the future. Second, I keep assuming that the Z-Wave binding operates similar to how other bindings operate notwithstanding the documentation making clear otherwise.
I have used HABmin and the REST API to look at the details of my Z-Wave devices. They both show the device about which I am concerned as being undefined even though the database has the correct device definition. Additionally, when I try to exclude the device, the system reports that it has been excluded, but when trying to re-include it, it has the same node ID as before exclusion and is still listed as an unknown device.
One last question, does the Z-Wave database affect the operational system, or is it only used to define the properties of devices when they are first included after which all operational information is in the things registry?
Once again, thanks for your help and response.

9

The binding uses its included copy of the database to properly configure the device settings when it is first dully discovered. Battery operated devices usually need to be woken up many times until this process is complete.

What particular devices and what version of openHAB?

10

There may be a time gap: The database is not used “online” during the runtime of the system. It is incorporated in the Z-Wave binding itself. Your device definition might be rather new (I did NOT check that) and you see it in the database, but it might not be in the binding yet that you have on your system. Hence your system does not recognize the thing correctly.
When you exclude a device and include it again, it will have a new ID. If it is shown with the same ID the exclusion did not work correctly, as far as I understood the conecpt.

11

I running 2.5.9 and the problem device is a Leviton DZ15W switch.
Thanks

12

I do not see that device listed in the community maintained database. That just means nobody has tried one previously.

If the device has been discovered there should be an xml file in the zwave directory of userdata that contains information from the device. That information along with a pdf of the user manual can be used to create a database entry. If you post the xml file here I can try to do that for you.

13

I’m sorry, I made a type and the model is a DZ15S, which is listed under Z-Wave bindings as zwave:DZ15S_00_000.
Sorry for the typo and confusion.

1 Like
14

HABmin shows undefined for many manufacturers since Habmin has not been updated for many years.

15

Although HABmin has not been updated for years, it still shows recent manufacturer data. E.g. my Fibaro FGRGBW-442 is shown although it is a relatively “new” device, being on the market for a year or so.
As far as I know, HABmin uses the data from the Z-Wave binding, the same as PaperUI. Everything else would mean double effort for the maintainer and does not make sense.

16

As your device already has a thing ID I suspect there is a XML file in the zwave folder as Bruce indicated. Could you post that, please?

1 Like
17

Not for the Manufacturer names. The device just gives the binding the manufacturer ID. The conversion to name is internal to HABnmin and is just a cosmetic issue.

1 Like