| Info |
|---|
For SmartServer 3.3 and higher, see Setting Up up Datapoint Connections. For SmartServer 2.9 or prior, see Defining Datapoint Connections (Release 2.9). |
You can define connection templates that specify how datapoint outputs are connected to datapoint inputs. A connection template, which is made up two or more rules, specifies how an update from one or more datapoints is automatically routed to one or more datapoint inputs. You define connection templates in a connection requirements (CON) file. The file is a manually-generated CSV file defining one or more connection rules for datapoints. A connection rule comprises two or more lines in the CSV file. All lines in the connection file that apply to the same connection rule will have the same Template Name. Each connection template (Template Name) specifies one or more source datapoints and one or more destination datapoints.
...
Point-to-Point connections can be used to convert data from different protocols, different datapoints types (scalar to structure, or structure to scalar) using the CON file map, or localization parameters. You can also specify that only certain values be sent to the destination datapoint by using presets (e.g., ON or OFF). Connection rules that use map, presets, or localization are point-to-point connections.
Point-to-point connections rely on the SmartServer receiving datapoint updates. In order to get datapoint updates, you typically configure the datapoint properties for all the datapoints you use for a connection using the Datapoint Properties widget (or DLA file) and set up monitoring (polling or event-driven). Updates will also occur and can be monitored on the Datapoint Browser widget as it received updates, or any other application that does on-demand GETs.
...
A CON file contains the following columns (not case sensitive, and parameter columns can be in any order):
| Parameter | Description | ||
|---|---|---|---|
| Template Name | Connection unique identifier. All connection filters with the same template name define a connection template. There should be at least one source and at least one destination entry with the same Template Name. | ||
| Reference Type | Specifies the type of datapoint reference. Values may be Fixed or Relative (case insensitive). If Reference Type is not specified, it is assumed to be Fixed. If a Device Name is specified then Reference Type is assumed to be Fixed. If a Device Name is not specified then Reference Type is assumed to be Relative. Fixed datapoint means that you are specifying the device name. Contexts, Target Type, Target Name, and Device Type can be blank. Relative datapoint means that you are specifying a device type based on a context. | ||
| Contexts | List of full context paths that the template applies to, with optional wildcards for any level of the context hierarchy. Context paths are separated with a semicolon. If contexts are specified for a fixed datapoint reference, and the context does not match any of the contexts containing the device specified with the device name, the CMS will display a warning message. If a connection template contains context-relative datapoints, then contexts should be defined for that template, otherwise no connections will be created. Only the first Contexts entry that is found for a template is used (others are ignored). The CMS will always export an empty value for the context for a specified context that does not match one of the contexts of the device specified by the device name. | ||
| Target Type | Target Type is used when Reference Type is Relative. Valid values are: blank, none, campus, campus area, building, foor, floor area, or room (case insensitive; spaces and separators are ignored). | ||
| Target Name | Target Name filter is used with Target Type. Example: The Target Type is room and you have the following room names: boiler, kitchen, office A, office B. If you specify office, then the connection rule only applies to office A and office B. | ||
| Device Name | Datapoint XIF name. This parameter must be specified for a fixed datapoint. This parameter is ignored with warning for context-relative datapoints. The CMS will always export an empty value for a context-relative datapoint reference. | ||
| Device Type | Device Type Name. This field is required for a context-relative datapoint reference. This field is optional for a fixed datapoint reference. If the Device Type is specified for a fixed datapoint reference and the Device Type does not match the Device Type of the device specified with the Device Name, then the CMS will display a warning message. The CMS will always export an empty value for the type for a specified device type that does not match the device type of the device specified by the device name. | ||
| Datapoint Name | Datapoint XIF name.
| ||
| Direction | Source or Destination. If the field is not specified, or is specified but empty, the direction will be source for non-writable datapoints and destination for writable datapoints. | ||
| Map | Mapping formula (JSON object) where $ is source value. Used for Source Map only. For destination mapping use Localization or Preset Map. $ is source value and map formula. Examples: Scalar (temperature in Celsius to temperature in Fahrenheit): {"transform": "$ * 1.8 + 32"} Map formula to go from scalar to structure datapoint (SNVT_count to SNVT_Switch which has two fields, state and value): {"state":{"transform":"$ ? 1 : 0"},"value":"$"} If doing a FAN IN connection, and the source datapoints have different map formulas, then you need to create separate rules for each source datapoint and include the same list of destination for each rule. (optional parameter) | ||
| Presets | Presets that both the source and destination must contain in order for the data to be transferred. Source and destination can have a different list of presets, but source value is only sent to destination if both source and destination have matching presets. All other values that do not have matching presets are not sent. To do destination mapping, do the map as part of the destination preset formula or use destination. "onlyPreset" - should always be set to true, means only connections with matching source and destination presets are transferred to destination. (optional parameter) | ||
| Repeat Presets | If set to true, all subsequent source or destinations use the same localization. (optional parameter) | ||
| Localization | Localization formula: For source $ is the source value, for destination $ is the connection value, and the localization formula value is what the CMS Datapoint Browser shows. Examples: Source localization for scalar (SNVT_count to SNVT_temp_p in deg F): Source localization: {"transform": "$ * 1.8 + 32"} Destination formula to go from scalar to structure datapoint (SNVT_count to SNVT_Switch): {"state":{"transform":"$ ? 1 : 0"},"value":"$"} {"value":{"transform": "$ + 10"}, "state":{"$ > 0 ? 1 : 0"}} (optional parameter) | ||
| Repeat Localization | If set to true, all subsequent source or destinations use the same localization. (optional parameter) |
...
| Note |
|---|
| Note: CON presets and localization are independent of Datapoint Properties (or DLA file) presets and localization, and only apply to the connections. Datapoint Properties (or DLA) presets and localization do not apply to connections. Converting a temperature datapoint from degrees Celsius to degrees Fahrenheit is typically done through the Datapoint Properties (or DLA file) and not the CON file. |
Using Presets, Localization, and Map
Presets and localization can be applied to source and destinations datapoints. Leave the cell blank in the CON file for any rule not using preset, localization or map.
Map, presets and localization is typically only used if the datapoint type is different. That is, if both the source and destination datapoints are the same datapoint type, then in most cases you would not use map, preset, or localization for the connection rules.
Map, preset and localization allow you to create a connection that translates values from one datapoint type to another (e.g., SNVT_switch to SNVT_count), or to manipulate the source or destination values. For example, if the source and destination datapoints are SNVT_count, but the source has a range of -100 to 300 and the destination only allows a range of 0 to 100, you can use use map or localization to change the allowed destination range.
The following scenarios are supported:
Localization | Presets | Map |
|---|---|---|
| yes | no | no |
| no | yes | no |
| no | no | yes |
| yes | yes | no |
| yes | no | yes |
| no | yes | yes |
| yes | yes | yes |
The order of the transformation for the source datapoint is IAP value → Localization → Presets → Map.
- If the source localization is defined, the datapoint is transformed to a localized value.
- If the source presets is not NULL, the IAP value (or the local value) is transformed to a preset value.
- If the map is defined, the last transformation value, which could be a preset value, a local value or an IAP value, is transformed according to the map rules.
The reverse transformation order for the destinations datapoint is Presets → Localization → IAP value. Presets (if defined) are specified using the local values. The localization rule must be specified to reverse transform the preset value to the IAP value.
The map is specified in source and will be applied to the source datapoint for all destinations. Only one map per connection rule ID is supported. Map should be left empty for destinations as it is not supported. Mapping for individual destinations is defined in presets or localization.
If the datapoint value does not map to any of the presets, then the value is not sent if the onlyPreset property is set to true. Otherwise, the native value will be sent instead. If both transformation map and presets are defined on the source datapoint, then the transformation map is ignored. Only one preset can be defined in the datapoint source. If you have more than one source that has different presets, you have to split it into different connection objects.
The CON file has an option to specify whether to skip sending datapoint values if the presetValue is not defined or the source presetValue does not map to any of the destination presets.
...
| Function | Function Name | Description | Formula |
|---|---|---|---|
| min(x,y) | Min | Min is used to limit a maximum value (e.g., to limit a scalar value high value to 100 or lower) | {"transform":"min($, 100)"} |
| max(x,y) | Max | Max is used to limit a minimum value (e.g., to positive numbers) | {"transform":"max($, 0)"} |
| sqrt(x) | Square Root | Calculates the square root of a value | {"transform":"sqrt($.value)"} |
Example formula to limit a datapoint value to a value between 10 and 100:
...
#filetype,con |
With Two Sources and One Destination (Different Source Mapping)
| Note |
|---|
| Note: Requires two source rules, one for each destination. |
The following CON file example shows two sources that are connected to, and one destination, with each source having a different mapping transformation. In this case, you need to create multiple rules (i.e., separate rules for each mapping transformation), or specify the mapping rules in Presets column, where presets and the mapping rules are defined, similar to the following:
- create a rule for sourceA/destA
- create another rule for sourceB/destA
#filetype,con |
...
#filetype,con |
Clear Connections
The following CON file example shows the format to clear all connections (using a connection file with no rules).
...