.. _conf.extd.iomaps: ================= Configure IO Maps ================= You can create, edit or delete :ref:`IO Maps ` from the **IO Maps** pane of the viewing area, which you can access in either of the following ways: - Choose :menuselection:`Configuration --> External Data --> IO Maps` from the menu. - In the Navigation sidebar, go to :menuselection:`Settings --> IO Maps`. Prerequisites ************* Before you can create IO Maps, you must set up data connectors as described in :ref:`conf.extd.data.connector`. For each data connector protocol created, a separate tab gets visible on the **IO Maps** pane, from which you can configure the related IO Maps as described below. Create IO Maps ************** 1. On the **IO Maps** pane, select the tab corresponding to the data connector protocol for which you want to create the IO Map. IO Maps are organised into tabs according to the the protocol type of their associated data connector, such as CSV or Excel. 2. Click |add| **Add** on the toolbar. 3. In the **Add IO Map** dialog, follow these three steps to specify the field values, as detailed below: **Step 1**: *Configure general IO Mapping parameters, including settings for raw and filtered tags.* .. list-table:: :widths: 1 5 1 :header-rows: 1 :class: tight-table * - Field - Description - Required * - **Connection Id** - Select the Data Connector that you want to associate with the IO mapping. - Yes * - **Enabled** - Select one of the following options: - *True*: The IO Map record will be processed according to the read/write time specified. - *False*: This record will be ignored during the read/write process. - Yes * - **Tag Alias** - Enter an alias name for the mapping. This is just for categorisation and won’t be used in any service or logic. - No * - **Description** - You can provide additional information about the IO Mapping to help identify its purpose or details. - No * - **IO Type Id** - Choose the type of operation from the following options: - *Input*: The value will be read/ingested into WIP - *Output*: The value will be sent from WIP to the external data source. - Yes * - **Filter Data Type** - Select the data type of the WIP tag for the Filtered Tag. - When using a filtered tag. * - **Raw Tag** - Enter the WIP tag name that will hold values from the external data source. No modifications such as filters or limits will be applied to this value. If you select *None*, the raw process value without filtering will be recorded, but you must set a Filtered Tag. - Yes * - **Filter Tag** - Enter the WIP tag that will receive the processed/filtered value if you want to apply modifications or filters to the value being read from the external data source. Examples include applying a gain/offset, specifying an Override value, applying limits, or holding the last good value if a bad or out-of-range value is received. - Yes * - **External Unit Type** - Select the unit of measure type for the external tag. - Yes * - **Raw Tag Data Type** - Choose the data type of the Raw WIP tag. - Yes * - **External Unit** - Select the actual unit of measure for the external data. A list of available units will be provided based on the selected External Unit Type. During a read operation, WIP will read the External Unit and convert it to the Unit Type base units of measure before storing the data. Similar conversions are performed during writes/outputs, where WIP converts to the proper external unit type before sending an output value. - Yes * - **External Id** - Enter the unique identifier needed to locate/request a value in the external data source. For example, when using OPC DA connectors, this would be the OPC Tag name. This links the WIP Raw/Filtered tag to the external data source. - Yes **Step 2**: *Set parameters for processing IO Map records, including filter configurations if needed.* .. list-table:: :widths: 1 5 1 :header-rows: 1 :class: tight-table * - Field - Description - Required * - **Protocol Parameter 1/2/3** - You can enter additional parameters specific to the data connector protocol. These parameters may be necessary to uniquely identify the information to be retrieved from the data source. For detailed information on these fields, refer to the data connector protocols. - No * - **Action Id** - Select the action to take when the value (after gain/offset has been applied) is not within the specified range. The selected value will determine the value of the Filtered Tag. You can select one of the following values: - *UseRawValue*: Use the adjusted value (Gain Offset Value) as the current Filtered Value. - *ClampAtLimit*: If the Gain Offset Value is below or above the minumum or maximum limit, then clamp the Filtered Value at the minimum or maximum value. The Data Quality is set to *Bad - BelowLoLimit* or *Bad - AboveHiLimit*. - *UseLastGoodValue*: Use the last good Filtered Value. - Yes * - **Frequency** - Set the processing frequency for the IO Map record. If operations are configured via the Scheduler, set the frequency to *OnDemand*. - Yes * - **Change Period Check** - Enter the period (in seconds) to check if a value has been changing. If the value has not changed over this period, it will be flagged in WIP, which can then be used to adjust calculations or raise an event. If set to 0, this check is not performed. - Yes * - **Gain** - Enter the gain value to adjust the raw value. The adjusted value is calculated as (Raw Value * Gain) + Offset. The default Gain value is *1*, which does not change the raw value (since it's multiplied by 1). - Yes * - **Offset** - Enter the offset value to adjust the raw value. The adjusted value is calculated as (Raw Value * Gain) + Offset. The default Offset value is 0, which does not change the raw value (since it adds 0 to the value). - Yes * - **Override Value** - Enter the value to be used if the **Override Enabled** field is set to *True*. This is useful when an instrument has failed or is giving invalid inputs, and you need to force a value to prevent downstream calculations from being impacted. - Yes * - **Override Enabled** - If you select *True*, the Override Value will be placed into the Filtered Tag. - Yes * - **Minimum** - Enter the minimum bound to check the adjusted value against (after applying Gain and Offset). This is in the external unit of measure. - Yes * - **Maximum** - Enter the maximum bound to check the adjusted value against (after applying Gain and Offset). This is in the external unit of measure. - Yes **Step 3**: *Define additional parameters.* .. list-table:: :widths: 1 5 1 :header-rows: 1 :class: tight-table * - Field - Description - Required * - **Comments** - Add any additional information you want to store about the IO Map record. - No * - **Group** - Use this field if you need to group tags for organisational purposes. - No * - **Future** - This field is designed for future use and can be used for filtering and sorting. - No 4. Click **Submit** to save your entry. .. admonition:: Result A new row for the IO Map record gets added to the grid. The system automatically fills in the following additional fields for the record: .. list-table:: :widths: 1 5 :header-rows: 1 :class: tight-table * - Field - Description * - **IO Last Read Write** - Shows the time when the operation was last attempted. * - **Filtered Value** - Displays the value saved to the Filtered Tag. It could be the override value (if specified), the last good value (if the raw value is missing or has bad data quality), the adjusted value (if within limits), or the value specified by the Action Id (either the last good value or clamped at the Minimum or Maximum value). * - **Raw Value** - Contains the last raw value received from the external data source, in the external unit of measure. * - **Gain Offset Value** - Shows the value obtained after the raw value has been adjusted using the gain and offset. * - **Change Timestamp** - If the Change Period Check is set to 0, this field is updated with the timestamp associated with the raw value. Otherwise, the change timestamp is updated to the timestamp associated with the raw value when the difference between the current raw value and the last change value is greater than the current raw value divided by 10^7. * - **Data Quality Code** - Contains the numeric value for the data quality associated with the value. This field is visually enhanced through conditional formatting based on the quality code: - **White**: Data quality is Good (Range 0-9) - **Yellow**: Data quality is Suspect (Range 10-29) - **Orange**: Data quality is Bad (Range 30+) The colour mappings are defined in the installation file ``src/Common/Quality/BuiltInQualities.txt``. To customise these colours, the corresponding entries in this file can be modified. * - **Data Quality Description** - Provides the description associated with the data quality. .. tip:: You can also create a new IO Map by copying an existing IO Map and editing its values. To copy an IO Map, click |copy| in the **Action** column of the relevant IO Map: .. image:: images/conf.extd.iomaps.copy.png | This creates a new entry for the copied IO Map, which you can edit as required. Edit IO Maps ************** 1. On the **IO Maps** pane, select the tab corresponding to the protocol of the relevant IO Map's data connector (for example, Excel, CSV, etc.) 2. For the required IO Map row, click |edit| **Edit** in the **Action** column. .. image:: images/conf.extd.iomaps.edit.png 3. In the **Edit IO Map** dialog, update the values as required. 4. Click **Submit** to save your entries. Delete IO Maps ************** 1. On the **IO Maps** pane, select the tab corresponding to the protocol of the relevant IO Map's data connector (for example, Excel, CSV, etc.) 2. Select the IO Maps that you want to delete. You can select multiple IO Maps at a time. 3. Click |delete| **Delete** on the toolbar. 4. Confirm the deletion. .. seealso:: - :ref:`io.map` - :ref:`dr.iomaps` .. |add| image:: images/icon.add.png .. |edit| image:: images/icon.edit.png .. |delete| image:: images/icon.delete.png .. |copy| image:: images/icon.copy.png