Info

For SmartServer 3.3 and higher, see Setting Up Datapoint Connections.

For SmartServer 3.0-3.2, see Defining Datapoint Connections (Release 3.0-3.2).

You can define connection rules that specify how datapoint outputs are connected to datapoint inputs. A connection rule specifies how an update from one or more datapoints is automatically routed to one or more datapoint inputs. You define connection rules 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 rule ID. Each rule ID specifies one or more source datapoints and one or more destination datapoints.

...

Table of Contents

maxLevel	3

Overview

Each time a new CON file is added, the new rules are checked against the existing rules. A rule that is in the existing and new CON file is unchanged. Any new rule that is added, and any old rule that does not exist in the new CON file, is deleted. Therefore, in order to add, change, or delete connections, a new CON file with all the desired connections needs to be imported. To clear all connections, import a connection file with the header and parameter name, but without any defined connection rules. See Clear Connections in this section.

...

1 = point-to-point
2 = LON peer-to-peer

Creating a CON File

Requirements

A CON file contains the following embedded metadata tags anywhere in the file, and typically in the first line:
{noformat}#filetype,con{noformat}

...

2. Example CSV files – already show converted formulas. Just copy the CSV file data to a text editor (i.e., notepad) and save it with a .CSV extension (or .CON.CSV). You can then view the CON file in Excel.

CON File Parameters

A CON file contains the following columns (not case sensitive):

Parameter	Description
Rule ID	Unique identifier There may be multiple entries with the same Rule ID. All entries with the same Rule ID are part of the same connection rule.
Area Scope	Leave blank when specifying Device name. When specifying Device Type this is the first part of the geozone path, with optional wildcards, to which the connection rule applies. First instance found for the rule is used and others are ignored silently. If no area scope is found in any rule line, the connection rule is ignored silently.
Zone Scope	Leave blank when specifying Device name. When specifying Device Type this is the second part of the geozone path, with optional wildcards, to which the connection rule applies. First instance found for the rule is used and others are ignored silently. If no zone scope is found in any rule line, all zones in the area scope are used.
Device Name	Device name or wild card
Device Type	XIF file name (not required if Device_Name is specified and not a wildcard). When using Device Type you need always need to specify area scope (either the area scope name or * for all area scope).
Datapoint Name	Datapoint XIF name Each datapoint has a Datapoint Instance name and a datapoint XIF name (datapoint XIF name is shown in CMS Datapoint Browser Widget Details view or Datapoint Properties). Specify the datapoint XIF name.
Direction	Source or Destination
Map	Mapping formula where $ is source value . 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 (Source, Destinations, or Both)	Presets (Source, Destinations, or Both)	Map (Source only)
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.

...

For structured destination datapoints you need to specify result for all fields. That is, if you have a five field destination, then the formulas you use must specify a destination value that has all five fields.

Understanding Connection Operations

Source value → Source Transform (by source map, preset, or localization) → Connection value → Destination Transform (by destination preset or localization) → Destination value.

There can be FAN INs (multiple sources) for one connection.
1. If the source map, preset, and localization are the same for all source datapoints, then you can use one connection rule.
2. If the source map, preset, or localization is different, then you need to specify the source in separate rules and duplicate the destination datapoints for both.
3. If you have some source datapoints with the same map, preset, or localization, then those can be in one rule and the other source datapoints need to be in separate rules.
There can be FAN OUTs (multiple destination) for one connection.
There can be FAN INs and FAN OUTs for one connection.
1. If the source map, preset, and localization are the same for all source datapoints, then you can use one connection rule.
2. If the source map, preset, or localization is different, then you need to specify the source in separate rules and duplicate the destination datapoints for both.
3. If you have some source datapoints with the same map, preset, or localization, then those can be in one rule and the other source datapoints need to be in separate rules.

Formula Examples

$ represents the input of a source or destination transform and specifies the complete datapoint value. For structured datapoints, like SNVT_switch, specify $.<field name> to access a datapoint field value.

...

You need to use a transform function in the formula any time the formula uses multiplication, division, addition, subtraction, if-then, math formula, or math function.

Math Functions

Math functions can be applied to datapoint values, such as limiting the range of the datapoint value.

...

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:

{"transform":"min(max($, 0),100)"}

Source Map Formulas

Destination map is configured by using preset map or localization.

...

Note
Note 1: This formula can only be used if the map formula has no multiplication, division, addition, subtraction, if-then, or math formula. Note 2: Transform function is required when map formula has multiplication, division, addition, subtraction, if-then, or math formula.

