[documentation] clarification of representation property

[andrewfg]

https://community.openhab.org/t/representation-property-and-configuration-parameters/101698

Signed-off-by: Andrew Fiddian-Green software@whitebear.ch

[netlify]

Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).

Built with commit e458500

https://deploy-preview-1248--openhab-docs-preview.netlify.app

[Confectrician]

Hi and thanks for your contribution.

I have left two small comments.
One needs to be discussed and clarified in my opinion.

[bobadair]

I think this doc update is great, because this is a topic that seems to be misunderstood by a lot of binding developers.
My unsolicited 2 cents is that I would also add the following two points in the developer docs.

First, if your binding makes use of a bridge, the representation property does not need to be globally unique, but only unique within the context of the bridge, as long as in your discovery service you call DiscoveryResultBuilder.withBridge(bridgeUID) when building your DiscoveryResult. So if bridge A has child things with their representation properties set to 1, 2, and 3, and bridge B also has child things with their representation properties set to 1, 2, and 3, they will not conflict.

Second, if your thing has two configuration parameters (e.g. channel and address) where each individually is not unique, but the combination of the two is unique, you can do the following to make auto-ignore work properly in all cases:

Make up a new property (“id” in the examples below) and define that as the representation property in the child’s thing xml file.

Example:

<representation-property>id</representation-property>

In your discovery service, combine the two parameters into the new property and add it to the DiscoveryResult using DiscoveryResultBuilder. withProperties().

Example:

        Map<String, Object> properties = new HashMap<>();
        properties.put(PROPERTY_ADDRESS, address);
        properties.put(PROPERTY_CHANNEL, channel);
        properties.put(PROPERTY_ID, String.format("%d-%d", address, channel));
        DiscoveryResult result = DiscoveryResultBuilder.create(uid).withBridge(bridgeUID).withProperties(properties)
                .withRepresentationProperty(PROPERTY_ID).build();

In the child thing handler’s initialize() routine, again combine the two parameters into the same property in the same way, and call updateProperty() with it.

Example:

        String id = String.format("%d-%d", address, channel);
        updateProperty(PROPERTY_ID, id); // set representation property used by discovery

[andrewfg]

Thanks everyone for the feedback. I will try to rework it based on your suggestions, and upload a new version later today.

[andrewfg]

@bobadair many thanks for the feedback..

First, if your binding makes use of a bridge, the representation property does not need to be globally unique, but only unique within the context of the bridge..

Second, if your thing has two configuration parameters (e.g. channel and address) where each individually is not unique, but the combination of the two is unique..

Both good points. I will add them.

[bgilmer77]

Great contribution. Thank you. Please consider my comments and suggested edits.

[andrewfg]

Re: Links

In my new text, to avoid duplicate descriptions, there are cross reference links to other pages / topics. The links are in the form of page.md links to other mark-down pages on github.com, but I suppose that when you publish to openhab.org your build system does convert those page.md links to the proper page.html links. Or do I need to do anything on my side??

[cweitkamp]

Great job. Thank you for improving this part of the documentation.

[Confectrician]

Thanks to all participants for the valid discussion and improvements.
I will do a last short check but i think, this can be merged later. :)