docs: Documented emitting connection errors in WireAsset [backport do…

…cs-release-5.6] (#5498)

docs: Documented emitting connection errors in WireAsset (#5480)

* docs: Documented emitting connection errors in WireAsset

Signed-off-by: Nicola Timeus <[email protected]>

* Addressed comments

* Fixed indentation

---------

Signed-off-by: Nicola Timeus <[email protected]>
(cherry picked from commit bd36914)

Co-authored-by: nicolatimeus <[email protected]>

docs/kura-wires/assets-as-wire-components.md

@@ -2,19 +2,21 @@
 
 An [Asset](../connect-field-devices/driver-and-assets.md) can be used inside a Wire Graph, in this case it is represented as node with two ports an input port and an output port. An Asset used in this way is called **WireAsset**.
 
-
-
 ## Read mode
 
 Every time a WireAsset receives an envelope on its input port, it will read the values of all of its channels with `READ` or `READ_WRITE` type. The result is emitted as a WireEnvelope with a single WireRecord. The WireRecord contains the following properties:
 
 * a property with key `assetName`, value type **STRING** and the emitting asset asset name as value
+* a property with key `assetError`, value type **STRING** if **emit.errors** and **emit.connection.errors** is enabled and a general connection failure is returned by the Driver. See the description of the **emit.connection.errors** parameter for more details.
+* a property with key `assetTimestamp`, value type **LONG**, reporting a timestamp in milliseconds since Unix epoch (midnight, January 1, 1970 UTC). This property may be present or not depending on the value of the **timestamp.mode** configuration parameter or in case of general connection exception reported by the Driver, see the configuration parameter description for more details.
+
 For each channel in asset configuration with **READ** or **READ_WRITE** type named **name**:
+
 * a property with key = **name**, value type = **value.type** in channel configuration and value = value obtained from read operation. This property will be present only if the read operation is successful.
 * a property with key = `<name>_timestamp` value type = `LONG` reporting a timestamp in milliseconds since UNIX epoch. This property will be present only if the **timestamp.mode** Asset configuration property is set to `PER_CHANNEL`
 * a property with key = `<name>_error`, value type = `STRING` reporting an error message. This property will be present only if read operation fails and the **emit.errors** Asset configuration property is set to true.
 
-For example, if the Asset attached to the Modbus Driver shown in the picture below receives a WireEnvelope on its input port, it can emit an envelope with the following content, assuming that the read operation for each channel succeed:
+For example, if an Asset that has the channel configuration shown in the picture below receives a WireEnvelope on its input port, it can emit an envelope with the following content, assuming that the read operation for each channel succeed:
 
 ![WireAsset Read Example](./images/asset-read-example.png)
 
@@ -103,4 +105,34 @@ The following operations will happen:
 * The **LED2**: `78` property will have no effect, since the Asset configuration contains a channel named **LED2** with **type** = `READ_WRITE`, but **value.type** = `BOOLEAN` != `LONG`.
 * The **Toggle-4**: `true` property will have no effect, since the asset contains a channel named `Toggle-4`, with **value.type** = `BOOLEAN` but **type**  = `READ` != `WRITE` | `READ_WRITE`
 * The  **foo**: `bar` property will have no effect, since none of the defined channels has `foo` as **name**.
-* The Asset will read and emit all of the channel values with **type** = `READ` or `READ_WRITE`, since a WireEnvelope has been received.
+* The Asset will read and emit all of the channel values with **type** = `READ` or `READ_WRITE`, since a WireEnvelope has been received.
+
+## Wire Asset global configuration parameters
+
+The WireAsset component provides the following global (non per-channel) configuration parameters that can be used to customize component behavior:
+
+* **emit.all.channels**: Specifies whether the values of all READ or READ_WRITE channels should be emitted when a channel event is received in listen mode. If set to true, the values for all channels will be read and emitted, if set to false, only the value for the channel related to the event will be emitted.
+
+* **timestamp.mode**: Allows to configure how timestamps are emitted, the following modes are supported:
+
+    * **NO_TIMESTAMPS**: no timestamp-related properties will be emitted.
+
+    * **PER_CHANNEL**: the component will emit a driver-generated timestamp property per channel, as the value of the `<channel name>_timestamp` property.
+
+    * **SINGLE_ASSET_GENERATED**: the component will emit a single timestamp per request, generated by the Asset itself before emitting the envelope as the value of the `assetTimestamp` property.
+
+    * **SINGLE_DRIVER_GENERATED_MAX** and **SINGLE_DRIVER_GENERATED_MIN**: the component will emit a single driver generated timestamp being respectively the max (most recent) or min (oldest) among the timestamps of the channels as the value of the `assetTimestamp` property.
+
+* **emit.errors**: Specifies whether channel specific errors should be included or not in emitted envelopes. If enabled, the component will add an additional property per channel, named `<channel_name>_error`. If the channel operation fails, the property value will be an error message reported by the Driver, if the operation succeeds the property value will be the empty string.
+
+* **emit.connection.errors**: Specifies whether the component should emit an envelope in case of a general connection exception reported by the Driver (for example due to the fact that the connection with a remote device cannot be established). The error message associated with the exception will be emitted in a property named `assetError`. In case of connection exception, channel values are not available and no channel related properties will be emitted. If the **timestamp.mode** property is set to a value other than **NO_TIMESTAMPS**, the component will also emit a `assetTimestamp` property reporting current system time. This property will be ignored if **emit.errors** is disabled. Example of emitted envelope contents:
+
+  * **WireEnvelope**
+    * **WireRecord[0]**
+        * **assetName**: `myAsset` (type = `STRING`)
+        * **assetError**: `Connection refused` (type = `STRING`)
+        * **assetTimestamp**: `1597925200` (type = `LONG`)
+
+* **emit.on.change**: If set to true, this component will include a channel value in the output emitted in Kura Wires only if it differs from the last emitted value for that channel. Channel errors will always be emitted if **emit.errors** is set to `true`. If as a result of a read operation no changes are detected in any referenced channel, the Asset will emit an envelope containing no channel values, unless **emit.empty.envelopes** is set to `false`.
+
+* **emit.empty.envelopes**: If set to false, this component will not emit empty envelopes.