Presets Formulas

These example formulas can be copied into an Excel cell.

Datapoint format	Datapoint type	Direction	Formula
Scalar	SNVT_count	Source
Scalar	SNVT_count	Destination	{"$": {"enumeration":{"source": "$", "map": {"ON": 100,"MID": 50, "OFF": 0}}}}
Structured	SNVT_switch	Source	{"$": {"transform": "$.value == 100 && $.state == 1 ? 'ON' : $.value == 50 && $.state == 1 ? 'MID' : $.value == 0 && $.state == 0 ? 'OFF' : ' ' "}}
Structured	SNVT_switch	Destination	{"$": {"value":{"enumeration":{"source": "$", "map": {"ON": 100,"MID": 50,"OFF": 0}}},"state":{"enumeration":{"source":"$","map":{"ON": 1,"MID": 1,"OFF": 0}}}},"onlyPreset": true}

Localization Formulas

These example formulas can be copied into an Excel cell.

Datapoint format	Datapoint type	Direction	Formula
Scalar	SNVT_count	Source	{"transform": "$ * 1.8 + 32"}
Scalar	SNVT_count	Destination	{"transform": "$ * 2"}
Structured	SNVT_switch	Source	{"value":{"transform": "$.value + 10"},"state":{"transform": "$.state"}}
Structured	SNVT_switch	Destination	{"value":{"transform": "$.value * 2"},"state":{"transform": "$.state"}}
Structured	SNVT_switch	Destination	{"state":{"transform":"$ ? 1 : 0"},"value":{"transform":"min(max($, 10), 100)"}}

CON File Examples

Using map, presets, and localization in datapoints is optional. A datapoint can have map only (Sources), presets only, localization only, have all three map, presets and localization, or neither. When both presets and localization are used, the presets map are typically configured based on the localization value. Therefore, when an update is received, the value needs to be localized first before mapping to a preset string. And, when a preset string is entered, the map value needs to be transformed using the revert transformation rule to get the native value.

...

The first example demonstrates a LON peer-to-peer connection, which is only available for LON devices (DMM mode only). All other examples show point-to-point connections ,which are used for all protocols including BACnet, Modbus, and LON connections.

LON Peer-to-Peer Connection

Note
Note: Used for DMM only. Source and destination datapoints are the same datapoint type.

...

#filetype,con,,,,,
Rule ID,Area Scope,Zone Scope,Device Name,Device Type,Datapoint Name,Direction
24,,,PulseGen1,,device/0/nvoSwitch2,Source
24,,,PulseGen2,,device/0/nviLamp2,Destination
25,,,PulseGen2,,device/0/nvoSwitch2,Source
25,,,PulseGen1,,device/0/nviLamp2,Destination

With Source Map

The following CON file example (Device Name Specified) shows the format for map, presets, and localization, when only map specified.

#filetype,con,,,,,,,,,,
Rule ID,Area Scope,Zone Scope,Device Name,Device Type,Datapoint Name,Direction,Map,Presets,Repeat Presets,Localization,Repeat Localization
22,,,PulseGen1,,device/0/nvoPulseOut,Source,"{""state"":{""transform"":""$ ? 1 : 0""},""value"":""$""}",,,,
22,,,PulseGen1,,device/0/nviLamp1,Destination,,,,,
23,,,PulseGen2,,device/0/nvoPulseOut,Source,"{""state"":{""transform"":""$ > 0 ? 1 : 0""},""value"":""$""}",,,,
23,,,PulseGen1,,device/0/nviLamp2,Destination,,,,,

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
Rule ID,Area Scope,Zone Scope,Device Name,Device Type,Datapoint Name,Direction,Map 
8,,,NcMultiSensor112.860,,Switch/0/nvoValue,Source,"{""value"": {""transform"":""sqrt($.value)""}, ""state"": {""transform"": ""$.state ? 0 : 1""}}" 
8,,,NcMultiSensor112.860,,Switch/0/nviValueFb,Destination,, 
9,,,NcMultiSensor112.860,,Switch/0/nvoValue,Source,"{""value"": {""transform"":""3.5*($.value%25)""}, ""state"": {""transform"": ""$.state ? 1 : 0""}}" 
9,,,NcMultiSensor112.860,,Switch/1/nviValueFb,Destination,,

With Presets

The following CON file example shows the format for map, presets, and localization.

