[documentation] clarification of representation property (#1248)

* [documentation] clarification of representation property

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

* [documentation] typo

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

* [documentation] adopt suggestions of reviewers

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

* [documentation] commas

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

* [documentation] typo

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

* [documentation] addopted suggestions of @bobadair

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

* [documentation] typo

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

* [documentaion] example added back

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

* [documentaion] simplified text

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

* [documentation] typo

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

* [documentation] adopted reviewer comment

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

concepts/discovery.md

@@ -27,9 +27,10 @@ Each discovery result also has a timestamp when it was added to or updated in th
 Discovery results can either be ignored or approved, where in the latter case a Thing is created for them and they become available in the application. 
 If an entry is ignored, it will be hidden in the inbox without creating a Thing for it. 
 
-openHAB offers a service to automatically ignore discovery results in the inbox, whenever a Thing is created manually, that represents the same Thing, as the respective discovery result would create. 
-This Thing would either have the same Thing UID or the value of its representation property is equal to the representation property's value in the discovery result.
-This service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`. 
+openHAB offers a service to automatically ignore duplicate discovery results in the inbox whenever, a) a Thing has been created manually, that represents the same Thing as the respective discovery result would create, or b) whenever a Thing has been discovered separately by two alternate discovery services.
+Such duplicate Things are identified as either Things with the same Thing UID, or Things with an identical `representation property`.
+For a manually created Thing, its representation property is either a `property` or a `configuration parameter` of the Thing.
+This auto-ignore service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`. 
 
 ### Auto Approve
 

developers/bindings/index.md

@@ -660,7 +660,7 @@ The following table gives an overview about the main parts of a `DiscoveryResult
 | `bridgeUID` | If the discovered thing belongs to a bridge, the `bridgeUID` contains the UID of that bridge.
 | `properties` | The `properties` of a `DiscoveryResult` contain the configuration for the newly created thing.
 | `label` | The human readable representation of the discovery result. Do not put IP/MAC addresses or similar into the label but use the special `representationProperty` instead. |
-| `representationProperty` | The name of one of the properties which discriminates the discovery result best against other results of the same type. Typically this is a serial number, IP or MAC address. The representationProperty often matches a configuration parameter and is also explicitly given in the thing-type definition. |
+| `representationProperty` | The name of one of the properties or configuration parameters, which best discriminates the result from other results of the same type. See chapter [Representation Property](#representation-property) below. |
 
 To simplify the implementation of custom discovery services, an abstract base class `AbstractDiscoveryService` implements the `DiscoveryService` and just needs to be extended.
 Subclasses of `AbstractDiscoveryService` do not need to handle the `DiscoveryListeners` themselves, they can use the methods `thingDiscovered` and `thingRemoved` to notify the registered listeners.
@@ -692,6 +692,57 @@ It uses the `DiscoveryResultBuilder` to create the discovery result.
 The discovery service needs to provide the list of supported thing types, that can be found by the discovery service.
 This list will be given to the constructor of `AbstractDiscoveryService` and can be requested by using `DiscoveryService#getSupportedThingTypes` method.
 
+### Representation Property
+
+The name of one of the properties or configuration parameters, which best discriminates the discovery result from other results of the same type.
+Typically this is a serial number, or an IP or MAC address.
+The representation property is used to auto-ignore discovery results of Things that already exist in the system.
+This can happen, a) if a Thing has been created manually, or b) if the Thing has been discovered separately by two mechanisms e.g. by mDNS, and by NetBios, or UPnP.
+If a new Thing goes online, the auto-ignore service of the inbox checks if the inbox already contains a discovery result of the same type where the existing representation property is identical to the representation property of the newly discovered Thing.
+If this is the case, the Thing in the inbox is automatically ignored.
+The representation property must be declared in the [thing-types.xml](thing-xml.md#representation-property)
+
+When comparing representation properties, the framework checks for matches between the representation property of the newly discovered Thing, and both the `properties` and the `configuration parameters` of existing Things.
+
+If defining a representation property for a bridge, the representation property does not need to be **globally** unique, but only unique within the context of the bridge, so long as the discovery service calls `.withBridge(bridgeUID)` when building the DiscoveryResult. e.g. if bridge A. has child Things with representation properties of 1, 2, and 3, and bridge B. also has child Things with representation properties of 1, 2, and 3, they will not conflict.
+
+```java
+DiscoveryResult result = DiscoveryResultBuilder.create(thingUID)
+  .withProperty("uniqueId", nonUniquePropertyValue)
+  .withBridge(bridgeUID) // bridgeUID plus nonUniquePropertyValue are unique
+  .withRepresentationProperty("uniqueId")
+  .build();
+```
+
+Furthermore, if a Thing has two configuration parameters where each individually is not globally unique, but the combination of the two is unique, one can define an extra property that combines the two:
+
+```java
+String cfgParamValA = "value-of-non-unique-config-param-A";
+String cfgParamValB = "value-of-non-unique-config-param-B";
+String uniquePropVal = String.format("%s-%s", cfgParamValA, cfgParamValB);
+...
+DiscoveryResult hub = DiscoveryResultBuilder.create(thingUID)
+  .withProperty("uniqueId", uniquePropVal)
+  .withRepresentationProperty("uniqueId")
+  .build();
+```
+
+If Things are created manually, the property or configuration parameter that will match the auto discovery representation property must be set.
+In the case that a `property` will be used to match the representation property its value must be set in the Thing handler's `initialize()` method:
+
+```java
+updateProperty("uniqueId", uniquePropVal);
+```
+
+Alternatively in the case that a `configuration parameter` will be used to match the auto discovery representation property, the parameter must be declared in either, a) the `thing-types.xml` file, or b) the `config-description` [XML file](config-xml.md).
+And it must also be declared in the Thing handler's `Configuration` class:
+
+```java
+public class MyThingConfiguration {
+    public String uniqueId;
+}
+```
+
 ### Registering as an OSGi service
 
 The `Discovery` class of a binding which implements `AbstractDiscoveryService` should be annotated with

