dzVents definition incorrect: ID should be idx

[mjdb]

The dzVents Wiki says:

Device attributes and methods for all devices
- id: Number. Id of the device

This is incorrect. It does not return the ID, but the index (idx) of the device.

The device ID is a long number that can be represented by 7 hexadecimal characters.
The device also has a unit number that together identify a device uniquely.

The index is local to the Domoticz installation and will be different on different instances.

I suggest to rectify this in the documentation (and the program) and also to add the real ID and Unit to the device attribute list.

[dannybloe]

You are correct. It is indeed the index. However, for most people this also works as a kind of id as the number is always increased and never reused.

The problem is that I cannot change this without breaking many people's scripts. What I can do is add the idx attribute (which will have the same value) and add deviceId. I will also add the possibility to get a device by either id(x) or deviceId. You can even use deviceId as the on-trigger.

So, what is Unit exactly?

[dannybloe]

Ehm.. I'm looking at my own system and seems to be that you are not correct. deviceId + Unit is not unique. I have several devices that have the same deviceID + Unit. In fact, the idx is more unique than this combination.

So for now I just add the deviceId and unit attributes to all devices and you can use the collection iterators to filter/search for devices with that deviceId/unit if they turn out to be unique for you.

Besides, the domoticz api also needs device idx instead of deviceId.

[mjdb]

My point is about naming convention. In Domoticz the (device) ID has a specific meaning. The idx has another meaning.
I think it is good practice to have just one name for one attribute, and not one name (ID) that can mean two different things (device-ID OR device-idx).

At least you should update your documentation. Now you use terms like 'device.id' or 'mydevice.id' where you mean idx.

The problem is that I cannot change this without breaking many people's scripts.

I don't think so, it won't be a problem. First of all, dzVents has just recently been added to Domoticz, so it is better to correct it now than wait longer. But, more important, changing the attribute-name from 'ID' to 'idx' does not influence 99% of the scripts. In the trigger, the key-word 'ID' or 'idx' are not used, just the number.

Ofcourse it is not my business. Perhaps the Domoticz developers should look at this and give their opinion about one name for two different things in their program.

Don't be afraid to take the right decision

- - - -

So, what is Unit exactly?

Some devices can switch two or more receivers. The unit-number is a kind of sub-number for the device.
A wall switch with two buttons has one ID and two unit-numbers.
A remote can switch three or even 16 devices. So, there are three or 16 unit-numbers.
For GPIO-switches, the unit-number identifies the gpio-pin.
Etc.

- - - -

What I can do is add the idx attribute (which will have the same value) and add deviceId. I will also add the possibility to get a device by either id(x) or deviceId.

That could be the second-best option.

deviceId + Unit is not unique. I have several devices that have the same deviceID + Unit. In fact, the idx is more unique than this combination.

For a switch (or transmitter) the (device)ID and Unit are the unique Identifier. That is independent of your Domoticz instance. In Domoticz, the idx is the Unique Identifier. If you delete and re-add a device, the ID and Unit will be the same, but the idx will change.
If you use a master-slave Domoticz, you will indeed see some ID's and Units twice (or more). The 'hardware' column indicates where the device comes from. Practically, the three columns 'hardware', 'ID' and 'Unit' together make the Unique Identifier of each device. But I don't think Domoticz has a check on this.

You can even use deviceId as the on-trigger.

I suppose not. You would also need the Unit and even the hardware-name.

- - - -

So for now I just add the deviceId and unit attributes to all devices and you can use the collection iterators to filter/search for devices with that deviceId/unit if they turn out to be unique for you.

I am happy with that. Thank you.

But... don't forget to update the documentation and write idx where you mean idx.

[dannybloe]

I don't have a master-slave setup and still see many doubles (deviceid+unit) in my list.
I updated the documentation to indicate that id is actually the index as shown in the device list. And as I said before, the api for sending commands from event scripts to domoticz is all based on the idx and not this hwid+dvid+unit combo. So I think that for most users the idx serves as an id so I will not change that. Especially since there is hardly any documentation about how to interpret this combo and what it all means. I don't want to complicate things too much (and after 1.5 years of dzVents using the idx as id you are the first to actually mention this).

[mjdb]

I updated the documentation to indicate that id is actually the index as shown in the device list

In the wiki:
https://www.domoticz.com/wiki/%27dzVent ... _scripting

In section "on = { ... }"
change "The name/id of your device ..." to "The name/idx of your device ..."

In section "Domoticz object API:"
3 x change "A function returning the device by id (or name)." to "A function returning the device by idx (or name)."

In section "Device attributes and methods for all devices"
change "id: Number. Id of the device" to "id: Number. Idx of the device"

[dannybloe]

Thanks. I already made the changes in the sources (documentation is versioned in git as well).