#filetype,con,,,,,,,,,,
Rule ID,Area Scope,Zone Scope,Device Name,Device Type,Datapoint Name,Direction,Map,Presets,Repeat Presets,Localization,Repeat Localization
3,,,PulseGen1,,device/0/nvoLamp1,Source,,"{""$"": {""transform"": ""$.value == 100 && $.state == 1 ? 'ON' : $.value == 50 && $.state == 1 ? 'MID' : $.value == 0 && $.state == 0 ? 'OFF' : ' ' ""}}",,,
3,,,PulseGen2,,device/0/nviTemp,Destination,,"{""$"": {""enumeration"":{""source"": ""$"", ""map"": {""ON"": 100,""MID"": 50, ""OFF"": 0}}}}",,,
3,,,PulseGen2,,device/0/nviLamp1,Destination,,"{""$"": {""value"":{""enumeration"":{""source"": ""$"", ""map"": {""ON"": 100,""MID"": 50,""OFF"": 0}}},""state"":{""enumeration"":{""source"":""$"",""map"":{""ON"": 1,""MID"": 1,""OFF"": 0}}}},""onlyPreset"": true}",,,

With Localization

The following CON file example shows the format for map, presets, and localization.

#filetype,con,,,,,,,,,,
Rule ID,Area Scope,Zone Scope,Device Name,Device Type,Datapoint Name,Direction,Map,Presets,Repeat Presets,Localization,Repeat Localization
3,,,PulseGen1,,device/0/nvoLamp1,Source,,,,,
3,,,PulseGen2,,device/0/nviLamp1,Destination,,,,"{""value"":{""transform"": ""$.value + 10""},""state"":{""transform"": ""$.state""}}",
4,,,PulseGen1,,device/0/nvoHVACTemp,Source,,,,,
4,,,PulseGen2,,device/0/nviTemp,Destination,,,,"{""transform"": ""$ * 1.8 + 32""}",
5,,,PulseGen1,,device/0/nvoCount,Source,,,,"{""transform"": ""$ * 2""}",
5,,,PulseGen2,,device/0/nviCount,Destination,,,,,

With Presets and Localization (One Source and Two Destinations)

The following CON file example shows the format for map, presets, and localization.

#filetype,con,,,,,,,,,,
Rule ID,Area Scope,Zone Scope,Device Name,Device Type,Datapoint Name,Direction,Map,Presets,Repeat Presets,Localization,Repeat Localization
3,,,PulseGen1,,device/0/nvoLamp1,Source,,"{""$"": {""transform"": ""$.value == 100 && $.state == 1 ? 'ON' : $.value == 50 && $.state == 1 ? 'MID' : $.value == 0 && $.state == 0 ? 'OFF' : ' ' ""}}",,,
3,,,PulseGen2,,device/0/nviTemp,Destination,,"{""$"": {""enumeration"":{""source"": ""$"", ""map"": {""ON"": 100,""MID"": 50, ""OFF"": 0}}}}",,"{""transform"": ""$ * 2""}",
3,,,PulseGen2,,device/0/nviLamp1,Destination,,"{""$"": {""value"":{""enumeration"":{""source"": ""$"", ""map"": {""ON"": 90,""MID"": 50,""OFF"": 0}}},""state"":{""enumeration"":{""source"":""$"",""map"":{""ON"": 1,""MID"": 1,""OFF"": 0}}}},""onlyPreset"": true}",,"{""value"":{""transform"": ""$.value + 10""},""state"":{""transform"": ""$.state""}}",

Clear Connections

The following CON file example shows the format to clear all connections (using a connection file with no rules).

...

Versions Compared

Old Version 2

New Version 3

Key

Overview

Creating a CON File

Requirements

CON File Parameters

Using Presets, Localization, and Map

Understanding Connection Operations

Formula Examples

Math Functions

Source Map Formulas

Presets Formulas

Localization Formulas

CON File Examples

LON Peer-to-Peer Connection

With Source Map

With Two Sources and One Destination (Different Source Mapping)

With Presets

With Localization

With Presets and Localization (One Source and Two Destinations)

Clear Connections

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

Overview

Creating a CON File

Requirements

CON File Parameters

Using Presets, Localization, and Map

Understanding Connection Operations

Formula Examples

Math Functions

Source Map Formulas

Presets Formulas

Localization Formulas

CON File Examples

LON Peer-to-Peer Connection

With Source Map

With Two Sources and One Destination (Different Source Mapping)

With Presets

With Localization

With Presets and Localization (One Source and Two Destinations)

Clear Connections