developers/bindings/thing-xml.md

@@ -488,38 +488,57 @@ In contrast to the properties defined in the 'ThingType' definitions the thing h
 ### Representation Property
 
 A thing type can contain a so-called `representation property`.
-This optional property contains the _name_ of a property whose value can be used to uniquely identify a device.
+This optional property contains the **name** of a property whose value can be used to uniquely identify a device.
 The `thingUID` cannot be used for this purpose because there can be more than one thing for the same device.
 
 Each physical device normally has some kind of a technical identifier which is unique.
 This could be a MAC address (e.g. Hue bridge, camera, all IP-based devices), a unique device id (e.g. a Hue lamp) or some other property that is unique per device type.
 This property is normally part of a discovery result for that specific thing type.
 Having this property identified per binding it could be used as the `representation property` for this thing.
 
-The `representation property` will be defined in the thing type XML: 
+The `representation property` shall be defined in the thing type XML: 
 
 ```xml
     <thing-type id="thingTypeId">
         ...
         <properties>
             <property name="vendor">Philips</property>
         </properties>
-        <representation-property>serialNumber</representation-property>
+        <representation-property>uniqueId</representation-property>
         ...
     </thing-type>
 ```
 
-Note that the `representation property` is normally not listed in the `properties` part of the thing type, as this part contains static properties, that are the same for each thing of this thing type.
-The name of the `representation property` identifies a property that is added to the thing in the thing handler upon successful initialization.
+Note that the `representation property` is normally not listed in the `properties` part of the Thing type XML, as this part contains static properties, that are the same for all instances of this Thing type.
+The name of the `representation property` identifies a property or configuration parameter that is added to the Thing in the Thing handler upon successful initialization.
 
 ### Representation Property and Discovery
 
-The representation property is being used to auto-ignore discovery results of devices that already have a corresponding thing.
-This happens if a device is being added manually.
-If the new thing is going online, the auto-ignore service of the inbox checks if the inbox already contains a discovery result of the same type where the value of its `representation property` is identical to the value of the `representation property` of the newly added thing.
-If this is the case, the result in the inbox is automatically set to ignored.
-Note that this result is automatically removed when the manual added thing is eventually removed.
-A new discovery would then automatically find this device again and add it to the inbox properly.
+The representation property is used to auto-ignore discovery results of Things that already exist in the system.
+This can happen if, a) a Thing has been created manually, or b) the Thing has been discovered separately by two mechanisms e.g. by mDNS, and by NetBios, or UPnP.
+If this is the case, the Thing in the inbox is automatically ignored.
+Note that this Thing is automatically removed when the manually added Thing is removed.
+A new discovery would then automatically find this Thing again and add it to the inbox properly.
+
+See also [Implementing a Discovery Service](index.md#representation-property)
+
+When comparing representation properties, the auto-ignore service checks for matches between the representation property of the newly discovered Thing, and both the properties and the configuration parameters of existing Things.
+If a configuration parameter will be used, then its respective `parameter` shall be declared in the XML `config-description` section or the `config-description` [XML file](config-xml.md):
+
+```xml
+    <thing-type id="thingTypeId">
+        ...
+        <representation-property>uniqueId</representation-property>
+        ...
+    		<config-description>
+  			  <parameter name="uniqueId" type="text">
+		  		  <label>Unique Id</label>
+			  	  <description>The Unique Id for Representation Property</description>
+  			  </parameter>
+    		</config-description>
+        ...
+    </thing-type>
+```
 
 ## Formatting Labels and Descriptions